ADXL313 driver

장치 개요와 가속도 속성

이 드라이버는 SPI 또는 I²C 버스에 연결된 Analog Devices ADXL313을 지원합니다.

ADXL313은 잡음 밀도와 소비 전력이 낮은 3축 가속도계이며 측정 범위를 선택할 수 있습니다. 지원 범위는 ±0.5 g, ±1 g, ±2 g, ±4 g입니다.

가속도계 측정값은 항상 제공됩니다. 각 IIO 장치에는 `/sys/bus/iio/devices/iio:deviceX` 폴더가 있으며 X는 장치 인덱스입니다. 하드웨어 기능에 따른 파일이 이 경로 아래에 생성되고 IIO ABI 규칙을 따릅니다.

.. SPDX-License-Identifier: GPL-2.0

===============
ADXL313 driver
===============

This driver supports Analog Device's ADXL313 on SPI/I2C bus.

1. Supported devices
====================

* `ADXL313 <https://www.analog.com/ADXL313>`_

The ADXL313is a low noise density, low power, 3-axis accelerometer with
selectable measurement ranges. The ADXL313 supports the ±0.5 g, ±1 g, ±2 g and
±4 g ranges.

2. Device attributes
====================

Accelerometer measurements are always provided.

Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
where X is the IIO index of the device. Under these folders reside a set of
device files, depending on the characteristics and features of the hardware
device in questions. These files are consistently generalized and documented in
the IIO ABI documentation.

The following tables show the adxl313 related device files, found in the
specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.

+---------------------------------------------------+----------------------------------------------------------+
| 3-Axis Accelerometer related device files         | Description                                              |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_scale                                    | Scale for the accelerometer channels.                    |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x_calibbias                              | Calibration offset for the X-axis accelerometer channel. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x_raw                                    | Raw X-axis accelerometer channel value.                  |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_y_calibbias                              | y-axis acceleration offset correction                    |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_y_raw                                    | Raw Y-axis accelerometer channel value.                  |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_z_calibbias                              | Calibration offset for the Z-axis accelerometer channel. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_z_raw                                    | Raw Z-axis accelerometer channel value.                  |
+---------------------------------------------------+----------------------------------------------------------+

+---------------------------------------+----------------------------------------------+
| Miscellaneous device files            | Description                                  |
+---------------------------------------+----------------------------------------------+
| name                                  | Name of the IIO device.                      |
+---------------------------------------+----------------------------------------------+
| in_accel_sampling_frequency           | Currently selected sample rate.              |
+---------------------------------------+----------------------------------------------+
| in_accel_sampling_frequency_available | Available sampling frequency configurations. |
+---------------------------------------+----------------------------------------------+

Activity·inactivity 이벤트와 처리 단위

IIO 이벤트 설정 파일은 `/sys/bus/iio/devices/iio:deviceX/events`에 있습니다.

기본 결합 방식은 DC입니다. DC 이벤트는 설정한 임계값을 직접 사용하고, AC 결합에서는 데이터시트에 설명된 적응형 임계값을 센서가 적용합니다.

Activity인 `ACTIVITY` 또는 `ACTIVITY_AC`와 inactivity인 `INACTIVITY` 또는 `INACTIVITY_AC`를 함께 활성화하면 auto-sleep과 연결됩니다. DC activity와 AC inactivity 같은 교차 조합도 문제없이 사용할 수 있습니다.

`ACTIVITY`와 `ACTIVITY_AC`는 상호 배타적입니다. 예를 들어 `ACTIVITY`가 켜진 상태에서 `ACTIVITY_AC`를 켜면 드라이버는 앞의 `ACTIVITY`를 끄고 `ACTIVITY_AC`만 켭니다. Inactivity에도 같은 규칙이 적용됩니다.

이벤트를 끌 때는 실제 활성화된 종류와 일치해야 합니다. `ACTIVITY_AC`를 켠 뒤 이미 꺼져 있는 `ACTIVITY`를 끄는 요청은 다른 비활성 이벤트를 끄는 요청처럼 무시됩니다.

