Mac Home Automation

The genmon plugin is released as an alpha. It is probably not feature complete yet but is running quite happily here against my Generac 22kw home backup generator. This plugin is included as part of the default XTension install but you will have to install the genmon software on your pi and set that up according to the |genmon wiki information.

A subset of the data provided by the genmon system is presented as units in XTension. As of this version no attempt to control the generator is done, in order to run the generator or transfer power you’ll need to log in via the genmon control web site. I can add these capabilities to the software if anyone wishes to be able to do that, please let me know.

This plugin can connect to the excellent |Raspberry Pi based genmon system. It will NOT connect to the generator monitor that Generac sells for their generators as that only provides a cloud based interface to the data. I do not believe that it is possible to have both the genmon pi and the commercial generac monitoring device connected at the same time but that could change or I might be wrong.

The genmon plugin will connect to a raspberry pi that you must install in the generator yourself. Depending on how you install it it may or may not disable the wifi device built into the generators. As far as I know without their own monitor device the wifi does not actually do anything but let them download firmware updates to the generator when performing service. If your service people need access that way to read logs and such you can very easily swap the single ATX 8 pin connector from the pi back to the wifi device until they are done working and then switch back.

Setting up the genmon software and hardware is well documented on the genmon wiki page linked to above. I purchased the ATX 8 cable extension cable they recommended which made building the cable to connect the two very easy. Be careful when you’re looking at the diagrams of what pin goes where as some of them count the pins from the back of the connector and some from the front. I initially connected the wrong two pins and spent quite a bit of time trying to figure out why it wasn’t working. Here is a picture of my current install. I opted to mount the pi in a separate box separate from the generator to keep it cooler during runtime and so as not to have to open the access panels every time I needed to access the pi. The pi is a model 3b and it keeps up just fine with the load on the system so far. I opted to run it an ethernet cable but to power it from the generator rather than over POE or otherwise so that it would share a ground with the generator making the running of the serial data more reliable.

I mounted the box to the wall opposite the generator and used cat-6 cabling for both the ethernet and the serial data and power from the generator.

The pi, serial level adaptor, usb power supply and a wago style connector block to make connecting it all up more easily are mounted inside the box. I plan to add some noalox to the project wires I used to connect the pi to the serial level shifter just to keep them from becoming less reliable in the future. I will probably put a blob of it on the ethernet connector as well unless I can get some proper silicone material for this job. Noalox is easily avaialable and appears to work just as well for most such applications though it is messier.

The XTension setup for the alpha version is very simple as it does not yet have any configuration options at all. Though I do plan to add a “slow polling” or low bandwidth mode to reduce the amount of network traffic it creates if you are connecting via a VPN or other system. Note that you should not expose the genmon built in web server to the internet directly via a nat port or any such things or someone could turn on and transfer your home to the generator at their own whim and cause you huge expense or even serious potential for damage to your generator or your home.

In the Address field enter the IP address or local mDNS hostname of your genmon pi. I always recommend giving your pi a static IP address and using that as I have seen many times that something goes wrong with the pi’s mDNS and it will stop updating the hostname and you’ll no longer be able to connect.

In the Port field enter the port number that the genmon software is listening on. Unless you have changed it in the genmon configuration it will be 8000.

The plugin will create some subset of the shown units depending on what data is available from your specific generator model. There may be others that the genmon interfaces shows or that are listed under the “unsupported sensors” portion that I could add support for if they contain useful information for you. The genmon software will also read 1-wire and 1-wire based thermocouple temperature sensors connected to the pi which can be quite valuable. As of this moment I don’t have any connected and so have not written in support for them but I do plan to do this also in the future. Let me know if this is something you need sooner than that.

The default unit names will be the name of the interface and then the data name as genmon shares it. Once the unit is created you can edit the units and give them any name you wish, or just remove the interface name portion if that makes your interface easier to read and work with. Do not change the address of the units as this is how the data gets to the right unit.

NOTE that there is still a lot I don’t understand about how the software will present the different states and some of the units may not work in every state or alarm state. As more data from others becomes available I will update the parsing of the info to the units.

Switch State: The state of the transfer switch. Mine seems to always say “Auto” which I am treating as the Off and normal state in the unit with the default label set to Auto. If the value ever changes to anything other than Auto the unit will turn on and the label will display whatever text value is sent from the software.

Engine State: Self explanatory, is the engine running or not. If the label is “Off - Ready” then the unit will be Off and the label will display that. If the engine reports any other state that will be shown here. Note that alert states may also be shown here that will currently turn the unit on and display whatever message is there. This may not be what is really desired as it might not be showing the actual state of the generator but that of an alert that I should parse out separately. I will update this as more data becomes available.

Battery Voltage: The current voltage of your starting battery. My generator seems to not float charge the battery constantly but rather runs the charger at low current up to a voltage that is changed by the outside temperature and when it reaches that it turns off and lets the battery slowly run itself down until it reaches 12.6 or 7 volts and then starts up again. This may impact where you should power your pi from. The genmon documentation suggests connecting that USB power supply directly to the battery but this may not be the best idea as it could cause more charge/discharge cycles and prematurely wear out your battery. Though with this information you can check for this state long before it becomes a problem. I plan to move the power for the pi to the 12v and gnd output that is available in the same 8pin ATX connection now and see how well it runs from there but I have not done this yet.

RPM: The RPM of the motor when running. On my generator it shoots for a constant 3600 or so and will adjust it’s throttle to try to keep that the same as the load changes.

