tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: iio: add ADXL313 accelerometer
Add documentation for the ADXL313 accelerometer driver.
Reviewed-by: Andy Shevchenko <andy@kernel.org>
Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Link: https://patch.msgid.link/20250702230819.19353-9-l.rubusch@gmail.com
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
authored by
Lothar Rubusch
and committed by
Jonathan Cameron
0755fd55
56d080b9
+294
+293
Documentation/iio/adxl313.rst
+293
Documentation/iio/adxl313.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
===============
4
+
ADXL313 driver
5
+
===============
6
+
7
+
This driver supports Analog Device's ADXL313 on SPI/I2C bus.
8
+
9
+
1. Supported devices
10
+
====================
11
+
12
+
* `ADXL313 <https://www.analog.com/ADXL313>`_
13
+
14
+
The ADXL313is a low noise density, low power, 3-axis accelerometer with
15
+
selectable measurement ranges. The ADXL313 supports the ±0.5 g, ±1 g, ±2 g and
16
+
±4 g ranges.
17
+
18
+
2. Device attributes
19
+
====================
20
+
21
+
Accelerometer measurements are always provided.
22
+
23
+
Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
24
+
where X is the IIO index of the device. Under these folders reside a set of
25
+
device files, depending on the characteristics and features of the hardware
26
+
device in questions. These files are consistently generalized and documented in
27
+
the IIO ABI documentation.
28
+
29
+
The following tables show the adxl313 related device files, found in the
30
+
specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.
31
+
32
+
+---------------------------------------------------+----------------------------------------------------------+
33
+
| 3-Axis Accelerometer related device files | Description |
34
+
+---------------------------------------------------+----------------------------------------------------------+
35
+
| in_accel_scale | Scale for the accelerometer channels. |
36
+
+---------------------------------------------------+----------------------------------------------------------+
37
+
| in_accel_x_calibbias | Calibration offset for the X-axis accelerometer channel. |
38
+
+---------------------------------------------------+----------------------------------------------------------+
39
+
| in_accel_x_raw | Raw X-axis accelerometer channel value. |
40
+
+---------------------------------------------------+----------------------------------------------------------+
41
+
| in_accel_y_calibbias | y-axis acceleration offset correction |
42
+
+---------------------------------------------------+----------------------------------------------------------+
43
+
| in_accel_y_raw | Raw Y-axis accelerometer channel value. |
44
+
+---------------------------------------------------+----------------------------------------------------------+
45
+
| in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. |
46
+
+---------------------------------------------------+----------------------------------------------------------+
47
+
| in_accel_z_raw | Raw Z-axis accelerometer channel value. |
48
+
+---------------------------------------------------+----------------------------------------------------------+
49
+
50
+
+---------------------------------------+----------------------------------------------+
51
+
| Miscellaneous device files | Description |
52
+
+---------------------------------------+----------------------------------------------+
53
+
| name | Name of the IIO device. |
54
+
+---------------------------------------+----------------------------------------------+
55
+
| in_accel_sampling_frequency | Currently selected sample rate. |
56
+
+---------------------------------------+----------------------------------------------+
57
+
| in_accel_sampling_frequency_available | Available sampling frequency configurations. |
58
+
+---------------------------------------+----------------------------------------------+
59
+
60
+
The iio event related settings, found in ``/sys/bus/iio/devices/iio:deviceX/events``.
61
+
62
+
+---------------------------------------------------+----------------------------------------------------------+
63
+
| in_accel_mag_adaptive_falling_period | AC coupled inactivity time. |
64
+
+---------------------------------------------------+----------------------------------------------------------+
65
+
| in_accel_mag_adaptive_falling_value | AC coupled inactivity threshold. |
66
+
+---------------------------------------------------+----------------------------------------------------------+
67
+
| in_accel_mag_adaptive_rising_value | AC coupled activity threshold. |
68
+
+---------------------------------------------------+----------------------------------------------------------+
69
+
| in_accel_mag_falling_period | Inactivity time. |
70
+
+---------------------------------------------------+----------------------------------------------------------+
71
+
| in_accel_mag_falling_value | Inactivity threshold. |
72
+
+---------------------------------------------------+----------------------------------------------------------+
73
+
| in_accel_mag_rising_value | Activity threshold. |
74
+
+---------------------------------------------------+----------------------------------------------------------+
75
+
| in_accel_x\&y\&z_mag_adaptive_falling_en | Enable or disable AC coupled inactivity events. |
76
+
+---------------------------------------------------+----------------------------------------------------------+
77
+
| in_accel_x\|y\|z_mag_adaptive_rising_en | Enable or disable AC coupled activity events. |
78
+
+---------------------------------------------------+----------------------------------------------------------+
79
+
| in_accel_x\&y\&z_mag_falling_en | Enable or disable inactivity events. |
80
+
+---------------------------------------------------+----------------------------------------------------------+
81
+
| in_accel_x\|y\|z_mag_rising_en | Enable or disable activity events. |
82
+
+---------------------------------------------------+----------------------------------------------------------+
83
+
84
+
The default coupling is DC coupled events. In this case the threshold will
85
+
be in place as such, where for the AC coupled case an adaptive threshold
86
+
(described in the datasheet) will be applied by the sensor. In general activity,
87
+
i.e. ``ACTIVITY`` or ``ACTIVITY_AC`` and inactivity i.e. ``INACTIVITY`` or
88
+
``INACTIVITY_AC``, will be linked with auto-sleep enabled when both are enabled.
89
+
This means in particular ``ACTIVITY`` can also be linked to ``INACTIVITY_AC``
90
+
and vice versa, without problem.
91
+
92
+
Note here, that ``ACTIVITY`` and ``ACTIVITY_AC`` are mutually exclusive. This
93
+
means, that the most recent configuration will be set. For instance, if
94
+
``ACTIVITY`` is enabled, and ``ACTIVITY_AC`` will be enabled, the sensor driver
95
+
will have ``ACTIVITY`` disabled, but ``ACTIVITY_AC`` enabled. The same is valid
96
+
for inactivity. In case of turning off an event, it has to match to what is
97
+
actually enabled, i.e. enabling ``ACTIVITY_AC`` and then disabling ``ACTIVITY``
98
+
is simply ignored as it is already disabled. Or, as if it was any other not
99
+
enabled event, too.
100
+
101
+
Channels processed values
102
+
-------------------------
103
+
104
+
A channel value can be read from its _raw attribute. The value returned is the
105
+
raw value as reported by the devices. To get the processed value of the channel,
106
+
apply the following formula:
107
+
108
+
.. code-block::
109
+
110
+
processed value = (_raw + _offset) * _scale
111
+
112
+
Where _offset and _scale are device attributes. If no _offset attribute is
113
+
present, simply assume its value is 0.
114
+
115
+
The ADXL313 driver offers data for a single types of channels, the table below
116
+
shows the measurement units for the processed value, which are defined by the
117
+
IIO framework:
118
+
119
+
+-------------------------------------+---------------------------+
120
+
| Channel type | Measurement unit |
121
+
+-------------------------------------+---------------------------+
122
+
| Acceleration on X, Y, and Z axis | Meters per Second squared |
123
+
+-------------------------------------+---------------------------+
124
+
125
+
Usage examples
126
+
--------------
127
+
128
+
Show device name:
129
+
130
+
.. code-block:: bash
131
+
132
+
root:/sys/bus/iio/devices/iio:device0> cat name
133
+
adxl313
134
+
135
+
Show accelerometer channels value:
136
+
137
+
.. code-block:: bash
138
+
139
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
140
+
2
141
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
142
+
-57
143
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
144
+
2
145
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
146
+
0.009576806
147
+
148
+
The accelerometer values will be:
149
+
150
+
- X-axis acceleration = in_accel_x_raw * in_accel_scale = 0.0191536 m/s^2
151
+
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = -0.5458779 m/s^2
152
+
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 0.0191536 m/s^2
153
+
154
+
Set calibration offset for accelerometer channels. Note, that the calibration
155
+
will be rounded according to the graduation of LSB units:
156
+
157
+
.. code-block:: bash
158
+
159
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
160
+
0
161
+
162
+
root:/sys/bus/iio/devices/iio:device0> echo 50 > in_accel_x_calibbias
163
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
164
+
48
165
+
166
+
Set sampling frequency:
167
+
168
+
.. code-block:: bash
169
+
170
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency
171
+
100.000000
172
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency_available
173
+
6.250000 12.500000 25.000000 50.000000 100.000000 200.000000 400.000000 800.000000 1600.000000 3200.000000
174
+
175
+
root:/sys/bus/iio/devices/iio:device0> echo 400 > in_accel_sampling_frequency
176
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency
177
+
400.000000
178
+
179
+
3. Device buffers and triggers
180
+
==============================
181
+
182
+
This driver supports IIO buffers.
183
+
184
+
All devices support retrieving the raw acceleration measurements using buffers.
185
+
186
+
Usage examples
187
+
--------------
188
+
189
+
Select channels for buffer read:
190
+
191
+
.. code-block:: bash
192
+
193
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_x_en
194
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_y_en
195
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_z_en
196
+
197
+
Set the number of samples to be stored in the buffer:
198
+
199
+
.. code-block:: bash
200
+
201
+
root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length
202
+
203
+
Enable buffer readings:
204
+
205
+
.. code-block:: bash
206
+
207
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable
208
+
209
+
Obtain buffered data:
210
+
211
+
.. code-block:: bash
212
+
213
+
root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0
214
+
...
215
+
000000d0 01 fc 31 00 c7 ff 03 fc 31 00 c7 ff 04 fc 33 00 |..1.....1.....3.|
216
+
000000e0 c8 ff 03 fc 32 00 c5 ff ff fc 32 00 c7 ff 0a fc |....2.....2.....|
217
+
000000f0 30 00 c8 ff 06 fc 33 00 c7 ff 01 fc 2f 00 c8 ff |0.....3...../...|
218
+
00000100 02 fc 32 00 c6 ff 04 fc 33 00 c8 ff 05 fc 33 00 |..2.....3.....3.|
219
+
00000110 ca ff 02 fc 31 00 c7 ff 02 fc 30 00 c9 ff 09 fc |....1.....0.....|
220
+
00000120 35 00 c9 ff 08 fc 35 00 c8 ff 02 fc 31 00 c5 ff |5.....5.....1...|
221
+
00000130 03 fc 32 00 c7 ff 04 fc 32 00 c7 ff 02 fc 31 00 |..2.....2.....1.|
222
+
00000140 c7 ff 08 fc 30 00 c7 ff 02 fc 32 00 c5 ff ff fc |....0.....2.....|
223
+
00000150 31 00 c5 ff 04 fc 31 00 c8 ff 03 fc 32 00 c8 ff |1.....1.....2...|
224
+
00000160 01 fc 31 00 c7 ff 05 fc 31 00 c3 ff 04 fc 31 00 |..1.....1.....1.|
225
+
00000170 c5 ff 04 fc 30 00 c7 ff 03 fc 31 00 c9 ff 03 fc |....0.....1.....|
226
+
...
227
+
228
+
Enabling activity detection:
229
+
230
+
.. code-block:: bash
231
+
232
+
root:/sys/bus/iio/devices/iio:device0> echo 1.28125 > ./events/in_accel_mag_rising_value
233
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\|y\|z_mag_rising_en
234
+
235
+
root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
236
+
Found IIO device with name adxl313 with device number 0
237
+
<only while moving the sensor>
238
+
Event: time: 1748795762298351281, type: accel(x|y|z), channel: 0, evtype: mag, direction: rising
239
+
Event: time: 1748795762302653704, type: accel(x|y|z), channel: 0, evtype: mag, direction: rising
240
+
Event: time: 1748795762304340726, type: accel(x|y|z), channel: 0, evtype: mag, direction: rising
241
+
...
242
+
243
+
Disabling activity detection:
244
+
245
+
.. code-block:: bash
246
+
247
+
root:/sys/bus/iio/devices/iio:device0> echo 0 > ./events/in_accel_x\|y\|z_mag_rising_en
248
+
root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
249
+
<nothing>
250
+
251
+
Enabling inactivity detection:
252
+
253
+
.. code-block:: bash
254
+
255
+
root:/sys/bus/iio/devices/iio:device0> echo 1.234375 > ./events/in_accel_mag_falling_value
256
+
root:/sys/bus/iio/devices/iio:device0> echo 5 > ./events/in_accel_mag_falling_period
257
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\&y\&z_mag_falling_en
258
+
259
+
root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
260
+
Found IIO device with name adxl313 with device number 0
261
+
Event: time: 1748796324115962975, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
262
+
Event: time: 1748796329329981772, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
263
+
Event: time: 1748796334543399706, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
264
+
...
265
+
<every 5s now indicates inactivity>
266
+
267
+
Now, enabling activity, e.g. the AC coupled counter-part ``ACTIVITY_AC``
268
+
269
+
.. code-block:: bash
270
+
271
+
root:/sys/bus/iio/devices/iio:device0> echo 1.28125 > ./events/in_accel_mag_rising_value
272
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\|y\|z_mag_rising_en
273
+
274
+
root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
275
+
Found IIO device with name adxl313 with device number 0
276
+
<some activity with the sensor>
277
+
Event: time: 1748796880354686777, type: accel(x|y|z), channel: 0, evtype: mag_adaptive, direction: rising
278
+
<5s of inactivity, then>
279
+
Event: time: 1748796885543252017, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
280
+
<some other activity detected by accelerating the sensor>
281
+
Event: time: 1748796887756634678, type: accel(x|y|z), channel: 0, evtype: mag_adaptive, direction: rising
282
+
<again, 5s of inactivity>
283
+
Event: time: 1748796892964368352, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
284
+
<stays like this until next activity in auto-sleep>
285
+
286
+
Note, when AC coupling is in place, the event type will be of ``mag_adaptive``.
287
+
AC- or DC-coupled (the default) events are used similarly.
288
+
289
+
4. IIO Interfacing Tools
290
+
========================
291
+
292
+
See Documentation/iio/iio_tools.rst for the description of the available IIO
293
+
interfacing tools.