Sensors

This section covers all of the RPCs that are specific to actively retrieving sensor data from the device. Each of these sensors has an equivalent passive form of access through PhoneIoT.listenToSensors(). The sensor names and message fields are provided for each sensor.

RPCS

PhoneIoT.getAccelerometer(device: Device)

Gets the current output of the accelerometer sensor, if the device supports it. This is a vector representing the acceleration along the x, y, and z axes, relative to the device. When at rest, you can expect to measure the acceleration due to gravity.

Sensor name: accelerometer

Message fields: x, y, z, facingDir, device

Arguments:

device: Device (Device) - id of the device

Returns: List (List) - current acceleration vector

PhoneIoT.getAltitude(device: Device)

Returns the current altitude of the device, expressed in meters above sea level. This is provided by the location service on the device, so you must have location turned on and give the app permission.

Sensor name: location

Message fields: latitude, longitude, heading, altitude, device

Arguments:

device: Device (Device) - id of the device

Returns: Number (Number) - current altitude in meters

PhoneIoT.getCompassCardinalDirection(device: Device)

Equivalent to PhoneIoT.getCompassDirection(), except that it only returns N, E, S, or W.

If you are getting inconsistent values, try moving and rotating your device around in a figure-8 to recalibrate it.

Sensor name: orientation

Message fields: x, y, z, heading, dir, cardinalDir, device

Arguments:

device: Device (Device) - id of the device

Returns: String (String) - the compass cardinal direction name

PhoneIoT.getCompassDirection(device: Device)

Returns the current compass direction of the device, which is one of N, NE, E, SE, S, SW, W, or NW. This is provided by the magnetic field sensor, so using this RPC on devices without a magnetometer will result in an error. The output of this RPC assumes the device is face-up.

If you are getting inconsistent values, try moving and rotating your device around in a figure-8 to recalibrate it.

Sensor name: orientation

Message fields: x, y, z, heading, dir, cardinalDir, device

Arguments:

device: Device (Device) - id of the device

Returns: String (String) - the current compass direction name

PhoneIoT.getCompassHeading(device: Device)

Gets the current compass heading from the device. This is similar to PhoneIoT.getGPSHeading(), except that it returns the angle from magnetic north, rather than the direction of travel. This is provided by the magnetic field sensor, so using this RPC on devices without a magnetometer will result in an error. The output of this RPC assumes the device is face-up.

If you are getting inconsistent values, try moving and rotating your device around in a figure-8 to recalibrate it.

Sensor name: orientation

Message fields: x, y, z, heading, dir, cardinalDir, device

Arguments:

device: Device (Device) - id of the device

Returns: Number (Number) - the compass heading (in degrees)

PhoneIoT.getFacingDirection(device: Device)

Attempts to determine the general orientation of the device based on the accelerometer output. This represents which direction the face of the device’s screen is pointing. The possible values are:

up - the device is face up
down - the device is face down
vertical - the device is upright
upside down - the device is vertical, but upside down
left - the device is horizontal, lying on its left side (when facing the screen)
right - the device is horizontal, lying on its right side (when facing the screen)

Sensor name: accelerometer

Message fields: x, y, z, facingDir, device

Arguments:

device: Device (Device) - id of the device

Returns: String (String) - name of the facing direction

PhoneIoT.getGPSHeading(device: Device)

Returns the current heading (direction of travel) from the device. This is provided by the location sensor, so you must have location turned on and give the app permission. The heading is expressed as the angle (in degrees) from North, going clockwise. Thus, you can directly use this value in a point in direction block to point a sprite in the direction of travel (assuming North is up).

Note that headings based on location work by approximating your direction of travel, rather than which way you are facing. Thus, this will not work while standing still. In these cases, consider using PhoneIoT.getCompassHeading() instead.

Sensor name: location

Message fields: latitude, longitude, heading, altitude, device

Arguments:

device: Device (Device) - id of the device

Returns: Number (Number) - current heading (in degrees)

PhoneIoT.getGravity(device: Device)

Attempts to get the gravity acceleration angle, divorced from any linear acceleration the device might be experiencing. For example, even if you start running, this vector should always have roughly the same value. This is provided by a hybrid sensor, and is not available on all devices.

The counterpart to this RPC is PhoneIoT.getLinearAcceleration().

Sensor name: gravity

Message fields: x, y, z, device

Arguments:

device: Device (Device) - id of the device

Returns: List (List) - gravitational acceleration vector

PhoneIoT.getGyroscope(device: Device)

