EmonLibCM - Version 2.2.2

EmonLibCM is a Continuous Monitoring alternative to EmonLib. Whereas emonLib repeats, every 5 or 10 s, a sequence of voltage and current measurements in each of the input channels for a short period, normally 200 ms, and then reports the measurements back to the sketch for onwards transmission to (for example) emonCMS; emonLibCM continuously measures in the background the voltage and all the current input channels in turn, calculates a true average quantity for each and then informs the sketch that the measurements are available and should be read and processed.

Temperature measurement with up to 6 DS18B20 sensors, and pulse counting, is included in the library. Neither must be added separately in the sketch.

The CM library will always give an accurate measurement of the average over the reporting period of the voltage, and for each of up to 5 channels the current, real and apparent power and power factor. A cumulative total of Watt-hours for each channel is also available. It is suitable for single phase or split phase operation at 50 Hz or 60 Hz. It will give more accurate values than the ā€˜discrete sampleā€™ sketch where rapidly switched loads are in use, for example a burst mode energy diverter or an induction hob.

The inputs can be calibrated for any realistic voltage and current, the default calibration is for an emonTx with a UK a.c. adapter and 100 A : 50 mA current transformers.

The library is distributed as a compressed Zip file. This contains the library files themselves (emonLibCM.cpp & emonLibCM.h), two directories with example sketches and a PDF format User Documentation file that contains notes on using the library, a full description of each method, instructions both for setting the initial configuration and for calibration, and brief notes explaining the example sketches. EmonLibCM also depends on several other libraries, and these are listed.

INSTALLING THE LIBRARY
The directory emonLibCM together with its contents should be extracted from the zip file and copied into the ā€œlibrariesā€ directory, alongside (in the same level of the hierarchy as) the emonLib directory.

If you wish to use the example sketches, these (in their respective directories) should be moved or copied into your Sketchbook.

The User Documentation PDF file can be moved or copied to a convenient location of your choosing.

emonLibCM.zip (131.3 KB)

It is my intention to post any updates here, in this Topic.

A separate sketch to measure the phase difference between the a.c. adapter and the c.tā€™s is available here;

CHANGES
Version 2.0 (released 21/11/2018): Corrected some errors generated when converting from the original sketch, and incorporates improved handling of phase/timing compensation and improved removal of the d.c. bias. There are no other major changes from the version that has been tested by @TrystanLea since early 2017.
Changes for V2.01 (released 3/12/2018): Errors in phase error correction.
Changes for V2.02 (released 13/7/2019): Temperature measurement: Added ā€œBAD_TEMPERATUREā€ return value when reporting period < 0.2 s, getLogicalChannel( ), ReCalibrate_VChannel( ), ReCalibrate_IChannel( ) added, setPulsePin( ) interrupt no. was obligatory, pulse & temperatures were set/enabled only at startup, setTemperatureDataPin was ineffective, preloaded sensor addresses were not handled properly.
Changes for V2.03 (released 25/10/2019): Mains Frequency reporting with getLineFrequency( ) added, energy calculation changed to use the internal clock rather than mains time. ADC reference source was AVCC and not selectable - ability to select using setADC_VRef( ) added (Note the warning in the documentation regarding the use of this function).
Changes for V2.04 (released 1/8/2020): getDatalog_period() has been added, the datalogging period now has a minimum value of 0.1 s. The list of temperature sensor addresses is now ignored if first device is not a DS18B20. ā€˜BAD_TEMPERATUREā€™ is now returned if sensor address is made invalid during operation, and ā€˜UNUSED_TEMPERATUREā€™ is returned for all addresses above the number of sensors detected. The sensor power pin (if used) is now always set low after a reading, and when temperature readings are disabled. The resolution of the temperature measurements is reduced when datalogging faster than once per second is requested, and temperature measurement is disabled when datalogging faster than 5 per second is set. In the example sketches, an ā€˜elseā€™ clause has added to ā€œif (EmonLibCM_Ready())ā€ to keep JeeLib alive, and a third example sketch, only for emonTxā€™s with a RFM69CW, using the JeeLib ā€˜Classicā€™ message format but not using JeeLib itself, has been added. There have also been some cosmetic changes.
Changes for V2.1.0 released 9/7/2021): The following features have been added: The ability to handle a 2nd pulse input (where the hardware permits). N.B. The definition setPulsePin(byte channel, int _pin) is incompatible with the old definition of setPulsePin(int _pin, int _interrupt). Also, a solution for the 85 Ā°C problem with temperature sensors, a special print format for the emonPi, ā€˜settersā€™ to initialise Wh counters & pulse count.
If no a.c. voltage is detected (the threshold is around 2% of the normal voltage), an assumed Vrms is now used to calculate power, VA & energy, whilst p.f. and frequency both report zero. An error in the phase shift calculation meant a wrong correction was applied when ctā€™s were sampled out of sequence.
Changes for V2.1.1 (released 26/7/2021): A typo for the name of the header file corrected. (No change to the documentation.)
Changes for V2.1.2 (released 7/7/2021): A name used only within the library conflicted with a global name used by some sketches.
Changes for V2.2.0 (released 14/9/2021) : The sole change in this release resolves a major shortcoming with the way pulse counting is handled. Sketches compiled with this release of the library and with no further changes might not count pulses correctly, or at all. It will almost certainly be necessary to change the value of the pulse counting parameter ā€˜periodā€™ taken by EmonLibCM_setPulseMinPeriod( ) to ensure correct operation. For full details, see emonLibCM V2.2.0 Release Note.pdf (136.0 KB)
Changes for V2.2.1 (released 30/10/2021) : Debugging statements accidentally left in pulse ISR removed. Re-released 5/12/2021 with zip file contents re-arranged & comment added to source files to clarify.
Changes for V2.2.2 (released 15 /9/2022) : If the temperature sensor pin had not been set but relied on the default, it was possible that the sensors would not be powered for the initial search.

