Inertial Module

The Librem 5 development board is equipped with a collection of sensors provided by the LSM9DS1 inertial module, including a accelerometer, gyroscope and magnetometer. At a low level, these sensors can be accessed programmatically via messages sent to the relevant addresses on the appropriate I2C bus. Applications will typically receive sensor information by accessing the appropriate system D-Bus interface.

This guide provides a basic overview of the commands that can be used to access each device; first via the D-Bus interface, then using the I2C bus.

D-Bus Interface

The sensors are exposed to applications via the net.hadess.SensorProxy service on the system D-Bus. This is provided by the iio-sensor-proxy service.

Information from the sensors can be obtained by querying the interface provided by the D-Bus service, calling methods to access devices and reading their properties.

Preparations

If the iio-sensor-proxy daemon is not already running, start it from the command line in the following way:

systemctl start iio-sensor-proxy

Check that it is running with this command:

systemctl status iio-sensor-proxy

This should include useful information to help diagnose problems if the service does not start.

Introspecting the D-Bus Object

It is useful to get an overview of the properties and methods that the service exposes via D-Bus. Use the gdbus tool from the command line to discover these:

gdbus introspect --system --dest net.hadess.SensorProxy \
                          --object-path /net/hadess/SensorProxy

Monitor the Sensor

It can be useful to quickly check that the sensors are working by running the monitor-sensor tool, as shown in this shell output:

purism@pureos:-$ monitor-sensor
    Waiting for iio-sensor-proxy to appear
+++ iio-sensor-proxy appeared
=== Has accelerometer (orientation: bottom-up)
=== Has ambient light sensor (value: 0.000000, unit: lux)
=== No proximity sensor

The tool outputs information from all sensors. By filtering the output from monitor-sensor you can see changes to the sensor you are interested in.

purism@pureos:~$ monitor-sensor | grep Accelerometer
    Accelerometer orientation changed: bottom-up
    Accelerometer orientation changed: right-up
    Accelerometer orientation changed: left-up
    Accelerometer orientation changed: normal

This provides verification that the sensor is reporting changes via the D-Bus interface.

Reading the Device Orientation

Using the gdbus tool again, first check that the accelerometer is available to be read:

gdbus call --system --dest net.hadess.SensorProxy \
                    --object-path /net/hadess/SensorProxy \
                    --method org.freedesktop.DBus.Properties.Get \
                             net.hadess.SensorProxy HasAccelerometer

If it returns (<true>,) then you can claim the sensor:

gdbus call --system --dest net.hadess.SensorProxy \
                    --object-path /net/hadess/SensorProxy \
                    --method net.hadess.SensorProxy.ClaimAccelerometer

This will cause the AccelerometerOrientation property to be updated:

gdbus call --system --dest net.hadess.SensorProxy \
                    --object-path /net/hadess/SensorProxy \
                    --method org.freedesktop.DBus.Properties.Get \
                    net.hadess.SensorProxy AccelerometerOrientation

Finally, release the sensor to stop the service from polling the device:

gdbus call --system --dest net.hadess.SensorProxy \
                    --object-path /net/hadess/SensorProxy \
                    --method net.hadess.SensorProxy.ReleaseAccelerometer

This can also be performed using the Gio.DBusProxy class – see the GNOME API Reference for further information.