eGauge is a building energy monitoring platform, not the cheapest, but high accuracy and very reliable (I’ve had one unit running for over 12 years continuously, and another at 8 years). They present data on the network over modbus, BACnet, and a local REST api, as well as an optional cloud platform.
For this simple integration I’m using the REST API, and the “rest” sensor platform in HA Core.
- eGauge website: https://www.egauge.net/
- Documentation for the eGauge local API: https://www.egauge.net/media/support/docs/egauge-xml-api.pdf
- Documentation for the HA Rest sensor platform: https://www.home-assistant.io/integrations/rest/
Initial Setup
Ensure that your eGauge is configured properly and visible on the network. Refer to their install manual to get everything up and running. Once things are working the way you want on the eGauge itself, you can proceed with the HA integration.
Visit the API URL in your browser to test the results:
- http://egaugeXYZ.local/cgi-bin/egauge?inst&tot <- Replace “egaugeXYZ” with your eGauge ID.
Note: we are using the inst and tot parameters to get more detail in the query - see the documentation for examples.
Example XML output when viewing the REST API URL in the browser:
<data serial="0x5555555">
<ts>1601133813</ts>
<r t="P" n="Grid" did="0">
<v>9941246985</v>
<i>-789</i>
</r>
<r t="P" n="Solar" did="1">
<v>10367491077</v>
<i>1608</i>
</r>
<r t="P" n="Mini Split" did="2">
<v>-457926256</v>
<i>-240</i>
</r>
<r rt="total" t="P" n="Total Usage">
<v>20308738062</v>
<i>819.000</i>
</r>
<r rt="total" t="P" n="Total Generation">
<v>10367491077</v>
<i>1608.000</i>
</r>
</data>
I have 5 registers setup in my eGauge, grid, solar and my mini split AC, as well as the default Total Generation and Total Usage registers. Your registers will be different but similar. The <i> readings are instantaneous power in watts. Negative means consuming energy, positive is generating.
Make a note of the order that your registers are in - this will be important when setting up the HA sensors to read each value in order.
We will use the HA rest sensor platform to query this url, convert XML to JSON and then extract the values we want using template sensors. We will also use the templates to reverse the sign of some readings and round the result for a nicer output.
Configure the rest and template sensors in Home Assistant
Below is the extract from my configuration.yaml:
# sensors from eGauge via API https://www.egauge.net/media/support/docs/egauge-xml-api.pdf
- platform: rest
name: egauge_meter
resource: http://egaugeXYZ.local/cgi-bin/egauge?inst&tot
json_attributes:
- data
value_template: 'OK'
# these sensors extract the individual attributes from the egauge_meter sensor, and format them using templates
- platform: template
sensors:
grid_power:
unique_id: grid_power
value_template: '{{ states.sensor.egauge_meter.attributes["data"]["r"][0]["i"]|round(0) }}'
device_class: Power
unit_of_measurement: 'W'
solar_power:
unique_id: solar_power
value_template: '{{ states.sensor.egauge_meter.attributes["data"]["r"][1]["i"]|round(0) }}'
device_class: Power
unit_of_measurement: 'W'
minisplit_power:
unique_id: minisplit_power
value_template: '{{ (states.sensor.egauge_meter.attributes["data"]["r"][2]["i"]|float * -1)|round(0) }}'
device_class: Power
unit_of_measurement: 'W'
total_usage:
unique_id: total_usage
value_template: '{{ states.sensor.egauge_meter.attributes["data"]["r"][3]["i"]|round(0) }}'
device_class: Power
unit_of_measurement: 'W'
total_generation:
unique_id: total_generation
value_template: '{{ states.sensor.egauge_meter.attributes["data"]["r"][4]["i"]|round(0) }}'
device_class: Power
unit_of_measurement: 'W'
What is happening here?
-
We use a single
restsensor to pull in the entire XML query, and format it asjsondata. This is better than using multiplerestsensors, because we only have to query the eGauge once. This sensor isn’t directly used in your automations and front end, since it just gives an “OK” or “unavailable” result, and stores the entire text of the json query. You will need to add your device url. -
Then we use template sensors to extract the individual readings from the
jsonin therestsensor. In each template you see the text{{ states.sensor.egauge_meter.attributes["data"]["r"][0]["i"]|round(0) }}. This means "from the attributes of theegauge_metersensor, extract the data fromi, inside the first (number 0)r, insidedata. Then, round to the nearest integer. -
Edit the
names,unique_idsand the[number]in the template to correspond to the order of sensors in your raw api output. Thefloat * -1you see in some changes the sign, if you want to invert any values.
Results:
Troubleshooting:
-
First make sure your eGauge is setup properly, and that you can see the XML result when visiting the URL. If that isn’t working yet than the rest won’t do anything.
-
Then, work on getting the
restsensor working. It will pull the XML data and reformat as json, and then store the entire json values as an attribute in the sensor, and it will have a main value of “OK” or “unavailable”. If it isn’t working, check the sensor formatting and the URL. You should get a sensor that looks like this in the configuration:
- Once that is working, get the
templatesensors going to extract each value. Experiment with the syntax in the template by trying out values in theDeveloper -> Templatearea of the HA configuration, that way you can see if you are getting the value you expect out of theegauge_sensor's json data without having to reload over and over.
Happy metering!
