Stability: 2 - Stable

The sensors module provides access to sensor information on your phone, including proximity, light, gravity, orientation sensors, etc. Note that scripts can only read sensor data; they cannot simulate or forge sensor data/events, so features like “simulate shake” are not possible.

To listen to a sensor, you must call sensors.register() to register a listener; only then does it start listening. When you no longer need it, call sensors.unregister() to unregister. When the script ends, all listeners are unregistered automatically. Note that registering listeners keeps the script running; if you never unregister, the script may keep running.

Example: listen to the light sensor:

// Light sensor
sensors.register("light").on("change", (event, light) => {
  log("Current light level:", light);
});

Note that different sensors produce different data, so callback parameters for on() differ. For example, light sensor callback is (event, light), while accelerometer callback is (event, ax, ay, az). On some devices, parameters may differ (e.g. some Huawei devices may report three parameters for proximity, while most devices report one).

Common sensors and their callback parameters:

• accelerometer Accelerometer. Callback (event, ax, ay, az):

  • event SensorEvent Sensor event object
  • ax {number} Acceleration on X axis (m/s^2)
  • ay {number} Acceleration on Y axis (m/s^2)
  • az {number} Acceleration on Z axis (m/s^2). Axis definition is shown below (Z is perpendicular to the screen surface):

  !!axis_device

• orientation Orientation sensor. Callback (event, azimuth, pitch, roll):

  • event SensorEvent Sensor event object
  • azimuth {number} Azimuth angle (degrees), range 0~359
  • pitch {number} Rotation around X axis (degrees), range -180~180
  • roll {number} Clockwise rotation around Y axis (degrees), range -90~90

• gyroscope Gyroscope. Callback (event, wx, wy, wz):

  • event SensorEvent Sensor event object
  • wx {number} Angular velocity around X axis (rad/s)
  • wy {number} Angular velocity around Y axis (rad/s)
  • wz {number} Angular velocity around Z axis (rad/s)

• magnetic_field Magnetic field sensor. Callback (event, bx, by, bz):

  • event SensorEvent Sensor event object
  • bx {number} Magnetic field on X axis (uT)
  • by {number} Magnetic field on Y axis (uT)
  • bz {number} Magnetic field on Z axis (uT)

• gravity Gravity sensor. Callback (event, gx, gy, gz):

  • event SensorEvent Sensor event object
  • gx {number} Gravity acceleration on X axis (m/s^2)
  • gy {number} Gravity acceleration on Y axis (m/s^2)
  • gz {number} Gravity acceleration on Z axis (m/s^2)

• linear_acceleration Linear acceleration sensor. Callback (event, ax, ay, az):

  • event SensorEvent Sensor event object
  • ax {number} Linear acceleration on X axis (m/s^2)
  • ay {number} Linear acceleration on Y axis (m/s^2)
  • az {number} Linear acceleration on Z axis (m/s^2)

• ambient_temperature Ambient temperature sensor (not supported on most devices). Callback (event, t):

  • event SensorEvent Sensor event object
  • t {number} Temperature in Celsius.

• light Light sensor. Callback (event, light):

  • event SensorEvent Sensor event object
  • light {number} Ambient light intensity (lux)

• pressure Pressure sensor. Callback (event, p):

  • event SensorEvent Sensor event object
  • p {number} Atmospheric pressure (hPa)

• proximity Proximity sensor. Callback (event, distance):

  • event SensorEvent Sensor event object
  • distance {number} Distance to obstacle in front of the sensor (often near front camera). On many devices, values are discrete: 0 when close, 5 when far / no obstacle within range.

• relative_humidity Relative humidity sensor (not supported on most devices). Callback (event, rh):

  • event SensorEvent Sensor event object
  • rh {number} Relative humidity, 0~100 (%)

sensors.register(sensorName[, delay])

• sensorName {string} Sensor name (see above)

