This describes the firmware provided for the emon32 energy monitoring system. The software is modular, and should be easily portable to other microcontrollers and implementations.

This firmware is intended to be used with the OpenEnergyMonitor platform. Hardware systems are available directly from them.

Issues can be reported:

• As a GitHub issue
• On the OpenEnergyMonitor forums

Please include as much information as possible (run the v command on the serial link), including at least:

• The emon32 hardware that you using and the emon32-fw version (run the 'v' command on the serial link)
• All settings (run the l command on the serial link)
• A full description, including a reproduction if possible, of the issue

Contributions are welcome! Small PRs can be accepted at any time. Please get in touch before making large changes to see if it's going to fit before spending too much time on things.

Most default parameters can be adjusted in emon32.h.

The following default values are set out of the box.

OPA1 is configured as a pulse input and OPA2 is configured as a OneWire input.

The firmware version numbering follows semantic versioning. That is, for version X.Y.Z:

• X : major version with no guaranteed backward compatibility with previous major versions.
• Y : minor version where any added functionality has backward compatibility.
• Z : improvements and bug fixes.

Any firmware with X == 0 is considered unstable and subject to change without notice.

The emonPi3 will enumerate as a normal serial device and show as emonPi3.

A dedicated UART is used for debug, configuration, and data transmission. It has the following UART configuration:

• 115200 baud
• 8N1

It is available on:

• Raspberry Pi:
  • GPIO 14 (UART TX from Raspberry Pi)
  • GPIO 15 (UART RX to the Raspberry Pi)

The emon32 firmware is compatible with the OpenEnergyMonitor emonPi2 configuration options, which can be accessed through the debug serial link.

The following options are added:

The ADC is triggered by a dedicated timer (TIMER_ADC) with no intervention from the processor. Data are accumulated by DMA into a ping-pong buffer - when one sample set is being processed, another is being captured in the background.

Raw data from the ADC are downsampled (if configured) and then injected into the energy and power calculation routines. As there is a single ADC, CT values are interpolated between the appropriate voltage samples.

When a full report is ready, the following actions take place:

• 1 s before the report is due, any temperature sensors present are triggered to record a value.
  • The DS18B20 temperature sensor takes 750 ms to take a measurement in the default 12bit mode.
  • A report can also be triggered with the command t on the serial link.
• At the report time, the following values are calculated:
  • Power for each CT.
  • Accumulated energy for each CT.
  • Mains frequency.
  • Power factor
• Data are packed into two formats:
  • Key:value pairs for serial transmission.
  • Packed structure for transmission by the RFM module.
• Data are sent over the configured interface.
  • It is configurable whether data are always echoed on the debug console.

Compiling the firmware requires the the Arm gcc toolchain (may be available as a package in your distribution). The Makefile is for a Cortex-M0+ based microcontrollers, specifically the Microchip ATSAMD21J17 (datasheet, errata).

To build the firmware:

> make -j

In bin/, the following binary files will be generated:

• emon32-vX.Y.Z-(commit[-dirty]).bin
• emon32-vX.Y.Z-(commit[-dirty]).elf
• emon32-vX.Y.Z-(commit[-dirty]).hex
• emon32-vX.Y.Z-(commit[-dirty]).uf2

The -dirty tag (if present) indicates that there are uncommitted changes when the binaries are built.

The emonPi3 comes preloaded with a UF2 bootloader. This allows the firmware to be updated over USB without any specialised hardware. The following procedure should be used:

1. Connect to the host computer through the USB-C port.
2. Quickly double press the RESET button.
   • The LED will pulse slowly to indicate it has entered bootloader mode,
   • The drive EMONBOOT will appear on the host computer.
3. Copy bin/emon32-vX.Y.Z-(commit[-dirty]).uf2 to the EMONBOOT drive. The board will reset and enter the main program.

The bootloader can be updated by the same process as for uploading normal firmware. This will not normally need to be done.