Frequency: The Frequency of the output when running. When testing mine seems to fluctuate between 60 and 59hz which should be fine.

Output Voltage: The output voltage of the generator when running. This will be the 240 or other full voltage of the single phase it generators and not the 120v of the individual legs of the center tapped phase.

Output Current: When running the amps being generated at any moment.

Output Power: The same info as current but calculated based on the output voltage to show kwatts.

Active Rotor Poles: Honestly I have no idea of what use this is? Are there models that can use a variable number of poles or is this an indication of a problem with the generator? Always shows 0 when the generator is not running.

Battery Charger Sensor: This is an “unsupported” sensor but it had a label so I decided to bring it out to a unit. It updates quite a lot and changes by a great deal. I am currently going on the idea that this is milliamps or possibly watts delivered to the battery but I have no idea yet.

Battery Status: Another “unsupported” sensor value but seems reliable on my machine. Will turn on and off as the label sent changes from charging to anything else.

Utility Voltage: The current voltage from the Utility. This is useful to watch the quality of your power coming into the house though it updates fairly often as well as load changes in your home and the others sharing the same transformer. It should not change by too much until you have an actual outage.

Utility Min Voltage and Utility Max Voltage: Either the generator or the genmon software keeps track of the min and max values sent by your utility. I’m not sure how to reset these or to know what time they occurred. You can do both from in XTension though.

Monitor Heath: I’m not sure exactly what this will display. Perhaps an error message if the serial port stops responding or some such. At the moment the unit will be off and show OK as the label until the label being sent from genmon changes to something other than OK in which case it will turn on and display the text of the message as the default label for the unit.

CPU Temperature: This is data from the pi itself and can be important for troubleshooting. If your pi is going into throttling mode or otherwise not operating properly at some times you can check to see if it is because of over heating or not.

CPU Frequency Throttling: Is the pi reducing it’s CPU speed in order to cope with either a low voltage or high temperature situation. Will be off and show OK as long as this is not happening.

ARM Frequency Cap: I’m not entirely sure yet how this is different than the throtteling above. Perhaps this is a permanent state that it gives up and goes into where as the above will clear when the situation returns to normal?

Fuel Consumption in last 30 days: in cubic feet. I have no idea how accurate this information is yet but I appear to have used 10cf just runining the last 5 minute exercize cycle with no load at all so these things will use a LOT of gas.

Run Hours in the last 30 days: The most recent runtime in hours, but with tenths of an hour available.

Ambient Temperature Sensor: I’m not sure where this temp sensor is, probably inside the generator controller so it is a temperature inside the case. It always runs higher than the real air temperature outside and even more so when sun is shining on the generator case so I am fairly sure it is inside and not meant to be an outside air value. I believe that this temp is used to decide what voltage the battery should be charged to. If it’s very cold out the end voltage of the float charge is capped quite a bit lower so as not to damage the battery in those situations.

Total Run Hours: This does not seem to support tenths of a hour but just total hours as an integer. You can see my 30 days runtime is 0.1 hours but this value is rounded down to just 0.

KW Hours in the last 30 days: How much power it’s generated for you in the last 30 days.

Alarm Log: The description of this unit will be set to the last Alarm Log entry. When the value changes you can catch that in the on descriptionChanged event in the Unit’s ON script. The unit will also be sent an ON whenever the log line changes. You can use a “Unit Description As Text” control type to add this display to a web interface or an XTension view.

Service Log: The description of this unit will be set to the last Service Log entry. When the value changes you can catch that in the on descriptionChanged event in the Unit’s ON script. The unit will also be sent an ON whenever the log line changes. You can use a “Unit Description As Text” control type to add this display to a web interface or an XTension view.

Run Log: The description of this unit will be set to the last Run Log entry. When the value changes you can catch that in the on descriptionChanged event in the Unit’s ON script. The unit will also be sent an ON whenever the log line changes. You can use a “Unit Description As Text” control type to add this display to a web interface or an XTension view.

If there are more data sources on your generator please let me know as adding support for them should not take too much time. If you have insight on what some of the values are, or have data from specific error or alert conditions I would love to see it so that I can make those operate properly or more usefully.

The Units are created automatically in XTension when the monitor first connects successfully to the generator. It is not necessary to create them manually though feel free to edit the names once they are created.

You may wish to edit some of the units like the battery charger sensor and the utility voltage units, go to the advanced tab and check the “don’t log new values” checkbox. These units are updated a lot and will spam your log unnecessarily with value received messages that are probably not helpful. The data will still be available in XTension and for graphing in XTdb.

As of this moment it may not catch every alert or error condition that might possible be sent. It will not alert you to maintenance due. Please let me know if you wish to capture some of this data from your own machine to speed up the process of supporting them all in the future.

When in regular polling mode the status data is polled every 2 seconds. It is possible that outages shorter than that length will not be caught by the software if the power returns before the next poll of data from genmon.

The “Monitor” data is updated less frequently at every 30 seconds. This includes the Monitor Status, CPU Temperature and other pi based information.

The “Maintenance” data is updated only every minute and includes the ambient temperature sensor as well as the run hours and total fuel use data.

If the genmon process or pi is restarting you will get errors in the log as it attempts to reconnect and probably many others as the initial messages do not have any data in them. Ignore that for the moment as I look into properly ignoring messages that are not really errors while still being able to handle the condition where the pi or the genmon process goes offline unexpectedly.

• The genmon plugin was added as alpha v0.1 in XTension version 9.4.43 in August of 2021