• delay {number} Update rate (optional). Default sensors.delay.normal. Values:

  • sensors.delay.normal Normal rate
  • sensors.delay.ui Suitable for UI updates
  • sensors.delay.game Suitable for games
  • sensors.delay.fastest Fastest rate

• Returns SensorEventEmitter

Register a sensor listener and return a SensorEventEmitter.

Example:

console.show();
// Register sensor listener
var sensor = sensors.register("gravity");
if (sensor == null) {
  toast("Gravity sensor not supported");
  exit();
}
// Listen to changes
sensor.on("change", (gx, gy, gz) => {
  log("Gravity: %d, %d, %d", gx, gy, gz);
});

You can use delay to specify the sensor update rate. For example:

var sensor = sensors.register("gravity", sensors.delay.game);

If the sensor specified by sensorName is not supported, this function returns null. However, if sensors.ignoresUnsupportedSensor is set to true, it returns a SensorEventEmitter that will not dispatch any sensor events.

Example:

sensors.ignoresUnsupportedSensor = true;
// No need to check null
sensors.register("gravity").on("change", (gx, gy, gz) => {
  log("Gravity: %d, %d, %d", gx, gy, gz);
});

For more information, see SensorEventEmitter.

sensors.unregister(emitter)

• emitter {SensorEventEmitter}

Unregister this sensor listener. Once unregistered, it will no longer receive sensor data.

// Register a sensor listener
var sensor = sensors.register("gravity");
if (sensor == null) {
  exit();
}
// Unregister after 2 seconds
setTimeout(() => {
  sensors.unregister(sensor);
}, 2000);

sensors.unregisterAll()

Unregister all sensor listeners.

sensors.ignoresUnsupportedSensor

• {boolean}

Whether to ignore unsupported sensors. If set to true, sensors.register() will return a virtual listener even for unsupported sensors (no data will ever be dispatched). This avoids null checks, and will also trigger the "unsupported_sensor" event on sensors.

// Ignore unsupported sensors
sensors.ignoresUnsupportedSensor = true;
// Listen for unsupported sensor registration
sensors.on("unsupported_sensor", function (sensorName) {
  toastLog("Unsupported sensor: " + sensorName);
});
// Register a non-existent sensor.
log(sensors.register("aaabbb"));

Event: 'unsupported_sensor'

• sensorName {string} Unsupported sensor name

Emitted when sensors.ignoresUnsupportedSensor is true and an unsupported sensor is registered. The event argument is the sensor name.

SensorEventEmitter

The object returned by registering a sensor. It is an EventEmitter used to listen for sensor events.

Event: 'change'

• ..args {Any} Sensor arguments

Emitted when sensor data changes. The maximum frequency is determined by the delay passed to sensors.register().

Event arguments vary by sensor type; see the list at the beginning of this page.

Example: listen to light and accelerometer, sample every 0.5s, and write to a CSV file:

// CSV file path
const csvPath = "/sdcard/sensors_data.csv";
// Store light sensor data
var light = 0;
// Store accelerometer data
var ax = 0;
var ay = 0;
var az = 0;
// Listen to light sensor
sensors.register("light", sensors.delay.fastest).on("change", (l) => {
  light = l;
});
// Listen to accelerometer
sensors
  .register("accelerometer", sensors.delay.fastest)
  .on("change", (ax0, ay0, az0) => {
    ax = ax0;
    ay = ay0;
    az = az0;
  });

var file = open(csvPath, "w");
// CSV header
file.writeline("light,ax,ay,az");
// Write a row every 0.5s
setInterval(() => {
  file.writeline(util.format("%d,%d,%d,%d", light, ax, ay, az));
}, 500);
// Exit after 10s and open the file
setTimeout(() => {
  file.close();
  sensors.unregisterAll();
  app.viewFile(csvPath);
}, 10 * 1000);

Event: 'accuracy_change'

• accuracy {number} Sensor accuracy. One of:
  • -1 Not connected
  • 0 Unreliable
  • 1 Low
  • 2 Medium
  • 3 High

Emitted when sensor accuracy changes. Rarely used.