genmon: reading a backup generator's controller over Modbus from a Pi

The controller is the interface, and there are many of them

genmon is a generator monitoring application using a Raspberry Pi and WiFi, and it monitors a backup generator that uses the Generac controllers over a WiFi or wired connection.

The long list of supported controllers is the substance of the project, because reading a generator means reading Modbus registers and the register map is specific to each controller family.

The Generac Nexus and Evolution controllers, versions 1.0 and 2.0, are the residential product line. Honeywell and Eaton use the same controllers under different names, which the readme spells out: they call them Sync 1.0 for Nexus, Sync 2.0 for Evolution 1.0, and Sync 3.0 for Evolution 2.0. That naming equivalence is a practical detail, since a controller sold as a Honeywell Sync or an Eaton Sync is a Generac Nexus or Evolution underneath, and the software support follows the underlying part rather than the brand on the label.

The industrial side is covered too, with the Generac H-100 controller used in industrial generators from Generac and Eaton, the G-Panel based industrial controllers, and the PowerPact line, for which the wiki has a page on replacing the Generac MobileLink with genmon. The PowerZone Pro and Sync and the PowerZone 410 are listed as well, and the 2008 era pre-Nexus controllers are supported with a known issues page for that generation.

Then the third party controllers, reached through a custom controller interface for supporting other generators that use Modbus over serial or Modbus over TCP. Deep See Electronics, including the 7320MKII controller, the ComAp controller, Briggs and Stratton including the GC-1031 and GC-1032, the Kohler APM604, the MEBAY DC4x and DC9x, and SmartGen HGM40x0 all appear in that list.

So the coverage is broad in brand names and narrow in mechanism. Everything here is Modbus, and the software value is in the per-controller register maps, which is why the wiki pages are per model rather than generic.

What the monitoring actually reports

The feature list is long and specific enough to be worth reading in detail, because it shows what a generator can tell you.

The monitoring detects and reports maintenance, start and stop and alarm logs, with the note that no maintenance log exists on the Nexus or the industrial units. It displays the generator serial number, and reports generator warnings and faults.

The generator status is where the depth is. Under engine state there is the generator switch state with Auto, On and Off, the engine state with values including Stopped, Starting, Exercising, Running Manual, Running Utility Loss, Stopped due to Alarm and Cooling Down, the battery voltage and charging status, the relay output state covering the starter, the fuel relay and the battery charger among others for liquid cooled models, and the engine RPM, Hz and voltage output. There is the generator controller time, and a line state with the utility voltage level and the transfer switch state, and that last one is documented as applying to the Evolution liquid cooled model and to industrial generators with HTS, MTS or STS transfer switches.

The outage information tracks the time since the last outage, the current utility voltage, and the minimum and maximum utility voltage since the program started. The maintenance information covers the weekly exercise time and day, weekly or biweekly and monthly where the generator supports it, the hours until the next scheduled service, the total run hours, and the firmware and hardware versions.

And there is a block of statistics about the monitoring program itself, including the time since the program launched and the health of the Modbus and serial communications alongside the health of the program, which is the diagnostic you want when the data stops arriving.

The output paths, and remote control of the generator

The alert and output surface is where this becomes a useful system rather than a status page.

Email notification covers engine state change, switch state change, and critical or warning messages from the generator. There is a web based application for viewing generator status with a limited rights and full rights login for the web interface. SMS notifications of generator state and power outages, via the Twilio SMS API or an Expansion Cellular Modem. Push notifications through pushover.net and Slack. CallMeBot notifications for WhatsApp and Telegram. And syslog logging of generator events.

Then the control side, which is the part to think carefully about. There is the ability to set the exercise time, to set the generator time, and to start, stop, exercise and start or activate the transfer switch, meaning powering the house off the generator, remotely. The transfer switch operation deserves a second look, because activating it means your house loses grid power whether or not the generator is running, and a remote command that does that needs to be right.

Beyond the core monitoring there are also the power, current and fuel consumption readings on selected models, MQTT integration for third party home automation support, a service journal for logging maintenance and repair, backup of configuration files, enhanced exercise options for the Evolution and Nexus controllers including exercising the transfer switch, a firmware update notification for the Evolution 2.0, SNMP monitoring, and optional LDAP authentication for the web interface.

