1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4ADE9000 driver 5=============== 6 7This driver supports Analog Device's ADE9000 energy measurement IC on SPI bus. 8 91. Supported devices 10==================== 11 12* `ADE9000 <https://www.analog.com/media/en/technical-documentation/data-sheets/ADE9000.pdf>`_ 13 14The ADE9000 is a highly accurate, fully integrated, multiphase energy and power 15quality monitoring device. Superior analog performance and a digital signal 16processing (DSP) core enable accurate energy monitoring over a wide dynamic 17range. An integrated high end reference ensures low drift over temperature 18with a combined drift of less than ±25 ppm/°C maximum for the entire channel 19including a programmable gain amplifier (PGA) and an analog-to-digital 20converter (ADC). 21 222. Device attributes 23==================== 24 25Power and energy measurements are provided for voltage, current, active power, 26reactive power, apparent power, and power factor across three phases. 27 28Each IIO device has a device folder under ``/sys/bus/iio/devices/iio:deviceX``, 29where X is the IIO index of the device. Under these folders reside a set of 30device files, depending on the characteristics and features of the hardware 31device in question. These files are consistently generalized and documented in 32the IIO ABI documentation. 33 34The following tables show the ADE9000 related device files, found in the 35specific device folder path ``/sys/bus/iio/devices/iio:deviceX``. 36 37+---------------------------------------------------+----------------------------------------------------------+ 38| Current measurement related device files | Description | 39+---------------------------------------------------+----------------------------------------------------------+ 40| in_current[0-2]_raw | Raw current measurement for phases A, B, C. | 41+---------------------------------------------------+----------------------------------------------------------+ 42| in_current[0-2]_scale | Scale for current channels. | 43+---------------------------------------------------+----------------------------------------------------------+ 44| in_current[0-2]_calibscale | Calibration gain for current channels (AIGAIN reg). | 45+---------------------------------------------------+----------------------------------------------------------+ 46| in_altcurrent[0-2]_rms_raw | RMS current measurement for phases A, B, C. | 47+---------------------------------------------------+----------------------------------------------------------+ 48| in_altcurrent[0-2]_rms_scale | Scale for RMS current channels. | 49+---------------------------------------------------+----------------------------------------------------------+ 50| in_altcurrent[0-2]_rms_calibbias | RMS offset correction for current channels (IRMSOS reg). | 51+---------------------------------------------------+----------------------------------------------------------+ 52 53+---------------------------------------------------+----------------------------------------------------------+ 54| Voltage measurement related device files | Description | 55+---------------------------------------------------+----------------------------------------------------------+ 56| in_voltage[0-2]_raw | Raw voltage measurement for phases A, B, C. | 57+---------------------------------------------------+----------------------------------------------------------+ 58| in_voltage[0-2]_scale | Scale for voltage channels. | 59+---------------------------------------------------+----------------------------------------------------------+ 60| in_voltage[0-2]_calibscale | Calibration gain for voltage channels (AVGAIN reg). | 61+---------------------------------------------------+----------------------------------------------------------+ 62| in_voltage[0-2]_frequency | Measured line frequency from instantaneous voltage. | 63+---------------------------------------------------+----------------------------------------------------------+ 64| in_altvoltage[0-2]_rms_raw | RMS voltage measurement for phases A, B, C. | 65+---------------------------------------------------+----------------------------------------------------------+ 66| in_altvoltage[0-2]_rms_scale | Scale for RMS voltage channels. | 67+---------------------------------------------------+----------------------------------------------------------+ 68| in_altvoltage[0-2]_rms_calibbias | RMS offset correction for voltage channels (VRMSOS reg). | 69+---------------------------------------------------+----------------------------------------------------------+ 70 71+---------------------------------------------------+----------------------------------------------------------+ 72| Power measurement related device files | Description | 73+---------------------------------------------------+----------------------------------------------------------+ 74| in_power[0-2]_active_raw | Active power measurement for phases A, B, C. | 75+---------------------------------------------------+----------------------------------------------------------+ 76| in_power[0-2]_active_scale | Scale for active power channels. | 77+---------------------------------------------------+----------------------------------------------------------+ 78| in_power[0-2]_active_calibbias | Calibration offset for active power (xWATTOS regs). | 79+---------------------------------------------------+----------------------------------------------------------+ 80| in_power[0-2]_active_calibscale | Calibration gain for active power (APGAIN reg). | 81+---------------------------------------------------+----------------------------------------------------------+ 82| in_power[0-2]_reactive_raw | Reactive power measurement for phases A, B, C. | 83+---------------------------------------------------+----------------------------------------------------------+ 84| in_power[0-2]_reactive_scale | Scale for reactive power channels. | 85+---------------------------------------------------+----------------------------------------------------------+ 86| in_power[0-2]_reactive_calibbias | Calibration offset for reactive power (xVAROS regs). | 87+---------------------------------------------------+----------------------------------------------------------+ 88| in_power[0-2]_apparent_raw | Apparent power measurement for phases A, B, C. | 89+---------------------------------------------------+----------------------------------------------------------+ 90| in_power[0-2]_apparent_scale | Scale for apparent power channels. | 91+---------------------------------------------------+----------------------------------------------------------+ 92| in_power[0-2]_powerfactor | Power factor for phases A, B, C. | 93+---------------------------------------------------+----------------------------------------------------------+ 94 95+---------------------------------------------------+----------------------------------------------------------+ 96| Energy measurement related device files | Description | 97+---------------------------------------------------+----------------------------------------------------------+ 98| in_energy[0-2]_active_raw | Active energy measurement for phases A, B, C. | 99+---------------------------------------------------+----------------------------------------------------------+ 100| in_energy[0-2]_reactive_raw | Reactive energy measurement for phases A, B, C. | 101+---------------------------------------------------+----------------------------------------------------------+ 102| in_energy[0-2]_apparent_raw | Apparent energy measurement for phases A, B, C. | 103+---------------------------------------------------+----------------------------------------------------------+ 104 105+------------------------------+------------------------------------------------------------------+ 106| Shared device attributes | Description | 107+------------------------------+------------------------------------------------------------------+ 108| name | Name of the IIO device. | 109+------------------------------+------------------------------------------------------------------+ 110| filter_type | Waveform buffer filter type (sinc4, sinc4+lp). | 111+------------------------------+------------------------------------------------------------------+ 112| filter_type_available | Available filter types for waveform buffer. | 113+------------------------------+------------------------------------------------------------------+ 114 1153. Calibration and scaling 116=========================== 117 118The ADE9000 provides multiple levels of gain and offset correction: 119 120**Calibration Gain (per-channel)** 121 Fine-tuning calibration gains applied in the digital domain for each channel type. 122 Controlled via ``calibscale`` attributes (AIGAIN, AVGAIN, APGAIN registers). 123 124**Calibration Bias (per-channel)** 125 Hardware calibration offsets applied by the device internally: 126 127 - Power measurements: Controlled via ``calibbias`` attributes for power channels (xWATTOS, xVAROS registers). 128 - RMS measurements: Controlled via ``calibbias`` attributes for RMS channels (IRMSOS, VRMSOS registers). 129 130 These are internal chip calibrations, not userspace-applied offsets. 131 1324. Event attributes 133=================== 134 135The ADE9000 provides various interrupts that are mapped to IIO events. 136Event functionality is only available if the corresponding interrupts are 137connected in the device tree. 138 139+---------------------------------------------------+----------------------------------------------------------+ 140| IIO Event Attribute | ADE9000 Datasheet Equivalent | 141+---------------------------------------------------+----------------------------------------------------------+ 142| in_voltage[0-2]_thresh_either_en | Zero crossing detection interrupt (ZXVx) | 143+---------------------------------------------------+----------------------------------------------------------+ 144| in_altvoltage[0-2]_rms_thresh_rising_en | RMS swell detection interrupt (SWELLx) | 145+---------------------------------------------------+----------------------------------------------------------+ 146| in_altvoltage[0-2]_rms_thresh_rising_value | RMS swell threshold (SWELL_LVL register) | 147+---------------------------------------------------+----------------------------------------------------------+ 148| in_altvoltage[0-2]_rms_thresh_falling_en | RMS sag/dip detection interrupt (DIPx) | 149+---------------------------------------------------+----------------------------------------------------------+ 150| in_altvoltage[0-2]_rms_thresh_falling_value | RMS sag/dip threshold (DIP_LVL register) | 151+---------------------------------------------------+----------------------------------------------------------+ 152| in_current[0-2]_thresh_either_en | Current zero crossing detection interrupt (ZXIx) | 153+---------------------------------------------------+----------------------------------------------------------+ 154 155Event directions: 156 157- ``rising``: Upper threshold crossing (swell detection) 158- ``falling``: Lower threshold crossing (sag/dip detection) 159- ``either``: Any threshold crossing (zero crossing detection) 160- ``none``: Timeout or non-directional events 161 162**Note**: Event attributes are only available if the corresponding interrupts 163(irq0, irq1, dready) are specified in the device tree. The driver works without 164interrupts but with reduced functionality. 165 1665. Device buffers 167================= 168 169This driver supports IIO buffers for waveform capture. Buffer functionality 170requires the dready interrupt to be connected. 171 172The device supports capturing voltage and current waveforms for power quality 173analysis. The waveform buffer can be configured to capture data from different 174channel combinations. 175 176Supported channel combinations for buffered capture: 177 178- Phase A: voltage and current (IA + VA) 179- Phase B: voltage and current (IB + VB) 180- Phase C: voltage and current (IC + VC) 181- All phases: all voltage and current channels 182- Individual channels: IA, VA, IB, VB, IC, VC 183 184Usage examples 185-------------- 186 187Enable waveform capture for Phase A: 188 189.. code-block:: bash 190 191 root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_current0_en 192 root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_voltage0_en 193 194Set buffer length and enable: 195 196.. code-block:: bash 197 198 root:/sys/bus/iio/devices/iio:device0> echo 100 > buffer/length 199 root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable 200 2016. Clock output 202=============== 203 204The ADE9000 can provide a clock output via the CLKOUT pin when using an external 205crystal/clock source. This feature is enabled by specifying ``#clock-cells = <0>`` 206in the device tree. The output clock will be registered as "clkout" and can be 207referenced by other devices. 208 2097. Usage examples 210================= 211 212Show device name: 213 214.. code-block:: bash 215 216 root:/sys/bus/iio/devices/iio:device0> cat name 217 ade9000 218 219Read voltage measurements: 220 221.. code-block:: bash 222 223 root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_raw 224 12345 225 root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_scale 226 0.000030517 227 228- Phase A voltage = in_voltage0_raw * in_voltage0_scale = 0.3769 V 229 230Read power measurements: 231 232.. code-block:: bash 233 234 root:/sys/bus/iio/devices/iio:device0> cat in_power0_active_raw 235 5678 236 root:/sys/bus/iio/devices/iio:device0> cat in_power0_scale 237 0.000244140 238 239- Phase A active power = in_power0_active_raw * in_power0_scale = 1.386 W 240 241Configure calibration gains: 242 243.. code-block:: bash 244 245 # Set current channel 0 calibration gain 246 root:/sys/bus/iio/devices/iio:device0> echo 0x800000 > in_current0_calibscale 247 # Set voltage channel 0 calibration gain 248 root:/sys/bus/iio/devices/iio:device0> echo 0x7FFFFF > in_voltage0_calibscale 249 250Configure RMS voltage event thresholds (requires interrupts): 251 252.. code-block:: bash 253 254 # Set RMS sag detection threshold 255 root:/sys/bus/iio/devices/iio:device0> echo 180000 > events/in_altvoltage0_rms_thresh_falling_value 256 # Enable RMS sag detection 257 root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_falling_en 258 259 # Set RMS swell detection threshold 260 root:/sys/bus/iio/devices/iio:device0> echo 260000 > events/in_altvoltage0_rms_thresh_rising_value 261 # Enable RMS swell detection 262 root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_rising_en 263 2648. IIO Interfacing Tools 265======================== 266 267See ``Documentation/iio/iio_tools.rst`` for the description of the available IIO 268interfacing tools. 269