1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4ADXL345 driver 5=============== 6 7This driver supports Analog Device's ADXL345/375 on SPI/I2C bus. 8 91. Supported Devices 10==================== 11 12* `ADXL345 <https://www.analog.com/ADXL345>`_ 13* `ADXL375 <https://www.analog.com/ADXL375>`_ 14 15The ADXL345 is a general-purpose, low-power, 3-axis accelerometer with selectable 16measurement ranges. The ADXL345 supports the following ranges: 17 18- ±2g (approx. ±19.61 m/s^2) 19- ±4g (approx. ±39.23 m/s^2) 20- ±8g (approx. ±78.45 m/s^2) 21- ±16g (approx. ±156.91 m/s^2) 22 232. Device Attributes 24==================== 25 26Each IIO device has a device folder under ``/sys/bus/iio/devices/iio:deviceX``, 27where X is the IIO index of the device. Under these folders reside a set of 28device files, depending on the characteristics and features of the hardware 29device in question. These files are consistently generalized and documented in 30the IIO ABI documentation. 31 32The following table shows the ADXL345 related device files, found in the 33specific device folder path ``/sys/bus/iio/devices/iio:deviceX``. 34 35+-------------------------------------------+----------------------------------------------------------+ 36| 3-Axis Accelerometer related device files | Description | 37+-------------------------------------------+----------------------------------------------------------+ 38| in_accel_sampling_frequency | Currently selected sample rate. | 39+-------------------------------------------+----------------------------------------------------------+ 40| in_accel_sampling_frequency_available | Available sampling frequency configurations. | 41+-------------------------------------------+----------------------------------------------------------+ 42| in_accel_scale | Scale/range for the accelerometer channels. | 43+-------------------------------------------+----------------------------------------------------------+ 44| in_accel_scale_available | Available scale ranges for the accelerometer channel. | 45+-------------------------------------------+----------------------------------------------------------+ 46| in_accel_x_calibbias | Calibration offset for the X-axis accelerometer channel. | 47+-------------------------------------------+----------------------------------------------------------+ 48| in_accel_x_raw | Raw X-axis accelerometer channel value. | 49+-------------------------------------------+----------------------------------------------------------+ 50| in_accel_y_calibbias | Y-axis acceleration offset correction | 51+-------------------------------------------+----------------------------------------------------------+ 52| in_accel_y_raw | Raw Y-axis accelerometer channel value. | 53+-------------------------------------------+----------------------------------------------------------+ 54| in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. | 55+-------------------------------------------+----------------------------------------------------------+ 56| in_accel_z_raw | Raw Z-axis accelerometer channel value. | 57+-------------------------------------------+----------------------------------------------------------+ 58 59Channel Processed Values 60------------------------- 61 62A channel value can be read from its _raw attribute. The value returned is the 63raw value as reported by the devices. To get the processed value of the channel, 64apply the following formula: 65 66.. code-block:: bash 67 68 processed value = (_raw + _offset) * _scale 69 70Where _offset and _scale are device attributes. If no _offset attribute is 71present, simply assume its value is 0. 72 73+-------------------------------------+---------------------------+ 74| Channel type | Measurement unit | 75+-------------------------------------+---------------------------+ 76| Acceleration on X, Y, and Z axes | Meters per second squared | 77+-------------------------------------+---------------------------+ 78 79Sensor Events 80------------- 81 82Specific IIO events are triggered by their corresponding interrupts. The sensor 83driver supports either none or a single active interrupt (INT) line, selectable 84from the two available options: INT1 or INT2. The active INT line should be 85specified in the device tree. If no INT line is configured, the sensor defaults 86to FIFO bypass mode, where event detection is disabled and only individual 87X, Y, and Z axis measurements are available. 88 89The table below lists the ADXL345-related device files located in the 90device-specific path: ``/sys/bus/iio/devices/iio:deviceX/events``. 91Note that activity and inactivity detection are DC-coupled by default; 92therefore, only the AC-coupled activity and inactivity events are explicitly 93listed. 94 95+---------------------------------------------+---------------------------------------------+ 96| Event handle | Description | 97+---------------------------------------------+---------------------------------------------+ 98| in_accel_gesture_doubletap_en | Enable double tap detection on all axes | 99+---------------------------------------------+---------------------------------------------+ 100| in_accel_gesture_doubletap_reset_timeout | Double tap window in [us] | 101+---------------------------------------------+---------------------------------------------+ 102| in_accel_gesture_doubletap_scale | Double tap gesture threshold scale. | 103+---------------------------------------------+---------------------------------------------+ 104| in_accel_gesture_doubletap_tap2_min_delay | Double tap latency in [us] | 105+---------------------------------------------+---------------------------------------------+ 106| in_accel_gesture_doubletap_value | Double tap threshold value | 107+---------------------------------------------+---------------------------------------------+ 108| in_accel_gesture_singletap_scale | Single tap gesture threshold scale. | 109+---------------------------------------------+---------------------------------------------+ 110| in_accel_gesture_singletap_timeout | Single tap duration in [us] | 111+---------------------------------------------+---------------------------------------------+ 112| in_accel_gesture_singletap_value | Single tap threshold value | 113+---------------------------------------------+---------------------------------------------+ 114| in_accel_mag_adaptive_falling_period | AC coupled inactivity time in seconds | 115+---------------------------------------------+---------------------------------------------+ 116| in_accel_mag_adaptive_falling_scale | AC coupled inactivity threshold scale. | 117+---------------------------------------------+---------------------------------------------+ 118| in_accel_mag_adaptive_falling_value | AC coupled inactivity threshold | 119+---------------------------------------------+---------------------------------------------+ 120| in_accel_mag_adaptive_rising_en | Enable AC coupled activity on X axis | 121+---------------------------------------------+---------------------------------------------+ 122| in_accel_mag_adaptive_rising_scale | AC coupled activity threshold scale. | 123+---------------------------------------------+---------------------------------------------+ 124| in_accel_mag_adaptive_rising_value | AC coupled activity threshold | 125+---------------------------------------------+---------------------------------------------+ 126| in_accel_mag_falling_period | Inactivity time in seconds | 127+---------------------------------------------+---------------------------------------------+ 128| in_accel_mag_falling_scale | DC coupled inactivity threshold scale. | 129+---------------------------------------------+---------------------------------------------+ 130| in_accel_mag_falling_value | Inactivity threshold value | 131+---------------------------------------------+---------------------------------------------+ 132| in_accel_mag_rising_en | Enable activity detection on X axis | 133+---------------------------------------------+---------------------------------------------+ 134| in_accel_mag_rising_scale | DC coupled activity threshold scale. | 135+---------------------------------------------+---------------------------------------------+ 136| in_accel_mag_rising_value | Activity threshold value | 137+---------------------------------------------+---------------------------------------------+ 138| in_accel_x&y&z_mag_adaptive_falling_en | Enable AC coupled inactivity on all axes | 139+---------------------------------------------+---------------------------------------------+ 140| in_accel_x&y&z_mag_falling_en | Enable inactivity detection on all axes | 141+---------------------------------------------+---------------------------------------------+ 142| in_accel_x_gesture_singletap_en | Enable single tap detection on X axis | 143+---------------------------------------------+---------------------------------------------+ 144| in_accel_y_gesture_singletap_en | Enable single tap detection on Y axis | 145+---------------------------------------------+---------------------------------------------+ 146| in_accel_z_gesture_singletap_en | Enable single tap detection on Z axis | 147+---------------------------------------------+---------------------------------------------+ 148 149Please refer to the sensor's datasheet for a detailed description of this 150functionality. 151 152Manually setting the **ODR** will cause the driver to estimate default values 153for inactivity detection timing, where higher ODR values correspond to longer 154default wait times, and lower ODR values to shorter ones. If these defaults do 155not meet your application’s needs, you can explicitly configure the inactivity 156wait time. Setting this value to 0 will revert to the default behavior. 157 158When changing the **g range** configuration, the driver attempts to estimate 159appropriate activity and inactivity thresholds by scaling the default values 160based on the ratio of the previous range to the new one. The resulting threshold 161will never be zero and will always fall between 1 and 255, corresponding to up 162to 62.5 mg/LSB (0.612915 m/s^2/LSB) as specified in the datasheet. However, 163you can override these estimated thresholds by setting explicit values. 164 165When **activity** and **inactivity** events are enabled, the driver 166automatically manages hysteresis behavior by setting the **link** and 167**auto-sleep** bits. The link bit connects the activity and inactivity 168functions, so that one follows the other. The auto-sleep function puts the 169sensor into sleep mode when inactivity is detected, reducing power consumption 170to the sub-12.5 Hz rate. 171 172The inactivity time is configurable between 1 and 255 seconds. In addition to 173inactivity detection, the sensor also supports free-fall detection, which, from 174the IIO perspective, is treated as a fall in magnitude across all axes. In 175sensor terms, free-fall is defined using an inactivity period ranging from 0.000 176to 1.000 seconds. 177 178The driver behaves as follows: 179 180* If the configured inactivity period is 1 second or more, the driver uses the 181 sensor's inactivity register. This allows the event to be linked with 182 activity detection, use auto-sleep, and be either AC- or DC-coupled. 183 184* If the inactivity period is less than 1 second, the event is treated as plain 185 inactivity or free-fall detection. In this case, auto-sleep and coupling 186 (AC/DC) are not applied. 187 188* If an inactivity time of 0 seconds is configured, the driver selects a 189 heuristically determined default period (greater than 1 second) to optimize 190 power consumption. This also uses the inactivity register. 191 192Note: According to the datasheet, the optimal ODR for detecting activity, 193or inactivity (or when operating with the free-fall register) should fall within 194the range of 12.5 Hz to 400 Hz. The recommended free-fall threshold is between 195300 mg and 600 mg (register values 0x05 to 0x09). 196 197In DC-coupled mode, the current acceleration magnitude is directly compared to 198the values in the THRESH_ACT and THRESH_INACT registers to determine activity or 199inactivity. In contrast, AC-coupled activity detection uses the acceleration 200value at the start of detection as a reference point, and subsequent samples are 201compared against this reference. While DC-coupling is the default mode-comparing 202live values to fixed thresholds-AC-coupling relies on an internal filter 203relative to the configured threshold. 204 205AC and DC coupling modes are configured separately for activity and inactivity 206detection, but only one mode can be active at a time for each. For example, if 207AC-coupled activity detection is enabled and then DC-coupled mode is set, only 208DC-coupled activity detection will be active. In other words, only the most 209recent configuration is applied. 210 211**Single tap** detection can be configured per the datasheet by setting the 212threshold and duration parameters. When only single tap detection is enabled, 213the single tap interrupt triggers as soon as the acceleration exceeds the 214threshold (marking the start of the duration) and then falls below it, provided 215the duration limit is not exceeded. If both single tap and double tap detections 216are enabled, the single tap interrupt is triggered only after the double tap 217event has been either confirmed or dismissed. 218 219To configure **double tap** detection, you must also set the window and latency 220parameters in microseconds (µs). The latency period begins once the single tap 221signal drops below the threshold and acts as a waiting time during which any 222spikes are ignored for double tap detection. After the latency period ends, the 223detection window starts. If the acceleration rises above the threshold and then 224falls below it again within this window, a double tap event is triggered upon 225the fall below the threshold. 226 227Double tap event detection is thoroughly explained in the datasheet. After a 228single tap event is detected, a double tap event may follow, provided the signal 229meets certain criteria. However, double tap detection can be invalidated for 230three reasons: 231 232* If the **suppress bit** is set, any acceleration spike above the tap 233 threshold during the tap latency period immediately invalidates the double tap 234 detection. In other words, no spikes are allowed during latency when the 235 suppress bit is active. 236 237* The double tap event is invalid if the acceleration is above the threshold at 238 the start of the double tap window. 239 240* Double tap detection is also invalidated if the acceleration duration exceeds 241 the limit set by the duration register. 242 243For double tap detection, the same duration applies as for single tap: the 244acceleration must rise above the threshold and then fall below it within the 245specified duration. Note that the suppress bit is typically enabled when double 246tap detection is active. 247 248Usage Examples 249-------------- 250 251Show device name: 252 253.. code-block:: bash 254 255 root:/sys/bus/iio/devices/iio:device0> cat name 256 adxl345 257 258Show accelerometer channels value: 259 260.. code-block:: bash 261 262 root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw 263 -1 264 root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw 265 2 266 root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw 267 -253 268 269Set calibration offset for accelerometer channels: 270 271.. code-block:: bash 272 273 root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias 274 0 275 276 root:/sys/bus/iio/devices/iio:device0> echo 50 > in_accel_x_calibbias 277 root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias 278 50 279 280Given the 13-bit full resolution, the available ranges are calculated by the 281following formula: 282 283.. code-block:: bash 284 285 (g * 2 * 9.80665) / (2^(resolution) - 1) * 100; for g := 2|4|8|16 286 287Scale range configuration: 288 289.. code-block:: bash 290 291 root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_scale 292 0.004789 293 root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_scale_available 294 0.004789 0.009578 0.019156 0.038312 295 296 root:/sys/bus/iio/devices/iio:device0> echo 0.019156 > ./in_accel_scale 297 root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_scale 298 0.019156 299 300Set output data rate (ODR): 301 302.. code-block:: bash 303 304 root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_sampling_frequency 305 200.000000 306 307 root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_sampling_frequency_available 308 0.097000 0.195000 0.390000 0.781000 1.562000 3.125000 6.250000 12.500000 25.000000 50.000000 100.000000 200.000000 400.000000 800.000000 1600.000000 3200.000000 309 310 root:/sys/bus/iio/devices/iio:device0> echo 1.562000 > ./in_accel_sampling_frequency 311 root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_sampling_frequency 312 1.562000 313 314Configure one or several events: 315 316.. code-block:: bash 317 318 root:> cd /sys/bus/iio/devices/iio:device0 319 320 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./buffer0/in_accel_x_en 321 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./buffer0/in_accel_y_en 322 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./buffer0/in_accel_z_en 323 324 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./scan_elements/in_accel_x_en 325 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./scan_elements/in_accel_y_en 326 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./scan_elements/in_accel_z_en 327 328 root:/sys/bus/iio/devices/iio:device0> echo 14 > ./in_accel_x_calibbias 329 root:/sys/bus/iio/devices/iio:device0> echo 2 > ./in_accel_y_calibbias 330 root:/sys/bus/iio/devices/iio:device0> echo -250 > ./in_accel_z_calibbias 331 332 root:/sys/bus/iio/devices/iio:device0> echo 24 > ./buffer0/length 333 334 ## Check the event scale factor (0.0625 * 9.80665) 335 root:/sys/bus/iio/devices/iio:device0> cat ./events/in_accel_gesture_doubletap_scale 336 0.612915 337 338 ## AC coupled activity, threshold [0.612915 m/s^2/LSB] 339 root:/sys/bus/iio/devices/iio:device0> echo 6 > ./events/in_accel_mag_adaptive_rising_value 340 341 ## AC coupled inactivity, threshold, [0.612915 m/s^2/LSB] 342 root:/sys/bus/iio/devices/iio:device0> echo 4 > ./events/in_accel_mag_adaptive_falling_value 343 344 ## AC coupled inactivity, time [s] 345 root:/sys/bus/iio/devices/iio:device0> echo 3 > ./events/in_accel_mag_adaptive_falling_period 346 347 ## singletap, threshold 348 root:/sys/bus/iio/devices/iio:device0> echo 35 > ./events/in_accel_gesture_singletap_value 349 350 ## singletap, duration [us] 351 root:/sys/bus/iio/devices/iio:device0> echo 0.001875 > ./events/in_accel_gesture_singletap_timeout 352 353 ## doubletap, window [us] 354 root:/sys/bus/iio/devices/iio:device0> echo 0.025 > ./events/in_accel_gesture_doubletap_reset_timeout 355 356 ## doubletap, latency [us] 357 root:/sys/bus/iio/devices/iio:device0> echo 0.025 > ./events/in_accel_gesture_doubletap_tap2_min_delay 358 359 ## AC coupled activity, enable 360 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_mag_adaptive_rising_en 361 362 ## AC coupled inactivity, enable 363 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\&y\&z_mag_adaptive_falling_en 364 365 ## singletap, enable 366 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x_gesture_singletap_en 367 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_y_gesture_singletap_en 368 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_z_gesture_singletap_en 369 370 ## doubletap, enable 371 root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_gesture_doubletap_en 372 373Verify incoming events: 374 375.. code-block:: bash 376 377 root:# iio_event_monitor adxl345 378 Found IIO device with name adxl345 with device number 0 379 Event: time: 1739063415957073383, type: accel(z), channel: 0, evtype: mag, direction: rising 380 Event: time: 1739063415963770218, type: accel(z), channel: 0, evtype: mag, direction: rising 381 Event: time: 1739063416002563061, type: accel(z), channel: 0, evtype: gesture, direction: singletap 382 Event: time: 1739063426271128739, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling 383 Event: time: 1739063436539080713, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling 384 Event: time: 1739063438357970381, type: accel(z), channel: 0, evtype: mag, direction: rising 385 Event: time: 1739063446726161586, type: accel(z), channel: 0, evtype: mag, direction: rising 386 Event: time: 1739063446727892670, type: accel(z), channel: 0, evtype: mag, direction: rising 387 Event: time: 1739063446743019768, type: accel(z), channel: 0, evtype: mag, direction: rising 388 Event: time: 1739063446744650696, type: accel(z), channel: 0, evtype: mag, direction: rising 389 Event: time: 1739063446763559386, type: accel(z), channel: 0, evtype: gesture, direction: singletap 390 Event: time: 1739063448818126480, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling 391 ... 392 393Activity and inactivity belong together and indicate state changes as follows 394 395.. code-block:: bash 396 397 root:# iio_event_monitor adxl345 398 Found IIO device with name adxl345 with device number 0 399 Event: time: 1744648001133946293, type: accel(x), channel: 0, evtype: mag, direction: rising 400 <after inactivity time elapsed> 401 Event: time: 1744648057724775499, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling 402 ... 403 4043. Device Buffers 405================= 406 407This driver supports IIO buffers. 408 409All devices support retrieving the raw acceleration and temperature measurements 410using buffers. 411 412Usage examples 413-------------- 414 415Select channels for buffer read: 416 417.. code-block:: bash 418 419 root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_x_en 420 root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_y_en 421 root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_z_en 422 423Set the number of samples to be stored in the buffer: 424 425.. code-block:: bash 426 427 root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length 428 429Enable buffer readings: 430 431.. code-block:: bash 432 433 root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable 434 435Obtain buffered data: 436 437.. code-block:: bash 438 439 root:> iio_readdev -b 16 -s 1024 adxl345 | hexdump -d 440 WARNING: High-speed mode not enabled 441 0000000 00003 00012 00013 00005 00010 00011 00005 00011 442 0000010 00013 00004 00012 00011 00003 00012 00014 00007 443 0000020 00011 00013 00004 00013 00014 00003 00012 00013 444 0000030 00004 00012 00013 00005 00011 00011 00005 00012 445 0000040 00014 00005 00012 00014 00004 00010 00012 00004 446 0000050 00013 00011 00003 00011 00012 00005 00011 00013 447 0000060 00003 00012 00012 00003 00012 00012 00004 00012 448 0000070 00012 00003 00013 00013 00003 00013 00012 00005 449 0000080 00012 00013 00003 00011 00012 00005 00012 00013 450 0000090 00003 00013 00011 00005 00013 00014 00003 00012 451 00000a0 00012 00003 00012 00013 00004 00012 00015 00004 452 00000b0 00014 00011 00003 00014 00013 00004 00012 00011 453 00000c0 00004 00012 00013 00004 00014 00011 00004 00013 454 00000d0 00012 00002 00014 00012 00005 00012 00013 00005 455 00000e0 00013 00013 00003 00013 00013 00005 00012 00013 456 00000f0 00004 00014 00015 00005 00012 00011 00005 00012 457 ... 458 459See Documentation/iio/iio_devbuf.rst for more information about how buffered 460data is structured. 461 4624. IIO Interfacing Tools 463======================== 464 465See Documentation/iio/iio_tools.rst for the description of the available IIO 466interfacing tools. 467