ADE9000 driver

장치 개요와 IIO 속성 위치

이 드라이버는 SPI 버스에 연결된 Analog Devices ADE9000 에너지 측정 IC를 지원합니다.

ADE9000은 정확도가 높은 완전 통합형 다상 에너지·전력 품질 감시 장치입니다. 우수한 아날로그 성능과 디지털 신호 처리(DSP) 코어를 결합해 넓은 동적 범위에서 에너지를 정확하게 감시합니다.

통합 고급 기준 전압은 온도 변화에 따른 드리프트를 낮춥니다. 프로그래머블 이득 증폭기(PGA)와 아날로그-디지털 변환기(ADC)를 포함한 전체 채널의 결합 드리프트는 최대 ±25 ppm/°C 미만입니다.

각 IIO 장치에는 `/sys/bus/iio/devices/iio:deviceX` 장치 폴더가 있습니다. 여기서 X는 장치의 IIO 인덱스입니다. 이 폴더 아래에는 하드웨어의 특성과 기능에 따른 장치 파일이 있으며, 파일 인터페이스는 IIO ABI 문서에서 일관된 방식으로 일반화해 설명합니다.

뒤의 표에 나오는 ADE9000 관련 파일은 모두 해당 장치의 `/sys/bus/iio/devices/iio:deviceX` 경로에서 찾을 수 있습니다.

.. SPDX-License-Identifier: GPL-2.0

===============
ADE9000 driver
===============

This driver supports Analog Device's ADE9000 energy measurement IC on SPI bus.

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

* `ADE9000 <https://www.analog.com/media/en/technical-documentation/data-sheets/ADE9000.pdf>`_

The ADE9000 is a highly accurate, fully integrated, multiphase energy and power
quality monitoring device. Superior analog performance and a digital signal
processing (DSP) core enable accurate energy monitoring over a wide dynamic
range. An integrated high end reference ensures low drift over temperature
with a combined drift of less than ±25 ppm/°C maximum for the entire channel
including a programmable gain amplifier (PGA) and an analog-to-digital
converter (ADC).

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

Power and energy measurements are provided for voltage, current, active power,
reactive power, apparent power, and power factor across three phases.

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 question. These files are consistently generalized and documented in
the IIO ABI documentation.

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

전류·전압·전력·에너지 속성

+---------------------------------------------------+----------------------------------------------------------+
| Current measurement related device files          | Description                                              |
+---------------------------------------------------+----------------------------------------------------------+
| in_current[0-2]_raw                               | Raw current measurement for phases A, B, C.              |
+---------------------------------------------------+----------------------------------------------------------+
| in_current[0-2]_scale                             | Scale for current channels.                              |
+---------------------------------------------------+----------------------------------------------------------+
| in_current[0-2]_calibscale                        | Calibration gain for current channels (AIGAIN reg).      |
+---------------------------------------------------+----------------------------------------------------------+
| in_altcurrent[0-2]_rms_raw                        | RMS current measurement for phases A, B, C.              |
+---------------------------------------------------+----------------------------------------------------------+
| in_altcurrent[0-2]_rms_scale                      | Scale for RMS current channels.                          |
+---------------------------------------------------+----------------------------------------------------------+
| in_altcurrent[0-2]_rms_calibbias                  | RMS offset correction for current channels (IRMSOS reg). |
+---------------------------------------------------+----------------------------------------------------------+

+---------------------------------------------------+----------------------------------------------------------+
| Voltage measurement related device files          | Description                                              |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_raw                               | Raw voltage measurement for phases A, B, C.              |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_scale                             | Scale for voltage channels.                              |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_calibscale                        | Calibration gain for voltage channels (AVGAIN reg).      |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_frequency                         | Measured line frequency from instantaneous voltage.      |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_raw                        | RMS voltage measurement for phases A, B, C.              |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_scale                      | Scale for RMS voltage channels.                          |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_calibbias                  | RMS offset correction for voltage channels (VRMSOS reg). |
+---------------------------------------------------+----------------------------------------------------------+

+---------------------------------------------------+----------------------------------------------------------+
| Power measurement related device files            | Description                                              |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_active_raw                          | Active power measurement for phases A, B, C.             |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_active_scale                        | Scale for active power channels.                         |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_active_calibbias                    | Calibration offset for active power (xWATTOS regs).      |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_active_calibscale                   | Calibration gain for active power (APGAIN reg).          |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_reactive_raw                        | Reactive power measurement for phases A, B, C.           |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_reactive_scale                      | Scale for reactive power channels.                       |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_reactive_calibbias                  | Calibration offset for reactive power (xVAROS regs).     |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_apparent_raw                        | Apparent power measurement for phases A, B, C.           |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_apparent_scale                      | Scale for apparent power channels.                       |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_powerfactor                         | Power factor for phases A, B, C.                         |
+---------------------------------------------------+----------------------------------------------------------+

