1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
.. 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.
|