The three integrations worth calling out are SNMP, MQTT and LDAP. SNMP gives you a place to send the generator's state into an existing monitoring system. MQTT is what makes it usable inside a home automation stack. And LDAP matters for anyone running the web interface on a network where a local password is not acceptable.

Running it on a Pi, and the hardware reality

The readme is unusually honest about what this involves, and that honesty is a good sign.

The software is written mostly in Python and has been tested with a Raspberry Pi 3, with the Pi Zero, Pi Zero W, Pi Zero 2W, Pi 2, Pi 3b+ and Pi 4 also validated. Both 32 and 64 bit versions of Raspbian have been used with the project.

The hardware requirement is stated without euphemism. To use the project you would need to create a physical enclosure for the Raspberry Pi and possibly make a cable to connect the Pi to the generator controller, or purchase pre-assembled hardware, with wiki pages for both the cable and the custom hat. And then the sentence that decides whether the project is for you: if you are comfortable doing these things and you have a backup generator that has a supported controller, then this project may be of interest to you.

That is an accurate description of the project. A generator controller is a serial or TCP device in a box next to the engine, and reading it means physically getting a computer next to it and wiring a serial connection.

The system requirements list the software side. Genmon 2.0 and higher requires Python 3.9 or higher, while version 1.20.00 could use Python 3.7 or higher, and the bullseye and higher version of the Raspberry Pi OS support Python 3.9 and higher, with the buster version supporting Python 3.7. It also needs a Linux based operating system, mostly for the file system storage location, and a TCP/IP.

The repository layout matches a system with several entry points rather than one application. There is genmon.py and genserv.py, plus genloader.py, ClientInterface.py, a genmonlib directory, a maintenance shell script genmonmaint.sh, a startgenmon.sh launcher, and an OtherApps directory for the extra integrations. There is an addon directory, conf and data directories, templates and static directories for the web interface, tests, and a Diagrams directory holding the controller reference images that the wiki pages link to.

Dependencies, and why some versions are pinned hard

The requirements file is a long list and several entries carry a comment explaining a pin, and those comments are the most informative lines in it.

The base set covers the web interface and the notification channels: Flask and flask-compress, configparser, pyserial for the serial link, crcmod for the Modbus checksums, pyowm for weather, pyopenssl, twilio for SMS, chump, paho-mqtt pinned at 1.6.1, smbus, ldap3 for the optional directory authentication, pyotp for one time passwords, webauthn pinned at 2.7.0, psutil, spidev, the bleson package pulled straight from a git repository, bleak, voipms, RPi.GPIO, aiohttp and zeroconf.

The pinning comments explain themselves. pysnmp is fixed at 7.1.21 because 7.1.22 is the last version to support Python 3.9. And pyasn1 is fixed at 0.6.1 because pysnmp 7.1.21 requires pyasn1 below 0.6.1. That is a chain of constraints, and the interesting thing is that the constraint is anchored on Python 3.9 rather than on the project.

One entry is commented out with a reason. The fluids package breaks on 32 bit trixie and takes a long time on slower systems like the Pi 3 and the Pi Zero, so it is removed from the base install.

The BLE packages deserve a note. bleson is pulled from a git repository rather than from PyPI, and bleak is the better known Bluetooth stack. Together with smbus and RPi.GPIO, they point to the wireless and sensor side of the project, which is the more general part of what genmon does: reading a controller over Modbus is the core, and the additional integrations let the same data feed a home automation stack.

The licence is GPL-2.0, and the support statement is the other thing worth reading. The project is free to use under the posted license agreement, and it was written and is supported by one person, with testing and some documentation supported by users of the software. The author created it for personal use and later made it available to anyone interested, and does accept tips via paypal.

Editorial conclusion

Adopt genmon if you own a generator whose controller speaks Modbus and you want its state visible and controllable without a commercial monitoring service. Do not adopt it if your controller is not on the supported list, since the Modbus register maps are specific per controller, and note that the author states it is written and supported by one person, so the bus factor is one. Before you commit, confirm your exact controller model against the list, plan the physical installation, and try it read-only first before using the remote start and transfer switch features.

Frequently asked questions

Official sources

1. Issues
2. jgyates/genmon on GitHub
3. License: GPL-2.0
4. README
5. Releases