Skip to content

Commit 484cfbd

Browse files
rbudai98nunojsa
rbudai98
authored and
nunojsa
committed
docs: iio: add documentation for adis16550 driver
Add documentation for adis16550 driver which describes the driver device files and shows how the user may use the ABI for various scenarios (configuration, measurement, etc.). Co-developed-by: Antoniu Miclaus <[email protected]> Signed-off-by: Antoniu Miclaus <[email protected]> Co-developed-by: Ramona Gradinariu <[email protected]> Signed-off-by: Ramona Gradinariu <[email protected]> Signed-off-by: Robert Budai <[email protected]> Link: https://patch.msgid.link/[email protected] Signed-off-by: Jonathan Cameron <[email protected]> (cherry picked from commit aaa9d61)
1 parent 25aeca0 commit 484cfbd

File tree

2 files changed

+377
-0
lines changed

2 files changed

+377
-0
lines changed

‎Documentation/iio/adis16550.rst‎

Lines changed: 376 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,376 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
================
4+
ADIS16550 driver
5+
================
6+
7+
This driver supports Analog Device's IMUs on SPI bus.
8+
9+
1. Supported devices
10+
====================
11+
12+
* `ADIS16550 <https://www.analog.com/ADIS16550>`_
13+
14+
The ADIS16550 is a complete inertial system that includes a triaxis gyroscope
15+
and a triaxis accelerometer. The factory calibration characterizes each sensor for
16+
sensitivity, bias, and alignment. As a result, each sensor has its own dynamic
17+
compensation formulas that provide accurate sensor measurements.
18+
19+
2. Device attributes
20+
====================
21+
22+
Accelerometer, gyroscope measurements are always provided. Furthermore, the
23+
driver offers the capability to retrieve the delta angle and the delta velocity
24+
measurements computed by the device.
25+
26+
The delta angle measurements represent a calculation of angular displacement
27+
between each sample update, while the delta velocity measurements represent a
28+
calculation of linear velocity change between each sample update.
29+
30+
Finally, temperature data are provided which show a coarse measurement of
31+
the temperature inside of the IMU device. This data is most useful for
32+
monitoring relative changes in the thermal environment.
33+
34+
Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
35+
where X is the IIO index of the device. Under these folders reside a set of
36+
device files, depending on the characteristics and features of the hardware
37+
device in questions. These files are consistently generalized and documented in
38+
the IIO ABI documentation.
39+
40+
The following tables show the adis16550 related device files, found in the
41+
specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.
42+
43+
+-------------------------------------------+----------------------------------------------------------+
44+
| 3-Axis Accelerometer related device files | Description |
45+
+-------------------------------------------+----------------------------------------------------------+
46+
| in_accel_scale | Scale for the accelerometer channels. |
47+
+-------------------------------------------+----------------------------------------------------------+
48+
| in_accel_filter_low_pass_3db_frequency | Bandwidth for the accelerometer channels. |
49+
+-------------------------------------------+----------------------------------------------------------+
50+
| in_accel_x_calibbias | Calibration offset for the X-axis accelerometer channel. |
51+
+-------------------------------------------+----------------------------------------------------------+
52+
| in_accel_x_calibscale | Calibration scale for the X-axis accelerometer channel. |
53+
+-------------------------------------------+----------------------------------------------------------+
54+
| in_accel_x_raw | Raw X-axis accelerometer channel value. |
55+
+-------------------------------------------+----------------------------------------------------------+
56+
| in_accel_y_calibbias | Calibration offset for the Y-axis accelerometer channel. |
57+
+-------------------------------------------+----------------------------------------------------------+
58+
| in_accel_y_calibscale | Calibration scale for the Y-axis accelerometer channel. |
59+
+-------------------------------------------+----------------------------------------------------------+
60+
| in_accel_y_raw | Raw Y-axis accelerometer channel value. |
61+
+-------------------------------------------+----------------------------------------------------------+
62+
| in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. |
63+
+-------------------------------------------+----------------------------------------------------------+
64+
| in_accel_z_calibscale | Calibration scale for the Z-axis accelerometer channel. |
65+
+-------------------------------------------+----------------------------------------------------------+
66+
| in_accel_z_raw | Raw Z-axis accelerometer channel value. |
67+
+-------------------------------------------+----------------------------------------------------------+
68+
| in_deltavelocity_scale | Scale for delta velocity channels. |
69+
+-------------------------------------------+----------------------------------------------------------+
70+
| in_deltavelocity_x_raw | Raw X-axis delta velocity channel value. |
71+
+-------------------------------------------+----------------------------------------------------------+
72+
| in_deltavelocity_y_raw | Raw Y-axis delta velocity channel value. |
73+
+-------------------------------------------+----------------------------------------------------------+
74+
| in_deltavelocity_z_raw | Raw Z-axis delta velocity channel value. |
75+
+-------------------------------------------+----------------------------------------------------------+
76+
77+
+--------------------------------------------+------------------------------------------------------+
78+
| 3-Axis Gyroscope related device files | Description |
79+
+--------------------------------------------+------------------------------------------------------+
80+
| in_anglvel_scale | Scale for the gyroscope channels. |
81+
+--------------------------------------------+------------------------------------------------------+
82+
| in_anglvel_filter_low_pass_3db_frequency | Scale for the gyroscope channels. |
83+
+--------------------------------------------+------------------------------------------------------+
84+
| in_anglvel_x_calibbias | Calibration offset for the X-axis gyroscope channel. |
85+
+--------------------------------------------+------------------------------------------------------+
86+
| in_anglvel_x_calibscale | Calibration scale for the X-axis gyroscope channel. |
87+
+--------------------------------------------+------------------------------------------------------+
88+
| in_anglvel_x_raw | Raw X-axis gyroscope channel value. |
89+
+--------------------------------------------+------------------------------------------------------+
90+
| in_anglvel_y_calibbias | Calibration offset for the Y-axis gyroscope channel. |
91+
+--------------------------------------------+------------------------------------------------------+
92+
| in_anglvel_y_calibscale | Calibration scale for the Y-axis gyroscope channel. |
93+
+--------------------------------------------+------------------------------------------------------+
94+
| in_anglvel_y_raw | Raw Y-axis gyroscope channel value. |
95+
+--------------------------------------------+------------------------------------------------------+
96+
| in_anglvel_z_calibbias | Calibration offset for the Z-axis gyroscope channel. |
97+
+--------------------------------------------+------------------------------------------------------+
98+
| in_anglvel_z_calibscale | Calibration scale for the Z-axis gyroscope channel. |
99+
+--------------------------------------------+------------------------------------------------------+
100+
| in_anglvel_z_raw | Raw Z-axis gyroscope channel value. |
101+
+--------------------------------------------+------------------------------------------------------+
102+
| in_deltaangl_scale | Scale for delta angle channels. |
103+
+--------------------------------------------+------------------------------------------------------+
104+
| in_deltaangl_x_raw | Raw X-axis delta angle channel value. |
105+
+--------------------------------------------+------------------------------------------------------+
106+
| in_deltaangl_y_raw | Raw Y-axis delta angle channel value. |
107+
+--------------------------------------------+------------------------------------------------------+
108+
| in_deltaangl_z_raw | Raw Z-axis delta angle channel value. |
109+
+--------------------------------------------+------------------------------------------------------+
110+
111+
+----------------------------------+-------------------------------------------+
112+
| Temperature sensor related files | Description |
113+
+----------------------------------+-------------------------------------------+
114+
| in_temp0_raw | Raw temperature channel value. |
115+
+----------------------------------+-------------------------------------------+
116+
| in_temp0_offset | Offset for the temperature sensor channel.|
117+
+----------------------------------+-------------------------------------------+
118+
| in_temp0_scale | Scale for the temperature sensor channel. |
119+
+----------------------------------+-------------------------------------------+
120+
121+
+----------------------------+--------------------------------------------------------------------------------+
122+
| Miscellaneous device files | Description |
123+
+----------------------------+--------------------------------------------------------------------------------+
124+
| name | Name of the IIO device. |
125+
+----------------------------+--------------------------------------------------------------------------------+
126+
| sampling_frequency | Currently selected sample rate. |
127+
+----------------------------+--------------------------------------------------------------------------------+
128+
129+
The following table shows the adis16550 related device debug files, found in the
130+
specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.
131+
132+
+----------------------+-------------------------------------------------------------------------+
133+
| Debugfs device files | Description |
134+
+----------------------+-------------------------------------------------------------------------+
135+
| serial_number | The serial number of the chip in hexadecimal format. |
136+
+----------------------+-------------------------------------------------------------------------+
137+
| product_id | Chip specific product id (16550). |
138+
+----------------------+-------------------------------------------------------------------------+
139+
| flash_count | The number of flash writes performed on the device. |
140+
+----------------------+-------------------------------------------------------------------------+
141+
| firmware_revision | String containing the firmware revision in the following format ##.##. |
142+
+----------------------+-------------------------------------------------------------------------+
143+
| firmware_date | String containing the firmware date in the following format mm-dd-yyyy. |
144+
+----------------------+-------------------------------------------------------------------------+
145+
146+
Channels processed values
147+
-------------------------
148+
149+
A channel value can be read from its _raw attribute. The value returned is the
150+
raw value as reported by the devices. To get the processed value of the channel,
151+
apply the following formula:
152+
153+
.. code-block:: bash
154+
155+
processed value = (_raw + _offset) * _scale
156+
157+
Where _offset and _scale are device attributes. If no _offset attribute is
158+
present, simply assume its value is 0.
159+
160+
The adis16550 driver offers data for 5 types of channels, the table below shows
161+
the measurement units for the processed value, which are defined by the IIO
162+
framework:
163+
164+
+--------------------------------------+---------------------------+
165+
| Channel type | Measurement unit |
166+
+--------------------------------------+---------------------------+
167+
| Acceleration on X, Y, and Z axis | Meters per Second squared |
168+
+--------------------------------------+---------------------------+
169+
| Angular velocity on X, Y and Z axis | Radians per second |
170+
+--------------------------------------+---------------------------+
171+
| Delta velocity on X. Y, and Z axis | Meters per Second |
172+
+--------------------------------------+---------------------------+
173+
| Delta angle on X, Y, and Z axis | Radians |
174+
+--------------------------------------+---------------------------+
175+
| Temperature | Millidegrees Celsius |
176+
+--------------------------------------+---------------------------+
177+
178+
Usage examples
179+
--------------
180+
181+
Show device name:
182+
183+
.. code-block:: bash
184+
185+
root:/sys/bus/iio/devices/iio:device0> cat name
186+
adis16550
187+
188+
Show accelerometer channels value:
189+
190+
.. code-block:: bash
191+
192+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
193+
6903851
194+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
195+
5650550
196+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
197+
104873530
198+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
199+
0.000000095
200+
201+
- X-axis acceleration = in_accel_x_raw * in_accel_scale = 0.655865845 m/s^2
202+
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = 0.53680225 m/s^2
203+
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.96298535 m/s^2
204+
205+
Show gyroscope channels value:
206+
207+
.. code-block:: bash
208+
209+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
210+
193309
211+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
212+
-763676
213+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
214+
-358108
215+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
216+
0.000000003
217+
218+
- X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = 0.000579927 rad/s
219+
- Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = −0.002291028 rad/s
220+
- Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = −0.001074324 rad/s
221+
222+
Set calibration offset for accelerometer channels:
223+
224+
.. code-block:: bash
225+
226+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
227+
0
228+
229+
root:/sys/bus/iio/devices/iio:device0> echo 5000 > in_accel_x_calibbias
230+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
231+
5000
232+
233+
Set calibration offset for gyroscope channels:
234+
235+
.. code-block:: bash
236+
237+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
238+
0
239+
240+
root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_calibbias
241+
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
242+
-5000
243+
244+
Set sampling frequency:
245+
246+
.. code-block:: bash
247+
248+
root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
249+
4000.000000
250+
251+
root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
252+
1000.000000
253+
254+
Set bandwidth for accelerometer channels:
255+
256+
.. code-block:: bash
257+
258+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency
259+
0
260+
261+
root:/sys/bus/iio/devices/iio:device0> echo 100 > in_accel_filter_low_pass_3db_frequency
262+
root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency
263+
100
264+
265+
Show serial number:
266+
267+
.. code-block:: bash
268+
269+
root:/sys/kernel/debug/iio/iio:device0> cat serial_number
270+
0x000000b6
271+
272+
Show product id:
273+
274+
.. code-block:: bash
275+
276+
root:/sys/kernel/debug/iio/iio:device0> cat product_id
277+
16550
278+
279+
Show flash count:
280+
281+
.. code-block:: bash
282+
283+
root:/sys/kernel/debug/iio/iio:device0> cat flash_count
284+
13
285+
286+
Show firmware revision:
287+
288+
.. code-block:: bash
289+
290+
root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
291+
1.5
292+
293+
Show firmware date:
294+
295+
.. code-block:: bash
296+
297+
root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
298+
28-04-2021
299+
300+
3. Device buffers
301+
=================
302+
303+
This driver supports IIO buffers.
304+
305+
The device supports retrieving the raw acceleration, gyroscope, delta velocity,
306+
delta angle and temperature measurements using buffers.
307+
308+
However, when retrieving acceleration or gyroscope data using buffers, delta
309+
readings will not be available and vice versa. This is because the device only
310+
allows to read either acceleration and gyroscope data or delta velocity and
311+
delta angle data at a time and switching between these two burst data selection
312+
modes is time consuming.
313+
314+
Usage examples
315+
--------------
316+
317+
Set device trigger in current_trigger, if not already set:
318+
319+
.. code-block:: bash
320+
321+
root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
322+
323+
root:/sys/bus/iio/devices/iio:device0> echo adis16550-dev0 > trigger/current_trigger
324+
root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
325+
adis16550-dev0
326+
327+
Select channels for buffer read:
328+
329+
.. code-block:: bash
330+
331+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_x_en
332+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_y_en
333+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_z_en
334+
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp0_en
335+
336+
Set the number of samples to be stored in the buffer:
337+
338+
.. code-block:: bash
339+
340+
root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length
341+
342+
Enable buffer readings:
343+
344+
.. code-block:: bash
345+
346+
root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable
347+
348+
Obtain buffered data:
349+
350+
.. code-block:: bash
351+
352+
root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0
353+
...
354+
0000cdf0 00 00 0d 2f 00 00 08 43 00 00 09 09 00 00 a4 5f |.../...C......._|
355+
0000ce00 00 00 0d 2f 00 00 07 de 00 00 08 db 00 00 a4 4b |.../...........K|
356+
0000ce10 00 00 0d 2f 00 00 07 58 00 00 08 a3 00 00 a4 55 |.../...X.......U|
357+
0000ce20 00 00 0d 2f 00 00 06 d6 00 00 08 5c 00 00 a4 62 |.../.......\...b|
358+
0000ce30 00 00 0d 2f 00 00 06 45 00 00 08 37 00 00 a4 47 |.../...E...7...G|
359+
0000ce40 00 00 0d 2f 00 00 05 d4 00 00 08 30 00 00 a3 fa |.../.......0....|
360+
0000ce50 00 00 0d 2f 00 00 05 d0 00 00 08 12 00 00 a3 d3 |.../............|
361+
0000ce60 00 00 0d 2f 00 00 05 dd 00 00 08 2e 00 00 a3 e9 |.../............|
362+
0000ce70 00 00 0d 2f 00 00 05 cc 00 00 08 51 00 00 a3 d5 |.../.......Q....|
363+
0000ce80 00 00 0d 2f 00 00 05 ba 00 00 08 22 00 00 a3 9a |.../......."....|
364+
0000ce90 00 00 0d 2f 00 00 05 9c 00 00 07 d9 00 00 a3 40 |.../...........@|
365+
0000cea0 00 00 0d 2f 00 00 05 68 00 00 07 94 00 00 a2 e4 |.../...h........|
366+
0000ceb0 00 00 0d 2f 00 00 05 25 00 00 07 8d 00 00 a2 ce |.../...%........|
367+
...
368+
369+
See ``Documentation/iio/iio_devbuf.rst`` for more information about how buffered
370+
data is structured.
371+
372+
4. IIO Interfacing Tools
373+
========================
374+
375+
See ``Documentation/iio/iio_tools.rst`` for the description of the available IIO
376+
interfacing tools.

‎Documentation/iio/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Industrial I/O Kernel Drivers
2525
ad7944
2626
adis16475
2727
adis16480
28+
adis16550
2829
adxl380
2930
bno055
3031
ep93xx_adc

0 commit comments

Comments
 (0)