Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: iio: add documentation for adis16475 driver
Add documentation for adis16475 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>
Link: https://lore.kernel.org/r/20240221085848.991413-4-ramona.gradinariu@analog.com
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
authored by
Ramona Gradinariu
and committed by
Jonathan Cameron
8243b287
d5422a85
+408
+407
Documentation/iio/adis16475.rst
+407
Documentation/iio/adis16475.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
================
4
+
ADIS16475 driver
5
+
================
6
+
7
+
This driver supports Analog Device's IMUs on SPI bus.
8
+
9
+
1. Supported devices
10
+
====================
11
+
12
+
* `ADIS16465 <https://www.analog.com/ADIS16465>`_
13
+
* `ADIS16467 <https://www.analog.com/ADIS16467>`_
14
+
* `ADIS16470 <https://www.analog.com/ADIS16470>`_
15
+
* `ADIS16475 <https://www.analog.com/ADIS16475>`_
16
+
* `ADIS16477 <https://www.analog.com/ADIS16477>`_
17
+
* `ADIS16500 <https://www.analog.com/ADIS16500>`_
18
+
* `ADIS16505 <https://www.analog.com/ADIS16505>`_
19
+
* `ADIS16507 <https://www.analog.com/ADIS16507>`_
20
+
21
+
Each supported device is a precision, miniature microelectromechanical system
22
+
(MEMS) inertial measurement unit (IMU) that includes a triaxial gyroscope and a
23
+
triaxial accelerometer. Each inertial sensor in the IMU device combines with
24
+
signal conditioning that optimizes dynamic performance. The factory calibration
25
+
characterizes each sensor for sensitivity, bias, alignment, linear acceleration
26
+
(gyroscope bias), and point of percussion (accelerometer location). As a result,
27
+
each sensor has dynamic compensation formulas that provide accurate sensor
28
+
measurements over a broad set of conditions.
29
+
30
+
2. Device attributes
31
+
====================
32
+
33
+
Accelerometer, gyroscope measurements are always provided. Furthermore, the
34
+
driver offers the capability to retrieve the delta angle and the delta velocity
35
+
measurements computed by the device.
36
+
37
+
The delta angle measurements represent a calculation of angular displacement
38
+
between each sample update, while the delta velocity measurements represent a
39
+
calculation of linear velocity change between each sample update.
40
+
41
+
Finally, temperature data are provided which show a coarse measurement of
42
+
the temperature inside of the IMU device. This data is most useful for
43
+
monitoring relative changes in the thermal environment.
44
+
45
+
The signal chain of each inertial sensor (accelerometers and gyroscopes)
46
+
includes the application of unique correction formulas, which are derived from
47
+
extensive characterization of bias, sensitivity, alignment, response to linear
48
+
acceleration (gyroscopes), and point of percussion (accelerometer location)
49
+
over a temperature range of −40°C to +85°C, for each ADIS device. These
50
+
correction formulas are not accessible, but users do have the opportunity to
51
+
adjust the bias for each sensor individually through the calibbias attribute.
52
+
53
+
Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
54
+
where X is the IIO index of the device. Under these folders reside a set of
55
+
device files, depending on the characteristics and features of the hardware
56
+
device in questions. These files are consistently generalized and documented in
57
+
the IIO ABI documentation.
58
+
59
+
The following tables show the adis16475 related device files, found in the
60
+
specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.
61
+
62
+
+-------------------------------------------+----------------------------------------------------------+
63
+
| 3-Axis Accelerometer related device files | Description |
64
+
+-------------------------------------------+----------------------------------------------------------+
65
+
| in_accel_scale | Scale for the accelerometer channels. |
66
+
+-------------------------------------------+----------------------------------------------------------+
67
+
| in_accel_x_calibbias | Calibration offset for the X-axis accelerometer channel. |
68
+
+-------------------------------------------+----------------------------------------------------------+
69
+
| in_accel_calibbias_x | x-axis acceleration offset correction |
70
+
+-------------------------------------------+----------------------------------------------------------+
71
+
| in_accel_x_raw | Raw X-axis accelerometer channel value. |
72
+
+-------------------------------------------+----------------------------------------------------------+
73
+
| in_accel_calibbias_y | y-axis acceleration offset correction |
74
+
+-------------------------------------------+----------------------------------------------------------+
75
+
| in_accel_y_raw | Raw Y-axis accelerometer channel value. |
76
+
+-------------------------------------------+----------------------------------------------------------+
77
+
| in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. |
78
+
+-------------------------------------------+----------------------------------------------------------+
79
+
| in_accel_z_raw | Raw Z-axis accelerometer channel value. |
80
+
+-------------------------------------------+----------------------------------------------------------+
81
+
| in_deltavelocity_scale | Scale for delta velocity channels. |
82
+
+-------------------------------------------+----------------------------------------------------------+
83
+
| in_deltavelocity_x_raw | Raw X-axis delta velocity channel value. |
84
+
+-------------------------------------------+----------------------------------------------------------+
85
+
| in_deltavelocity_y_raw | Raw Y-axis delta velocity channel value. |
86
+
+-------------------------------------------+----------------------------------------------------------+
87
+
| in_deltavelocity_z_raw | Raw Z-axis delta velocity channel value. |
88
+
+-------------------------------------------+----------------------------------------------------------+
89
+
90
+
+---------------------------------------+------------------------------------------------------+
91
+
| 3-Axis Gyroscope related device files | Description |
92
+
+---------------------------------------+------------------------------------------------------+
93
+
| in_anglvel_scale | Scale for the gyroscope channels. |
94
+
+---------------------------------------+------------------------------------------------------+
95
+
| in_anglvel_x_calibbias | Calibration offset for the X-axis gyroscope channel. |
96
+
+---------------------------------------+------------------------------------------------------+
97
+
| in_anglvel_calibbias_x | x-axis gyroscope offset correction |
98
+
+---------------------------------------+------------------------------------------------------+
99
+
| in_anglvel_x_raw | Raw X-axis gyroscope channel value. |
100
+
+---------------------------------------+------------------------------------------------------+
101
+
| in_anglvel_calibbias_y | y-axis gyroscope offset correction |
102
+
+---------------------------------------+------------------------------------------------------+
103
+
| in_anglvel_y_raw | Raw Y-axis gyroscope channel value. |
104
+
+---------------------------------------+------------------------------------------------------+
105
+
| in_anglvel_z_calibbias | Calibration offset for the Z-axis gyroscope channel. |
106
+
+---------------------------------------+------------------------------------------------------+
107
+
| in_anglvel_z_raw | Raw Z-axis gyroscope channel value. |
108
+
+---------------------------------------+------------------------------------------------------+
109
+
| in_deltaangl_scale | Scale for delta angle channels. |
110
+
+---------------------------------------+------------------------------------------------------+
111
+
| in_deltaangl_x_raw | Raw X-axis delta angle channel value. |
112
+
+---------------------------------------+------------------------------------------------------+
113
+
| in_deltaangl_y_raw | Raw Y-axis delta angle channel value. |
114
+
+---------------------------------------+------------------------------------------------------+
115
+
| in_deltaangl_z_raw | Raw Z-axis delta angle channel value. |
116
+
+---------------------------------------+------------------------------------------------------+
117
+
118
+
+----------------------------------+-------------------------------------------+
119
+
| Temperature sensor related files | Description |
120
+
+----------------------------------+-------------------------------------------+
121
+
| in_temp0_raw | Raw temperature channel value. |
122
+
+----------------------------------+-------------------------------------------+
123
+
| in_temp0_scale | Scale for the temperature sensor channel. |
124
+
+----------------------------------+-------------------------------------------+
125
+
126
+
+-------------------------------+---------------------------------------------------------+
127
+
| Miscellaneous device files | Description |
128
+
+-------------------------------+---------------------------------------------------------+
129
+
| name | Name of the IIO device. |
130
+
+-------------------------------+---------------------------------------------------------+
131
+
| sampling_frequency | Currently selected sample rate. |
132
+
+-------------------------------+---------------------------------------------------------+
133
+
| filter_low_pass_3db_frequency | Bandwidth for the accelerometer and gyroscope channels. |
134
+
+-------------------------------+---------------------------------------------------------+
135
+
136
+
The following table shows the adis16475 related device debug files, found in the
137
+
specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.
138
+
139
+
+----------------------+-------------------------------------------------------------------------+
140
+
| Debugfs device files | Description |
141
+
+----------------------+-------------------------------------------------------------------------+
142
+
| serial_number | The serial number of the chip in hexadecimal format. |
143
+
+----------------------+-------------------------------------------------------------------------+
144
+
| product_id | Chip specific product id (e.g. 16475, 16500, 16505, etc.). |
145
+
+----------------------+-------------------------------------------------------------------------+
146
+
| flash_count | The number of flash writes performed on the device. |
147
+
+----------------------+-------------------------------------------------------------------------+
148
+
| firmware_revision | String containing the firmware revision in the following format ##.##. |
149
+
+----------------------+-------------------------------------------------------------------------+
150
+
| firmware_date | String containing the firmware date in the following format mm-dd-yyyy. |
151
+
+----------------------+-------------------------------------------------------------------------+
152
+
153
+
Channels processed values
154
+
-------------------------
155
+
156
+
A channel value can be read from its _raw attribute. The value returned is the
157
+
raw value as reported by the devices. To get the processed value of the channel,
158
+
apply the following formula:
159
+
160
+
.. code-block:: bash
161
+
162
+
processed value = (_raw + _offset) * _scale
163
+
164
+
Where _offset and _scale are device attributes. If no _offset attribute is
165
+
present, simply assume its value is 0.
166
+
167
+
The adis16475 driver offers data for 5 types of channels, the table below shows
168
+
the measurement units for the processed value, which are defined by the IIO
169
+
framework:
170
+
171
+
+-------------------------------------+---------------------------+
172
+
| Channel type | Measurement unit |
173
+
+-------------------------------------+---------------------------+
174
+
| Acceleration on X, Y, and Z axis | Meters per Second squared |
175
+
+-------------------------------------+---------------------------+
176
+
| Angular velocity on X, Y and Z axis | Radians per second |
177
+
+-------------------------------------+---------------------------+
178
+
| Delta velocity on X. Y, and Z axis | Meters per Second |
179
+
+-------------------------------------+---------------------------+
180
+
| Delta angle on X, Y, and Z axis | Radians |
181
+
+-------------------------------------+---------------------------+
182
+
| Temperature | Millidegrees Celsius |
183
+
+-------------------------------------+---------------------------+
184
+
185
+
Usage examples
186
+
--------------
187
+
188
+
Show device name:
189
+
190
+
.. code-block:: bash
191
+
192
+
root:/sys/bus/iio/devices/iio:device0> cat name
193
+
adis16505-2
194
+
195
+
Show accelerometer channels value:
196
+
197
+
.. code-block:: bash
198
+
199
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
200
+
-275924
201
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
202
+
-30142222
203
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
204
+
261265769
205
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
206
+
0.000000037
207
+
208
+
- X-axis acceleration = in_accel_x_raw * in_accel_scale = −0.010209188 m/s^2
209
+
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = −1.115262214 m/s^2
210
+
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.666833453 m/s^2
211
+
212
+
Show gyroscope channels value:
213
+
214
+
.. code-block:: bash
215
+
216
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
217
+
-3324626
218
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
219
+
1336980
220
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
221
+
-602983
222
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
223
+
0.000000006
224
+
225
+
- X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = −0.019947756 rad/s
226
+
- Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = 0.00802188 rad/s
227
+
- Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = −0.003617898 rad/s
228
+
229
+
Set calibration offset for accelerometer channels:
230
+
231
+
.. code-block:: bash
232
+
233
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
234
+
0
235
+
236
+
root:/sys/bus/iio/devices/iio:device0> echo 5000 > in_accel_x_calibbias
237
+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
238
+
5000
239
+
240
+
Set calibration offset for gyroscope channels:
241
+
242
+
.. code-block:: bash
243
+
244
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
245
+
0
246
+
247
+
root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_calibbias
248
+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
249
+
-5000
250
+
251
+
Set sampling frequency:
252
+
253
+
.. code-block:: bash
254
+
255
+
root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
256
+
2000.000000
257
+
258
+
root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
259
+
1000.000000
260
+
261
+
Set bandwidth for accelerometer and gyroscope:
262
+
263
+
.. code-block:: bash
264
+
265
+
root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
266
+
720
267
+
268
+
root:/sys/bus/iio/devices/iio:device0> echo 360 > filter_low_pass_3db_frequency
269
+
root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
270
+
360
271
+
272
+
Show serial number:
273
+
274
+
.. code-block:: bash
275
+
276
+
root:/sys/kernel/debug/iio/iio:device0> cat serial_number
277
+
0x04f9
278
+
279
+
Show product id:
280
+
281
+
.. code-block:: bash
282
+
283
+
root:/sys/kernel/debug/iio/iio:device0> cat product_id
284
+
16505
285
+
286
+
Show flash count:
287
+
288
+
.. code-block:: bash
289
+
290
+
root:/sys/kernel/debug/iio/iio:device0> cat flash_count
291
+
150
292
+
293
+
Show firmware revision:
294
+
295
+
.. code-block:: bash
296
+
297
+
root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
298
+
1.6
299
+
300
+
Show firmware date:
301
+
302
+
.. code-block:: bash
303
+
304
+
root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
305
+
06-27-2019
306
+
307
+
3. Device buffers
308
+
=================
309
+
310
+
This driver supports IIO buffers.
311
+
312
+
All devices support retrieving the raw acceleration, gyroscope and temperature
313
+
measurements using buffers.
314
+
315
+
The following device families also support retrieving the delta velocity, delta
316
+
angle and temperature measurements using buffers:
317
+
318
+
- ADIS16477
319
+
- ADIS16500
320
+
- ADIS16505
321
+
- ADIS16507
322
+
323
+
However, when retrieving acceleration or gyroscope data using buffers, delta
324
+
readings will not be available and vice versa.
325
+
326
+
Usage examples
327
+
--------------
328
+
329
+
Set device trigger in current_trigger, if not already set:
330
+
331
+
.. code-block:: bash
332
+
333
+
root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
334
+
335
+
root:/sys/bus/iio/devices/iio:device0> echo adis16505-2-dev0 > trigger/current_trigger
336
+
root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
337
+
adis16505-2-dev0
338
+
339
+
Select channels for buffer read:
340
+
341
+
.. code-block:: bash
342
+
343
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_x_en
344
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_y_en
345
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_z_en
346
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp0_en
347
+
348
+
Set the number of samples to be stored in the buffer:
349
+
350
+
.. code-block:: bash
351
+
352
+
root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length
353
+
354
+
Enable buffer readings:
355
+
356
+
.. code-block:: bash
357
+
358
+
root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable
359
+
360
+
Obtain buffered data:
361
+
362
+
.. code-block:: bash
363
+
364
+
root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0
365
+
...
366
+
00001680 01 1f 00 00 ff ff fe ef 00 00 47 bf 00 03 35 55 |..........G...5U|
367
+
00001690 01 1f 00 00 ff ff ff d9 00 00 46 f1 00 03 35 35 |..........F...55|
368
+
000016a0 01 1f 00 00 ff ff fe fc 00 00 46 cb 00 03 35 7b |..........F...5{|
369
+
000016b0 01 1f 00 00 ff ff fe 41 00 00 47 0d 00 03 35 8b |.......A..G...5.|
370
+
000016c0 01 1f 00 00 ff ff fe 37 00 00 46 b4 00 03 35 90 |.......7..F...5.|
371
+
000016d0 01 1d 00 00 ff ff fe 5a 00 00 45 d7 00 03 36 08 |.......Z..E...6.|
372
+
000016e0 01 1b 00 00 ff ff fe fb 00 00 45 e7 00 03 36 60 |..........E...6`|
373
+
000016f0 01 1a 00 00 ff ff ff 17 00 00 46 bc 00 03 36 de |..........F...6.|
374
+
00001700 01 1a 00 00 ff ff fe 59 00 00 46 d7 00 03 37 b8 |.......Y..F...7.|
375
+
00001710 01 1a 00 00 ff ff fe ae 00 00 46 95 00 03 37 ba |..........F...7.|
376
+
00001720 01 1a 00 00 ff ff fe c5 00 00 46 63 00 03 37 9f |..........Fc..7.|
377
+
00001730 01 1a 00 00 ff ff fe 55 00 00 46 89 00 03 37 c1 |.......U..F...7.|
378
+
00001740 01 1a 00 00 ff ff fe 31 00 00 46 aa 00 03 37 f7 |.......1..F...7.|
379
+
...
380
+
381
+
See ``Documentation/iio/iio_devbuf.rst`` for more information about how buffered
382
+
data is structured.
383
+
384
+
4. IIO Interfacing Tools
385
+
========================
386
+
387
+
Linux Kernel Tools
388
+
------------------
389
+
390
+
Linux Kernel provides some userspace tools that can be used to retrieve data
391
+
from IIO sysfs:
392
+
393
+
* lsiio: example application that provides a list of IIO devices and triggers
394
+
* iio_event_monitor: example application that reads events from an IIO device
395
+
and prints them
396
+
* iio_generic_buffer: example application that reads data from buffer
397
+
* iio_utils: set of APIs, typically used to access sysfs files.
398
+
399
+
LibIIO
400
+
------
401
+
402
+
LibIIO is a C/C++ library that provides generic access to IIO devices. The
403
+
library abstracts the low-level details of the hardware, and provides a simple
404
+
yet complete programming interface that can be used for advanced projects.
405
+
406
+
For more information about LibIIO, please see:
407
+
https://github.com/analogdevicesinc/libiio