채널의 `_raw` 속성은 센서 원시 값을 반환합니다. 처리된 값은 다음 공식으로 계산합니다.

processed value = (_raw + _offset) * _scale

`_offset`과 `_scale`은 장치 속성입니다. `_offset`이 없으면 0으로 간주합니다. ADXL313이 제공하는 채널 유형은 가속도 하나이며 처리 단위는 X·Y·Z축 모두 m/s²입니다.

The iio event related settings, found in ``/sys/bus/iio/devices/iio:deviceX/events``.

+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_adaptive_falling_period              | AC coupled inactivity time.                              |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_adaptive_falling_value               | AC coupled inactivity threshold.                         |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_adaptive_rising_value                | AC coupled activity threshold.                           |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_falling_period                       | Inactivity time.                                         |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_falling_value                        | Inactivity threshold.                                    |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_rising_value                         | Activity threshold.                                      |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x\&y\&z_mag_adaptive_falling_en          | Enable or disable AC coupled inactivity events.          |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x\|y\|z_mag_adaptive_rising_en           | Enable or disable AC coupled activity events.            |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x\&y\&z_mag_falling_en                   | Enable or disable inactivity events.                     |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x\|y\|z_mag_rising_en                    | Enable or disable activity events.                       |
+---------------------------------------------------+----------------------------------------------------------+

The default coupling is DC coupled events. In this case the threshold will
be in place as such, where for the AC coupled case an adaptive threshold
(described in the datasheet) will be applied by the sensor. In general activity,
i.e. ``ACTIVITY`` or ``ACTIVITY_AC`` and inactivity i.e. ``INACTIVITY`` or
``INACTIVITY_AC``, will be linked with auto-sleep enabled when both are enabled.
This means in particular ``ACTIVITY`` can also be linked to ``INACTIVITY_AC``
and vice versa, without problem.

Note here, that ``ACTIVITY`` and ``ACTIVITY_AC`` are mutually exclusive. This
means, that the most recent configuration will be set. For instance, if
``ACTIVITY`` is enabled, and ``ACTIVITY_AC`` will be enabled, the sensor driver
will have ``ACTIVITY`` disabled, but ``ACTIVITY_AC`` enabled. The same is valid
for inactivity. In case of turning off an event, it has to match to what is
actually enabled, i.e. enabling ``ACTIVITY_AC`` and then disabling ``ACTIVITY``
is simply ignored as it is already disabled. Or, as if it was any other not
enabled event, too.

Channels processed values
-------------------------

A channel value can be read from its _raw attribute. The value returned is the
raw value as reported by the devices. To get the processed value of the channel,
apply the following formula:

.. code-block::

        processed value = (_raw + _offset) * _scale

Where _offset and _scale are device attributes. If no _offset attribute is
present, simply assume its value is 0.

The ADXL313 driver offers data for a single types of channels, the table below
shows the measurement units for the processed value, which are defined by the
IIO framework:

+-------------------------------------+---------------------------+
| Channel type                        | Measurement unit          |
+-------------------------------------+---------------------------+
| Acceleration on X, Y, and Z axis    | Meters per Second squared |
+-------------------------------------+---------------------------+

가속도·보정·샘플링 예제

장치 이름을 읽는 예제 결과는 `adxl313`입니다.

root:/sys/bus/iio/devices/iio:device0> cat name
adxl313

가속도계 예제는 X·Y·Z축 원시 값 2, −57, 2와 배율 0.009576806을 읽습니다.

root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
2
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
-57
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
2
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
0.009576806

가속도계 보정 오프셋은 LSB 단계에 맞춰 반올림됩니다. 예제에서 X축 `calibbias`에 50을 쓰지만 다시 읽으면 48이 반환됩니다.

root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
0
root:/sys/bus/iio/devices/iio:device0> echo 50 > in_accel_x_calibbias
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
48

현재 샘플링 주파수는 100 Hz입니다. 사용 가능한 값은 6.25, 12.5, 25, 50, 100, 200, 400, 800, 1600, 3200 Hz이며 예제에서는 400 Hz로 변경합니다.

