xref: /linux/Documentation/iio/adxl313.rst (revision 0d5ec7919f3747193f051036b2301734a4b5e1d6) 
1.. SPDX-License-Identifier: GPL-2.0
2
3===============
4ADXL313 driver
5===============
6
7This driver supports Analog Device's ADXL313 on SPI/I2C bus.
8
91. Supported devices
10====================
11
12* `ADXL313 <https://www.analog.com/ADXL313>`_
13
14The ADXL313is a low noise density, low power, 3-axis accelerometer with
15selectable measurement ranges. The ADXL313 supports the ±0.5 g, ±1 g, ±2 g and
16±4 g ranges.
17
182. Device attributes
19====================
20
21Accelerometer measurements are always provided.
22
23Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
24where X is the IIO index of the device. Under these folders reside a set of
25device files, depending on the characteristics and features of the hardware
26device in questions. These files are consistently generalized and documented in
27the IIO ABI documentation.
28
29The following tables show the adxl313 related device files, found in the
30specific 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
60The 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
84The default coupling is DC coupled events. In this case the threshold will
85be 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,
87i.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.
89This means in particular ``ACTIVITY`` can also be linked to ``INACTIVITY_AC``
90and vice versa, without problem.
91
92Note here, that ``ACTIVITY`` and ``ACTIVITY_AC`` are mutually exclusive. This
93means, that the most recent configuration will be set. For instance, if
94``ACTIVITY`` is enabled, and ``ACTIVITY_AC`` will be enabled, the sensor driver
95will have ``ACTIVITY`` disabled, but ``ACTIVITY_AC`` enabled. The same is valid
96for inactivity. In case of turning off an event, it has to match to what is
97actually enabled, i.e. enabling ``ACTIVITY_AC`` and then disabling ``ACTIVITY``
98is simply ignored as it is already disabled. Or, as if it was any other not
99enabled event, too.
100
101Channels processed values
102-------------------------
103
104A channel value can be read from its _raw attribute. The value returned is the
105raw value as reported by the devices. To get the processed value of the channel,
106apply the following formula:
107
108.. code-block::
109
110        processed value = (_raw + _offset) * _scale
111
112Where _offset and _scale are device attributes. If no _offset attribute is
113present, simply assume its value is 0.
114
115The ADXL313 driver offers data for a single types of channels, the table below
116shows the measurement units for the processed value, which are defined by the
117IIO framework:
118
119+-------------------------------------+---------------------------+
120| Channel type                        | Measurement unit          |
121+-------------------------------------+---------------------------+
122| Acceleration on X, Y, and Z axis    | Meters per Second squared |
123+-------------------------------------+---------------------------+
124
125Usage examples
126--------------
127
128Show device name:
129
130.. code-block:: bash
131
132        root:/sys/bus/iio/devices/iio:device0> cat name
133        adxl313
134
135Show 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
148The 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
154Set calibration offset for accelerometer channels. Note, that the calibration
155will 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
166Set 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
1793. Device buffers and triggers
180==============================
181
182This driver supports IIO buffers.
183
184All devices support retrieving the raw acceleration measurements using buffers.
185
186Usage examples
187--------------
188
189Select 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
197Set 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
203Enable buffer readings:
204
205.. code-block:: bash
206
207        root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable
208
209Obtain 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
228Enabling 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
243Disabling 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
251Enabling 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
267Now, 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
286Note, when AC coupling is in place, the event type will be of ``mag_adaptive``.
287AC- or DC-coupled (the default) events are used similarly.
288
2894. IIO Interfacing Tools
290========================
291
292See Documentation/iio/iio_tools.rst for the description of the available IIO
293interfacing tools.
294