David Smart / PowerMeasurement

Minor update to improve documentation and add missing functions.

PowerMeasurement.h@2:7f6a39ec5c01, 2016-10-17 (annotated)

Committer:
WiredHome
Date:
Mon Oct 17 11:31:18 2016 +0000
Revision:
2:7f6a39ec5c01
Parent:
1:d99a72afec32 
Update docs and add missing functions.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 0:51c019b83ede 1 ///
WiredHome 0:51c019b83ede 2 ///
WiredHome 0:51c019b83ede 3 ///
WiredHome 0:51c019b83ede 4
WiredHome 0:51c019b83ede 5 #ifndef POWERMEASUREMENT_H
WiredHome 0:51c019b83ede 6 #define POWERMEASUREMENT_H
WiredHome 0:51c019b83ede 7
WiredHome 0:51c019b83ede 8 #include "mbed.h"
WiredHome 0:51c019b83ede 9
WiredHome 0:51c019b83ede 10
WiredHome 0:51c019b83ede 11 /// The PowerMeasurement class is used to take voltage and current measurements and compute power consumption.
WiredHome 0:51c019b83ede 12 ///
WiredHome 0:51c019b83ede 13 /// This is done as a process that takes some amount of time, as it will sample two inputs over a number of
WiredHome 0:51c019b83ede 14 /// cycles of the AC line input (typically 60 Hz). In order to avoid blocking the CPU any more than necessary
WiredHome 0:51c019b83ede 15 /// it will be processed with a ticker. So, there will be functions to start an acquisition, monitor the
WiredHome 0:51c019b83ede 16 /// acquisition, and extract the results when it is done.
WiredHome 0:51c019b83ede 17 ///
WiredHome 0:51c019b83ede 18 /// The power measurement is performed on virtual channels, which map to real analog inputs. The virtual
WiredHome 0:51c019b83ede 19 /// channels may be direct-wired to the processor analog inputs, or it may be esternally multiplexed.
WiredHome 0:51c019b83ede 20 ///
WiredHome 0:51c019b83ede 21 /// Electrically, the voltage measurements are normalized so the A/C swing is biased to mid-range on the
WiredHome 0:51c019b83ede 22 /// A/D and then peak-to-peak is measured from 0 to FFFF.
WiredHome 0:51c019b83ede 23 ///
WiredHome 0:51c019b83ede 24 /// @code
WiredHome 0:51c019b83ede 25 /// NumMuxes
WiredHome 0:51c019b83ede 26 /// +----------+ MuxChannels
WiredHome 0:51c019b83ede 27 /// Input 1 ---|0 a|--------------------------------------+
WiredHome 0:51c019b83ede 28 /// Input 2 ---|1 b|--------------------------------------+
WiredHome 0:51c019b83ede 29 /// Input 3 ---|2 c|--------------------------------------+
WiredHome 0:51c019b83ede 30 /// ... ---| | |
WiredHome 0:51c019b83ede 31 /// ... ---| inh|------------------------------------+ |
WiredHome 0:51c019b83ede 32 /// ... ---| | AinCount | |
WiredHome 0:51c019b83ede 33 /// ... ---| | +--------------+ | |
WiredHome 0:51c019b83ede 34 /// Input 8 ---|7 Y|--------|p15 | | |
WiredHome 0:51c019b83ede 35 /// +----------+ | | Select | |
WiredHome 0:51c019b83ede 36 /// | pxx|------------+ |
WiredHome 0:51c019b83ede 37 /// - - -|p16 | |
WiredHome 0:51c019b83ede 38 /// | | |
WiredHome 0:51c019b83ede 39 /// | | |
WiredHome 0:51c019b83ede 40 /// | | MusBus |
WiredHome 0:51c019b83ede 41 /// | pcc|--------------+
WiredHome 0:51c019b83ede 42 /// | pbb|--------------+
WiredHome 0:51c019b83ede 43 /// | paa|--------------+
WiredHome 0:51c019b83ede 44 /// GetVoltage() -------> | |
WiredHome 0:51c019b83ede 45 /// +--------------+
WiredHome 0:51c019b83ede 46 ///
WiredHome 0:51c019b83ede 47 /// @endcode
WiredHome 0:51c019b83ede 48 ///
WiredHome 0:51c019b83ede 49 class PowerMeasurement {
WiredHome 0:51c019b83ede 50 public:
WiredHome 0:51c019b83ede 51 /// The callback to get the instantaneous value of the voltage time-synchronous with the current measurement.
WiredHome 0:51c019b83ede 52 ///
WiredHome 0:51c019b83ede 53 /// The called function should return the instantaneous voltage measurement. The value is an unsigned value
WiredHome 0:51c019b83ede 54 /// normalized to the range of 0 to FFFF, with a zero-offset of 32768.
WiredHome 0:51c019b83ede 55 ///
WiredHome 2:7f6a39ec5c01 56 /// If not voltage measurement system is in place, the user may choose not to define this function, in
WiredHome 2:7f6a39ec5c01 57 /// which case the power measurements cannot be made. The current measurements are still valid, and power
WiredHome 2:7f6a39ec5c01 58 /// can be computed by the users program.
WiredHome 2:7f6a39ec5c01 59 ///
WiredHome 2:7f6a39ec5c01 60 /// @returns a value in the range of 0 to FFFF, biased to the mid-point of 32768 which represents 0.0v.
WiredHome 0:51c019b83ede 61 ///
WiredHome 0:51c019b83ede 62 typedef uint16_t (* GetVoltage_T)(void);
WiredHome 0:51c019b83ede 63
WiredHome 2:7f6a39ec5c01 64 /// Each raw sample consists of 2 values - the voltage and the current at that moment. The labels 'voltage'
WiredHome 2:7f6a39ec5c01 65 /// and 'current' are somewhat artificial. The 'current' values are gathers from the analog inputs and
WiredHome 2:7f6a39ec5c01 66 /// multiplexers. The 'voltage' is from an external callback, which in turn might be using one of the
WiredHome 2:7f6a39ec5c01 67 /// analog inputs, or it might be from an external measurement source.
WiredHome 1:d99a72afec32 68 typedef struct {
WiredHome 1:d99a72afec32 69 uint16_t voltage; ///< The voltage, in A/D units, which are scaled 0 to FFFF
WiredHome 1:d99a72afec32 70 uint16_t current; ///< The current, in A/D units, which are scaled 0 to FFFF
WiredHome 1:d99a72afec32 71 } RawPowerData_T;
WiredHome 1:d99a72afec32 72
WiredHome 0:51c019b83ede 73 #define SAMPLES_PER_CYCLE 100 ///< The number of samples in each cycle
WiredHome 0:51c019b83ede 74 #define CYCLES_PER_SAMPLE 2 ///< The number of cycles in the sample
WiredHome 0:51c019b83ede 75 #define PM_ZERO_OFFSET 32767 ///< Zero-Offset applied to A/D values
WiredHome 0:51c019b83ede 76 #define PM_FULL_SCALE 32767 ///< The full-scale value against the calibration
WiredHome 0:51c019b83ede 77
WiredHome 0:51c019b83ede 78 /// The constructor for the PowerMeasurement class is used to create various hardware assignments.
WiredHome 0:51c019b83ede 79 ///
WiredHome 1:d99a72afec32 80 /// @param[in] AinList is a pointer to an array of AnalogIn classes
WiredHome 0:51c019b83ede 81 /// @param[in] MuxBus is a pointer to a BusOut that is used to select the external multiplexer channel.
WiredHome 1:d99a72afec32 82 /// @param[in] Select is a pointer to a DigitalOut that is used to enable the external multplexer.
WiredHome 0:51c019b83ede 83 /// @param[in] v_get is the callback used to get the voltage time synchronous with the current measurement.
WiredHome 0:51c019b83ede 84 /// @param[in] AinCount is the count of Analog Inputs to use, from 1 to 6, which maps to p15 thru p20. Default: 6.
WiredHome 0:51c019b83ede 85 /// @param[in] MuxChannels is the count of channels on each external multiplexer. Default: 8.
WiredHome 0:51c019b83ede 86 ///
WiredHome 1:d99a72afec32 87 PowerMeasurement(AnalogIn * AinList, BusOut * MuxBus = NULL, DigitalOut * Select = NULL,
WiredHome 1:d99a72afec32 88 GetVoltage_T callback = NULL, int AinCount = 6, int MuxChannels = 8);
WiredHome 0:51c019b83ede 89
WiredHome 0:51c019b83ede 90 /// The destructor.
WiredHome 0:51c019b83ede 91 ~PowerMeasurement();
WiredHome 0:51c019b83ede 92
WiredHome 2:7f6a39ec5c01 93 /// Define the frequency of the line voltage, which in turn defines the sample-rate.
WiredHome 0:51c019b83ede 94 ///
WiredHome 2:7f6a39ec5c01 95 /// Based on this line frequency, the sample-rate for the measurement is set to achieve
WiredHome 2:7f6a39ec5c01 96 /// 'SAMPLES_PER_CYCLE' samples per cycle, and 'CYCLES_PER_SAMPLE' cycles.
WiredHome 0:51c019b83ede 97 ///
WiredHome 0:51c019b83ede 98 /// @param[in] Hz sets the line frequency.
WiredHome 0:51c019b83ede 99 ///
WiredHome 0:51c019b83ede 100 void frequency(float _Hz);
WiredHome 0:51c019b83ede 101
WiredHome 2:7f6a39ec5c01 102 /// Define the measuremenbt interval, as an alternative to setting the frequency.
WiredHome 0:51c019b83ede 103 ///
WiredHome 2:7f6a39ec5c01 104 /// Instead of defining the measurement interval by specifying the line frequency, the period
WiredHome 0:51c019b83ede 105 /// can be directly set.
WiredHome 0:51c019b83ede 106 ///
WiredHome 0:51c019b83ede 107 /// @param uSec is the number of microseconds between samples.
WiredHome 0:51c019b83ede 108 ///
WiredHome 0:51c019b83ede 109 void period_us(uint32_t uSec);
WiredHome 0:51c019b83ede 110
WiredHome 2:7f6a39ec5c01 111 /// Set the analog input to current calibration value for a channel.
WiredHome 0:51c019b83ede 112 ///
WiredHome 0:51c019b83ede 113 /// Each analog input channel can be configured for the current sensor used on that channel.
WiredHome 0:51c019b83ede 114 /// If the channel has a 30 A current sensor, that channel should be set to 30.0f.
WiredHome 0:51c019b83ede 115 /// If the user calibrates the sensor more precisely, an improved calibration factor (e.g. 31.1)
WiredHome 0:51c019b83ede 116 /// can be defined.
WiredHome 0:51c019b83ede 117 ///
WiredHome 2:7f6a39ec5c01 118 /// The calibration is based on the full-scale reading from the A/D. As the A/D is a normalized
WiredHome 2:7f6a39ec5c01 119 /// uint16_t value, and biased to approximately mid-supply, the full scale range is then
WiredHome 2:7f6a39ec5c01 120 /// 1/2 of the total range, or approximately 32767. Component tolerances, of the voltage
WiredHome 2:7f6a39ec5c01 121 /// reference, the mid-supply divider, and the current sensing component can affect this.
WiredHome 2:7f6a39ec5c01 122 ///
WiredHome 0:51c019b83ede 123 /// @param[in] channel defines the channel to calibrate.
WiredHome 0:51c019b83ede 124 /// @param[in] fullScaleCurrentCalibration is the calibration factor representing the full-scale current.
WiredHome 0:51c019b83ede 125 /// @returns true if the value is accepted.
WiredHome 0:51c019b83ede 126 /// @returns false if the channel was incorrect.
WiredHome 0:51c019b83ede 127 ///
WiredHome 0:51c019b83ede 128 bool SetFullScaleCurrent(int channel, float fullScaleCurrentCalibration);
WiredHome 0:51c019b83ede 129
WiredHome 0:51c019b83ede 130 /// Set the voltage value representing the full scale measurement.
WiredHome 0:51c019b83ede 131 ///
WiredHome 2:7f6a39ec5c01 132 /// The GetVoltage callback is expecting a uint16_t as the return value. When configured for a
WiredHome 2:7f6a39ec5c01 133 /// 120V circuit, which measures approximately 170v peak, the fullScaleVoltageCalibration value
WiredHome 2:7f6a39ec5c01 134 /// would be 170.0f.
WiredHome 0:51c019b83ede 135 ///
WiredHome 2:7f6a39ec5c01 136 /// The calibration is based on the full-scale reading from the A/D. As the A/D is a normalized
WiredHome 2:7f6a39ec5c01 137 /// uint16_t value, and biased to approximately mid-supply, the full scale range is then
WiredHome 2:7f6a39ec5c01 138 /// 1/2 of the total range, or approximately 32767. Component tolerances, of the voltage
WiredHome 2:7f6a39ec5c01 139 /// reference, the mid-supply divider, and the current sensing component can affect this.
WiredHome 2:7f6a39ec5c01 140 ///
WiredHome 0:51c019b83ede 141 /// @param[in] fullScaleVoltageCalibration is the full-scale voltage value.
WiredHome 2:7f6a39ec5c01 142 /// @returns true if the value is accepted, which it will be.
WiredHome 0:51c019b83ede 143 ///
WiredHome 0:51c019b83ede 144 bool SetFullScaleVoltage(float fullScaleVoltageCalibration);
WiredHome 0:51c019b83ede 145
WiredHome 0:51c019b83ede 146 /// Starts a measurement on the specified channel.
WiredHome 0:51c019b83ede 147 ///
WiredHome 2:7f6a39ec5c01 148 /// This starts the measurement on a specified channel. The subsystem will then configure
WiredHome 2:7f6a39ec5c01 149 /// the external multiplexer and a/d sampling to gather the the samples.
WiredHome 2:7f6a39ec5c01 150 ///
WiredHome 2:7f6a39ec5c01 151 /// The actual sampling of the data can be either synchronous, or asynchonous, based on a
WiredHome 2:7f6a39ec5c01 152 /// #define value.
WiredHome 0:51c019b83ede 153 ///
WiredHome 0:51c019b83ede 154 /// @param[in] channel defines the channel to measure. This is in the range of 0 to N-1, where N is
WiredHome 0:51c019b83ede 155 /// AinCount * MuxChannels.
WiredHome 2:7f6a39ec5c01 156 /// @returns true if the measurement can be started (in async mode), or if the measurement is complete
WiredHome 2:7f6a39ec5c01 157 /// when operating in synchonous mode.
WiredHome 0:51c019b83ede 158 /// @returns false if the measurement cannot be started - likely because of an incorrect channel
WiredHome 0:51c019b83ede 159 /// selection.
WiredHome 0:51c019b83ede 160 ///
WiredHome 0:51c019b83ede 161 bool StartMeasurement(int channel);
WiredHome 0:51c019b83ede 162
WiredHome 0:51c019b83ede 163 /// Determines if the conversion is complete and the results are readable.
WiredHome 0:51c019b83ede 164 ///
WiredHome 2:7f6a39ec5c01 165 /// When operating in the asynchronous mode, this API can be used to detect when the conversion
WiredHome 2:7f6a39ec5c01 166 /// is complete.
WiredHome 2:7f6a39ec5c01 167 ///
WiredHome 0:51c019b83ede 168 /// @returns true if the measurement is complete (or if no measurement is in process).
WiredHome 0:51c019b83ede 169 /// @returns false if the measurement is in process.
WiredHome 0:51c019b83ede 170 ///
WiredHome 0:51c019b83ede 171 bool readable();
WiredHome 0:51c019b83ede 172
WiredHome 0:51c019b83ede 173 /// Get the rms current measurement.
WiredHome 0:51c019b83ede 174 ///
WiredHome 0:51c019b83ede 175 /// This retrieves the rms current measurement for the channel which just completed measurement.
WiredHome 0:51c019b83ede 176 ///
WiredHome 0:51c019b83ede 177 /// @returns the rm current measurement.
WiredHome 0:51c019b83ede 178 ///
WiredHome 0:51c019b83ede 179 float GetRMSCurrent();
WiredHome 0:51c019b83ede 180
WiredHome 2:7f6a39ec5c01 181 /// Get the rms voltage measurement.
WiredHome 2:7f6a39ec5c01 182 ///
WiredHome 2:7f6a39ec5c01 183 /// This retrieves the rms voltage measurement for the channel which just completed measurement.
WiredHome 2:7f6a39ec5c01 184 ///
WiredHome 2:7f6a39ec5c01 185 /// @note This is only valid if the user supplied GetVoltage() function was provided.
WiredHome 2:7f6a39ec5c01 186 ///
WiredHome 2:7f6a39ec5c01 187 /// @returns the rms voltage measurement.
WiredHome 2:7f6a39ec5c01 188 ///
WiredHome 2:7f6a39ec5c01 189 float GetRMSVoltage();
WiredHome 2:7f6a39ec5c01 190
WiredHome 2:7f6a39ec5c01 191 /// Get the real power measurement.
WiredHome 2:7f6a39ec5c01 192 ///
WiredHome 2:7f6a39ec5c01 193 /// This retrieves the real power measurement for the channel which just completed measurement.
WiredHome 2:7f6a39ec5c01 194 /// This is the average of the instantaneous power.
WiredHome 2:7f6a39ec5c01 195 ///
WiredHome 2:7f6a39ec5c01 196 /// @note This is only valid if the user supplied GetVoltage() function was provided.
WiredHome 2:7f6a39ec5c01 197 ///
WiredHome 2:7f6a39ec5c01 198 /// @returns the real power measurement.
WiredHome 2:7f6a39ec5c01 199 ///
WiredHome 2:7f6a39ec5c01 200 float GetRealPower();
WiredHome 2:7f6a39ec5c01 201
WiredHome 0:51c019b83ede 202 /// Get the apparent power measurement.
WiredHome 0:51c019b83ede 203 ///
WiredHome 0:51c019b83ede 204 /// This retrieves the apparent power measurement for the channel which just completed measurement.
WiredHome 0:51c019b83ede 205 ///
WiredHome 2:7f6a39ec5c01 206 /// @note This is only valid if the user supplied GetVoltage() function was provided.
WiredHome 2:7f6a39ec5c01 207 ///
WiredHome 0:51c019b83ede 208 /// @returns the apparent power measurement.
WiredHome 0:51c019b83ede 209 ///
WiredHome 0:51c019b83ede 210 float GetApparentPower();
WiredHome 0:51c019b83ede 211
WiredHome 0:51c019b83ede 212 /// Get the power factor
WiredHome 0:51c019b83ede 213 ///
WiredHome 2:7f6a39ec5c01 214 /// @note This is only valid if the user supplied GetVoltage() function was provided.
WiredHome 2:7f6a39ec5c01 215 ///
WiredHome 0:51c019b83ede 216 /// @returns the power factor measurement.
WiredHome 0:51c019b83ede 217 ///
WiredHome 0:51c019b83ede 218 float GetPowerFactor();
WiredHome 0:51c019b83ede 219
WiredHome 0:51c019b83ede 220 /// Get the peak current measurement values from the recent sample.
WiredHome 0:51c019b83ede 221 ///
WiredHome 2:7f6a39ec5c01 222 /// @note if either parameter is null, that data will not be provided.
WiredHome 2:7f6a39ec5c01 223 ///
WiredHome 0:51c019b83ede 224 /// @param[inout] negPeak is a pointer to the negative going peak current measured.
WiredHome 0:51c019b83ede 225 /// @param[inout] posPeak is a pointer to the positive going peak current measured.
WiredHome 0:51c019b83ede 226 /// @returns true if a measurement was completed and the data was updated.
WiredHome 0:51c019b83ede 227 /// @returns false if a measurement has not started or is in process.
WiredHome 0:51c019b83ede 228 ///
WiredHome 0:51c019b83ede 229 bool GetPeakCurrent(float * negPeak, float * posPeak);
WiredHome 0:51c019b83ede 230
WiredHome 1:d99a72afec32 231 /// Get the raw sample data for a given sample number.
WiredHome 1:d99a72afec32 232 ///
WiredHome 1:d99a72afec32 233 /// If a measurement is complete, or has at least proceeded beyond the desired
WiredHome 1:d99a72afec32 234 /// sample, then pass that raw data to the calling function.
WiredHome 1:d99a72afec32 235 ///
WiredHome 1:d99a72afec32 236 /// @param[in] sample is the sample number of interest, ranging from 0 to N-1.
WiredHome 1:d99a72afec32 237 /// @param[inout] rawsample is a pointer to where the specified sample will be written.
WiredHome 1:d99a72afec32 238 /// @returns true if the sample was available for the calling function.
WiredHome 1:d99a72afec32 239 /// @returns false if the same was not available.
WiredHome 1:d99a72afec32 240 ///
WiredHome 1:d99a72afec32 241 bool GetRawSample(int sample, RawPowerData_T * rawsample);
WiredHome 1:d99a72afec32 242
WiredHome 2:7f6a39ec5c01 243 /// Get the count of raw samples that are being taken,
WiredHome 1:d99a72afec32 244 ///
WiredHome 1:d99a72afec32 245 /// @returns count of samples that are taken.
WiredHome 1:d99a72afec32 246 ///
WiredHome 1:d99a72afec32 247 int GetRawSampleCount(void);
WiredHome 0:51c019b83ede 248
WiredHome 1:d99a72afec32 249 private:
WiredHome 0:51c019b83ede 250
WiredHome 1:d99a72afec32 251 void TakeSample(void); ///< Ticker callback to take a sample
WiredHome 1:d99a72afec32 252 BusOut * MuxBus; ///< pointer to the bus used to modify the multiplexer.
WiredHome 1:d99a72afec32 253 DigitalOut * Select; ///< pointer to the pin used to enable the multiplexer.
WiredHome 1:d99a72afec32 254 GetVoltage_T * GetVoltage; ///< pointer to the GetVoltage callback.
WiredHome 1:d99a72afec32 255 int AinCount; ///< count of direct A/D channels.
WiredHome 1:d99a72afec32 256 int NumMuxes; ///< count of the number of multiplexers.
WiredHome 1:d99a72afec32 257 int MuxChannels; ///< count of the number of channels per multiplexer.
WiredHome 1:d99a72afec32 258
WiredHome 1:d99a72afec32 259 AnalogIn * AinList; ///< This defines the list of AnalogInputs
WiredHome 1:d99a72afec32 260 int a2dChannel; ///< the AnalogIn channel number to sample
WiredHome 1:d99a72afec32 261 uint32_t uSecInterval; ///< time in uSec between each sample
WiredHome 1:d99a72afec32 262 int totalChannels; ///< total number of input channels
WiredHome 1:d99a72afec32 263 Ticker sampleTimer; ///< Timer to schedule the a/d sample.
WiredHome 2:7f6a39ec5c01 264 volatile bool inProcess; ///< indicates when a sample is in process.
WiredHome 2:7f6a39ec5c01 265 volatile bool isComplete; ///< indicates when conversion is complete.
WiredHome 1:d99a72afec32 266 RawPowerData_T * rawSamples; ///< points to an array of raw a/d value samples.
WiredHome 2:7f6a39ec5c01 267 volatile int sampleNum; ///< keeps track of the current sample in process.
WiredHome 1:d99a72afec32 268 float * fullScaleCurrent; ///< pointer to an array sized based on total number of channels.
WiredHome 1:d99a72afec32 269 float fullScaleVoltage; ///< the full scale voltage calibration setting.
WiredHome 0:51c019b83ede 270 };
WiredHome 0:51c019b83ede 271
WiredHome 0:51c019b83ede 272
WiredHome 0:51c019b83ede 273
WiredHome 0:51c019b83ede 274
WiredHome 0:51c019b83ede 275 #endif // POWERMEASUREMENT_H