1.. SPDX-License-Identifier: GPL-2.0 2 3================ 4ADIS16475 driver 5================ 6 7This driver supports Analog Device's IMUs on SPI bus. 8 91. 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 21Each supported device is a precision, miniature microelectromechanical system 22(MEMS) inertial measurement unit (IMU) that includes a triaxial gyroscope and a 23triaxial accelerometer. Each inertial sensor in the IMU device combines with 24signal conditioning that optimizes dynamic performance. The factory calibration 25characterizes each sensor for sensitivity, bias, alignment, linear acceleration 26(gyroscope bias), and point of percussion (accelerometer location). As a result, 27each sensor has dynamic compensation formulas that provide accurate sensor 28measurements over a broad set of conditions. 29 302. Device attributes 31==================== 32 33Accelerometer, gyroscope measurements are always provided. Furthermore, the 34driver offers the capability to retrieve the delta angle and the delta velocity 35measurements computed by the device. 36 37The delta angle measurements represent a calculation of angular displacement 38between each sample update, while the delta velocity measurements represent a 39calculation of linear velocity change between each sample update. 40 41Finally, temperature data are provided which show a coarse measurement of 42the temperature inside of the IMU device. This data is most useful for 43monitoring relative changes in the thermal environment. 44 45The signal chain of each inertial sensor (accelerometers and gyroscopes) 46includes the application of unique correction formulas, which are derived from 47extensive characterization of bias, sensitivity, alignment, response to linear 48acceleration (gyroscopes), and point of percussion (accelerometer location) 49over a temperature range of −40°C to +85°C, for each ADIS device. These 50correction formulas are not accessible, but users do have the opportunity to 51adjust the bias for each sensor individually through the calibbias attribute. 52 53Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``, 54where X is the IIO index of the device. Under these folders reside a set of 55device files, depending on the characteristics and features of the hardware 56device in questions. These files are consistently generalized and documented in 57the IIO ABI documentation. 58 59The following tables show the adis16475 related device files, found in the 60specific 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 132The following table shows the adis16475 related device debug files, found in the 133specific 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 149Channels processed values 150------------------------- 151 152A channel value can be read from its _raw attribute. The value returned is the 153raw value as reported by the devices. To get the processed value of the channel, 154apply the following formula: 155 156.. code-block:: bash 157 158 processed value = (_raw + _offset) * _scale 159 160Where _offset and _scale are device attributes. If no _offset attribute is 161present, simply assume its value is 0. 162 163The adis16475 driver offers data for 5 types of channels, the table below shows 164the measurement units for the processed value, which are defined by the IIO 165framework: 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 181Usage examples 182-------------- 183 184Show device name: 185 186.. code-block:: bash 187 188 root:/sys/bus/iio/devices/iio:device0> cat name 189 adis16505-2 190 191Show 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 208Show 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 225Set 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 236Set 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 247Set 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 257Set 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 268Show serial number: 269 270.. code-block:: bash 271 272 root:/sys/kernel/debug/iio/iio:device0> cat serial_number 273 0x04f9 274 275Show product id: 276 277.. code-block:: bash 278 279 root:/sys/kernel/debug/iio/iio:device0> cat product_id 280 16505 281 282Show flash count: 283 284.. code-block:: bash 285 286 root:/sys/kernel/debug/iio/iio:device0> cat flash_count 287 150 288 289Show firmware revision: 290 291.. code-block:: bash 292 293 root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision 294 1.6 295 296Show firmware date: 297 298.. code-block:: bash 299 300 root:/sys/kernel/debug/iio/iio:device0> cat firmware_date 301 06-27-2019 302 3033. Device buffers 304================= 305 306This driver supports IIO buffers. 307 308All devices support retrieving the raw acceleration, gyroscope and temperature 309measurements using buffers. 310 311The following device families also support retrieving the delta velocity, delta 312angle and temperature measurements using buffers: 313 314- ADIS16477 315- ADIS16500 316- ADIS16505 317- ADIS16507 318 319However, when retrieving acceleration or gyroscope data using buffers, delta 320readings will not be available and vice versa. 321 322Usage examples 323-------------- 324 325Set 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 335Select 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 344Set 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 350Enable buffer readings: 351 352.. code-block:: bash 353 354 root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable 355 356Obtain 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 377See ``Documentation/iio/iio_devbuf.rst`` for more information about how buffered 378data is structured. 379 3804. IIO Interfacing Tools 381======================== 382 383Linux Kernel Tools 384------------------ 385 386Linux Kernel provides some userspace tools that can be used to retrieve data 387from IIO sysfs: 388 389* lsiio: example application that provides a list of IIO devices and triggers 390* iio_event_monitor: example application that reads events from an IIO device 391 and prints them 392* iio_generic_buffer: example application that reads data from buffer 393* iio_utils: set of APIs, typically used to access sysfs files. 394 395LibIIO 396------ 397 398LibIIO is a C/C++ library that provides generic access to IIO devices. The 399library abstracts the low-level details of the hardware, and provides a simple 400yet complete programming interface that can be used for advanced projects. 401 402For more information about LibIIO, please see: 403https://github.com/analogdevicesinc/libiio 404