-
-
Notifications
You must be signed in to change notification settings - Fork 79
1 Software Overview
genmon.py is a python program to communicate with the Generac Evolution Controller used in some liquid and air cooled standby generators. The project uses python3. It was originally tested with python 2.7, however python 3.x is the default and testing only occurs with python 3.x. This program will communicate with the Generator Controller over the serial port using the MODBUS protocol. The application will allow the display and monitoring of the generator much like the Generac Mobile Link product.
Once setup the genmon.py program will send an email when your generator does interesting things (power goes out, alarm on the generator, weekly exercise, etc). The program will also allow emails to be sent to an IMAP email folder. The program monitors the IMAP folder and takes commands from the email subject. The format of the subject of the email should have "generator:" followed by one or more of the following commands:
Commands:
status - display engine and line information
maint - display maintenance and service information
outage - display current and last outage (since program launched)
info, also shows utility min and max values
monitor - display communication statistics and monitor health
logs - display all alarm, on/off, and maintenance logs
registers - display contents of registers being monitored
settime - set generator time to system time
setexercise - set the exercise time of the generator
i.e. setexercise=Monday,13:30,Weekly
setquiet - enable or disable exercise quiet mode,
i.e. setquiet=on or setquiet=off
setremote - issue remote command. format is setremote=command,
where command is start, stop, starttransfer,
startexercise. i.e. setremote=start
help - Display help on commands
Example email subject lines:
generator: status maint
generator: setexercise=Tuesday,23:45,Weekly setquiet=on
A few notes about commands:
The setremote command issues commands directly to the controller. Start and stop commands should be back to back, i.e. is is not recommended to issue start followed by starttransfer, you should have a stop after each start command. Also, when the starttransfer command is used, once a stop command is issued the controller will set the transfer switch back to "utility" but the generator will continue to run in "cool down" mode for few minutes. This is normal and the behavior is controlled by the controller.
Remote commands that start and stop the generator engine will not work if the following conditions are true:
- Mains power is disconnected, in any mode
- The generator is in 'off'
- The generator is running in 'Manual'
The setexercise command can not set an exercise time that is within a few minutes of the current generator time. This is a limitation of the controller.
The settime command will set the generator time to the time of the Raspberry Pi. If you Raspberry Pi is setup to your correct time zone and your Linux distribution (e.i. Raspbian ) uses network time protocol (NTP) then this will set your generator time to the accurate time. Since the register interface to the generator controller does not expose seconds, genmon.py will wait until the Raspberry Pi time seconds are zero before setting the command. This allow the time to be accurate within a minute and the seconds that are off from the exact time are consistent. For this reason the time may not be update for one minute when this command is used.
The program uses the file genmon.conf for configuration data. Typical use is to install the software and edit the settings vis the web interface. By default the *.conf files used to configure genmon.py and the other associated programs is located in the /etc/genmon/ directory. genmon.py uses the following modules so they are external dependencies of the program and they will need to be installed before running the program. These modules are installed via the genmonmaint.sh program.:
- crcmod - used for MODBUS CRC calculation.
- pyserial - used for serial communication.
- pytz - Helper library for timezone parsing, which is used for determining Daylight Savings Time.
- configparser - used for parsing configuration file
- python-openssl - Python wrapper module around the OpenSSL library
In addition the the external dependencies there are additional python modules and files included in this project that are used by the software. The *.py files must reside in the genmonlib directory below the location of genmon.py
- ./genmonlib/mymail.py - This module provides support for sending email and monitoring an IMAP email folder for incoming mail. The mail module can be configured by modifying the mymail.conf file and placing it in the /etc directory.
- ./genmonlib/mylog.py - This modules provides logging support to the other modules.
- ./genmonlib/mythread.py - This module provides thread related housekeeping for genmon.py and mymail.py
- ./genmonlib/mypipe.py - This module provides internal program communications
- ./genmonlib/mycommon.py - This module provides common functions for all modules
- ./genmonlib/mymodbus.py - Provides modbus protocol support
- ./genmonlib/myserial.py - Provides serial communications support
- ./data/ALARMS.txt - This text file contains generator error codes with descriptions and potential solutions. It is used by the program to supply additional details when error conditions are detected by the generator monitor.
Due to the location of log files and conf files, root privileges are needed to execute the program. Other than these files, there are no requirements of root privileges.
Installation of genmon.py is simple. You can install the files manually however it is recommended to use the genmonmaint.sh program to install and startgenmon.sh to start and stop the program.
The program is designed to run in the directory structure that exist in the github repository. All config files (./conf/*.conf) go in /etc/genmon/ (you can change this directory the command line if you want to install multiple instances of genmon). Edit the *.conf files so they are specific to your installation (email user name and password, etc). You can launch the program as a background application if needed, i.e. "python3 genmon.py &". Also I use crontab to load the application as a background process on boot by launching a bash script via crontab. The script loads the app via the "python3 genmon.py &" command.
To run genmon.py as a foreground application:
sudo python3 genmon.py
To run as a background app:
sudo python3 genmon.py &
To stop genmon.py as a foreground application type Ctrl+C. The following command will stop the running instance of genmon.py:
sudo pkill -f genmon.py
Note the above will work if you are running a single instance of genmon. If you are monitoring multiple generators then you should kill the process by the process ID (pid).
The configuration file genmon.conf is used to set options for the genmon.py program. The genmon.py will auto-detect your controller type but you can override that in genmon.conf.
Evolution Controller Front Panel
These options documented here and the file /etc/genmon/genmon.conf can be edited directly, however most settings can be modified via the web interface. The web interface is the recommended method to update the configuration file.
These options are used for configuration and enabling debugging. genmon.conf has the following options:
The parameters for genmon.conf are documented here
Note: Weather information relies on the pyowm (Python Open Weather Map) python library. If you installed the Generator Monitor Software before version 1.9.6 and are upgrading you must run this command:
sudo pip3 install pyowm
If you installed version 1.9.6 or later then this library installation is included in install script and instructions.
Gmail IMAP has been tested with this application. It should be easy to test this other email providers. All mail processing is contained in mymail.py and mymail.conf.
The parameters for mymail.conf are documented here
Please note that if you use IMAP to receive email (i.e. allow genmon to receive commands via email) you will need to also set the incoming_mail_folder and processed_mail_folder options in genmon.conf.
A note about email and security: The genmon.py app monitors folder on an IMAP email account for emails with a subject containing "generator:". If this is found, the remaining characters of the subject filed are parsed for commands for the monitor program. Since commands are sent to genmon.py via the subject line of an email, is is suggested that some level of email filtering occur on the receiving email account. For example, gmail supports email filters that if emails arrive from specific people with specific words in the subject, move them to specific folders. You could then have genmon.py monitor the specific folder used in your filter to only allow specific emails to send commands to genmon.py. If this approach is used then genmon.py can be configured (via mymail.com) to monitor a specific IMAP folder.
For sending email, SMTP is used. The email recipient can be any valid email. Many mobile providers implement email to SMS translations so SMS can be used if your mobile provider supports this feature. A list of email to SMS provides is here.
Most email providers like Google or Microsoft have increased security on email accounts. These security increases dictate that approved and reviewed applications use the higher security protocols and smaller or open source applications are required to use one of the following workarounds to access email:
Use enable "less secure apps". - This method reduces the security of the account by enabling legacy protocols to access email. Google has deprecated this method and I expect other providers to do the same.
Application Specific Passwords. - This method is preferred and requires two factor auth (2FA) to be enabled on the email provider account settings. More info on application specific passwords for gmail is provided here.
See the Tips and Tricks wiki page on how to setup genmon mail with a gmail account.
The program ClientInterface.py is a test application for communicating with genmon.py via sockets. this program is designed to be run on the command line and requires some of the modules in the ./genmonlib directory (mycommon.py, mylog.py and myclient.py). If you want to run ClientInterface.py on a different machine, you must have python3 installed and it is recommended that you use the directory structure of the github repository. The ClientInterface.py app takes one command line argument, the IP address of the computer running genmon.py (the default is localhost). To issues commands to an instance genmon.py on a system at IP address of 192.168.11.100 you would do the following:
python3 ClientInterface.py -a 192.168.11.100
Clientinterface.py takes two optional command line parameters:
-a IP Address or none for localhost -p TCP port or none for default port
If you are running ClientInterface on the system running genmon then you do not need any command line parameters. If you are only running once instance of genmon then you do not need to specify the TCP port.
Once the app is executed you should be faced with a prompt ">". From this prompt you can send commands to genmon.py. Commands are prefaced with "generator:". For example to issue the command "status" you would enter the "generator: status" at the ">" prompt when running ClientInterface.py. The commands accepted are listed in the genmon.py section and they match the email based commands.
ClientInterface.py logs errors to client.log in the current directory.
The program gengpio.py is a console python application that will communicate with genmon.py and set or reset GPIO pins on the Raspberry Pi. The application requires modules in the genmonlib directory. The program takes one command line argument of the IP address of the system that genmon.py is running (localhost is default).
The following are the default values for the GPIO pin assignment. These values can be modified by editing the /etc/genmon/gengpio.conf file. Set any value to zero in gengpio.conf to have this value ignored (no used) so you can free up GPIO for other uses
The parameters for this add on are documented here
- Generator READY GPIO 23 (pin 16)
- Generator ALARM GPIO 24 (pin 18)
- Generator SERVICE DUE GPIO 25 (pin 22)
- Generator EXERCISING GPIO 8 (pin 24)
- Generator RUNNING GPIO 7 (pin 26) (Running in Manual or Auto)
- Generator OFF GPIO 9 (pin 21) (Off with Switch Off or Manual)
- Genmon Health GPIO 2 (pin3) (Off when system OK)
- Internet Connection GPIO 3 (pin 5) (Off when internet connection OK)
- Raspberry PI CPU Temp (see gengpio.conf file for details)
The following GPIO will be activated on Evolution Controllers:
- Overspeed/Underspeed (alarms 1200-1206, 1600-1603) GPIO 5 (pin 29)
- Low Oil (alarm 1300) GPIO 6 (pin 31)
- High Temp (alarm 1400) GPIO 13 (pin 33
- RPM Sensor (alarm 1500-1521) GPIO 19 (pin 35)
- Overvoltage/Undervoltage (alarm 1800-1803, 1900-1906) GPIO 26 (pin 37)
- Overcrank (alarm 1100-1101) GPIO 21 (pin 40)
- Overload (alarm 2100-2103) GPIO 20 (pin 38)
- Governor (alarm 2500-2502) GPIO 16 (pin 36)
- Warning (alarm 0000, Evolution Air Cooled Only) GPIO 12 (pin 32)
All outputs are high when active.
Example of LED circuit connected to Raspberry Pi GPIO. To execute gengpio.py type:
sudo python3 gengpio.py <-a IPAddress, -c PathToConfig>
Where: -a IP Address of your Pi running genmon.py or omit for localhost -c path to the genmon.conf file (omit for the default of /etc/genmon/)
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
The program gengpioin.py is a console python application that will communicate with genmon.py and issue remote commands based on Raspberry Pi GPIO input pin. The application requires modules in the genmonlib directory. The program takes one command line argument of the IP address of the system that genmon.py is running (localhost is default). The program uses the internal pull up resistors in the Broadcom chipset on the Raspberry Pi. The program also uses the python module RPI.GPIO which comes already installed on most raspberry Pi distributions.
- If GPIO 17 (header pin 11) makes a high to low transition, the remote stop command is issued
- If GPIO 27 (header pin 13) makes a high to low transition, the remote start command is issued
- If GPIO 22 (header pin 15) makes a high to low transition, the remote start/transfer command is issued
To execute gengpioin.py type:
sudo python3 gengpioin.py <-a IPAddress, -c PathToConfig>
Where: -a IP Address of your Pi running genmon.py or omit for localhost -c path to the genmon.conf file (omit for the default of /etc/genmon/)
The parameters for this add on are documented here
Example GPIO input circuit. Note: external pull up resistor is not needed as it is handled by the chipset.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
This is a much simplified version of gengpio.py that drives just a single LED to give two possible outputs by controlling the number of ‘fast’ blinks. The program gengpioledblink.py is a console python application that will communicate with genmon.py and if genmon Monitor Health is OK, it will blink a LED connected to a GPIO pin on the Raspberry Pi, 1 long then 5 short blinks if all is OK or 1 long then 3 short blinks if not OK.
The application requires modules in the genmonlib directory. The program optionally takes 1 or 2 command line arguments, the IP address of the system that genmon.py is running (localhost is default) and/or then path to the gengpioledblink.conf file. The default GPIO is 18 which is pin number 12. This can be changed in the gengpioledblink.conf file once it is copied to the config directory, it is the only parameter in the file and is given as the board pin number not the GPIO number.
Example of LED circuit connected to Raspberry Pi GPIO.
To execute gengpioledblink.py type:
sudo python3 gengpioledblink.py <-a IPAddress -c PathToConfig>
Where: -a IP Address of your Pi running genmon.py or omit for localhost -c path to the genmon.conf file (omit for the default of /etc/genmon/)
The parameters for this add on are documented here
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
This program will log the state of the generator (RUNNING, EXERCISE,READY, ALARM, SERVICE) along with a date/time to a comma delimited text file (.csv). This file can be opened by Excel. The date/time entry can be formated to an Excel date/time data type. This will allow an analysis to be performed on your generator usage. The program has the following command line syntax:
sudo python3 genlog.py -a <IP Address or localhost> -f <outputfile> -c <Optional, path to config files>
Example:
sudo python3 genlog.py -a 192.168.1.50 -f logfile.csv
The application requires modules in the genmonlib directory. This program can be executed remotely (not on the Raspberry Pi) if the IP address of the Raspberry Pi is provided on the command line. If this program is executed as at boot from a crontab job you musty specify the full path of the output file (i.e. /home/pi/out.csv. If you execute this program locally you can use a relative path (i.e. ./out.csv).
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
In addition the the above mentioned ClientInterface.py application, genmon.py supports communicating via the socket interface so the application and generator can be monitored by network monitoring tools like Nagios. The program check_monitor_system.py can be used with as a Nagios Plugin to monitor genmon.py. See https://www.nagios.org/ for Nagios details. check_monitor_system.py is the name of the supplied nagios plug-in.
genserv.py is a python application that uses the Flask library/framework (http://flask.pocoo.org/). This approach allows a quick and simple python socket interface to be translated to a javascript based web interface. The genserv.py app, when executed, will serve up a simple web page that will display the status of the generator. Both the genserv.py app and the genmon.py app can be hosted on a single Raspberry Pi although you should be able to move the genserv.py program to another system with little modification. The web application provides most of the information supplied by genmon.py. The setup for flask is detailed at http://flask.pocoo.org/. I did not used a virtual environment since this is a single purpose and low traffic web app (i.e. I do not expose the web app to the internet, only my local network). If you want expose the web app to the internet I would recommend adding authentication, using virtual environment and possibly a full web server to actually serve up the web pages since security concerns would be heightened on a public web server. To install Flask type:
pip3 install Flask
The application requires modules in the genmonlib directory. Genserv.py also uses the same configuration files (/etc/genmon/genmon.py and /etc/genmon/mymail.conf). The file /var/log/genserv.log is used for logging errors. The program genserv.py has one optional command line argument of the IP address of the system genserv.py is hosted. The default value is localhost, so if no command line argument is supplied the program assumes that genmon.py and genserv.py are on the same system. The flask library serve up static HTML, CSS and javascript files which are stored in a directory below the genserv.py app named static.
The default settings provide for hosting the web app on port 8000 however you can change the port number via the settings. Once genmon.py and genserv.py are running, from your internet browser use the following format for the web address:
Example: http://YourIPAddressGoesHere:8000
Internally, the javascript, calls to the genserv.py app, which communicates with genmon.py via private socket calls.
To execute genserv.py as a background process type:
sudo python3 genserv.py &
The highlight colors in the web interface will change color based on the generator status (running, ready, exercise).
To utilize a low bandwidth page append /low to the web address.
Example: http://YourIPAddressGoesHere:8000/low or https://YourIPAddressGoesHere/low
If you are using the secure web interface to and have an admin or limited user password setup (see the web interface Settings page to setup) you can logout of the current session by appending /logout to the web address.
Example: https://YourIPAddressGoesHere/logout
The web interface menu will change colors based on your generators status:
- Gold / Yellow - Service Due
- Green - Switch in Auto / Ready
- Red - Alarm
- Blue - Exercise
- Black - Switch Off
- Gray - Running in Manual
- Dark Green (Blue / Green ) Running
In normal instances, the genloader program is responsible for loading and unloading the application.
The program serialtest.py is a simple application that transmits test data out the serial port and attempts to read the same data back (loopback test). This test can be used to test the serial port and cable. The application takes one optional command line argument of the serial port you are testing with. The default device name is /dev/serial0, unless on a Raspberry Pi5 or higher, then the default is /dev/ttyAMA0. To test with the default port name type:
python3 serialtest.py
You can specifiy the serial device name on the command line, for example, to test a USB based serial port type:
python3 serialtest.py /dev/ttyUSB0
The program will output success or failure depending on the results of the serial test.
NOTE - The serialtest.py program uses the serial port and so does the genmon monitor software. To use the serialtest.py program you must stop the genmon monitor software (bash ./startgenmon.sh stop).
The program sockettest.py is an simple loopback test for serial over TCP/IP using TCP sockets. The application transmits test data out to the TCP socket on the serial server and attempts to read the same data back from the socket server (loopback test). This test can be used to test the serial server and cable. The application takes two command line arguments of the serial server IP address and server socket port.
python3 sockettest.py -a SERIAL_SERVER_IP -p SERIAL_SERVER_PORT
Replace SERIAL_SERVER_IP with and actual IP address and SERIAL_SERVER_PORT with the port number, for example:
python3 sockettest.py -a 192.168.1.20 -p 8899
The program will output success or failure depending on the results of the serial test.
startgenmon.sh is a Linux script that is designed to be called at system boot from a crontab job. This script can also be called to manually start or stop genmon and genserv. The first time you use this script you must change the permissions of the file to make it executable with the following command:
sudo chmod 775 startgenmon.sh
To start genmon and genserv use the following command (all examples assume you are in the /pi/genmon directory:
./startgenmon.sh start
To stop genmon and genserv use:
./startgenmon.sh stop
To restart genmon and genserv use:
./startgenmon.sh restart
Also, if you do not wish to change the file permissions you can run the program like this:
bash ./startgenmon.sh restart
NOTE - The startgenmon.sh program was originally written to start and stop the programs directly, however the file is overwritten every time the software is updated. To resolve this issue the startgenmon.sh script now calls genloader.py (see below) to start and stop each program.
The second command line parameter is only used if you are running multiple instances of genmon. The second parameter is the full path to the configruation directory.
usage:
./startgenmon.sh <options> start|stop|restart|hardstop
valid options:
-h display help
-c path of config files
-p Specifiy 2 or 3 for python version. 3 is default
The genloader.py program is used to start and stop genmon and the supporting programs. genloader.py is typically called from the script file startgenmon.sh when the system boots.
The parameters for this program are documented here
Multiple sections are allowed so multiple programs can be loaded. Errors for genloader.py will be logged to /var/log/genloader.log
genloader.py has the following command line arguments:
-x Exit all genmon programs
-r Restart. Stop and start all genmon programs
-s Start. Start all genmon programs
-z Force all genmon programs to exit immediately (use with caution)
For example, to restart all programs specified in conf file type:
python3 genloader.py -r
updategenmon.sh is a Linux bash script that is designed aid in the maintenance of genmon. This has the following functionality:
- update - Update the software to the latest version at GitHub
- install - Install the required libraries needed to run genmon and optionally setup the serial port
- updatelibs - Update installed libraries to the latest version
- backup - backup configuration and data files
The web interfacea uses this program to update the software and backup configuration files.
Usage:
genmonmaint.sh
Options:
-i Install genmon and required libraries
-b Backup genmon configuration
-r Refresh (update) required libraries
-u Update genmon to the latest version
-C Remove *.pyc files (clean pre-compiled python files)
-n Do not prompt for Y/N, assume yes
-c Used to specify the full path to config file directory
-p Specify 2 to use python 2, 3 is the default
-s Just copy config files to config directory
-h Display help
The first time you use this script you must change the permissions of the file to make it executable with the following command:
sudo chmod 775 updategenmon.sh
To update to the latest version of genmon, from the directory where genmon was downloaded via the "git" command, type:
./genmonmaint.sh -u
To install the required libraries type:
./genmonmaint.sh -i
The "install" option will optionally modify your crontab scripts to have genmon run at boot time and optionally copy your configuration files to the /etc/genmon/ directory. Also, if you do not wish to change the file permissions you can run the program like this:
bash ./genmonmaint.sh -u
The program gensms.py is a program that will send mobile text (SMS) messages when the generator changes state. With gensms.py, messages are sent via the service Twilio. If you only want simple message notifications from genmon you can use this option and disable email in mymail.conf. gensms.py takes only one command line option but also has a configuration file that must reside in the /etc/genmon/ directory. The name of the configuration file is gensms.conf. The application requires modules in the genmonlib directory.
The SMS implementation utilizes a Twilio account for sending SMS messages. A free trial account is available and pricing for a non-trial account information is on the Twilio site.
The program will send a short text message when the generator enters the following states: READY, RUNNING, RUNNING in MANUAL Mode, EXERCISING, ALARM, SERVICEDUE, OFF, OFF in MANUAL MODE.
These are the conditions that are notified. These are handled via the /genmon/genmonlib/mynotify.py module. These short message notices are used with gensms, gensms_modem, genpushover, genslack, gencallmebot, gensms_voip and gensyslog add-ons:
- Alarm - when alarms or warnings are reported by the controller
- Software Update - When a software update is available
- System Health - This is the reported when there is a change in the Monitor - > Generator Monitor Stats -> Monitor Health state. Things like serial communication problems or internal genmon software errors are reported
- Fuel - If your controller supports fuel consumption calculation low (below 20%) this state is active
- Outage - If your controller supports utility voltage then this is active if there is a change in the outage state. Outage is reported if the utility voltage drops below the threshold voltage and is normal if the utility voltage is above the pickup voltage
- Run State - Ready(not running but in Auto mode), Running, Exercise or Running in Manual Mode are the run states. A change in run state is notified
- Service State - Active is service is due with the controller (Evolution and Nexus only)
- Pi Hardware Sensor State - OK if all is good, otherwise it will report if CPU Throttling, CPU Undervoltage or CPU Frequency cap conditions have occurred on the pi. These are indicators of overheating or power supply voltage problems and can cause issues with the operation of your pi. These messages will not be sent on non pi platforms.
To install the Twilio support library type:
apt-get install build-essential libssl-dev libffi-dev python3-dev
sudo pip3 install -U pyopenssl
sudo pip3 install twilio
The parameters for this add on are documented here
Any errors will be logged to /etc/genmon/gensms.log
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
The program gensms_modem.py is a program that will send mobile text (SMS) messages when the generator changes state. With gensms_modem.py, messages are sent via and attached expansion board with a cellular modem and SIM card. If you only want simple message notifications from genmon you can use this option and disable email in mymail.conf. gensms_modem.py takes only one command line option but also has a configuration file that must reside in the /etc/genmon/ directory. The name of the configuration file is mymodem.conf, and this file must be copied into the /etc/genmon/ directory. This application requires modules in the genmonlib directory.
The SMS implementation utilizes an expansion board or HAT for the Raspberry Pi to send SMS messages via a cellular modem. The expansion board is the LTE Pi Hat. Please note that there are three versions of this expansion board (European, Verizon, or AT&T). The AT&T version will work on other GSM cellular networks like T-Mobile.
A SIM card is also required to be installed in the expansion board. The SIM card must be programmed and provisioned by a cellular service provider (AT&T, T-Mobile, etc.)
If you are using the expansion card to send SMS messages, the Hat card will use the built in serial port of the pi, therefore you must use a USB serial port for the generator monitor software.
NOTE: To use the modem you must install the rpirtscts program located here. This program source files must be downloaded and built however the process is straightforward and is described on the rpirtscts project page. Starting with version 1.10.3 the command "bash ./genmonmaint.sh install" will install all required libraries including rpirtscts.
This program sends short notices using the same topics described in the gensms add on.
The program will send a short text message when the generator enters the following states: READY, RUNNING, RUNNING in MANUAL Mode, EXERCISING, ALARM, SERVICEDUE, OFF, OFF in MANUAL MODE. Changes in the utility power status will also be reported vis SMS.
The parameters for this add on are documented here
Any errors will be logged to /etc/genmon/gensms_modem.log
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
The gensms_voip.py add on To use this module:
Create an account at voip.ms.
The WAN IP address (not the local IP address) of the system running genmon must be entered into your VoIP.ms account at Main Menu - > SOAP and REST/JSON API. You can get your WAN IP address by running this command on the console of your pi:
curl http://ipinfo.io/json
The application requires modules in the genmonlib directory.
The parameters for this add on are documented here
This program sends short notices using the same topics described in the gensms add on.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
The genpushover.py module, provided by @sjbader, will send push notifications via the Pushover Application Framework to a mobile device with the Pushover Application installed. To use this module:
Create an account at pushover.net.
Install chump on your raspberry pi:
sudo pip3 install chump
The application requires modules in the genmonlib directory.
The parameters for this add on are documented here
This program sends short notices using the same topics described in the gensms add on.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
The gencallmebot.py module, provided by @buschauer, will send push notifications via the CallMeBot Application Framework to a the messaging service from either WhatsApp, Facebook, Telegram or Signal. To use this module:
Follow the instructions at callmebot.com. Each service (Telegram, Signal, etc) must be enabled via the method descried at callmebot.com.
This add, like the other add on programs, requires modules in the genmonlib directory.
When used with the genmon project, the configuration file, gencallmebot.conf will be copied to to /etc/genmon/ by the loader program (genloader.py).
The parameters for this add on are documented here
NOTE: Facebook and Signal support has not been tested.
This program sends short notices using the same topics described in the gensms add on.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
The genslack.py module, provided by @naterenbarger, will send notifications via the Slack Application Framework.
The application requires modules in the genmonlib directory.
The parameters for this add on are documented here
This program sends short notices using the same topics described in the gensms add on.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
The gensyslog.py module will send generator notifications to the system log (syslog). The application requires modules in the genmonlib directory.
This program sends short notices using the same topics described in the gensms add on.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
genmqtt.py is a python program that allow genmon data to be imported into a MQTT broker server. MQTT is a messaging standard frequently used in Home Automation application like Home Assistant and others. The program is configured by copying the file genmqtt.conf into the /etc/genmon/ directory and modifying the file to match your system and MQTT server settings.
The parameters for this add on are documented here
In addition to publishing genmon data to MQTT topics, the ability to send commands to genmon the MQTT topic "generator/command" (or root_topic/command). The software will subscribe to this topic. Any data published to this topic will be sent to genmon as a command. For example, if the following is published :
publish:
topic: "generator/command"
payload : "setremote=start"
The above will start an Evolution controller. For more commads see the genmon.py overview.
The genmqtt.py program requires the paho-mqtt python library. To install this library run the following command:
sudo pip3 install paho-mqtt
You can validate settings with the mosquitto_sub program, which is included with mosquitto MQTT server like this (assuming you have not changed the default root topic of 'generator'):
mosquitto_sub -h localhost -t generator/# -u username -P password -F %t:%p
The above command will dump all topics. Each generator type has different set of topics, however you can easily get a feel for the names of the topics by looking at the web interface. The Status, Maintenance, Outage, and Monitor pages of the web interface show data, presented in a structured form. This form is parsed directly into MQTT topics and "generator" is used for the root topic. For example if you look at the Monitor page, the first entry is
Monitor :
Generator Monitor Stats :
Monitor Health : OK
The MQTT topic would be
/generator/Monitor/Generator Monitor Stats/Monitor Health/"OK"
The MQTT last will and testament topic is "generator/client_status" and the valid states are "Online" and "Offline". The MQTT keep alive value is 60 seconds.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
genmqttin.py is a python program that allow data to be imported from an MQTT broker into genmon. MQTT is a messaging standard frequently used in Home Automation application like Home Assistant and others. The program is configured by copying the file genmqttin.conf into the /etc/genmon/ directory and modifying the file to match your system and MQTT server settings.
The parameters for this add on are documented here
The genmqtt.py program requires the paho-mqtt python library. The install script will install this library.
Usage Notes: If you enable the "Use Data for Calculations" option in the add on, this will import data for the following sensor types will be imported into genmon:
fuel,power,current,ct1,ct2,voltageleg1, voltageleg2, ctpower1 and ctpower2
If you have this "Use Data for Calculations" enabled and one of the above types you may see additional gagues that duplicate an existing gague. You can disable one of the gauges by using the "Exclude Gauge" setting.
Since this add on program relies on imput from an MQTT broker, the data (text) will not be displayed and the gague will read zero until the MQTT data for a given topic arrives from the MQTT broker
Data imported via MQTT will be displayed as both a gauge (unless the "Exclude Gauge" setting is used) and as text. Text will appear on the Status page of the web interface under "Status > External Sensors" . The text under "External Line Sensors" is data imported with the "Use Data for Calculations" setting.
The "Use Data for Calculations" setting can not be used with the gencthat.py add on as the both import the same types of data.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
genexercise.py is a python program that allow generators with Evolution or Nexus Controllers to have additional exercise functionality. The program is configured by copying the file genexercise.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Genloader.py will copy the files and the configuration can be set via the web interface Add On page. The genexercise.conf file has the following parameters.
The parameters for this add on are documented here
The genexercise program will not replace the existing exercise functionality built into the controller, but it will add an additional exercise cycle. The additional exercise cycle can also exercise the transfer switch, have a warm up period and more variation in the exercise duration.
If bi-weekly frequency is selected, the exercise occurs on the next day specified if no bi-weekly exercise initiated by genexercise.py has occurred in the last 14 days. If a bi-weekly exercise initiated by genexercise.py has occurred within the last 14 days then the exercise will occur 14 day after the last bi-weekly exercise that genexercise.py initiated..
NOTE: The exercise functions provided by genexercise.py are implemented via modbus calls hosted on the raspberry pi. If you pi is shutdown properly with the "shutdown" command the exercise cycle will stop. If you pi unexpectedly loses power (i.e. unplugged) you will need to manually stop the exercise cycle if it is currently running.
NOTE: Please note that like the built in exercise cycle, if your generator is in alarm the generator will not start until the alarm is reset.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
genemail2sms.py is a python program that will send short messages when the generator status changes. This can be used to send SMS via a carrier supplied email to SMS gateway. Another use of the program is to send generator status via email but with less details than the built in notifications. Note that this program uses the existing mail settings in /etc/genmon/mymail.conf for sending the email. Outbound email must be setup via the Settings page in the web interface or by directly editing the /etc/mymail.conf file. The program is configured by copying the file genemail2sms.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Genloader.py will copy the files and the configuration can be set via the web interface Add On page. The genemail2sms.conf file has the following parameters.
[genemail2sms]
# email to SMS email recipient. Must be a valid email address
# see this page for your mobile carrier address formats:
# https://support.teamunify.com/en/articles/227
# For example :
# (555) 555-5555 mobile number would send to [email protected]
destination =
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
gentankutil.py is a python program that will retrieve tank data from www.tankutility.com and integrate it with genmon. The program is configured by copying the file gentankutil.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Genloader.py will copy the files and the configuration can be set via the web interface Add On page.
The parameters for this add on are documented here
To support two tanks, add the value "tank_name_2" to the config file. This must match the second tank name associated with your account at tankutility.com.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
Note that once the application is started via the Add-Ons page in the web interface, your browser will need to be refreshed before the fuel gauge will be displayed.
gentankdiy.py is a python program that will retrieve tank data from a custom fuel gauge sensor and integrate it with genmon. The program is configured by copying the file gentankdiy.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Genloader.py will copy the files and the configuration can be set via the web interface Add On page.
The parameters for this add on are documented here
Currently, the gentankdiy.py genmon add on only supports Nexus and Evolution controllers.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
More info in the sensor circuits used for each gauge type can be found here.
For Type 2 sensor, see comment above the ‘ang_pct_pnt_x’ on how to create the calibration table for your installation. The program DIY2TankSensorCalibrate.py is in the ~/genmon/OtherApps directory and needs to be run from that folder.
sudo python3 DIY2TankSensorCalibrate.py
By default this will modify the file /etc/genmon/gentankdiy.py however you can specify a different config file location with the -c command line option.
sudo python3 DIY2TankSensorCalibrate.py -c /etc/genmon/
To use the DIY2TankSensorCalibrate.py program you need the tank gauge connected to your raspberry pi (not on the tank yet) and DIY2TankSensorCalibrate will ask you (options 3 and 4) to move the tank gauge dial pointer to specific places. This can easily be done by holding a small magnet near the dial and moving it around until you get the tank gauge dial pointer pointing to the desired setting. The program will update the cofig file with the appropriate settings.
Note that once the application is started via the Add-Ons page in the web interface, your browser will need to be refreshed before the fuel gauge will be displayed.
genalexa.py is a python program that will integrate your Amazon Echo Speaker with your genmon and allow for 2 basic voice commands to be sent to your generator to turn your generator on and off. To set up the Alexa Integration, enabled this addon. Then go to your Echo speaker and ask Alexa to discover your device. Say, "Discover my devices," or select Add Device in the Devices section of the Alexa app, then select “Discover Devices” Once Alexa has discovered your generator, you can use the Alexa app to complete the setup.
A physical Amazon speaker device is required to act as a hub for this application to function. Universal Plug and Play (UPnP) must be enabled on your router for Amazon Alex to discover devices properly. UPnP is enabled in most home routers.
To turn on your generator via the Echo speaker, say "Alexa, turn on the generator". And to off the generator again, "Alexa, turn off the generator". If you prefer to state the likes of "Alexa, start my generator" or "Alexa, stop my generator" (rather than using the words ON or OFF), you can set up a Routine with Alexa.
The program is configured by copying the file genalexa.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Most users however won’t have to modify the config file. Genloader.py will copy the files and the configuration can be set via the web interface Add On page.
The parameters for this add on are documented here
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
Note: Given that the generator takes more than a few seconds to start and stop, it is normal that the Echo speaker responds to a command stating that the "generator is not responding". It really is responding, just a few seconds slower than Echo is willing to wait. You will see on the Alexa app that after about 10 seconds, the status of the generator correctly reflects the command.
Note: Some users have reported that earlier models of Alexa hardware may not discover the genalexa service.
gensnmp.py is a python program that allow genmon data to be exported via the SNMP protocol. The program is configured by copying the file gensnmp.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Genloader.py will copy the files and the configuration can be set via the web interface Add On page.
The parameters for this add on are documented here
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
This project has a registered SNMP enterprise ID of 58399. You have the ability to change this ID if needed by editing the conf file enterpriseid entry. SNMP V1 is supported. The enterprise ID used for Genmon is configurable via the web interface or by editing the conf file. The format for the OID is:
.1.3.6.1.4.1.58399.x.y.z.a
Parameter X is used to split the OID tree between Genmon itself (0), Evolution/Nexus (1), H100(2), and PowerZone (3). Custom defined controllers using the JSON config file method use the value of 4 for this value. Parameter Y and Z further split the OID tree into sections and subsections, ex. Status/Engine (0,0), Status/Controller(0/1) and generally sticks to the UI's representation. For more information, consult the OID tables below.
The MIB is located in genmon/data/mib. In order to use the MIB instead of the specific OIDs in numerical format, just copy the files (except the README.md) into your NMS's SNMP MIBs directory. For most Linux-based NMSes (like Nagios), the directory is usually /usr/share/snmp/mibs however you may need to consult your distro's documentation and NMS configuration for the specific location.
Be aware that if you change the Enterprise ID from '58399', the MIB will also need to be updated to reflect this change, otherwise the MIB will not identify the OIDs correctly!
NOTE: Not all values are supported across all models. If the values does not show up on the web interface then your model does not support this value. If it shows up but is not in the table below the software does not export this value via SNMP at this time.
To monitor the health of your Raspberry Pi and the GenMon software, you can use a controller ID of '0' to monitor the relevant OIDs and subtrees as listed in the below table. Unlike the controller specific OIDs, this subtree only uses three layers (58399.0.y.z).
GenMon stats, communication stats, and hardware platform health (X=0)
| Ending OID (y.z) | MIB OID | Definition | Sample Output |
|---|---|---|---|
| 0 | Genmon Subtree | ||
| 0.1 | gmMonHealth | Overall Genmon Health | STRING: "OK" |
| 0.2 | gmUpTime | Uptime of GenMon | STRING: "Generator Monitor running for 0:34:40." |
| 0.3 | gmPwrLogFileSize | Power Log Filesize | STRING: "0.00 MB of 15.00 MB" |
| 0.4 | gmSWVer | Software version of GenMon | STRING: "V1.18.04" |
| 1 | Serial Subtree | ||
| 1.1 | serialPacketCount | Serial Packet count | STRING: "M:65595, S: 65995" |
| 1.2 | serialCRCErrors | Serial CRC Error count | STRING: "0" |
| 1.3 | serialCRCPercentErrors | CRC errors as % of packets | STRING: "0" |
| 1.4 | serialTimeoutErrors | Serial Timeout Error count | STRING: "0" |
| 1.5 | serialTimeoutPercentErrors | Timeouts as % of packets | STRING: "0" |
| 1.6 | serialModbusExceptions | Serial Modbus Exceptions | STRING: "0" |
| 1.7 | serialValidationErrors | Count of Validation Errors | STRING: "0" |
| 1.8 | serialInvalidData | Count of Invalid Data Pkts | STRING: "0" |
| 1.9 | serialDiscardedBytes | Bytes discarded | STRING: "0" |
| 1.10 | serialCommRestarts | Count of serial port restarts | STRING: "0" |
| 1.11 | serialPktsPerSecond | Serial Port Packets Per Second | STRING: "63.45" |
| 1.12 | serialAvgTransactionTime | The average transaction time | STRING: "0.0310 sec" |
| 2 | RasPi subtree | ||
| 2.1 | piCPUTemp | The CPU Temperature from the RasPi | STRING: "98.60 F" |
| 2.2 | piHardwareModel | The RasPi hardware version | STRING: "Raspberry Pi 4 Model B Rev 1.2" |
| 2.3 | piCPUFreqThrottle | Is the CPU being throttled? | STRING: "OK" |
| 2.4 | piARMFreqCap | Is the CPU frequency throttling? | STRING: "OK" |
| 2.5 | piUnderVolt | Is the pi Undervolting/ | STRING: "OK" |
| 2.6 | piCPUUtil | The current load average of the CPU | STRING: "4.17%" |
| 2.7 | piOSName | The OS running on the Pi | STRING: "Raspbian GNU/Linux" |
| 2.8 | piOSVersion | The OS version on the Pi | STRING: "10 (buster)" |
| 2.9 | piSysUptime | The OS's system uptime | STRING: "10 days, 5:29:36" |
| 2.10 | piNICUsed | The Active network interface | STRING: "eth0" |
Evolution 1.0 and 2.0/Nexus (X=1)
| Ending OID (y.z.a) | Evolution / Nexus Data |
|---|---|
| 0.0.1 | Switch State |
| 0.0.2 | Engine State |
| 0.0.3 | Active Relays |
| 0.0.4 | Active Sensors |
| 0.0.5 | Battery Voltage |
| 0.0.6 | Battery Status |
| 0.0.7 | RPM |
| 0.0.8 | Frequency |
| 0.0.9 | Output Voltage |
| 0.0.10 | Output Current |
| 0.0.11 | Output Power |
| 0.0.12 | Rotor Poles |
| 0.1.1 | Utility Voltage |
| 0.1.2 | Utility Voltage Max |
| 0.1.3 | Utility Voltage Min |
| 0.1.4 | Utility Threshold Voltage |
| 0.1.5 | Utility Pickup Voltage |
| 0.1.6 | Set Output Voltage |
| 0.2.1 | Last Alarm Log Entry |
| 0.2.2 | Last Service Log Entry |
| 0.2.3 | Last Run Log Entry |
| 0.3.1 | Monitor Time |
| 0.3.2 | Generator Time |
| 1.0.1 | Model |
| 1.0.2 | Generator Serial Number |
| 1.0.3 | Controller Detected |
| 1.0.4 | Nominal RPM |
| 1.0.5 | Rated kW |
| 1.0.6 | Nominal Frequency |
| 1.0.7 | Fuel Type |
| 1.0.8 | Fuel Level Sensor |
| 1.0.8.1 | Fuel Level Sensor Tank 2 |
| 1.0.8.2 | Fuel Level Sensor Tank 3 |
| 1.0.8.3 | Fuel Level Sensor Tank 4 |
| 1.0.9 | Estimated Fuel In Tank |
| 1.0.10 | Engine Displacement |
| 1.0.11 | Ambient Temperature Sensor |
| 1.0.12 | kW Hours in last 30 days |
| 1.0.13 | Fuel Consumption in last 30 days |
| 1.0.14 | Total Power Log Fuel Consumption |
| 1.0.15 | Run Hours in last 30 days |
| 1.0.16 | Estimated Hours of Fuel Remaining base on fixed load |
| 1.0.17 | Estimated Hours of Fuel Remaining based on current load |
| 1.0.18 | Fuel In Tank (Sensor) |
| 1.0.19 | Fuel Level State |
| 1.0.20 | Run Hours in the last year |
| 1.1.1 | Calibrate Current 1 |
| 1.1.2 | Calibrate Current 2 |
| 1.1.3 | Calibrate Volts |
| 1.1.4 | Nominal Line Voltage |
| 1.1.5 | Rated Max Power |
| 1.1.6 | Param Group |
| 1.1.7 | Voltage Code |
| 1.1.8 | Phase |
| 1.1.9 | Hours of Protection |
| 1.1.10 | Volts Per Hertz |
| 1.1.11 | Gain |
| 1.1.12 | Target Frequency |
| 1.1.13 | Target Voltage |
| 1.2.1 | Exercise Time |
| 1.2.2 | Exercise Duration |
| 1.3.1 | Air Filter Service Due |
| 1.3.2 | Oil and Oil Filter Service Due |
| 1.3.3 | Spark Plug Service Due |
| 1.3.4 | Battery Service Due |
| 1.3.5 | Service A Due |
| 1.3.6 | Service B Due |
| 1.3.7 | Battery Check Due |
| 1.3.8 | Total Run Hours |
| 1.3.9 | Hardware Version |
| 1.3.10 | Firmware Version |
Values for H-100 and G-Panel controllers (X=2)
| Ending OID (y.z.a) | H-100 / G-Panel Data |
|---|---|
| 0.0.1 | Switch State |
| 0.0.2 | Engine Status |
| 0.0.3 | Generator Status |
| 0.0.4 | Output Power |
| 0.0.5 | Output Power Factor |
| 0.0.6 | RPM |
| 0.0.7 | Frequency |
| 0.0.8 | Throttle Position |
| 0.0.9 | Coolant Temp |
| 0.0.10 | Coolant Level |
| 0.0.11 | Oil Pressure |
| 0.0.12 | Oil Temp |
| 0.0.13 | Fuel Level |
| 0.0.14 | Oxygen Sensor |
| 0.0.15 | Current Phase A |
| 0.0.16 | Current Phase B |
| 0.0.17 | Current Phase C |
| 0.0.18 | Average Current |
| 0.0.19 | Voltage A-B |
| 0.0.20 | Voltage B-C |
| 0.0.21 | Voltage C-A |
| 0.0.22 | Average Voltage |
| 0.0.23 | Air Fuel Duty Cycle |
| 0.1.1 | Number of Active Alarms |
| 0.1.2 | Number of Acknowledged Alarms |
| 0.1.3 | Alarm List |
| 0.2.1 | Battery Voltage |
| 0.2.2 | Battery Charger Current |
| 0.3.1 | Monitor Time |
| 0.3.2 | Generator Time |
| 0.4.1 | Transfer Switch State |
Values for PowerZone controllers (X=3)
| Ending OID (y.z.a) | H-100 / G-Panel Data |
|---|---|
| 0.0.1 | Switch State |
| 0.0.2 | Engine Status |
| 0.0.3 | Generator Status |
| 0.0.4 | Output Power |
| 0.0.5 | Output Power Factor |
| 0.0.6 | RPM |
| 0.0.7 | Frequency |
| 0.0.8 | Throttle Position |
| 0.0.9 | Coolant Temp |
| 0.0.10 | Coolant Level |
| 0.0.11 | Oil Pressure |
| 0.0.12 | Oil Temp |
| 0.0.13 | Fuel Level |
| 0.0.14 | Oxygen Sensor |
| 0.0.15 | Current Phase A |
| 0.0.16 | Current Phase B |
| 0.0.17 | Current Phase C |
| 0.0.18 | Average Current |
| 0.0.19 | Voltage A-B |
| 0.0.20 | Voltage B-C |
| 0.0.21 | Voltage C-A |
| 0.0.22 | Average Voltage |
| 0.0.23 | Air Fuel Duty Cycle |
| 0.1.1 | Alarm List |
| 0.2.1 | Battery Voltage |
| 0.2.2 | Battery Charger Current |
| 0.3.1 | Monitor Time |
| 0.3.2 | Generator Time |
All SNMP OID values are type STRING.
This will display all values for a genmon system at IP address 192.168.1.10, regardless of controller.
snmpwalk -v1 -c public 192.168.1.10 .
If you have the MIB installed, you will see all of the GenMon specific OIDs show up with their names (ex: GenMon-MIB::engineStatus) versus their OID (ex: .1.3.6.1.4.1.58399.1.0.0.2 ).
If you have the MIB installed, you can query a specific OID by using the OID's name. As an example, the below command will pull the generator's switch state from an Evo/Nexus controlled generator.
snmpget -v1 -c public 192.168.1.10 GenMon-MIB::switchState
The command below pulls the same data, except it uses the explicit OID instead of the OID name.
snmpget -v1 -c public 192.168.1.10 .1.3.6.1.4.1.58399.1.0.0.1
If you decide to install the MIB, you can use snmptranslate to look up specific OIDs of interest. For example, to get the OID name for the Raspberry Pi's CPU temperature:
snmptranslate -Td 1.3.6.1.4.1.58399.0.2.1
which will return the OID name of "GenMon-MIB::piCPUTemperature"
You can use snmptranslate to obtain a description about any OID in the MIB, along with what controller the OID pertains to. Once you know the OID (either name or number), you can implement checks in your preferred NMS.
Nagios contains a basic plugin called 'check_snmp' which can be used to query GenMon and alert if values change. For a sample check, the below command would alert if Nagios detects that the generator is taken out of 'Auto' state either by a failure or by user input at the control panel.
$./check_snmp -C public -H IP.ADDR.OF.GENMON -o GenMon-MIB::switchState -s "Auto"
The above command uses Nagios' builtin plugin to query GenMon and get the switch state. If GenMon returns any status other than 'Auto', an alert will trigger.
While configuring Nagios is beyond the scope of this document, this is just a simple example of how you can use the SNMP functionality and the MIB to write checks for Nagios for implementation.
You can display user defined data in genmon as described on this page. If you want to assign SNMP identifiers to your user defined data you can add a second file named userdefined.json to the ./genmon/data/mib folder. This second file, while named the same as the page linked above, has a different format. This file defines how the data will be displayed in the SNMP schema. See the file gensnmp.py for more details.
gentemp.py is a python program that allow data from 1 wire temperature sensors to be imported into genmon. The program is configured by copying the file gentemp.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Genloader.py will copy the files and the configuration can be set via the web interface Add On page.
The parameters for this add on are documented here
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
NOTE: One wire temperature sensosrs are supported in two varieties, DS18B20 and Type K thermocouples. They are enumerated by Linux in the following file paths:
DS18B20:
/sys/bus/w1/devices/28-00000bc558d8/w1_slave
The name 28-00000bc558d8 above is the device name and will be unique for each device on the system.
Type K thermocouple:
/sys/bus/w1/devices/w1_bus_master1/3b-2c880b6ab007/w1_slave
The name 3b-2c880b6ab007 above is the device name and will be unique for each device on the system.
Type K thermocouples are typically wired using a MAX31855 thermocouple amplifier on the SPI bus. The SPI bus must be enabled via raspi-config (Interfacing Options->SPI). DS18B20 temp sensors are also connected to the SPI but and must be enabled with raspi-config under Interfacing Options->1 Wire.
The gentemp app will enumerate the above type 1 wire sensors. If you wish to black list any of the devices in the system (have gentemp.py ignore them) the just put the name (e.g. 3b-2c880b6ab007) in the BlackList parameter above.
The temperature read from the sensor will ve displayed on the Status page of the web interface. Each sensor will be displayed with either the device name (e.g. 3b-2c880b6ab007) or with a name of your choosing from the device_labels setting in the conf file.
This module was tested with the hardware from this project.
The issue thread on this program for this project is located here.
gencthat.py is a python program that allow data from current transformers to be imported into genmon. The program is configured by copying the file gencthat.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Genloader.py will copy the files and the configuration can be set via the web interface Add On page.
The parameters for this add on are documented here
The CT sensor HAT used with this add on has been discontinued. An alternate method for importing power and current data is via the genmqttin add on.
NOTE: To use the CT sensor hat the SPI interface must be enabled on the raspberry pi. To SPI, run the raspi-config program with root privileges like this:
sudo raspi-config
Then select interfacing options, then select SPI, then select enable. This program will ask you to reboot your pi for the changes to be enabled. You will also need to add a line to the /boot/config.txt file to enable both SPI buses (SPI0 and SPI1). Your editor must be run with root privileges. Edit the file like this:
sudo nano /boot/config.txt
Add the following line to the /boot/config.txt file.
dtoverlay=spi1-1cs
Save the file, then reboot your pi.
In earlier raspbian versions you can add this to the bottom of the file. Starting with Bullseye there are sections (i.e. [all], [pi4], [cm4], etc) in the config.txt file. Add the above line to the first (unnamed section).
This add on, along with the sensor HAT, allows monitoring of the two output legs of the transformer. The HAT supports two CT (current transformer) sensors. The readings on these two sensors is input into genmon and used for fuel calculation and displayed as a gauge.
Once enabled, the add on will import the CT reading in amps (current). Genmon will convert amps to power using the generator output voltage. Two additional gauges will show up in the web interface (External Current and External Power).
If you are running a controller that does not support fuel estimation (e.g. Nexus) then you can use this add and HAT to get both the power graph and fuel estimations. To enable fuel estimations you will need to setup the three fuel parameters on the advanced page as described here.
The model SCT-013-000 (100A input per 1V output) current transformer was used for testing however the HAT was designed to facilitate other size CTs. If another size CT is desired, you must use a voltage output model, not a current output model. There is also support in the HAT to change the burden resistor, which may be required depending on the type of CT you use.
NOTE: This add on is can not be used with the "Use Data for Calculations" setting on the genmqttin.py add on as they both import data via the same method.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
genmopeka.py is a python program that allow data from the Mopeka Pro propane tank sensor into genmon. The program is configured by copying the file genmopeka.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Genloader.py will copy the files and the configuration can be set via the web interface Add On page.
The parameters for this add on are documented here
To use the mopeka pro sensor with genmon the python bleson library (this is installed with the install script) must be installed and your system must have a compatible Bluetooth controller.
NOTE: The install script will install both the bleson library and the fluids python library. Both are requried and this plug in will not work unless you have them installed.
There are two additional programs that are need to be used before you can successfully use the sensor, /genmon/OtherApps/mopeka_utility.py and /genmon/OtherApps/serialconfig.py.
NOTE: To use the mopeka sensor the Bluetooth interface must be enabled on the raspberry pi. Normally, the Bluetooth device on the pi would default to using the onboard serial port, however genmon typically uses the onboard serial port so the serial setup program serialconfig.py disables the Bluetooth device. Since Bluetooth is required to communicate with the mopeka sensor the Bluetooth device needs to be enabled, but mapped to the secondary serial port. To do this run the following command in the /genmon/OtherApps folder from the console on your pi:
sudo python3 serialconfig.py -e -b
Once this command is executed the status should be displayed and a reboot of your pi would be required for the changes to take effect. Once the system has rebooted you can log in and check the settings with this command in the /genmon/OtherApps folder:
sudo python3 serialconfig.py -c -b
You can also validate that Bluetooth is enabled with this command:
sudo bluetoothctl
This should show the MAC address of your controller if Bluetooth is enabled like this:
Agent registered
[CHG] Controller E4:5F:01:2E:3D:ac Pairable: yes
[bluetooth]#
To exit, type 'exit'. If a valid controller address does not display, then Bluetooth is not enabled on your pi. You may need to restore your serialconfig.py settings then try enabling again with these commands:
sudo python3 seiralconfig.py -r
sudo python3 serialconfig -e -b
Once you reboot after running serialconfig.py, try to validate that Bluetooth is enabled agina by running "sudo bluetoothctl" as described above.
NOTE: If you have already configured your serial port with serialconfig but not enabled bluetooth, you will likely need to restore your original settings and then enable bluetooth with serial using serialconfig.py as described above.
Once Bluetooth has been setup you will need to find your sensor and obtain the Bluetooth MAC address of the sensor. This address is used as the sensor / tank address in the Mopeka Add On program. To obtain this address run the following command from the /genmon/OtherApps folder while holding down the SYNC button on your modeka pro sensor:
sudo python3 mopeka_utility.py
If your pi can communicate over Bluetooth with your sensor you will see and output indicating that a sensor was found. The sensor address will be printed to the console output. This address will need to be input as the "Sensor Address" parameter for the genmon Mopeka Pro Add On.
The size your tank must be setup on the Settings Page under "Fuel Tank Size" and "Fuel Type" must also be set to Propane. This allows genmon to calculate the amount of fuel left in your tank.
Multiple sensors / tanks can be used with the Add On. Up to four sensors are supported. There is a caveat that all the tanks must be the same size. To use multiple sensors, add each sensor address to the "Sensor Address" field in the add on web interface (same parameter as tank_address in the conf file) separating each sensor address with commas.
NOTE: The sensor readings take several seconds to complete. As a result it may be around 20 seconds after genmon starts that a gauge reading shows up. If the fuel gauge is not showing up after 20 seconds since genmon was restarted, refresh your browser.
This program, like other add on programs, is enabled and configured via the web interface on the Add On page. If using the Add On interface the setup, configuration and execution is handled by genlaoder via the web interface.
gencustomgpio.py is a python program that allows GPIO state to be displayed on the genmon Monitor page in the web interface. This data can also be sent over MQTT with the genmqtt add on. The program is configured by copying the file gencustomgpio.conf into the /etc/genmon/ directory and modifying the file to match your desired settings. Genloader.py will copy the files however to enable the add on you must manually edit the /etc/genmon/geloader.conf file and set enable = True in the gencustomgpio section of the conf file. The configuration can be set via manually editing the /etc/genmon/gencustomgpio.conf file.
The parameters for this add on are documented here
This program, unlike other add on programs, is not configured via the web interfact. It must be manually configured by editing the /etc/genmon/gencustomgpio.conf file abd enabled via the /etc/genmon/genloader.conf file.
For more info in the userdefined.json file see this page
This python program will extract the power log (if current output is supported by your controller) and store it as a CSV (comma separated value) format file. CSV format files can be opened with a spread sheet application like Excel. This will allow you to view and graph your kilowatt output in a spreadsheet. The program has the following usage:
python3 kwlog2csv.py -a <IP Address or localhost> -f <outputfile>
Example:
python3 kwlog2csv.py -a 192.168.1.100 -f Output.csv
Command Line Arguments:
-a Address of system with genmon (omit for localhost)"
-f Filename to output the kW log in CSV format"
This program can be executed on the same system running genmon or on a PC system that has python installed. This program does require modules form the genmonlib directory included with the project.
The program serialconfig.py will check or set the needed serial port setting for a Raspberry Pi. To check your settings type:
sudo python3 serialconfig.py -c
Usage: python3 serialconfig.py [-r -e -c]
Command line options
- -e Enable serial port
- -r Restore modified files
- -c Check status of serial port
- -b Allow bluetooth to be used with genmon (set this with both -c and -e options if enabling or checking)
Example:
sudo python3 serialconfig.py -e
sudo python3 serialconfig.py -c
sudo python3 serialconfig.py -e -b
sudo python3 serialconfig.py -c -b
This program is intended to supplement the install process. Full details on the serial port setup process can be found in the project wiki. This program must be run with "root" privileges (e.g. sudo).
The program modbusdump.py is a program used to direcetly read the modbus registers of a modbus device. To use this program genmon.py and any add on programs must not be running. The modbusdump.py program requires the genmon project to be installed via the genmonmaint.sh script as it uses the same libaries that genmon does. The modbusdump.py program can read modbus registes using either serial or serial over TCP.
Serial Example using 9600 baud, no parity, 8 data bits, one stop bit, serial device /dev/serial0, modbus address 9d hex (157 decimal), starting register 5 (decimal), ending register 100 (decimal):
python3 modbusdump.py -r 9600 -p /dev/serial0 -a 9d -s 5 -e 100
Serial over TCP Example using IP address 192.168.1.10, port 9988, modbus address 64 hex (100 decimal), starting register 5 (decimal), ending register 100 (decimal):
python3 modbusdump.py -i 192.168.1.10 -t 9988 -a 64 -s 5 -e 100
Command Line Options:
-r Baud rate of serial port (9600, 115300, etc)
-p Operating System device name of the serail port (/dev/serial0)
-a Modbus address to query in hexidecimal, 0 - ff (e.g. 9d, 10, ff) or 'all' to probe all addresses
-s Starting modbus register to read (decimal number)
-e Ending modbus register to read (decimal number, must be greater than start register)
-b Stop bits. If omitted 1 stop bit, if present use 1.5 stop bits
-x Omit for no parity. -x 1 for odd parity, -x 2 for even parity
-w write this value to register instead of read. Start register is used as register
-c read coils (bits) instead of holding register
-i IP address if modbus over TCP is used
-t TCP port if modbus over TCP is used
-m Use Modbus TCP, if omitted and IP and port provided then use Modbus RTU over TCP
-f use modbus function 4 instead of function 3 to read input registers insteae of holding registers
This program is primarly used to read the modbus registers when trying to add a custom controller support for an unsupported generator controller.