| .. 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. |
