Add documentation for ade9000 driver which describes the driver
device files and shows how the user may use the ABI for various
scenarios (configuration, measurement, etc.).
Signed-off-by: Antoniu Miclaus <antoniu.miclaus@analog.com>
---
changes in v7:
- remove PGA gain documentation section
- remove frequency configuration section
- remove scale and frequency attributes from device-level attributes table
- update examples to remove PGA gain and frequency configuration
Documentation/iio/ade9000.rst | 265 ++++++++++++++++++++++++++++++++++
Documentation/iio/index.rst | 1 +
2 files changed, 266 insertions(+)
create mode 100644 Documentation/iio/ade9000.rst
diff --git a/Documentation/iio/ade9000.rst b/Documentation/iio/ade9000.rst
new file mode 100644
index 000000000000..163d36a56be3
--- /dev/null
+++ b/Documentation/iio/ade9000.rst
@@ -0,0 +1,265 @@
+.. 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.
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index c106402a91f7..792c815286f4 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -28,6 +28,7 @@ Industrial I/O Kernel Drivers
ad7606
ad7625
ad7944
+ ade9000
adis16475
adis16480
adis16550
--
2.43.0
On Mon, 8 Sep 2025 07:35:25 +0000 Antoniu Miclaus <antoniu.miclaus@analog.com> wrote: > Add documentation for ade9000 driver which describes the driver > device files and shows how the user may use the ABI for various > scenarios (configuration, measurement, etc.). > > Signed-off-by: Antoniu Miclaus <antoniu.miclaus@analog.com> Please test your docs build and carefully look at the output. There were a few formatting errors in here that I have fixed up. Jonathan > + > ++---------------------------------------------------+----------------------------------------------------------+ > +| 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: blank line before bulleted list. > +- ``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: blank line before bulleted list. > +- 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. > diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst > index c106402a91f7..792c815286f4 100644 > --- a/Documentation/iio/index.rst > +++ b/Documentation/iio/index.rst > @@ -28,6 +28,7 @@ Industrial I/O Kernel Drivers > ad7606 > ad7625 > ad7944 > + ade9000 > adis16475 > adis16480 > adis16550
On Mon, 8 Sep 2025 07:35:25 +0000 Antoniu Miclaus <antoniu.miclaus@analog.com> wrote: > Add documentation for ade9000 driver which describes the driver > device files and shows how the user may use the ABI for various > scenarios (configuration, measurement, etc.). > > Signed-off-by: Antoniu Miclaus <antoniu.miclaus@analog.com> > --- > changes in v7: > - remove PGA gain documentation section > - remove frequency configuration section > - remove scale and frequency attributes from device-level attributes table > - update examples to remove PGA gain and frequency configuration > Documentation/iio/ade9000.rst | 265 ++++++++++++++++++++++++++++++++++ > Documentation/iio/index.rst | 1 + > 2 files changed, 266 insertions(+) > create mode 100644 Documentation/iio/ade9000.rst > > diff --git a/Documentation/iio/ade9000.rst b/Documentation/iio/ade9000.rst > new file mode 100644 > index 000000000000..163d36a56be3 > --- /dev/null > +++ b/Documentation/iio/ade9000.rst > @@ -0,0 +1,265 @@ > +.. 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). | I thought someone raised this on the previous version, but perhaps I imagined it. Missing line break here. > +| 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. > diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst > index c106402a91f7..792c815286f4 100644 > --- a/Documentation/iio/index.rst > +++ b/Documentation/iio/index.rst > @@ -28,6 +28,7 @@ Industrial I/O Kernel Drivers > ad7606 > ad7625 > ad7944 > + ade9000 > adis16475 > adis16480 > adis16550
© 2016 - 2025 Red Hat, Inc.