Documentation / iio / adis16475.rst


Based on kernel version 6.9. Page generated on 2024-05-14 10:02 EST.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407
.. SPDX-License-Identifier: GPL-2.0

================
ADIS16475 driver
================

This driver supports Analog Device's IMUs on SPI bus.

1. Supported devices
====================

* `ADIS16465 <https://www.analog.com/ADIS16465>`_
* `ADIS16467 <https://www.analog.com/ADIS16467>`_
* `ADIS16470 <https://www.analog.com/ADIS16470>`_
* `ADIS16475 <https://www.analog.com/ADIS16475>`_
* `ADIS16477 <https://www.analog.com/ADIS16477>`_
* `ADIS16500 <https://www.analog.com/ADIS16500>`_
* `ADIS16505 <https://www.analog.com/ADIS16505>`_
* `ADIS16507 <https://www.analog.com/ADIS16507>`_

Each supported device is a precision, miniature microelectromechanical system
(MEMS) inertial measurement unit (IMU) that includes a triaxial gyroscope and a
triaxial accelerometer. Each inertial sensor in the IMU device combines with
signal conditioning that optimizes dynamic performance. The factory calibration
characterizes each sensor for sensitivity, bias, alignment, linear acceleration
(gyroscope bias), and point of percussion (accelerometer location). As a result,
each sensor has dynamic compensation formulas that provide accurate sensor
measurements over a broad set of conditions.

2. Device attributes
====================

Accelerometer, gyroscope measurements are always provided. Furthermore, the
driver offers the capability to retrieve the delta angle and the delta velocity
measurements computed by the device.

The delta angle measurements represent a calculation of angular displacement
between each sample update, while the delta velocity measurements represent a
calculation of linear velocity change between each sample update.

Finally, temperature data are provided which show a coarse measurement of
the temperature inside of the IMU device. This data is most useful for
monitoring relative changes in the thermal environment.

The signal chain of each inertial sensor (accelerometers and gyroscopes)
includes the application of unique correction formulas, which are derived from
extensive characterization of bias, sensitivity, alignment, response to linear
acceleration (gyroscopes), and point of percussion (accelerometer location)
over a temperature range of −40°C to +85°C, for each ADIS device. These
correction formulas are not accessible, but users do have the opportunity to
adjust the bias for each sensor individually through the calibbias attribute.

Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
where X is the IIO index of the device. Under these folders reside a set of
device files, depending on the characteristics and features of the hardware
device in questions. These files are consistently generalized and documented in
the IIO ABI documentation.

The following tables show the adis16475 related device files, found in the
specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.

+-------------------------------------------+----------------------------------------------------------+
| 3-Axis Accelerometer related device files | Description                                              |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_scale                            | Scale for the accelerometer channels.                    |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_x_calibbias                      | Calibration offset for the X-axis accelerometer channel. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_calibbias_x                      | x-axis acceleration offset correction                    |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_x_raw                            | Raw X-axis accelerometer channel value.                  |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_calibbias_y                      | y-axis acceleration offset correction                    |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_y_raw                            | Raw Y-axis accelerometer channel value.                  |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_z_calibbias                      | Calibration offset for the Z-axis accelerometer channel. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_z_raw                            | Raw Z-axis accelerometer channel value.                  |
+-------------------------------------------+----------------------------------------------------------+
| in_deltavelocity_scale                    | Scale for delta velocity channels.                       |
+-------------------------------------------+----------------------------------------------------------+
| in_deltavelocity_x_raw                    | Raw X-axis delta velocity channel value.                 |
+-------------------------------------------+----------------------------------------------------------+
| in_deltavelocity_y_raw                    | Raw Y-axis delta velocity channel value.                 |
+-------------------------------------------+----------------------------------------------------------+
| in_deltavelocity_z_raw                    | Raw Z-axis delta velocity channel value.                 |
+-------------------------------------------+----------------------------------------------------------+

