Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: iio: add documentation for adis16480 driver
Add documentation for adis16480 driver which describes the driver
device files and shows how the user may use the ABI for various
scenarios (configuration, measurement, etc.).
Signed-off-by: Ramona Gradinariu <ramona.gradinariu@analog.com>
Reviewed-by: Nuno Sa <nuno.sa@analog.com>
Link: https://lore.kernel.org/r/20240528142409.239187-7-ramona.gradinariu@analog.com
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
authored by
Ramona Gradinariu
and committed by
Jonathan Cameron
ef60f9ca
9bc8b4d2
+444
+443
Documentation/iio/adis16480.rst
+443
Documentation/iio/adis16480.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
================
4
+
ADIS16480 driver
5
+
================
6
+
7
+
This driver supports Analog Device's IMUs on SPI bus.
8
+
9
+
1. Supported devices
10
+
====================
11
+
12
+
* `ADIS16375 <https://www.analog.com/ADIS16375>`_
13
+
* `ADIS16480 <https://www.analog.com/ADIS16480>`_
14
+
* `ADIS16485 <https://www.analog.com/ADIS16485>`_
15
+
* `ADIS16488 <https://www.analog.com/ADIS16488>`_
16
+
* `ADIS16490 <https://www.analog.com/ADIS16490>`_
17
+
* `ADIS16495 <https://www.analog.com/ADIS16495>`_
18
+
* `ADIS16497 <https://www.analog.com/ADIS16497>`_
19
+
* `ADIS16545 <https://www.analog.com/ADIS16545>`_
20
+
* `ADIS16547 <https://www.analog.com/ADIS16547>`_
21
+
22
+
Each supported device is a complete inertial system that includes a triaxial
23
+
gyroscope and a triaxial accelerometer. Each inertial sensor in device combines
24
+
with signal conditioning that optimizes dynamic performance. The factory
25
+
calibration characterizes each sensor for sensitivity, bias, and alignment. As
26
+
a result, each sensor has its own dynamic compensation formulas that provide
27
+
accurate sensor measurements.
28
+
29
+
2. Device attributes
30
+
====================
31
+
32
+
Accelerometer, gyroscope measurements are always provided. Furthermore, the
33
+
driver offers the capability to retrieve the delta angle and the delta velocity
34
+
measurements computed by the device.
35
+
36
+
The delta angle measurements represent a calculation of angular displacement
37
+
between each sample update, while the delta velocity measurements represent a
38
+
calculation of linear velocity change between each sample update.
39
+
40
+
Finally, temperature data are provided which show a coarse measurement of
41
+
the temperature inside of the IMU device. This data is most useful for
42
+
monitoring relative changes in the thermal environment.
43
+
44
+
ADIS16480 and ADIS16488 also provide access to barometric pressure data and
45
+
triaxial magnetometer measurements.
46
+
47
+
Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
48
+
where X is the IIO index of the device. Under these folders reside a set of
49
+
device files, depending on the characteristics and features of the hardware
50
+
device in questions. These files are consistently generalized and documented in
51
+
the IIO ABI documentation.
52
+
53
+
The following tables show the adis16480 related device files, found in the
54
+
specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.
55
+
56
+
**Available only for ADIS16480 and ADIS16488:**
57
+
58
+
+------------------------------------------+---------------------------------------------------------+
59
+
| 3-Axis Magnetometer related device files | Description |
60
+
+------------------------------------------+---------------------------------------------------------+
61
+
| in_magn_scale | Scale for the magnetometer channels. |
62
+
+------------------------------------------+---------------------------------------------------------+
63
+
| in_magn_x_calibbias | Calibration offset for the X-axis magnetometer channel. |
64
+
+------------------------------------------+---------------------------------------------------------+
65
+
| in_magn_x_filter_low_pass_3db_frequency | Bandwidth for the X-axis magnetometer channel. |
66
+
+------------------------------------------+---------------------------------------------------------+
67
+
| in_magn_x_raw | Raw X-axis magnetometer channel value. |
68
+
+------------------------------------------+---------------------------------------------------------+
69
+
| in_magn_y_calibbias | Calibration offset for the Y-axis magnetometer channel. |
70
+
+------------------------------------------+---------------------------------------------------------+
71
+
| in_magn_y_filter_low_pass_3db_frequency | Bandwidth for the Y-axis magnetometer channel. |
72
+
+------------------------------------------+---------------------------------------------------------+
73
+
| in_magn_y_raw | Raw Y-axis magnetometer channel value. |
74
+
+------------------------------------------+---------------------------------------------------------+
75
+
| in_magn_z_calibbias | Calibration offset for the Z-axis magnetometer channel. |
76
+
+------------------------------------------+---------------------------------------------------------+
77
+
| in_magn_z_filter_low_pass_3db_frequency | Bandwidth for the Z-axis magnetometer channel. |
78
+
+------------------------------------------+---------------------------------------------------------+
79
+
| in_magn_z_raw | Raw Z-axis magnetometer channel value. |
80
+
+------------------------------------------+---------------------------------------------------------+
81
+
82
+
+------------------------------------------+-----------------------------------------------------+
83
+
| Barometric pressure sensor related files | Description |
84
+
+------------------------------------------+-----------------------------------------------------+
85
+
| in_pressure0_calibbias | Calibration offset for barometric pressure channel. |
86
+
+------------------------------------------+-----------------------------------------------------+
87
+
| in_pressure0_raw | Raw barometric pressure channel value. |
88
+
+------------------------------------------+-----------------------------------------------------+
89
+
| in_pressure0_scale | Scale for the barometric pressure sensor channel. |
90
+
+------------------------------------------+-----------------------------------------------------+
91
+
92
+
**Available for all supported devices:**
93
+
94
+
+-------------------------------------------+----------------------------------------------------------+
95
+
| 3-Axis Accelerometer related device files | Description |
96
+
+-------------------------------------------+----------------------------------------------------------+
97
+
| in_accel_scale | Scale for the accelerometer channels. |
98
+
+-------------------------------------------+----------------------------------------------------------+
99
+
| in_accel_x_calibbias | Calibration offset for the X-axis accelerometer channel. |
100
+
+-------------------------------------------+----------------------------------------------------------+
101
+
| in_accel_x_calibscale | Calibration scale for the X-axis accelerometer channel. |
102
+
+-------------------------------------------+----------------------------------------------------------+
103
+
| in_accel_x_filter_low_pass_3db_frequency | Bandwidth for the X-axis accelerometer channel. |
104
+
+-------------------------------------------+----------------------------------------------------------+
105
+
| in_accel_x_raw | Raw X-axis accelerometer channel value. |
106
+
+-------------------------------------------+----------------------------------------------------------+
107
+
| in_accel_y_calibbias | Calibration offset for the Y-axis accelerometer channel. |
108
+
+-------------------------------------------+----------------------------------------------------------+
109
+
| in_accel_y_calibscale | Calibration scale for the Y-axis accelerometer channel. |
110
+
+-------------------------------------------+----------------------------------------------------------+
111
+
| in_accel_y_filter_low_pass_3db_frequency | Bandwidth for the Y-axis accelerometer channel. |
112
+
+-------------------------------------------+----------------------------------------------------------+
113
+
| in_accel_y_raw | Raw Y-axis accelerometer channel value. |
114
+
+-------------------------------------------+----------------------------------------------------------+
115
+
| in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. |
116
+
+-------------------------------------------+----------------------------------------------------------+
117
+
| in_accel_z_calibscale | Calibration scale for the Z-axis accelerometer channel. |
118
+
+-------------------------------------------+----------------------------------------------------------+
119
+
| in_accel_z_filter_low_pass_3db_frequency | Bandwidth for the Z-axis accelerometer channel. |
120
+
+-------------------------------------------+----------------------------------------------------------+
121
+
| in_accel_z_raw | Raw Z-axis accelerometer channel value. |
122
+
+-------------------------------------------+----------------------------------------------------------+
123
+
| in_deltavelocity_scale | Scale for delta velocity channels. |
124
+
+-------------------------------------------+----------------------------------------------------------+
125
+
| in_deltavelocity_x_raw | Raw X-axis delta velocity channel value. |
126
+
+-------------------------------------------+----------------------------------------------------------+
127
+
| in_deltavelocity_y_raw | Raw Y-axis delta velocity channel value. |
128
+
+-------------------------------------------+----------------------------------------------------------+
129
+
| in_deltavelocity_z_raw | Raw Z-axis delta velocity channel value. |
130
+
+-------------------------------------------+----------------------------------------------------------+
131
+
132
+
+--------------------------------------------+------------------------------------------------------+
133
+
| 3-Axis Gyroscope related device files | Description |
134
+
+--------------------------------------------+------------------------------------------------------+
135
+
| in_anglvel_scale | Scale for the gyroscope channels. |
136
+
+--------------------------------------------+------------------------------------------------------+
137
+
| in_anglvel_x_calibbias | Calibration offset for the X-axis gyroscope channel. |
138
+
+--------------------------------------------+------------------------------------------------------+
139
+
| in_anglvel_x_calibscale | Calibration scale for the X-axis gyroscope channel. |
140
+
+--------------------------------------------+------------------------------------------------------+
141
+
| in_anglvel_x_filter_low_pass_3db_frequency | Bandwidth for the X-axis gyroscope channel. |
142
+
+--------------------------------------------+------------------------------------------------------+
143
+
| in_anglvel_x_raw | Raw X-axis gyroscope channel value. |
144
+
+--------------------------------------------+------------------------------------------------------+
145
+
| in_anglvel_y_calibbias | Calibration offset for the Y-axis gyroscope channel. |
146
+
+--------------------------------------------+------------------------------------------------------+
147
+
| in_anglvel_y_calibscale | Calibration scale for the Y-axis gyroscope channel. |
148
+
+--------------------------------------------+------------------------------------------------------+
149
+
| in_anglvel_y_filter_low_pass_3db_frequency | Bandwidth for the Y-axis gyroscope channel. |
150
+
+--------------------------------------------+------------------------------------------------------+
151
+
| in_anglvel_y_raw | Raw Y-axis gyroscope channel value. |
152
+
+--------------------------------------------+------------------------------------------------------+
153
+
| in_anglvel_z_calibbias | Calibration offset for the Z-axis gyroscope channel. |
154
+
+--------------------------------------------+------------------------------------------------------+
155
+
| in_anglvel_z_calibscale | Calibration scale for the Z-axis gyroscope channel. |
156
+
+--------------------------------------------+------------------------------------------------------+
157
+
| in_anglvel_z_filter_low_pass_3db_frequency | Bandwidth for the Z-axis gyroscope channel. |
158
+
+--------------------------------------------+------------------------------------------------------+
159
+
| in_anglvel_z_raw | Raw Z-axis gyroscope channel value. |
160
+
+--------------------------------------------+------------------------------------------------------+
161
+
| in_deltaangl_scale | Scale for delta angle channels. |
162
+
+--------------------------------------------+------------------------------------------------------+
163
+
| in_deltaangl_x_raw | Raw X-axis delta angle channel value. |
164
+
+--------------------------------------------+------------------------------------------------------+
165
+
| in_deltaangl_y_raw | Raw Y-axis delta angle channel value. |
166
+
+--------------------------------------------+------------------------------------------------------+
167
+
| in_deltaangl_z_raw | Raw Z-axis delta angle channel value. |
168
+
+--------------------------------------------+------------------------------------------------------+
169
+
170
+
+----------------------------------+-------------------------------------------+
171
+
| Temperature sensor related files | Description |
172
+
+----------------------------------+-------------------------------------------+
173
+
| in_temp0_raw | Raw temperature channel value. |
174
+
+----------------------------------+-------------------------------------------+
175
+
| in_temp0_offset | Offset for the temperature sensor channel.|
176
+
+----------------------------------+-------------------------------------------+
177
+
| in_temp0_scale | Scale for the temperature sensor channel. |
178
+
+----------------------------------+-------------------------------------------+
179
+
180
+
+-------------------------------+---------------------------------------------------------+
181
+
| Miscellaneous device files | Description |
182
+
+-------------------------------+---------------------------------------------------------+
183
+
| name | Name of the IIO device. |
184
+
+-------------------------------+---------------------------------------------------------+
185
+
| sampling_frequency | Currently selected sample rate. |
186
+
+-------------------------------+---------------------------------------------------------+
187
+
188
+
The following table shows the adis16480 related device debug files, found in the
189
+
specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.
190
+
191
+
+----------------------+-------------------------------------------------------------------------+
192
+
| Debugfs device files | Description |
193
+
+----------------------+-------------------------------------------------------------------------+
194
+
| serial_number | The serial number of the chip in hexadecimal format. |
195
+
+----------------------+-------------------------------------------------------------------------+
196
+
| product_id | Chip specific product id (e.g. 16480, 16488, 16545, etc.). |
197
+
+----------------------+-------------------------------------------------------------------------+
198
+
| flash_count | The number of flash writes performed on the device. |
199
+
+----------------------+-------------------------------------------------------------------------+
200
+
| firmware_revision | String containing the firmware revision in the following format ##.##. |
201
+
+----------------------+-------------------------------------------------------------------------+
202
+
| firmware_date | String containing the firmware date in the following format mm-dd-yyyy. |
203
+
+----------------------+-------------------------------------------------------------------------+
204
+
205
+
Channels processed values
206
+
-------------------------
207
+
208
+
A channel value can be read from its _raw attribute. The value returned is the
209
+
raw value as reported by the devices. To get the processed value of the channel,
210
+
apply the following formula:
211
+
212
+
.. code-block:: bash
213
+
214
+
processed value = (_raw + _offset) * _scale
215
+
216
+
Where _offset and _scale are device attributes. If no _offset attribute is
217
+
present, simply assume its value is 0.
218
+
219
+
The adis16480 driver offers data for 7 types of channels, the table below shows
220
+
the measurement units for the processed value, which are defined by the IIO
221
+
framework:
222
+
223
+
+--------------------------------------+---------------------------+
224
+
| Channel type | Measurement unit |
225
+
+--------------------------------------+---------------------------+
226
+
| Acceleration on X, Y, and Z axis | Meters per Second squared |
227
+
+--------------------------------------+---------------------------+
228
+
| Angular velocity on X, Y and Z axis | Radians per second |
229
+
+--------------------------------------+---------------------------+
230
+
| Delta velocity on X. Y, and Z axis | Meters per Second |
231
+
+--------------------------------------+---------------------------+
232
+
| Delta angle on X, Y, and Z axis | Radians |
233
+
+--------------------------------------+---------------------------+
234
+
| Temperature | Millidegrees Celsius |
235
+
+--------------------------------------+---------------------------+
236
+
| Magnetic field along X, Y and Z axis | Gauss |
237
+
+--------------------------------------+---------------------------+
238
+
| Barometric pressure | kilo Pascal |
239
+
+--------------------------------------+---------------------------+
240
+
241
+
Usage examples
242
+
--------------
243
+
244
+
Show device name:
245
+
246
+
.. code-block:: bash
247
+
248
+
root:/sys/bus/iio/devices/iio:device0> cat name
249
+
adis16545-1
250
+
251
+
Show accelerometer channels value:
252
+
253
+
.. code-block:: bash
254
+
255
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
256
+
1376728
257
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
258
+
4487621
259
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
260
+
262773792
261
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
262
+
0.000000037
263
+
264
+
- X-axis acceleration = in_accel_x_raw * in_accel_scale = 0.050938936 m/s^2
265
+
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = 0.166041977 m/s^2
266
+
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.722630304 m/s^2
267
+
268
+
Show gyroscope channels value:
269
+
270
+
.. code-block:: bash
271
+
272
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
273
+
-1041702
274
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
275
+
-273013
276
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
277
+
2745116
278
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
279
+
0.000000001
280
+
281
+
- X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = −0.001041702 rad/s
282
+
- Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = −0.000273013 rad/s
283
+
- Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = 0.002745116 rad/s
284
+
285
+
Set calibration offset for accelerometer channels:
286
+
287
+
.. code-block:: bash
288
+
289
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
290
+
0
291
+
292
+
root:/sys/bus/iio/devices/iio:device0> echo 5000 > in_accel_x_calibbias
293
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
294
+
5000
295
+
296
+
Set calibration offset for gyroscope channels:
297
+
298
+
.. code-block:: bash
299
+
300
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
301
+
0
302
+
303
+
root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_calibbias
304
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
305
+
-5000
306
+
307
+
Set sampling frequency:
308
+
309
+
.. code-block:: bash
310
+
311
+
root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
312
+
4250.000000
313
+
314
+
root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
315
+
1062.500000
316
+
317
+
Set bandwidth for accelerometer channels:
318
+
319
+
.. code-block:: bash
320
+
321
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_filter_low_pass_3db_frequency
322
+
0
323
+
324
+
root:/sys/bus/iio/devices/iio:device0> echo 300 > in_accel_x_filter_low_pass_3db_frequency
325
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_filter_low_pass_3db_frequency
326
+
300
327
+
328
+
Show serial number:
329
+
330
+
.. code-block:: bash
331
+
332
+
root:/sys/kernel/debug/iio/iio:device0> cat serial_number
333
+
0x000c
334
+
335
+
Show product id:
336
+
337
+
.. code-block:: bash
338
+
339
+
root:/sys/kernel/debug/iio/iio:device0> cat product_id
340
+
16545
341
+
342
+
Show flash count:
343
+
344
+
.. code-block:: bash
345
+
346
+
root:/sys/kernel/debug/iio/iio:device0> cat flash_count
347
+
88
348
+
349
+
Show firmware revision:
350
+
351
+
.. code-block:: bash
352
+
353
+
root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
354
+
1.4
355
+
356
+
Show firmware date:
357
+
358
+
.. code-block:: bash
359
+
360
+
root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
361
+
09-23-2023
362
+
363
+
3. Device buffers
364
+
=================
365
+
366
+
This driver supports IIO buffers.
367
+
368
+
All devices support retrieving the raw acceleration, gyroscope and temperature
369
+
measurements using buffers.
370
+
371
+
The following device families also support retrieving the delta velocity, delta
372
+
angle and temperature measurements using buffers:
373
+
374
+
- ADIS16545
375
+
- ADIS16547
376
+
377
+
However, when retrieving acceleration or gyroscope data using buffers, delta
378
+
readings will not be available and vice versa. This is because the device only
379
+
allows to read either acceleration and gyroscope data or delta velocity and
380
+
delta angle data at a time and switching between these two burst data selection
381
+
modes is time consuming.
382
+
383
+
Usage examples
384
+
--------------
385
+
386
+
Set device trigger in current_trigger, if not already set:
387
+
388
+
.. code-block:: bash
389
+
390
+
root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
391
+
392
+
root:/sys/bus/iio/devices/iio:device0> echo adis16545-1-dev0 > trigger/current_trigger
393
+
root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
394
+
adis16545-1-dev0
395
+
396
+
Select channels for buffer read:
397
+
398
+
.. code-block:: bash
399
+
400
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_x_en
401
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_y_en
402
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_z_en
403
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp0_en
404
+
405
+
Set the number of samples to be stored in the buffer:
406
+
407
+
.. code-block:: bash
408
+
409
+
root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length
410
+
411
+
Enable buffer readings:
412
+
413
+
.. code-block:: bash
414
+
415
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable
416
+
417
+
Obtain buffered data::
418
+
419
+
root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0
420
+
...
421
+
00006aa0 09 62 00 00 ff ff fc a4 00 00 01 69 00 03 3c 08 |.b.........i..<.|
422
+
00006ab0 09 61 00 00 00 00 02 96 00 00 02 8f 00 03 37 50 |.a............7P|
423
+
00006ac0 09 61 00 00 00 00 12 3d 00 00 0b 89 00 03 2c 0b |.a.....=......,.|
424
+
00006ad0 09 61 00 00 00 00 1e dc 00 00 16 dd 00 03 25 bf |.a............%.|
425
+
00006ae0 09 61 00 00 00 00 1e e3 00 00 1b bf 00 03 27 0b |.a............'.|
426
+
00006af0 09 61 00 00 00 00 15 50 00 00 19 44 00 03 30 fd |.a.....P...D..0.|
427
+
00006b00 09 61 00 00 00 00 09 0e 00 00 14 41 00 03 3d 7f |.a.........A..=.|
428
+
00006b10 09 61 00 00 ff ff ff f0 00 00 0e bc 00 03 48 d0 |.a............H.|
429
+
00006b20 09 63 00 00 00 00 00 9f 00 00 0f 37 00 03 4c fe |.c.........7..L.|
430
+
00006b30 09 64 00 00 00 00 0b f6 00 00 18 92 00 03 43 22 |.d............C"|
431
+
00006b40 09 64 00 00 00 00 18 df 00 00 22 33 00 03 33 ab |.d........"3..3.|
432
+
00006b50 09 63 00 00 00 00 1e 81 00 00 26 be 00 03 29 60 |.c........&...)`|
433
+
00006b60 09 63 00 00 00 00 1b 13 00 00 22 2f 00 03 23 91 |.c........"/..#.|
434
+
...
435
+
436
+
See ``Documentation/iio/iio_devbuf.rst`` for more information about how buffered
437
+
data is structured.
438
+
439
+
4. IIO Interfacing Tools
440
+
========================
441
+
442
+
See ``Documentation/iio/iio_tools.rst`` for the description of the available IIO
443
+
interfacing tools.