root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency
100.000000
root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency_available
6.250000 12.500000 25.000000 50.000000 100.000000 200.000000 400.000000 800.000000 1600.000000 3200.000000
root:/sys/bus/iio/devices/iio:device0> echo 400 > in_accel_sampling_frequency
root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency
400.000000

Usage examples
--------------

Show device name:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat name
        adxl313

Show accelerometer channels value:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
        2
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
        -57
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
        2
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
        0.009576806

The accelerometer values will be:

- X-axis acceleration = in_accel_x_raw * in_accel_scale = 0.0191536 m/s^2
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = -0.5458779 m/s^2
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 0.0191536 m/s^2

Set calibration offset for accelerometer channels. Note, that the calibration
will be rounded according to the graduation of LSB units:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
        0

        root:/sys/bus/iio/devices/iio:device0> echo 50 > in_accel_x_calibbias
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
        48

Set sampling frequency:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency
        100.000000
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency_available
        6.250000 12.500000 25.000000 50.000000 100.000000 200.000000 400.000000 800.000000 1600.000000 3200.000000

        root:/sys/bus/iio/devices/iio:device0> echo 400 > in_accel_sampling_frequency
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency
        400.000000

IIO 가속도 버퍼

이 드라이버는 IIO 버퍼를 지원하며 ADXL313의 원시 X·Y·Z 가속도 값을 버퍼로 읽을 수 있습니다.

버퍼 읽기를 위해 세 축의 scan element를 활성화합니다.

root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_x_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_y_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_z_en

저장할 샘플 수는 `buffer/length`에 10을 쓰고, `buffer/enable`에 1을 써서 버퍼 읽기를 활성화합니다.

root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length
root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable

버퍼 데이터는 `hexdump -C /dev/iio\:device0`로 읽습니다. 원문의 16진수 예제는 연속된 X·Y·Z 스캔 레코드의 원시 바이트를 보여 줍니다.

root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0

3. Device buffers and triggers
==============================

This driver supports IIO buffers.

All devices support retrieving the raw acceleration measurements using buffers.

Usage examples
--------------

Select channels for buffer read:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_x_en
        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_y_en
        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_z_en

Set the number of samples to be stored in the buffer:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length

Enable buffer readings:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable

Obtain buffered data:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0
        ...
        000000d0  01 fc 31 00 c7 ff 03 fc  31 00 c7 ff 04 fc 33 00  |..1.....1.....3.|
        000000e0  c8 ff 03 fc 32 00 c5 ff  ff fc 32 00 c7 ff 0a fc  |....2.....2.....|
        000000f0  30 00 c8 ff 06 fc 33 00  c7 ff 01 fc 2f 00 c8 ff  |0.....3...../...|
        00000100  02 fc 32 00 c6 ff 04 fc  33 00 c8 ff 05 fc 33 00  |..2.....3.....3.|
        00000110  ca ff 02 fc 31 00 c7 ff  02 fc 30 00 c9 ff 09 fc  |....1.....0.....|
        00000120  35 00 c9 ff 08 fc 35 00  c8 ff 02 fc 31 00 c5 ff  |5.....5.....1...|
        00000130  03 fc 32 00 c7 ff 04 fc  32 00 c7 ff 02 fc 31 00  |..2.....2.....1.|
        00000140  c7 ff 08 fc 30 00 c7 ff  02 fc 32 00 c5 ff ff fc  |....0.....2.....|
        00000150  31 00 c5 ff 04 fc 31 00  c8 ff 03 fc 32 00 c8 ff  |1.....1.....2...|
        00000160  01 fc 31 00 c7 ff 05 fc  31 00 c3 ff 04 fc 31 00  |..1.....1.....1.|
        00000170  c5 ff 04 fc 30 00 c7 ff  03 fc 31 00 c9 ff 03 fc  |....0.....1.....|
        ...

Activity·inactivity 이벤트 예제와 도구

DC 결합 activity 감지를 활성화하려면 rising 임계값을 1.28125로 설정하고 `in_accel_x\|y\|z_mag_rising_en`을 1로 설정합니다. `iio_event_monitor adxl313`은 센서를 움직이는 동안 `accel(x|y|z)`, `mag`, `rising` 이벤트와 타임스탬프를 출력합니다.

