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 :func:`PhoneIoT.listenToSensors`. The sensor names and message fields are provided for each sensor. RPCS ---- .. function:: 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 .. function:: 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 .. function:: PhoneIoT.getCompassCardinalDirection(device: Device) Equivalent to :func:`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 .. function:: 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 .. function:: PhoneIoT.getCompassHeading(device: Device) Gets the current compass heading from the device. This is similar to :func:`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) .. function:: 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 .. function:: 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 :func:`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) .. function:: 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 :func:`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 .. function:: 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 .. function:: 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 .. function:: 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 :func:`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 .. function:: 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 .. function:: 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 .. function:: 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 .. function:: 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 .. function:: 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 .. function:: 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 .. function:: 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 .. function:: 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 .. function:: 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