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_x_raw | Raw X-axis accelerometer channel value. |
70 +-------------------------------------------+----------------------------------------------------------+
71 | in_accel_y_calibbias | Calibration offset for the Y-axis accelerometer channel. |
72 +-------------------------------------------+----------------------------------------------------------+
73 | in_accel_y_raw | Raw Y-axis accelerometer channel value. |
74 +-------------------------------------------+----------------------------------------------------------+
75 | in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. |
76 +-------------------------------------------+----------------------------------------------------------+
77 | in_accel_z_raw | Raw Z-axis accelerometer channel value. |
78 +-------------------------------------------+----------------------------------------------------------+
79 | in_deltavelocity_scale | Scale for delta velocity channels. |
80 +-------------------------------------------+----------------------------------------------------------+
81 | in_deltavelocity_x_raw | Raw X-axis delta velocity channel value. |
82 +-------------------------------------------+----------------------------------------------------------+
83 | in_deltavelocity_y_raw | Raw Y-axis delta velocity channel value. |
84 +-------------------------------------------+----------------------------------------------------------+
85 | in_deltavelocity_z_raw | Raw Z-axis delta velocity channel value. |
86 +-------------------------------------------+----------------------------------------------------------+
87
88 +---------------------------------------+------------------------------------------------------+
89 | 3-Axis Gyroscope related device files | Description |
90 +---------------------------------------+------------------------------------------------------+
91 | in_anglvel_scale | Scale for the gyroscope channels. |
92 +---------------------------------------+------------------------------------------------------+
93 | in_anglvel_x_calibbias | Calibration offset for the X-axis gyroscope channel. |
94 +---------------------------------------+------------------------------------------------------+
95 | in_anglvel_x_raw | Raw X-axis gyroscope channel value. |
96 +---------------------------------------+------------------------------------------------------+
97 | in_anglvel_y_calibbias | Calibration offset for the Y-axis gyroscope channel. |
98 +---------------------------------------+------------------------------------------------------+
99 | in_anglvel_y_raw | Raw Y-axis gyroscope channel value. |
100 +---------------------------------------+------------------------------------------------------+
101 | in_anglvel_z_calibbias | Calibration offset for the Z-axis gyroscope channel. |
102 +---------------------------------------+------------------------------------------------------+
103 | in_anglvel_z_raw | Raw Z-axis gyroscope channel value. |
104 +---------------------------------------+------------------------------------------------------+
105 | in_deltaangl_scale | Scale for delta angle channels. |
106 +---------------------------------------+------------------------------------------------------+
107 | in_deltaangl_x_raw | Raw X-axis delta angle channel value. |
108 +---------------------------------------+------------------------------------------------------+
109 | in_deltaangl_y_raw | Raw Y-axis delta angle channel value. |
110 +---------------------------------------+------------------------------------------------------+
111 | in_deltaangl_z_raw | Raw Z-axis delta angle channel value. |
112 +---------------------------------------+------------------------------------------------------+
113
114 +----------------------------------+-------------------------------------------+
115 | Temperature sensor related files | Description |
116 +----------------------------------+-------------------------------------------+
117 | in_temp0_raw | Raw temperature channel value. |
118 +----------------------------------+-------------------------------------------+
119 | in_temp0_scale | Scale for the temperature sensor channel. |
120 +----------------------------------+-------------------------------------------+
121
122 +-------------------------------+---------------------------------------------------------+
123 | Miscellaneous device files | Description |
124 +-------------------------------+---------------------------------------------------------+
125 | name | Name of the IIO device. |
126 +-------------------------------+---------------------------------------------------------+
127 | sampling_frequency | Currently selected sample rate. |
128 +-------------------------------+---------------------------------------------------------+
129 | filter_low_pass_3db_frequency | Bandwidth for the accelerometer and gyroscope channels. |
130 +-------------------------------+---------------------------------------------------------+
131
132 The following table shows the adis16475 related device debug files, found in the
133 specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.
134
135 +----------------------+-------------------------------------------------------------------------+
136 | Debugfs device files | Description |
137 +----------------------+-------------------------------------------------------------------------+
138 | serial_number | The serial number of the chip in hexadecimal format. |
139 +----------------------+-------------------------------------------------------------------------+
140 | product_id | Chip specific product id (e.g. 16475, 16500, 16505, etc.). |
141 +----------------------+-------------------------------------------------------------------------+
142 | flash_count | The number of flash writes performed on the device. |
143 +----------------------+-------------------------------------------------------------------------+
144 | firmware_revision | String containing the firmware revision in the following format ##.##. |
145 +----------------------+-------------------------------------------------------------------------+
146 | firmware_date | String containing the firmware date in the following format mm-dd-yyyy. |
147 +----------------------+-------------------------------------------------------------------------+
148
149 Channels processed values
150 -------------------------
151
152 A channel value can be read from its _raw attribute. The value returned is the
153 raw value as reported by the devices. To get the processed value of the channel,
154 apply the following formula:
155
156 .. code-block:: bash
157
158 processed value = (_raw + _offset) * _scale
159
160 Where _offset and _scale are device attributes. If no _offset attribute is
161 present, simply assume its value is 0.
162
163 The adis16475 driver offers data for 5 types of channels, the table below shows
164 the measurement units for the processed value, which are defined by the IIO
165 framework:
166
167 +-------------------------------------+---------------------------+
168 | Channel type | Measurement unit |
169 +-------------------------------------+---------------------------+
170 | Acceleration on X, Y, and Z axis | Meters per Second squared |
171 +-------------------------------------+---------------------------+
172 | Angular velocity on X, Y and Z axis | Radians per second |
173 +-------------------------------------+---------------------------+
174 | Delta velocity on X. Y, and Z axis | Meters per Second |
175 +-------------------------------------+---------------------------+
176 | Delta angle on X, Y, and Z axis | Radians |
177 +-------------------------------------+---------------------------+
178 | Temperature | Millidegrees Celsius |
179 +-------------------------------------+---------------------------+
180
181 Usage examples
182 --------------
183
184 Show device name:
185
186 .. code-block:: bash
187
188 root:/sys/bus/iio/devices/iio:device0> cat name
189 adis16505-2
190
191 Show accelerometer channels value:
192
193 .. code-block:: bash
194
195 root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
196 -275924
197 root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
198 -30142222
199 root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
200 261265769
201 root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
202 0.000000037
203
204 - X-axis acceleration = in_accel_x_raw * in_accel_scale = −0.010209188 m/s^2
205 - Y-axis acceleration = in_accel_y_raw * in_accel_scale = −1.115262214 m/s^2
206 - Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.666833453 m/s^2
207
208 Show gyroscope channels value:
209
210 .. code-block:: bash
211
212 root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
213 -3324626
214 root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
215 1336980
216 root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
217 -602983
218 root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
219 0.000000006
220
221 - X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = −0.019947756 rad/s
222 - Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = 0.00802188 rad/s
223 - Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = −0.003617898 rad/s
224
225 Set calibration offset for accelerometer channels:
226
227 .. code-block:: bash
228
229 root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
230 0
231
232 root:/sys/bus/iio/devices/iio:device0> echo 5000 > in_accel_x_calibbias
233 root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
234 5000
235
236 Set calibration offset for gyroscope channels:
237
238 .. code-block:: bash
239
240 root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
241 0
242
243 root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_calibbias
244 root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
245 -5000
246
247 Set sampling frequency:
248
249 .. code-block:: bash
250
251 root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
252 2000.000000
253
254 root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
255 1000.000000
256
257 Set bandwidth for accelerometer and gyroscope:
258
259 .. code-block:: bash
260
261 root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
262 720
263
264 root:/sys/bus/iio/devices/iio:device0> echo 360 > filter_low_pass_3db_frequency
265 root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
266 360
267
268 Show serial number:
269
270 .. code-block:: bash
271
272 root:/sys/kernel/debug/iio/iio:device0> cat serial_number
273 0x04f9
274
275 Show product id:
276
277 .. code-block:: bash
278
279 root:/sys/kernel/debug/iio/iio:device0> cat product_id
280 16505
281
282 Show flash count:
283
284 .. code-block:: bash
285
286 root:/sys/kernel/debug/iio/iio:device0> cat flash_count
287 150
288
289 Show firmware revision:
290
291 .. code-block:: bash
292
293 root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
294 1.6
295
296 Show firmware date:
297
298 .. code-block:: bash
299
300 root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
301 06-27-2019
302
303 3. Device buffers
304 =================
305
306 This driver supports IIO buffers.
307
308 All devices support retrieving the raw acceleration, gyroscope and temperature
309 measurements using buffers.
310
311 The following device families also support retrieving the delta velocity, delta
312 angle and temperature measurements using buffers:
313
314 - ADIS16477
315 - ADIS16500
316 - ADIS16505
317 - ADIS16507
318
319 However, when retrieving acceleration or gyroscope data using buffers, delta
320 readings will not be available and vice versa.
321
322 Usage examples
323 --------------
324
325 Set device trigger in current_trigger, if not already set:
326
327 .. code-block:: bash
328
329 root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
330
331 root:/sys/bus/iio/devices/iio:device0> echo adis16505-2-dev0 > trigger/current_trigger
332 root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
333 adis16505-2-dev0
334
335 Select channels for buffer read:
336
337 .. code-block:: bash
338
339 root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_x_en
340 root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_y_en
341 root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_z_en
342 root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp0_en
343
344 Set the number of samples to be stored in the buffer:
345
346 .. code-block:: bash
347
348 root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length
349
350 Enable buffer readings:
351
352 .. code-block:: bash
353
354 root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable
355
356 Obtain buffered data:
357
358 .. code-block:: bash
359
360 root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0
361 ...
362 00001680 01 1f 00 00 ff ff fe ef 00 00 47 bf 00 03 35 55 |..........G...5U|
363 00001690 01 1f 00 00 ff ff ff d9 00 00 46 f1 00 03 35 35 |..........F...55|
364 000016a0 01 1f 00 00 ff ff fe fc 00 00 46 cb 00 03 35 7b |..........F...5{|
365 000016b0 01 1f 00 00 ff ff fe 41 00 00 47 0d 00 03 35 8b |.......A..G...5.|
366 000016c0 01 1f 00 00 ff ff fe 37 00 00 46 b4 00 03 35 90 |.......7..F...5.|
367 000016d0 01 1d 00 00 ff ff fe 5a 00 00 45 d7 00 03 36 08 |.......Z..E...6.|
368 000016e0 01 1b 00 00 ff ff fe fb 00 00 45 e7 00 03 36 60 |..........E...6`|
369 000016f0 01 1a 00 00 ff ff ff 17 00 00 46 bc 00 03 36 de |..........F...6.|
370 00001700 01 1a 00 00 ff ff fe 59 00 00 46 d7 00 03 37 b8 |.......Y..F...7.|
371 00001710 01 1a 00 00 ff ff fe ae 00 00 46 95 00 03 37 ba |..........F...7.|
372 00001720 01 1a 00 00 ff ff fe c5 00 00 46 63 00 03 37 9f |..........Fc..7.|
373 00001730 01 1a 00 00 ff ff fe 55 00 00 46 89 00 03 37 c1 |.......U..F...7.|
374 00001740 01 1a 00 00 ff ff fe 31 00 00 46 aa 00 03 37 f7 |.......1..F...7.|
375 ...
376
377 See ``Documentation/iio/iio_devbuf.rst`` for more information about how buffered
378 data is structured.
379
380 4. IIO Interfacing Tools
381 ========================
382
383 See ``Documentation/iio/iio_tools.rst`` for the description of the available IIO
384 interfacing tools.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.