echo 1.28125 > ./events/in_accel_mag_rising_value
echo 1 > ./events/in_accel_x\|y\|z_mag_rising_en
iio_event_monitor adxl313

Activity 감지를 끄려면 같은 enable 파일에 0을 씁니다. 이후 이벤트 모니터에는 아무 이벤트도 나타나지 않습니다.

echo 0 > ./events/in_accel_x\|y\|z_mag_rising_en
iio_event_monitor adxl313
<nothing>

DC 결합 inactivity 감지는 falling 임계값 1.234375와 기간 5초를 설정한 뒤 `in_accel_x\&y\&z_mag_falling_en`을 켭니다. 모니터는 `accel(x&y&z)`, `mag`, `falling` 이벤트를 약 5초마다 출력해 비활동 상태를 알립니다.

echo 1.234375 > ./events/in_accel_mag_falling_value
echo 5 > ./events/in_accel_mag_falling_period
echo 1 > ./events/in_accel_x\&y\&z_mag_falling_en
iio_event_monitor adxl313

그 상태에서 AC 결합 activity인 `ACTIVITY_AC`를 활성화할 수 있습니다. 센서 활동 시 `mag_adaptive` rising 이벤트가 발생하고, 5초 동안 비활동이면 기존 `mag` falling 이벤트가 발생합니다. Auto-sleep에서는 다음 활동이 감지될 때까지 이 상태가 유지됩니다.

AC 결합이 사용되면 이벤트 유형은 `mag_adaptive`입니다. 그 밖의 사용 절차는 기본 DC 결합 이벤트와 같습니다.

사용 가능한 IIO 인터페이스 도구에 관한 설명은 `Documentation/iio/iio_tools.rst`를 참고합니다.

Enabling activity detection:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 1.28125 > ./events/in_accel_mag_rising_value
        root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\|y\|z_mag_rising_en

        root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
        Found IIO device with name adxl313 with device number 0
        <only while moving the sensor>
        Event: time: 1748795762298351281, type: accel(x|y|z), channel: 0, evtype: mag, direction: rising
        Event: time: 1748795762302653704, type: accel(x|y|z), channel: 0, evtype: mag, direction: rising
        Event: time: 1748795762304340726, type: accel(x|y|z), channel: 0, evtype: mag, direction: rising
        ...

Disabling activity detection:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 0 > ./events/in_accel_x\|y\|z_mag_rising_en
        root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
        <nothing>

Enabling inactivity detection:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 1.234375 > ./events/in_accel_mag_falling_value
        root:/sys/bus/iio/devices/iio:device0> echo 5 > ./events/in_accel_mag_falling_period
        root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\&y\&z_mag_falling_en

        root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
        Found IIO device with name adxl313 with device number 0
        Event: time: 1748796324115962975, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
        Event: time: 1748796329329981772, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
        Event: time: 1748796334543399706, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
        ...
        <every 5s now indicates inactivity>

Now, enabling activity, e.g. the AC coupled counter-part ``ACTIVITY_AC``

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 1.28125 > ./events/in_accel_mag_rising_value
        root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\|y\|z_mag_rising_en

        root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
        Found IIO device with name adxl313 with device number 0
        <some activity with the sensor>
        Event: time: 1748796880354686777, type: accel(x|y|z), channel: 0, evtype: mag_adaptive, direction: rising
        <5s of inactivity, then>
        Event: time: 1748796885543252017, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
        <some other activity detected by accelerating the sensor>
        Event: time: 1748796887756634678, type: accel(x|y|z), channel: 0, evtype: mag_adaptive, direction: rising
        <again, 5s of inactivity>
        Event: time: 1748796892964368352, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
        <stays like this until next activity in auto-sleep>

Note, when AC coupling is in place, the event type will be of ``mag_adaptive``.
AC- or DC-coupled (the default) events are used similarly.

4. IIO Interfacing Tools
========================

See Documentation/iio/iio_tools.rst for the description of the available IIO
interfacing tools.