Gets the current output of the gyroscope sensor, which measures angular velocity (in degrees/s) along the three axes of the device.

Sensor name: gyroscope

Message fields: x, y, z, device

Arguments:

device: Device (Device) - id of the device

Returns: List (List) - rotational acceleration vector

PhoneIoT.getLightLevel(device: Device)

Gets the current light level from the device. This is represented as a number with higher values being brighter.

Sensor name: lightLevel

Message fields: level, device

Arguments:

device: Device (Device) - id of the device

Returns: Number (Number) - current light level

PhoneIoT.getLinearAcceleration(device: Device)

This RPC attempts to get the linear acceleration vector, divorced from the constant gravitational acceleration. Theoretically, if the device is at rest this RPC would report a nearly-zero vector (nothing is ever perfectly still). This is provided by a hybrid sensor, and is not available on all devices.

The counterpart to this RPC is PhoneIoT.getGravity().

Sensor name: linearAcceleration

Message fields: x, y, z, device

Arguments:

device: Device (Device) - id of the device

Returns: List (List) - current linear acceleration vector

PhoneIoT.getLocation(device: Device)

Gets the current location of the device, specified as latitude and longitude coordinates (in degrees). This is provided by the location service on the device, so you must have location turned on and give the app permission.

Sensor name: location

Message fields: latitude, longitude, heading, altitude, device

Arguments:

device: Device (Device) - id of the device

Returns: List (List) - a list containing the latitude and longitude

PhoneIoT.getMagneticField(device: Device)

Gets the current output of the magnetic field sensor, measured in μT (micro Tesla) along each axis of the device. This is provided by the magnetic field sensor, so using this RPC on devices without a magnetometer will result in an error.

Notably, this RPC can be used as a compass (measuring Earth’s magnetic field).

Sensor name: magneticField

Message fields: x, y, z, device

Arguments:

device: Device (Device) - id of the device

Returns: List (List) - magnetic field vector

PhoneIoT.getMicrophoneLevel(device: Device)

Gets the current level (volume) of the microphone on the device. This is specified as a number where 0.0 denotes silence and 1.0 is the maximum volume the microphone can record.

Sensor name: microphoneLevel

Message fields: volume, device

Arguments:

device: Device (Device) - id of the device

Returns: List (List) - the current volume level

PhoneIoT.getOrientation(device: Device)

Gets the current output of the orientation sensor, relative to Earth’s magnetic reference frame. This is given as a vector (list) with three angular components (in degrees):

azimuth (effectively the compass heading) [-180, 180]
pitch (vertical tilt) [-90, 90]
roll [-180, 180]

If you are getting inconsistent values for the first (azimuth) angle, try moving and rotating your device around in a figure-8 to recalibrate it.

Sensor name: orientation

Message fields: x, y, z, heading, dir, cardinalDir, device

Arguments:

device: Device (Device) - id of the device

Returns: List (List) - the current orientation vector

PhoneIoT.getPressure(device: Device)

Gets the current atmospheric pressure around the device in kPa (kilopascals). For reference, 1 atmosphere of pressure is 101.325 kPa.

Sensor name: pressure

Message fields: pressure, device

Arguments:

device: Device (Device) - id of the device

Returns: Number (Number) - current pressure level

PhoneIoT.getProximity(device: Device)

Gets the current output of the proximity (distance) sensor, measured in cm. Phones typically have this sensor for turning off the display when you put it to your ear, but tablets typically do not. In any case, the distances are not typically very long, and some devices only have binary (near/far) sensors.

Sensor name: proximity

Message fields: distance, device

Arguments:

device: Device (Device) - id of the device

Returns: Number (Number) - current proximity sensor output

PhoneIoT.getRelativeHumidity(device: Device)

Gets the relative humidity as a percent.

Sensor name: humidity

Message fields: humidity, device

Arguments:

device: Device (Device) - id of the device

Returns: Number (Number) - current relative humidity

PhoneIoT.getStepCount(device: Device)

Gets the current step count from the device’s step counter sensor. Not all devices have a step counter sensor, but you can manually emulate one by using the accelerometer.

Sensor name: stepCount

Message fields: count, device

Arguments:

device: Device (Device) - id of the device

Returns: Number (Number) - current step count

PhoneIoT.getTemperature(device: Device)

Gets the current ambient temperature around the device in Celsius.

Sensor name: temperature

Message fields: temp, device

Arguments:

device: Device (Device) - id of the device

Returns: Number (Number) - current temperature