This describes the firmware provided for the emonTH3 temperature, humidity, and pulse counting system.
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 emonTH3 hardware that you using and the emonTH3-fw version (run the 'v' command on the serial link)
- All settings (run the
lcommand 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.
Tip
A clang-format autoformat pattern is included in the repository. Run the install-hooks.sh script to install the pre-commit hook to the autoformatter. You may need to install clang-format using your OS's package manager.
Note
Please bear in mind that this is an open source project and PRs and enhancements may not be addressed quickly, or at all. This is no comment on the quality of the contribution, and please feel free to fork as you like!
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 versionsY: minor version where any added functionality has backward compatibilityZ: improvements and bug fixes
Any firmware with X == 0 is considered unstable and subject to change without notice.
Note
Build information, including compiler version and commit, is generated during the build process and included in the binary.
A dedicated UART is used for debug, configuration, and data transmission. It has the following UART configuration:
- 115200 baud
- 8N1
REVISIT Configuration options
Note
All options can be listed by entering ?.
Warning
The RFM69 transmitter will be damaged if it is run at maximum power without an antenna.
REVISIT Update description for SAML
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).
Note
To find which version, if any, of the toolchain is on your path, enter arm-none-eabi-gcc --version. You can set the path to a compiler off your path by setting the TC_PATH variable in Makefile.
To build the firmware:
> make -j
In bin/, the following binary files will be generated:
emonTH-vX.Y.Z-(commit[-dirty]).binemonTH-vX.Y.Z-(commit[-dirty]).elfemonTH-vX.Y.Z-(commit[-dirty]).hexemonTH-vX.Y.Z-(commit[-dirty]).uf2
The -dirty tag (if present) indicates that there are uncommitted changes when the binaries are built.
REVISIT Instructions to flash through SWD
Note
A Python virtual environment shoulde be setup by running python3 -m venv venv && source venv/bin/activate && pip3 install -r requirements.txt in ./scripts/.
a2l.sh: converts a hex address to a file line. Usage:a2l.sh <address>elf-size.sh: this script decomposes the built.elffile into functions with their sizes.
The Cortex-M23 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.
REVISIT Anything to do at compile time?
Assertions are implemented by the EMONTH_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.
- mcu-starter-projects - good starting point for build chains for microcontrollers.
- RFM69 - RFM69 driver from Low Power Labs used as reference.
- Using Asserts in Embedded Systems - custom assertions from Interrupt by Memfault.
- Wintertools - various build and linker scripts from Winterbloom.
- Glyn Hudson @ OpenEnergyMonitor
- Trystan Lea @ OpenEnergyMonitor