If, for whatever reason, the bootloader is corrupted it can be flashed back to the board with the included binary. The bootloader binary is included in bin/bootloader-emonPi3-v* as a .bin and .elf file. You will need a suitable SWD programmer to do this.

• a2l.sh: converts a hex address to a file line. Usage: a2l.sh <address>
• elf-size.sh: this script decomposes the built .elf file into functions with their sizes.
• filter.py: generates the half band filter coefficients. Described in "Digital Filter".

The Cortex-M0+ does not have a hardware floating point unit, so all floating point operations are done in software. The gcc built in floating point functions are quite large and slow, and have been replaced with the Qfplib library. All floating point operations, including type conversions, should use these functions.

Below is a list of the compile time options, grouped by location. The value for emonPi3 is given in bold, and the allowed range in general is given:

• src/board_def.h; values mostly constrained by the physical arrangement.
  • NUM_CT: The number of CT channels. These must be contiguous from the lowest index above the voltage channels, but can be less than the number of physical channels. 12 [1..12]
  • NUM_V: The number of physical voltage channels. Due to the ADC and software architecture, this must always be the physical number of voltage channels even when only using a single phase. 3, [1..3]
  • SAMPLE_RATE: Sample rate, in Hz, for each channel before any downsampling. This is typically restricted by the -3dB point of the anti-aliasing filter. The total ADC sampling rate is (SAMPLE_RATE * (NUM_V + NUM_CT)). 4800, [4800]

The base configuration has an oversampling factor of 2X to ease the anti-aliasing requirments. Samples are then low pass filtered and reduced to f/2 with a half band filter. Filter coefficients can be generated using the filter.py script (./scripts/filter.py). This generates a header file (emon_CM_coeffs.h) which can be copied to the <emon32-fw>/src/ folder for use.

You will need SciPy and Matplotlib to use the filter designer. These are included in the virtual environment described in "Helper Scripts".

Assertions are implemented by the EMON32_ASSERT(condition) macro. The microcontroller will enter a breakpoint when an assertion fails and the PC is stored in the g_assert_info variable. The PC is used to find the file and line where the assertion failed using arm-none-eabi-addr2line.

Test programs are available for the emon_CM and eeprom modules, abstracted from the underlying hardware. In ./tests, run make cm or make eeprom followed by ./cm.test or ./eeprom.test respectively.

The following table lists the peripherals used in the SAMD21.

The files /src/board_def.h and /src/board_def.c contain options for configuring the microcontroller for a given board. Pin mappings and peripheral usage will need to be adjusted to your design.

Within the top level loop, there are no direct calls to low level hardware. You must provide functions that handle the hardware specific to the microcontroller you are using.

All peripheral drivers are in header/source pairs named driver_<PERIPHERAL>. For example, the ADC driver is in driver_ADC.*. If you are porting to a new microcontroller, you will need to provide implementations of all the functions exposed in driver_<PERIPHERAL>.h and any internal functions within driver_<PERIPHERAL>.c. If your microcontroller does not support a particular function (for example, it doesn't have a DMA), then either no operation or an alternative must be provided.

You will also need to ensure that the vendor's headers are included and visible to the compiler.

• mcu-starter-projects - good starting point for build chains for microcontrollers.
• printf - embedded printf implementation.
• pid.codes - reuse of a retired USB VID for open source projects.
• Qfplib - soft floating point library for Arm Cortex-M0.
• RFM69 - RFM69 driver from Low Power Labs used as reference.
• SSD1306 library - used as a reference for this implementation.
• tinyUSB - USB library (derived from 236aa9622).
• Using Asserts in Embedded Systems - custom assertions from Interrupt by Memfault.
• Wintertools - various build and linker scripts from Winterbloom.

• Glyn Hudson @ OpenEnergyMonitor
• Rob Wall @ OpenEnergyMonitor forums for discussions around all aspects of energy monitoring.
• Trystan Lea @ OpenEnergyMonitor