--- /dev/null
+.. 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. |
++------------------------------+------------------------------------------------------------------+
+
+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.
+
+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.
+
+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.
projects / thirdparty / kernel / linux.git / commitdiff
