Commit 1253ed9c authored by David Boddie's avatar David Boddie
Browse files

Add basic information about system interfaces to the inertial module

parent a241bbce
......@@ -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. Others, 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 is described below.
.. contents::
:local:
See :ref:`this guide <devkit_howto_inertial_module>` for basic information about accessing sensors from user space.
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`` and ``/dev`` directory structures. 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`` and ``/dev`` directories.
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. Although each subdirectory is actually a symbolic link to a device directory in the ``/dev`` directory structure it is easier to locate devices in ``/sys``.
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
......@@ -138,6 +138,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