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