+---------------------------------------+------------------------------------------------------+
| 3-Axis Gyroscope related device files | Description                                          |
+---------------------------------------+------------------------------------------------------+
| in_anglvel_scale                      | Scale for the gyroscope channels.                    |
+---------------------------------------+------------------------------------------------------+
| in_anglvel_x_calibbias                | Calibration offset for the X-axis gyroscope channel. |
+---------------------------------------+------------------------------------------------------+
| in_anglvel_calibbias_x                | x-axis gyroscope offset correction                   |
+---------------------------------------+------------------------------------------------------+
| in_anglvel_x_raw                      | Raw X-axis gyroscope channel value.                  |
+---------------------------------------+------------------------------------------------------+
| in_anglvel_calibbias_y                | y-axis gyroscope offset correction                   |
+---------------------------------------+------------------------------------------------------+
| in_anglvel_y_raw                      | Raw Y-axis gyroscope channel value.                  |
+---------------------------------------+------------------------------------------------------+
| in_anglvel_z_calibbias                | Calibration offset for the Z-axis gyroscope channel. |
+---------------------------------------+------------------------------------------------------+
| in_anglvel_z_raw                      | Raw Z-axis gyroscope channel value.                  |
+---------------------------------------+------------------------------------------------------+
| in_deltaangl_scale                    | Scale for delta angle channels.                      |
+---------------------------------------+------------------------------------------------------+
| in_deltaangl_x_raw                    | Raw X-axis delta angle channel value.                |
+---------------------------------------+------------------------------------------------------+
| in_deltaangl_y_raw                    | Raw Y-axis delta angle channel value.                |
+---------------------------------------+------------------------------------------------------+
| in_deltaangl_z_raw                    | Raw Z-axis delta angle channel value.                |
+---------------------------------------+------------------------------------------------------+

+----------------------------------+-------------------------------------------+
| Temperature sensor related files | Description                               |
+----------------------------------+-------------------------------------------+
| in_temp0_raw                     | Raw temperature channel value.            |
+----------------------------------+-------------------------------------------+
| in_temp0_scale                   | Scale for the temperature sensor channel. |
+----------------------------------+-------------------------------------------+

+-------------------------------+---------------------------------------------------------+
| Miscellaneous device files    | Description                                             |
+-------------------------------+---------------------------------------------------------+
| name                          | Name of the IIO device.                                 |
+-------------------------------+---------------------------------------------------------+
| sampling_frequency            | Currently selected sample rate.                         |
+-------------------------------+---------------------------------------------------------+
| filter_low_pass_3db_frequency | Bandwidth for the accelerometer and gyroscope channels. |
+-------------------------------+---------------------------------------------------------+

The following table shows the adis16475 related device debug files, found in the
specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.

+----------------------+-------------------------------------------------------------------------+
| Debugfs device files | Description                                                             |
+----------------------+-------------------------------------------------------------------------+
| serial_number        | The serial number of the chip in hexadecimal format.                    |
+----------------------+-------------------------------------------------------------------------+
| product_id           | Chip specific product id (e.g. 16475, 16500, 16505, etc.).              |
+----------------------+-------------------------------------------------------------------------+
| flash_count          | The number of flash writes performed on the device.                     |
+----------------------+-------------------------------------------------------------------------+
| firmware_revision    | String containing the firmware revision in the following format ##.##.  |
+----------------------+-------------------------------------------------------------------------+
| firmware_date        | String containing the firmware date in the following format mm-dd-yyyy. |
+----------------------+-------------------------------------------------------------------------+

Channels processed values
-------------------------

A channel value can be read from its _raw attribute. The value returned is the
raw value as reported by the devices. To get the processed value of the channel,
apply the following formula:

.. code-block:: bash

        processed value = (_raw + _offset) * _scale

Where _offset and _scale are device attributes. If no _offset attribute is
present, simply assume its value is 0.

The adis16475 driver offers data for 5 types of channels, the table below shows
the measurement units for the processed value, which are defined by the IIO
framework:

+-------------------------------------+---------------------------+
| Channel type                        | Measurement unit          |
+-------------------------------------+---------------------------+
| Acceleration on X, Y, and Z axis    | Meters per Second squared |
+-------------------------------------+---------------------------+
| Angular velocity on X, Y and Z axis | Radians per second        |
+-------------------------------------+---------------------------+
| Delta velocity on X. Y, and Z axis  | Meters per Second         |
+-------------------------------------+---------------------------+
| Delta angle on X, Y, and Z axis     | Radians                   |
+-------------------------------------+---------------------------+
| Temperature                         | Millidegrees Celsius      |
+-------------------------------------+---------------------------+

Usage examples
--------------

Show device name:

.. code-block:: bash

	root:/sys/bus/iio/devices/iio:device0> cat name
        adis16505-2

Show accelerometer channels value:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
        -275924
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
        -30142222
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
        261265769
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
        0.000000037

