Commit 8297e6f6 authored by David Boddie's avatar David Boddie

Merge branch '106-add-application-level-documentation-for-the-inertial-module' into 'master'

Add documentation for the inertial module

See merge request !388
parents 045c68cb cec84dce
Pipeline #53006 canceled with stages
......@@ -13,6 +13,7 @@ Librem 5 stack and includes links to useful external resources.
Software_Reference/Linux_Kernel
Software_Reference/Environments
Software_Reference/Wayland
Software_Reference/Sensors
Software_Reference/Storage_Devices
Summary
......
.. _software_reference_sensors:
Sensors
=======
The Librem 5 is equipped with a variety of sensors to measure the physical environment of the phone. Some of these, such as the accelerometer and proximity sensor, are accessible to user applications -- see the :ref:`devkit_howto_inertial_module` and :ref:`devkit_howto_proximity_sensor` guides.
Other sensors, such as temperature sensors, are used by the system software to ensure that the phone functions within expected parameters.
.. toctree::
:maxdepth: 1
Sensors/Inertial_Module
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. The system-level interfaces to this peripheral are described below.
See :ref:`this guide <devkit_howto_inertial_module>` for basic information about accessing sensors from user space.
.. contents::
:local:
Overview
--------
The sensor hardware is accessed via |I2C| bus 2 by a kernel module which exports data from the sensors as files in the ``/sys`` directory structure. Daemons and other middleware components, such as `iio-sensor-proxy`_ access these files to present information and services to applications that require sensor data.
Device Files
------------
The accelerometer, gyroscope and magnetometer are exposed to user space in the sys file system, exported via the ``/sys`` directory.
Each sensor device is exposed as a subdirectory of ``/sys/bus/iio/devices`` with a name following the scheme ``iio:device<n>`` where ``<n>`` is the numeric index of the device.
The index of any given sensor may not strictly defined in advance, or may be subject to change, so it may be useful to inspect the name of each device. This is exported in the ``name`` file in each device directory.
Each device directory also contains files that can be used to read the properties of the sensor. These are described in the `Linux kernel sysfs interface to IIO devices`_ file in the kernel documentation.
|I2C| Bus
---------
The inertial module exposes a magnetometer via address ``0x1e`` on |I2C| bus 2, and both an accelerometer and gyroscope via address ``0x6a`` on the same bus. Each device contains a set of registers that can be accessed by their addresses in that device.
Normally, when the kernel modules are loaded, the |I2C| addresses are not available to user space programs. However, when the modules are not loaded, you can use the ``i2cget`` and ``i2cset`` tools to interact with them.
The ``i2cdetect`` tool can be used to check for availability of the sensors on the |I2C| bus. The following shows the output when the devices are available:
.. code:: bash
purism@pureos:~$ sudo i2cdetect -y 1
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- 1e --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- UU --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: 60 -- -- -- -- -- -- -- -- -- UU -- -- -- -- --
70: -- -- -- -- -- -- -- --
If they are in use, ``UU`` will be shown instead of the device addresses.
.. include:: /links.txt
......@@ -139,6 +139,7 @@
.. _`linux-emcraft issue 22`: https://source.puri.sm/Librem5/linux-emcraft/issues/22
.. _`linux-emcraft issue 27`: https://source.puri.sm/Librem5/linux-emcraft/issues/27
.. _`linux-next repository`: https://source.puri.sm/Librem5/linux-next/
.. _`Linux kernel sysfs interface to IIO devices`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/ABI/testing/sysfs-bus-iio
.. _`Meson`: https://mesonbuild.com/
.. _`Meson Localisation guide`: https://mesonbuild.com/Localisation.html
.. _`ModemManager`: https://www.freedesktop.org/wiki/Software/ModemManager/
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment