ADIS16550 driver

장치 개요와 측정 기능

이 드라이버는 SPI 버스에 연결된 Analog Devices ADIS16550 IMU를 지원합니다.

ADIS16550은 3축 자이로스코프와 3축 가속도계를 포함한 완전 관성 시스템입니다. 공장 보정은 각 센서의 감도, 바이어스, 정렬을 특성화하며, 각 센서의 동적 보상 공식이 정확한 측정값을 제공합니다.

가속도계와 자이로스코프 측정값은 항상 제공됩니다. 드라이버는 장치가 계산한 delta angle과 delta velocity도 읽을 수 있습니다.

Delta angle은 샘플 갱신 사이의 각변위를, delta velocity는 샘플 갱신 사이의 선형 속도 변화를 나타냅니다.

온도 데이터는 IMU 내부 온도의 대략적인 측정값이며, 열 환경의 상대 변화를 감시하는 데 가장 유용합니다.

각 IIO 장치에는 `/sys/bus/iio/devices/iio:deviceX` 폴더가 있습니다. X는 장치의 IIO 인덱스이며 하드웨어 특성에 따른 파일이 이 폴더 아래에 생성됩니다. 인터페이스의 일반 규칙은 IIO ABI 문서에 정의됩니다.

.. SPDX-License-Identifier: GPL-2.0

================
ADIS16550 driver
================

This driver supports Analog Device's IMUs on SPI bus.

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

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

The ADIS16550 is a complete inertial system that includes a triaxis gyroscope
and a triaxis accelerometer. The factory calibration characterizes each sensor for
sensitivity, bias, and alignment. As a result, each sensor has its own dynamic
compensation formulas that provide accurate sensor measurements.

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

Accelerometer, gyroscope measurements are always provided. Furthermore, the
driver offers the capability to retrieve the delta angle and the delta velocity
measurements computed by the device.

The delta angle measurements represent a calculation of angular displacement
between each sample update, while the delta velocity measurements represent a
calculation of linear velocity change between each sample update.

Finally, temperature data are provided which show a coarse measurement of
the temperature inside of the IMU device. This data is most useful for
monitoring relative changes in the thermal environment.

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 adis16550 related device files, found in the
specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.

센서 속성과 debugfs

ADIS16550 관련 디버그 파일은 `/sys/kernel/debug/iio/iio:deviceX`에서 찾을 수 있습니다.

+-------------------------------------------+----------------------------------------------------------+
| 3-Axis Accelerometer related device files | Description                                              |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_scale                            | Scale for the accelerometer channels.                    |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_filter_low_pass_3db_frequency    | Bandwidth for the accelerometer channels.                |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_x_calibbias                      | Calibration offset for the X-axis accelerometer channel. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_x_calibscale                     | Calibration scale for the X-axis accelerometer channel.  |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_x_raw                            | Raw X-axis accelerometer channel value.                  |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_y_calibbias                      | Calibration offset for the Y-axis accelerometer channel. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_y_calibscale                     | Calibration scale for the Y-axis accelerometer channel.  |
+-------------------------------------------+----------------------------------------------------------+
| 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_calibscale                     | Calibration scale for the Z-axis accelerometer channel.  |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_z_raw                            | Raw Z-axis accelerometer channel value.                  |
+-------------------------------------------+----------------------------------------------------------+
| in_deltavelocity_scale                    | Scale for delta velocity channels.                       |
+-------------------------------------------+----------------------------------------------------------+
| in_deltavelocity_x_raw                    | Raw X-axis delta velocity channel value.                 |
+-------------------------------------------+----------------------------------------------------------+
| in_deltavelocity_y_raw                    | Raw Y-axis delta velocity channel value.                 |
+-------------------------------------------+----------------------------------------------------------+
| in_deltavelocity_z_raw                    | Raw Z-axis delta velocity channel value.                 |
+-------------------------------------------+----------------------------------------------------------+

+--------------------------------------------+------------------------------------------------------+
| 3-Axis Gyroscope related device files      | Description                                          |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_scale                           | Scale for the gyroscope channels.                    |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_filter_low_pass_3db_frequency   | Scale for the gyroscope channels.                    |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_x_calibbias                     | Calibration offset for the X-axis gyroscope channel. |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_x_calibscale                    | Calibration scale for the X-axis gyroscope channel.  |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_x_raw                           | Raw X-axis gyroscope channel value.                  |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_y_calibbias                     | Calibration offset for the Y-axis gyroscope channel. |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_y_calibscale                    | Calibration scale for the Y-axis gyroscope channel.  |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_y_raw                           | Raw Y-axis gyroscope channel value.                  |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_z_calibbias                     | Calibration offset for the Z-axis gyroscope channel. |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_z_calibscale                    | Calibration scale for the Z-axis gyroscope channel.  |
+--------------------------------------------+------------------------------------------------------+
| in_anglvel_z_raw                           | Raw Z-axis gyroscope channel value.                  |
+--------------------------------------------+------------------------------------------------------+
| in_deltaangl_scale                         | Scale for delta angle channels.                      |
+--------------------------------------------+------------------------------------------------------+
| in_deltaangl_x_raw                         | Raw X-axis delta angle channel value.                |
+--------------------------------------------+------------------------------------------------------+
| in_deltaangl_y_raw                         | Raw Y-axis delta angle channel value.                |
+--------------------------------------------+------------------------------------------------------+
| in_deltaangl_z_raw                         | Raw Z-axis delta angle channel value.                |
+--------------------------------------------+------------------------------------------------------+

+----------------------------------+-------------------------------------------+
| Temperature sensor related files | Description                               |
+----------------------------------+-------------------------------------------+
| in_temp0_raw                     | Raw temperature channel value.            |
+----------------------------------+-------------------------------------------+
| in_temp0_offset                  | Offset for the temperature sensor channel.|
+----------------------------------+-------------------------------------------+
| in_temp0_scale                   | Scale for the temperature sensor channel. |
+----------------------------------+-------------------------------------------+

+----------------------------+--------------------------------------------------------------------------------+
| Miscellaneous device files | Description                                                                    |
+----------------------------+--------------------------------------------------------------------------------+
| name                       | Name of the IIO device.                                                        |
+----------------------------+--------------------------------------------------------------------------------+
| sampling_frequency         | Currently selected sample rate.                                                |
+----------------------------+--------------------------------------------------------------------------------+

The following table shows the adis16550 related device debug files, found in the
specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.

+----------------------+-------------------------------------------------------------------------+
| Debugfs device files | Description                                                             |
+----------------------+-------------------------------------------------------------------------+
| serial_number        | The serial number of the chip in hexadecimal format.                    |
+----------------------+-------------------------------------------------------------------------+
| product_id           | Chip specific product id (16550).                                       |
+----------------------+-------------------------------------------------------------------------+
| flash_count          | The number of flash writes performed on the device.                     |
+----------------------+-------------------------------------------------------------------------+
| firmware_revision    | String containing the firmware revision in the following format ##.##.  |
+----------------------+-------------------------------------------------------------------------+
| firmware_date        | String containing the firmware date in the following format mm-dd-yyyy. |
+----------------------+-------------------------------------------------------------------------+

처리값 공식과 센서 예제

채널의 `_raw` 속성은 장치가 보고한 원시 값을 반환합니다. 처리된 채널 값은 다음 공식으로 계산합니다.

processed value = (_raw + _offset) * _scale

`_offset`과 `_scale`은 장치 속성입니다. `_offset` 속성이 없으면 값은 0으로 간주합니다.

장치 이름을 확인하는 예제는 `name`에서 `adis16550`을 읽습니다.

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

가속도계 예제는 X·Y·Z축 원시 값 6903851, 5650550, 104873530과 배율 0.000000095를 읽습니다.

root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
6903851
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
5650550
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
104873530
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
0.000000095

자이로스코프 예제는 X·Y·Z축 원시 값 193309, −763676, −358108과 배율 0.000000003을 읽습니다.

root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
193309
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
-763676
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
-358108
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
0.000000003

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:: bash

        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 adis16550 driver offers data for 5 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 |
+--------------------------------------+---------------------------+
| Angular velocity on X, Y and Z axis  | Radians per second        |
+--------------------------------------+---------------------------+
| Delta velocity on X. Y, and Z axis   | Meters per Second         |
+--------------------------------------+---------------------------+
| Delta angle on X, Y, and Z axis      | Radians                   |
+--------------------------------------+---------------------------+
| Temperature                          | Millidegrees Celsius      |
+--------------------------------------+---------------------------+

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

Show device name:

.. code-block:: bash

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

Show accelerometer channels value:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
        6903851
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
        5650550
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
        104873530
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
        0.000000095

- X-axis acceleration = in_accel_x_raw * in_accel_scale = 0.655865845 m/s^2
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = 0.53680225 m/s^2
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.96298535 m/s^2

Show gyroscope channels value:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
        193309
        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
        -763676
        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
        -358108
        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
        0.000000003

- X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = 0.000579927 rad/s
- Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = −0.002291028 rad/s
- Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = −0.001074324 rad/s

보정·샘플링·대역폭과 진단 예제

가속도계 X축 보정 오프셋은 처음 0이며 `in_accel_x_calibbias`에 5000을 쓰면 5000으로 변경됩니다.

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

자이로스코프 Y축 보정 오프셋은 처음 0이며 `in_anglvel_y_calibbias`에 −5000을 쓰면 −5000으로 변경됩니다.

root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
0
root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_calibbias
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
-5000

샘플링 주파수는 4000.000000에서 `sampling_frequency`에 1000을 써서 1000.000000으로 변경합니다.

root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
4000.000000
root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
1000.000000

가속도계 공통 저역 통과 3 dB 대역폭은 `in_accel_filter_low_pass_3db_frequency`로 설정합니다. 예제에서는 0에서 100으로 변경합니다.

root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency
0
root:/sys/bus/iio/devices/iio:device0> echo 100 > in_accel_filter_low_pass_3db_frequency
root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency
100

Debugfs 예제는 일련번호 `0x000000b6`, 제품 ID `16550`, flash write 횟수 `13`, 펌웨어 리비전 `1.5`, 펌웨어 날짜 `28-04-2021`을 읽습니다.

root:/sys/kernel/debug/iio/iio:device0> cat serial_number
0x000000b6
root:/sys/kernel/debug/iio/iio:device0> cat product_id
16550
root:/sys/kernel/debug/iio/iio:device0> cat flash_count
13
root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
1.5
root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
28-04-2021

Set calibration offset for accelerometer channels:

.. code-block:: bash

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

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

Set calibration offset for gyroscope channels:

.. code-block:: bash

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

        root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_calibbias
        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
        -5000

Set sampling frequency:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
        4000.000000

        root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
        1000.000000

Set bandwidth for accelerometer channels:

.. code-block:: bash

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

        root:/sys/bus/iio/devices/iio:device0> echo 100 > in_accel_filter_low_pass_3db_frequency
        root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency
        100

Show serial number:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat serial_number
        0x000000b6

Show product id:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat product_id
        16550

Show flash count:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat flash_count
        13

Show firmware revision:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
        1.5

Show firmware date:

.. code-block:: bash

        root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
        28-04-2021

IIO 버퍼와 인터페이스 도구

이 드라이버는 IIO 버퍼를 지원합니다. ADIS16550은 버퍼를 통해 원시 가속도, 자이로스코프, delta velocity, delta angle, 온도 측정값을 읽을 수 있습니다.

가속도 또는 자이로스코프 데이터를 버퍼로 읽을 때 delta 값은 사용할 수 없고 그 반대도 마찬가지입니다. 장치는 한 번에 일반 가속도·자이로스코프 또는 delta velocity·delta angle burst 중 하나만 읽을 수 있으며 두 모드 전환에 시간이 많이 듭니다.

버퍼 사용 전에 `trigger/current_trigger`가 비어 있으면 `adis16550-dev0`을 설정합니다.

root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
root:/sys/bus/iio/devices/iio:device0> echo adis16550-dev0 > trigger/current_trigger
root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
adis16550-dev0

X·Y·Z축 delta velocity와 온도 scan element를 활성화하고 버퍼 길이를 10으로 설정한 뒤 버퍼를 켭니다.

root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_x_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_y_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_z_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp0_en
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진수 출력은 각 스캔 레코드의 원시 바이트를 주소별로 보여 줍니다.

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

버퍼 데이터 구조는 `Documentation/iio/iio_devbuf.rst`를 참고합니다. 사용 가능한 IIO 인터페이스 도구는 `Documentation/iio/iio_tools.rst`에 설명되어 있습니다.

3. Device buffers
=================

This driver supports IIO buffers.

The device supports retrieving the raw acceleration, gyroscope, delta velocity,
delta angle and temperature measurements using buffers.

However, when retrieving acceleration or gyroscope data using buffers, delta
readings will not be available and vice versa. This is because the device only
allows to read either acceleration and gyroscope data or delta velocity and
delta angle data at a time and switching between these two burst data selection
modes is time consuming.

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

Set device trigger in current_trigger, if not already set:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger

        root:/sys/bus/iio/devices/iio:device0> echo adis16550-dev0 > trigger/current_trigger
        root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
        adis16550-dev0

Select channels for buffer read:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_x_en
        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_y_en
        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_z_en
        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp0_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
        ...
        0000cdf0  00 00 0d 2f 00 00 08 43  00 00 09 09 00 00 a4 5f  |.../...C......._|
        0000ce00  00 00 0d 2f 00 00 07 de  00 00 08 db 00 00 a4 4b  |.../...........K|
        0000ce10  00 00 0d 2f 00 00 07 58  00 00 08 a3 00 00 a4 55  |.../...X.......U|
        0000ce20  00 00 0d 2f 00 00 06 d6  00 00 08 5c 00 00 a4 62  |.../.......\...b|
        0000ce30  00 00 0d 2f 00 00 06 45  00 00 08 37 00 00 a4 47  |.../...E...7...G|
        0000ce40  00 00 0d 2f 00 00 05 d4  00 00 08 30 00 00 a3 fa  |.../.......0....|
        0000ce50  00 00 0d 2f 00 00 05 d0  00 00 08 12 00 00 a3 d3  |.../............|
        0000ce60  00 00 0d 2f 00 00 05 dd  00 00 08 2e 00 00 a3 e9  |.../............|
        0000ce70  00 00 0d 2f 00 00 05 cc  00 00 08 51 00 00 a3 d5  |.../.......Q....|
        0000ce80  00 00 0d 2f 00 00 05 ba  00 00 08 22 00 00 a3 9a  |.../......."....|
        0000ce90  00 00 0d 2f 00 00 05 9c  00 00 07 d9 00 00 a3 40  |.../...........@|
        0000cea0  00 00 0d 2f 00 00 05 68  00 00 07 94 00 00 a2 e4  |.../...h........|
        0000ceb0  00 00 0d 2f 00 00 05 25  00 00 07 8d 00 00 a2 ce  |.../...%........|
        ...

See ``Documentation/iio/iio_devbuf.rst`` for more information about how buffered
data is structured.

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

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