- X-axis acceleration = in_accel_x_raw * in_accel_scale = −0.010209188 m/s^2
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = −1.115262214 m/s^2
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.666833453 m/s^2

Show gyroscope channels value:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
        -3324626
        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
        1336980
        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
        -602983
        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
        0.000000006

- X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = −0.019947756 rad/s
- Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = 0.00802188 rad/s
- Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = −0.003617898 rad/s

Set calibration offset for accelerometer channels:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
        0

        root:/sys/bus/iio/devices/iio:device0> echo 5000 > in_accel_x_calibbias
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
        5000

Set calibration offset for gyroscope channels:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
        0

        root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_calibbias
        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
        -5000

Set sampling frequency:

.. code-block:: bash

	root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
        2000.000000

        root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
        1000.000000

Set bandwidth for accelerometer and gyroscope:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
        720

        root:/sys/bus/iio/devices/iio:device0> echo 360 > filter_low_pass_3db_frequency
        root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
        360

Show serial number:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat serial_number
        0x04f9

Show product id:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat product_id
        16505

Show flash count:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat flash_count
        150

Show firmware revision:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
        1.6

Show firmware date:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
        06-27-2019

3. Device buffers
=================

This driver supports IIO buffers.

All devices support retrieving the raw acceleration, gyroscope and temperature
measurements using buffers.

The following device families also support retrieving the delta velocity, delta
angle and temperature measurements using buffers:

- ADIS16477
- ADIS16500
- ADIS16505
- ADIS16507

However, when retrieving acceleration or gyroscope data using buffers, delta
readings will not be available and vice versa.

Usage examples
--------------

Set device trigger in current_trigger, if not already set:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger

        root:/sys/bus/iio/devices/iio:device0> echo adis16505-2-dev0 > trigger/current_trigger
        root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
        adis16505-2-dev0

Select channels for buffer read:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_x_en
        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_y_en
        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_z_en
        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp0_en

Set the number of samples to be stored in the buffer:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length

Enable buffer readings:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable

Obtain buffered data:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0
        ...
        00001680  01 1f 00 00 ff ff fe ef  00 00 47 bf 00 03 35 55  |..........G...5U|
        00001690  01 1f 00 00 ff ff ff d9  00 00 46 f1 00 03 35 35  |..........F...55|
        000016a0  01 1f 00 00 ff ff fe fc  00 00 46 cb 00 03 35 7b  |..........F...5{|
        000016b0  01 1f 00 00 ff ff fe 41  00 00 47 0d 00 03 35 8b  |.......A..G...5.|
        000016c0  01 1f 00 00 ff ff fe 37  00 00 46 b4 00 03 35 90  |.......7..F...5.|
        000016d0  01 1d 00 00 ff ff fe 5a  00 00 45 d7 00 03 36 08  |.......Z..E...6.|
        000016e0  01 1b 00 00 ff ff fe fb  00 00 45 e7 00 03 36 60  |..........E...6`|
        000016f0  01 1a 00 00 ff ff ff 17  00 00 46 bc 00 03 36 de  |..........F...6.|
        00001700  01 1a 00 00 ff ff fe 59  00 00 46 d7 00 03 37 b8  |.......Y..F...7.|
        00001710  01 1a 00 00 ff ff fe ae  00 00 46 95 00 03 37 ba  |..........F...7.|
        00001720  01 1a 00 00 ff ff fe c5  00 00 46 63 00 03 37 9f  |..........Fc..7.|
        00001730  01 1a 00 00 ff ff fe 55  00 00 46 89 00 03 37 c1  |.......U..F...7.|
        00001740  01 1a 00 00 ff ff fe 31  00 00 46 aa 00 03 37 f7  |.......1..F...7.|
        ...

See ``Documentation/iio/iio_devbuf.rst`` for more information about how buffered
data is structured.

4. IIO Interfacing Tools
========================

Linux Kernel Tools
------------------

Linux Kernel provides some userspace tools that can be used to retrieve data
from IIO sysfs:

* lsiio: example application that provides a list of IIO devices and triggers
* iio_event_monitor: example application that reads events from an IIO device
  and prints them
* iio_generic_buffer: example application that reads data from buffer
* iio_utils: set of APIs, typically used to access sysfs files.

LibIIO
------

LibIIO is a C/C++ library that provides generic access to IIO devices. The
library abstracts the low-level details of the hardware, and provides a simple
yet complete programming interface that can be used for advanced projects.

For more information about LibIIO, please see:
https://github.com/analogdevicesinc/libiio