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