Diff: PowerMeasurement.h

Revision:

2:7f6a39ec5c01

Parent:

1:d99a72afec32

--- a/PowerMeasurement.h	Fri Oct 14 11:31:07 2016 +0000
+++ b/PowerMeasurement.h	Mon Oct 17 11:31:18 2016 +0000
@@ -53,11 +53,18 @@
     /// The called function should return the instantaneous voltage measurement. The value is an unsigned value
     /// normalized to the range of 0 to FFFF, with a zero-offset of 32768.
     ///
-    /// @returns a value in the range of 0 to FFFF.
+    /// If not voltage measurement system is in place, the user may choose not to define this function, in 
+    /// which case the power measurements cannot be made. The current measurements are still valid, and power
+    /// can be computed by the users program.
+    ///
+    /// @returns a value in the range of 0 to FFFF, biased to the mid-point of 32768 which represents 0.0v.
     ///
     typedef uint16_t (* GetVoltage_T)(void);
     
-    /// Each raw sample consists of 2 values - the voltage and the current at that moment.
+    /// Each raw sample consists of 2 values - the voltage and the current at that moment. The labels 'voltage'
+    /// and 'current' are somewhat artificial. The 'current' values are gathers from the analog inputs and 
+    /// multiplexers. The 'voltage' is from an external callback, which in turn might be using one of the 
+    /// analog inputs, or it might be from an external measurement source.
     typedef struct {
         uint16_t voltage;               ///< The voltage, in A/D units, which are scaled 0 to FFFF
         uint16_t current;               ///< The current, in A/D units, which are scaled 0 to FFFF
@@ -83,30 +90,36 @@
     /// The destructor.
     ~PowerMeasurement();
 
-    /// Defines the overall frequency of the line voltage.
+    /// Define the frequency of the line voltage, which in turn defines the sample-rate.
     ///
-    /// Based on this line frequency, the sample-rate for the measurement is set.
+    /// Based on this line frequency, the sample-rate for the measurement is set to achieve
+    /// 'SAMPLES_PER_CYCLE' samples per cycle, and 'CYCLES_PER_SAMPLE' cycles.
     /// 
     /// @param[in] Hz sets the line frequency.
     ///
     void frequency(float _Hz);
 
-    /// Defines the measuremenbt interval.
+    /// Define the measuremenbt interval, as an alternative to setting the frequency.
     ///
-    /// Instead of defining the measurement interval by line frequency, the period
+    /// Instead of defining the measurement interval by specifying the line frequency, the period
     /// can be directly set.
     ///
     /// @param uSec is the number of microseconds between samples.
     /// 
     void period_us(uint32_t uSec);
 
-    /// Set the voltage to current calibration value for a channel.
+    /// Set the analog input to current calibration value for a channel.
     ///
     /// Each analog input channel can be configured for the current sensor used on that channel.
     /// If the channel has a 30 A current sensor, that channel should be set to 30.0f.
     /// If the user calibrates the sensor more precisely, an improved calibration factor (e.g. 31.1)
     /// can be defined.
     ///
+    /// The calibration is based on the full-scale reading from the A/D. As the A/D is a normalized
+    /// uint16_t value, and biased to approximately mid-supply, the full scale range is then
+    /// 1/2 of the total range, or approximately 32767. Component tolerances, of the voltage 
+    /// reference, the mid-supply divider, and the current sensing component can affect this.
+    ///
     /// @param[in] channel defines the channel to calibrate.
     /// @param[in] fullScaleCurrentCalibration is the calibration factor representing the full-scale current.
     /// @returns true if the value is accepted.
@@ -116,23 +129,32 @@
 
     /// Set the voltage value representing the full scale measurement.
     ///
-    /// The GetVoltage callback is based on a uint16_t. This API sets the full scale voltage
-    /// representing the value FFFF. Based on an A/C input, biased to the split supply, this
-    /// represents an A/D value of 7FFF. When configured for a 120V circuit, which measures
-    /// approximately 170v peak, the fullScaleVoltageCalibration value would be 170.0f.
+    /// The GetVoltage callback is expecting a uint16_t as the return value. When configured for a 
+    /// 120V circuit, which measures approximately 170v peak, the fullScaleVoltageCalibration value 
+    /// would be 170.0f.
     /// 
+    /// The calibration is based on the full-scale reading from the A/D. As the A/D is a normalized
+    /// uint16_t value, and biased to approximately mid-supply, the full scale range is then
+    /// 1/2 of the total range, or approximately 32767. Component tolerances, of the voltage 
+    /// reference, the mid-supply divider, and the current sensing component can affect this.
+    ///
     /// @param[in] fullScaleVoltageCalibration is the full-scale voltage value.
-    /// @returns true if the value is accepted.
+    /// @returns true if the value is accepted, which it will be.
     /// 
     bool SetFullScaleVoltage(float fullScaleVoltageCalibration);
 
     /// Starts a measurement on the specified channel.
     ///
-    /// This starts the measurement on a specified channel.
+    /// This starts the measurement on a specified channel. The subsystem will then configure
+    /// the external multiplexer and a/d sampling to gather the the samples.
+    ///
+    /// The actual sampling of the data can be either synchronous, or asynchonous, based on a
+    /// #define value.
     ///
     /// @param[in] channel defines the channel to measure. This is in the range of 0 to N-1, where N is 
     ///         AinCount * MuxChannels.
-    /// @returns true if the measurement can be started.
+    /// @returns true if the measurement can be started (in async mode), or if the measurement is complete
+    ///         when operating in synchonous mode.
     /// @returns false if the measurement cannot be started - likely because of an incorrect channel 
     ///         selection.
     ///
@@ -140,28 +162,14 @@
 
     /// Determines if the conversion is complete and the results are readable.
     ///
+    /// When operating in the asynchronous mode, this API can be used to detect when the conversion
+    /// is complete.
+    ///
     /// @returns true if the measurement is complete (or if no measurement is in process).
     /// @returns false if the measurement is in process.
     ///
     bool readable();
 
-    /// Get the real power measurement.
-    ///
-    /// This retrieves the real power measurement for the channel which just completed measurement.
-    /// This is the average of the instantaneous power.
-    ///
-    /// @returns the real power measurement.
-    ///
-    float GetRealPower();
-
-    /// Get the rms voltage measurement.
-    ///
-    /// This retrieves the rms voltage measurement for the channel which just completed measurement.
-    ///
-    /// @returns the rms voltage measurement.
-    ///
-    float GetRMSVoltage();
-
     /// Get the rms current measurement.
     ///
     /// This retrieves the rms current measurement for the channel which just completed measurement.
@@ -170,22 +178,49 @@
     ///
     float GetRMSCurrent();
 
+    /// Get the rms voltage measurement.
+    ///
+    /// This retrieves the rms voltage measurement for the channel which just completed measurement.
+    ///
+    /// @note This is only valid if the user supplied GetVoltage() function was provided.
+    ///
+    /// @returns the rms voltage measurement.
+    ///
+    float GetRMSVoltage();
+
+    /// Get the real power measurement.
+    ///
+    /// This retrieves the real power measurement for the channel which just completed measurement.
+    /// This is the average of the instantaneous power.
+    ///
+    /// @note This is only valid if the user supplied GetVoltage() function was provided.
+    ///
+    /// @returns the real power measurement.
+    ///
+    float GetRealPower();
+
     /// Get the apparent power measurement.
     ///
     /// This retrieves the apparent power measurement for the channel which just completed measurement.
     ///
+    /// @note This is only valid if the user supplied GetVoltage() function was provided.
+    ///
     /// @returns the apparent power measurement.
     ///
     float GetApparentPower();
 
     /// Get the power factor
     ///
+    /// @note This is only valid if the user supplied GetVoltage() function was provided.
+    ///
     /// @returns the power factor measurement.
     ///
     float GetPowerFactor();
 
     /// Get the peak current measurement values from the recent sample.
     ///
+    /// @note if either parameter is null, that data will not be provided.
+    ///
     /// @param[inout] negPeak is a pointer to the negative going peak current measured.
     /// @param[inout] posPeak is a pointer to the positive going peak current measured.
     /// @returns true if a measurement was completed and the data was updated.
@@ -205,8 +240,7 @@
     ///
     bool GetRawSample(int sample, RawPowerData_T * rawsample);
 
-
-    /// Get the count of raw samples that are being taken
+    /// Get the count of raw samples that are being taken,
     ///
     /// @returns count of samples that are taken.
     ///
@@ -227,10 +261,10 @@
     uint32_t uSecInterval;          ///< time in uSec between each sample
     int totalChannels;              ///< total number of input channels
     Ticker sampleTimer;             ///< Timer to schedule the a/d sample.    
-    bool inProcess;                 ///< indicates when a sample is in process.
-    bool isComplete;                ///< indicates when conversion is complete.
+    volatile bool inProcess;                 ///< indicates when a sample is in process.
+    volatile bool isComplete;                ///< indicates when conversion is complete.
     RawPowerData_T * rawSamples;    ///< points to an array of raw a/d value samples.
-    int sampleNum;                  ///< keeps track of the current sample in process.
+    volatile int sampleNum;                  ///< keeps track of the current sample in process.
     float * fullScaleCurrent;       ///< pointer to an array sized based on total number of channels.
     float fullScaleVoltage;         ///< the full scale voltage calibration setting.
 };