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
, andz
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 returnsN
,E
,S
, orW
.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
, orNW
. 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 updown
- the device is face downvertical
- the device is uprightupside down
- the device is vertical, but upside downleft
- 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 and1.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 is101.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