Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: iio: add documentation for ade9000 driver
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>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
authored by
Antoniu Miclaus
and committed by
Jonathan Cameron
942ab02b
81de7b46
+269
+268
Documentation/iio/ade9000.rst
+268
Documentation/iio/ade9000.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
===============
4
+
ADE9000 driver
5
+
===============
6
+
7
+
This driver supports Analog Device's ADE9000 energy measurement IC on SPI bus.
8
+
9
+
1. Supported devices
10
+
====================
11
+
12
+
* `ADE9000 <https://www.analog.com/media/en/technical-documentation/data-sheets/ADE9000.pdf>`_
13
+
14
+
The ADE9000 is a highly accurate, fully integrated, multiphase energy and power
15
+
quality monitoring device. Superior analog performance and a digital signal
16
+
processing (DSP) core enable accurate energy monitoring over a wide dynamic
17
+
range. An integrated high end reference ensures low drift over temperature
18
+
with a combined drift of less than ±25 ppm/°C maximum for the entire channel
19
+
including a programmable gain amplifier (PGA) and an analog-to-digital
20
+
converter (ADC).
21
+
22
+
2. Device attributes
23
+
====================
24
+
25
+
Power and energy measurements are provided for voltage, current, active power,
26
+
reactive power, apparent power, and power factor across three phases.
27
+
28
+
Each IIO device has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
29
+
where X is the IIO index of the device. Under these folders reside a set of
30
+
device files, depending on the characteristics and features of the hardware
31
+
device in question. These files are consistently generalized and documented in
32
+
the IIO ABI documentation.
33
+
34
+
The following tables show the ADE9000 related device files, found in the
35
+
specific 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
+
115
+
3. Calibration and scaling
116
+
===========================
117
+
118
+
The 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
+
132
+
4. Event attributes
133
+
===================
134
+
135
+
The ADE9000 provides various interrupts that are mapped to IIO events.
136
+
Event functionality is only available if the corresponding interrupts are
137
+
connected 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
+
155
+
Event 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
164
+
interrupts but with reduced functionality.
165
+
166
+
5. Device buffers
167
+
=================
168
+
169
+
This driver supports IIO buffers for waveform capture. Buffer functionality
170
+
requires the dready interrupt to be connected.
171
+
172
+
The device supports capturing voltage and current waveforms for power quality
173
+
analysis. The waveform buffer can be configured to capture data from different
174
+
channel combinations.
175
+
176
+
Supported 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
+
184
+
Usage examples
185
+
--------------
186
+
187
+
Enable 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
+
194
+
Set 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
+
201
+
6. Clock output
202
+
===============
203
+
204
+
The ADE9000 can provide a clock output via the CLKOUT pin when using an external
205
+
crystal/clock source. This feature is enabled by specifying ``#clock-cells = <0>``
206
+
in the device tree. The output clock will be registered as "clkout" and can be
207
+
referenced by other devices.
208
+
209
+
7. Usage examples
210
+
=================
211
+
212
+
Show device name:
213
+
214
+
.. code-block:: bash
215
+
216
+
root:/sys/bus/iio/devices/iio:device0> cat name
217
+
ade9000
218
+
219
+
Read 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
+
230
+
Read 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
+
241
+
Configure 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
+
250
+
Configure 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
+
264
+
8. IIO Interfacing Tools
265
+
========================
266
+
267
+
See ``Documentation/iio/iio_tools.rst`` for the description of the available IIO
268
+
interfacing tools.