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