Sensors

Accelerometer, Gyroscope, Magnetometer, and Barometer stream readings as async iterators, in the same units and axes on every platform. See the Sensors guide for setup and platform differences.

Motion and pressure sensors, as async iterators.

Enable it in pythonnative.toml:

[plugins]
use = ["sensors"]

[permissions]
motion = "Measure air pressure for your altitude."

iOS's CMAltimeter, behind Barometer, needs NSMotionUsageDescription: without it the app is terminated at the call. The plugin compiles that API in, so the build requires the motion line even if you only use the accelerometer, which never prompts.

Every platform reports the same units and axes:

Sensor	Unit	At rest, flat on a table, screen up
Accelerometer	m/s^2, including gravity	z is about +9.81
Gyroscope	rad/s, counterclockwise positive	all about 0
Magnetometer	microtesla	depends on where you are
Barometer	hPa	about 1013 at sea level

Axes are the device's: x to the right of the screen, y to its top, and z out of its face.

Example

from pythonnative.sensors import Accelerometer

async def watch_motion() -> None:
    if not Accelerometer.is_available():
        return
    async for reading in Accelerometer.readings(hz=30):
        print(reading.x, reading.y, reading.z)

Classes:

Name	Description
Vector	One three-axis reading.
Pressure	One barometer reading.
Accelerometer	Acceleration in m/s^2, including gravity.
Gyroscope	Rotation rate in rad/s around each axis, counterclockwise positive.
Magnetometer	Magnetic field in microtesla.
Barometer	Air pressure in hPa.

Vector dataclass

Vector(x: float, y: float, z: float, timestamp: float)

One three-axis reading.

Attributes:

Name	Type	Description
x	float	Along the device's right edge.
y	float	Along the device's top edge.
z	float	Out of the device's face.
timestamp	float	Unix seconds when the sensor took the reading.

Pressure dataclass

Pressure(hpa: float, timestamp: float)

One barometer reading.

Attributes:

Name	Type	Description
hpa	float	Air pressure in hectopascals.
timestamp	float	Unix seconds when the sensor took the reading.

Accelerometer

Bases: _VectorSensor

Acceleration in m/s^2, including gravity.

A device at rest, flat on a table with its screen up, reads z of about +9.81: the sensor reports the table pushing up. Android and the W3C DeviceMotionEvent work this way natively. CoreMotion reports g with the opposite sign, so iOS multiplies by -9.80665.

Gyroscope

Bases: _VectorSensor

Rotation rate in rad/s around each axis, counterclockwise positive.

CoreMotion and Android already agree on this. The browser reports degrees per second, so the preview converts them.

Magnetometer

Bases: _VectorSensor

Magnetic field in microtesla.

iOS reports the raw field, which includes the device's own bias of up to hundreds of microtesla. Android reports a calibrated field, around 25 to 65 microtesla. Don't build a compass on the raw value without calibrating it. Browsers have no magnetometer API, so it's unavailable in the preview.

Barometer

Air pressure in hPa.

iOS reads CMAltimeter, which reports kilopascals (multiplied by 10 here), delivers about once a second regardless of hz, and may ask the user for Motion and Fitness permission on first use. Android delivers at the requested rate where the hardware can. Browsers have no barometer API, so it's unavailable in the preview.

Methods:

Name	Description
is_available	Whether this device has a barometer.
readings	Yield readings until the iteration ends, which stops the sensor.

is_available staticmethod

is_available() -> bool

Whether this device has a barometer.

Returns:

Type	Description
bool	True when readings can start. Always False on the iOS
bool	simulator, which has no sensors.

readings async staticmethod

readings(*, hz: float = 30) -> AsyncIterator[Pressure]

Yield readings until the iteration ends, which stops the sensor.

Parameters:

Name	Type	Description	Default
hz	float	Readings per second to ask for, above 0 and at most 100. iOS ignores it and delivers about once a second.	30

Yields:

Type	Description
AsyncIterator[Pressure]	One Pressure per reading.

Raises:

Type	Description
ValueError	If hz is out of range.
NativeModuleError	With the code unavailable when the device has no barometer, permission_denied when the user refuses on iOS, or plugin_not_enabled when sensors isn't in the build.