+---------------------------------------------------+----------------------------------------------------------+
| Energy measurement related device files           | Description                                              |
+---------------------------------------------------+----------------------------------------------------------+
| in_energy[0-2]_active_raw                         | Active energy measurement for phases A, B, C.            |
+---------------------------------------------------+----------------------------------------------------------+
| in_energy[0-2]_reactive_raw                       | Reactive energy measurement for phases A, B, C.          |
+---------------------------------------------------+----------------------------------------------------------+
| in_energy[0-2]_apparent_raw                       | Apparent energy measurement for phases A, B, C.          |
+---------------------------------------------------+----------------------------------------------------------+

+------------------------------+------------------------------------------------------------------+
| Shared device attributes     | Description                                                      |
+------------------------------+------------------------------------------------------------------+
| name                         | Name of the IIO device.                                          |
+------------------------------+------------------------------------------------------------------+
| filter_type                  | Waveform buffer filter type (sinc4, sinc4+lp).                   |
+------------------------------+------------------------------------------------------------------+
| filter_type_available        | Available filter types for waveform buffer.                      |
+------------------------------+------------------------------------------------------------------+

보정 단계와 IIO 이벤트

ADE9000은 여러 단계의 이득 및 오프셋 보정을 제공합니다.

채널별 Calibration Gain은 각 채널 유형에 디지털 영역에서 적용하는 미세 조정 보정 이득입니다. `calibscale` 속성으로 제어하며 AIGAIN, AVGAIN, APGAIN 레지스터에 대응합니다.

채널별 Calibration Bias는 장치 내부에서 적용하는 하드웨어 보정 오프셋입니다. 전력 채널의 `calibbias` 속성은 xWATTOS와 xVAROS 레지스터를 제어하고, RMS 채널의 `calibbias` 속성은 IRMSOS와 VRMSOS 레지스터를 제어합니다. 이 값은 사용자 공간에서 사후 적용하는 오프셋이 아니라 칩 내부 보정입니다.

ADE9000의 여러 인터럽트는 IIO 이벤트로 매핑됩니다. 해당 인터럽트를 Device Tree에 연결했을 때만 이벤트 기능을 사용할 수 있습니다.

이벤트 속성은 Device Tree에 해당 인터럽트 `irq0`, `irq1`, `dready`가 지정된 경우에만 나타납니다. 인터럽트가 없어도 드라이버는 동작하지만 사용할 수 있는 기능이 줄어듭니다.

3. Calibration and scaling
===========================

The ADE9000 provides multiple levels of gain and offset correction:

**Calibration Gain (per-channel)**
  Fine-tuning calibration gains applied in the digital domain for each channel type.
  Controlled via ``calibscale`` attributes (AIGAIN, AVGAIN, APGAIN registers).

**Calibration Bias (per-channel)**
  Hardware calibration offsets applied by the device internally:

  - Power measurements: Controlled via ``calibbias`` attributes for power channels (xWATTOS, xVAROS registers).
  - RMS measurements: Controlled via ``calibbias`` attributes for RMS channels (IRMSOS, VRMSOS registers).

  These are internal chip calibrations, not userspace-applied offsets.

4. Event attributes
===================

The ADE9000 provides various interrupts that are mapped to IIO events.
Event functionality is only available if the corresponding interrupts are
connected in the device tree.

+---------------------------------------------------+----------------------------------------------------------+
| IIO Event Attribute                               | ADE9000 Datasheet Equivalent                             |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_thresh_either_en                  | Zero crossing detection interrupt (ZXVx)                 |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_thresh_rising_en           | RMS swell detection interrupt (SWELLx)                   |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_thresh_rising_value        | RMS swell threshold (SWELL_LVL register)                 |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_thresh_falling_en          | RMS sag/dip detection interrupt (DIPx)                   |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_thresh_falling_value       | RMS sag/dip threshold (DIP_LVL register)                 |
+---------------------------------------------------+----------------------------------------------------------+
| in_current[0-2]_thresh_either_en                  | Current zero crossing detection interrupt (ZXIx)         |
+---------------------------------------------------+----------------------------------------------------------+

Event directions:

- ``rising``: Upper threshold crossing (swell detection)
- ``falling``: Lower threshold crossing (sag/dip detection)
- ``either``: Any threshold crossing (zero crossing detection)
- ``none``: Timeout or non-directional events

**Note**: Event attributes are only available if the corresponding interrupts
(irq0, irq1, dready) are specified in the device tree. The driver works without
interrupts but with reduced functionality.

파형 버퍼와 CLKOUT

이 드라이버는 파형 캡처용 IIO 버퍼를 지원합니다. 버퍼 기능을 사용하려면 `dready` 인터럽트를 연결해야 합니다.

ADE9000은 전력 품질 분석을 위해 전압과 전류 파형을 캡처할 수 있습니다. 파형 버퍼는 여러 채널 조합 가운데 하나를 선택하도록 구성할 수 있습니다.

다음 명령은 A상의 전류와 전압 파형 캡처를 활성화합니다.

root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_current0_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_voltage0_en

