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_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.