USING THE LIBRARY
Three example sketches are provided as part of the distribution:
EmonTxV34CM_min is the absolute minimum sketch required to exercise the library and produce meaningful values.
EmonTxV34CM_max gives an example of every API call available. However, as distributed, it actually changes nothing as everything is again given the default value. If you need to change one of the defaults, then only the API call that sets that value is needed, and you can copy and add that call to the "minimumā€™ demo sketch.
EmonTxV34CM_min_RFM69 is essentially the same as EmonTxV34CM_min, but uses the code in the file rfm.ino to drive the RFM69CW radio, so making better use of the RFM69ā€™s capabilities and minimising disturbance to the energy sampling.

The EmonLibCM library is not a direct replacement for the ā€˜discrete sampleā€™ library emonLib. Significant changes will be need to be made if emonLibCM is to replace emonLib in any particular sketch.
The example sketches are intended only as a demonstration of the library. They do not (for example) take any account of the DIP switch settings of the emonTx V3.4. Great care must be taken if any significant additional load is to be put on the processor.

 

Acknowledgements.
Jƶrg Becker (@joergbecker32) for his background work on interrupts and the ADC.
Robin Emley (@calypso_rae) for his energy diverter software, from which the major part of the library was derived by @TrystanLea
@ursi (Andries) and @mafheldt (Mike Afheldt) for suggestions made at EmonLib: Inaccurate power factor and Rms calculations in EmonLib and Learn documentation - #3 by mafheldt

 

MD5 Hashes: 
EmonLibCM.zipda9f749f61acc5664b02486d3811a5ed
EmonLibCM.cppe56bbecd674432ae0bff61653fdf99b1
EmonLibCM.haaa337da3bd9b164eedfc46c30b60eb1
 
emonLibCM User Doc.pdf6654bb51c76fe6bccabd09c7438bd0dd

Please see EmonLibCM - Version 2 (Support) to comment or request support.

3 Likes

EmonLibCM - Version 2 is also mirrored on Github here

GitHub - openenergymonitor/EmonLibCM: Continuous Monitoring alternative to EmonLib

As of 10 October, 2023, this is no longer true. I understand that the Github version has diverged from this, and support for that will be provided by Trystan Lea. - Robert Wall [maintainer of the version published here]