다음 명령은 버퍼 길이를 100으로 설정한 뒤 버퍼를 활성화합니다.

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

외부 크리스털 또는 클록 소스를 사용할 때 ADE9000은 CLKOUT 핀으로 클록을 출력할 수 있습니다. Device Tree에 `#clock-cells = <0>`을 지정하면 이 기능이 활성화됩니다. 출력 클록은 `clkout`이라는 이름으로 등록되며 다른 장치가 참조할 수 있습니다.

5. Device buffers
=================

This driver supports IIO buffers for waveform capture. Buffer functionality
requires the dready interrupt to be connected.

The device supports capturing voltage and current waveforms for power quality
analysis. The waveform buffer can be configured to capture data from different
channel combinations.

Supported channel combinations for buffered capture:

- Phase A: voltage and current (IA + VA)
- Phase B: voltage and current (IB + VB)
- Phase C: voltage and current (IC + VC)
- All phases: all voltage and current channels
- Individual channels: IA, VA, IB, VB, IC, VC

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

Enable waveform capture for Phase A:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_current0_en
        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_voltage0_en

Set buffer length and enable:

.. code-block:: bash

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

6. Clock output
===============

The ADE9000 can provide a clock output via the CLKOUT pin when using an external
crystal/clock source. This feature is enabled by specifying ``#clock-cells = <0>``
in the device tree. The output clock will be registered as "clkout" and can be
referenced by other devices.

측정·보정·이벤트 사용 예

장치 이름을 확인하려면 `name`을 읽습니다. 예제 결과는 `ade9000`입니다.

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

A상 전압은 `in_voltage0_raw`와 `in_voltage0_scale`을 읽어 계산합니다. 예제 값 12345와 0.000030517을 곱하면 0.3769 V입니다.

root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_raw
12345
root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_scale
0.000030517
Phase A voltage = in_voltage0_raw * in_voltage0_scale = 0.3769 V

A상 유효 전력도 같은 방식으로 `in_power0_active_raw`와 `in_power0_scale`을 곱합니다. 예제 값 5678과 0.000244140의 결과는 1.386 W입니다.

root:/sys/bus/iio/devices/iio:device0> cat in_power0_active_raw
5678
root:/sys/bus/iio/devices/iio:device0> cat in_power0_scale
0.000244140
Phase A active power = in_power0_active_raw * in_power0_scale = 1.386 W

다음 예제는 전류 채널 0의 보정 이득을 `0x800000`으로, 전압 채널 0의 보정 이득을 `0x7FFFFF`로 설정합니다.

# Set current channel 0 calibration gain
root:/sys/bus/iio/devices/iio:device0> echo 0x800000 > in_current0_calibscale
# Set voltage channel 0 calibration gain
root:/sys/bus/iio/devices/iio:device0> echo 0x7FFFFF > in_voltage0_calibscale

RMS 전압 이벤트 임계값 설정은 인터럽트가 연결된 경우에만 사용할 수 있습니다. 다음 명령은 sag 감지 임계값을 180000으로 설정해 활성화하고, swell 감지 임계값을 260000으로 설정해 활성화합니다.

# Set RMS sag detection threshold
root:/sys/bus/iio/devices/iio:device0> echo 180000 > events/in_altvoltage0_rms_thresh_falling_value
# Enable RMS sag detection
root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_falling_en

# Set RMS swell detection threshold
root:/sys/bus/iio/devices/iio:device0> echo 260000 > events/in_altvoltage0_rms_thresh_rising_value
# Enable RMS swell detection
root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_rising_en

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

7. Usage examples
=================

Show device name:

.. code-block:: bash

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

Read voltage measurements:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_raw
        12345
        root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_scale
        0.000030517

- Phase A voltage = in_voltage0_raw * in_voltage0_scale = 0.3769 V

Read power measurements:

.. code-block:: bash

        root:/sys/bus/iio/devices/iio:device0> cat in_power0_active_raw
        5678
        root:/sys/bus/iio/devices/iio:device0> cat in_power0_scale
        0.000244140

- Phase A active power = in_power0_active_raw * in_power0_scale = 1.386 W

Configure calibration gains:

.. code-block:: bash

        # Set current channel 0 calibration gain
        root:/sys/bus/iio/devices/iio:device0> echo 0x800000 > in_current0_calibscale
        # Set voltage channel 0 calibration gain
        root:/sys/bus/iio/devices/iio:device0> echo 0x7FFFFF > in_voltage0_calibscale

Configure RMS voltage event thresholds (requires interrupts):

.. code-block:: bash

        # Set RMS sag detection threshold
        root:/sys/bus/iio/devices/iio:device0> echo 180000 > events/in_altvoltage0_rms_thresh_falling_value
        # Enable RMS sag detection
        root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_falling_en

        # Set RMS swell detection threshold
        root:/sys/bus/iio/devices/iio:device0> echo 260000 > events/in_altvoltage0_rms_thresh_rising_value
        # Enable RMS swell detection
        root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_rising_en

8. IIO Interfacing Tools
========================

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