# ¶ Emon EVSE - MQTT integration

## ¶ About EmonEVSE

The EmonEVSE shares a software platform with the OpenEVSE. Full instructions on this are available at http://files.openenergymonitor.org/datasheet/EmonEVSE-datasheet.pdf (PDF).

## ¶ Initial Checks

The EmonEVSE should be powered up and awake. Check that single presses of the button will successfully send the device into sleep mode (display goes purple) and wake it up again (display green).

## ¶ Connect EVSE to COFYbox WiFi

On first boot, OpenEVSE should broadcast a WiFI access point (AP) OpenEVSE_XXXX. Connect to this using the default password openevse and navigate to http://192.168.4.1 in a web browser. The EVSE should present you with a list of visible WiFi networks which includes the COFYbox WiFi network. If not, you will need to move the COFYbox closer to the EVSE. If so, connect to the COFYbox network. The EmonEVSE should restart and display its new IP address briefly as it boots up.

## ¶ Connect MQTT

The EmonEVSE needs to be connected to the MQTT server on the COFYbox. Navigate to the Services tab and enable MQTT control. Under the Host field enter the IP address of the COFYbox (do not copy the https:// protocol into this field). The username and password should be blank and the topic should be the EVSE ID (e.g. openevse-1a23). After saving these details you should see “Connected: Yes”.
Checklist

- Connect EmonEVSE to COFYbox WiFi network.

- Update firmware

- Configure MQTT.

- Test control.

## ¶ Home Assistant

While connected to the COFYbox WiFi, navigate to 10.42.0.1. This will give you access to the Home Assistant application. On first use you will set up a user account. Set the username to the be SSID of the COFYbox’s WiFi hotspot, and use the WiFi password (from the back of the COFYbox) as the password for this account.

You should now be able to control all devices from the Home Assistant dashboard. Test that you can control the EVSE by clicking the lightning icons on the dashboard next to the ‘Relay’ control: you should be able to send the EmonEVSE into sleep mode (purple display) and wake it up again (green display). By default the HASS seems to assume that the EVSE is asleep, so the first ‘wake’ command may not have any effect.

## ¶ Connecting to CoFyCloud

We can get data from the EmonEVSE chargers into CoFyCloud. Right now (27/9/2022) we are in the process of rolling out a method for doing this which requires minimal effort from the user. However, it is still useful to have a record of the old version of the process. This will not stop working once the new method is rolled out, by several steps will become unnecessary.

An attempt has been made to write these instructions so that they can be followed by someone with minimal knowledge of the CoFyBox and CoFyCloud system, but they do require access to Balena and they assume that at least the name of the CoFyBox is known.

1. Log into the box in Balena. Go to Settings → Devices & Services → Click on the ‘devices’ link under configuration.yaml in the MQTT tile.

   - If there’s no MQTT tile, or the ‘devices’ link only reports one device, you can immediately tell that this is going to require some troubleshooting. In this case it’s best to contact Carbon Co-op directly.

2. If the EmonEVSE is properly attached and configured, you’ll see a device with the manufacturer “OpenEVSE”. On the left is the device name, in the format openevse- where is a four character identifier for that particular unit. For example we might see openevse-2b9s. Make a note of this four character identifier.

3. This is also a good time to note the device location. Go to the map page in Home Assistant (HA) on the left of the page, and zoom in to make a note of an approximate street address. This is to search for in CoFyCloud later, and doesn’t need to be precise.

4. Go to the device configurator. This is accessed by going to the device’s HA URL /configurator, for example https://<device id>.balena-devices.com/configurator

5. Once in the configurator, click the folder icon in the top left of the screen and select glue_keys.json - this is the glue config file.

6. Glue works using ingredients (the data coming in from the sensors, and any mathematical operations performed on it) and recipes (instructions for how to output the data and metadata, potentially including mathematical functions of multiple ingredients). The ingredients are at the top and the recipes at the bottom. The tricky part with these EmonEVSE chargers has been that the glue config needs to know the four character identifier for the charger. An example glue config is given below. This uses the openevse-2b9s example from earlier. It also has the necessary configuration information for Shellies, a very common sensor that we use, which will most likely already be in the glue config file and should not be altered.

   - Note that the EmonEVSE reports in mA and CoFyCloud expects A, so in the ev_charging_current ingredient we divide by 1000 to convert the unit.

7. Once the alterations to glue_keys.json have been made, save it using the red and white floppy disk icon in the top right.

8. We can now test that this has worked by going back to the Balena management page for the box. In the terminal in the bottom right, start a session in the mosquitto service, and when it has loaded execute the command `mosquitto_sub -t ‘aggregated_data/#’ -v` and wait until something appears, this may take up to five minutes.

9. An example good output from the aggregated_data MQTT topic is given here. If the output from the box is similar, with four or different sections, three of which reference “electricVehicleCharging”, go on to the next step.

   `aggregated_data/e3c493d5347f/mqtt_consumer {"fields":{"timestamp_mean":1664272335.0306346,"value_mean":0},"name":"mqtt_consumer","tags":{"cofybox_id":"c17aec779eac4d92a29ab1a9ba7ce603","host":"e3c493d5347f","topic":"data/devices/heartbeat"},"timestamp":1664272500}`

   `aggregated_data/e3c493d5347f/mqtt_consumer {"fields":{"value_mean":0},"name":"mqtt_consumer","tags":{"cofybox_id":"c17aec779eac4d92a29ab1a9ba7ce603","device":"ev","host":"e3c493d5347f","metric":"electricVehicleCharging","metricKind":"gauge","sensor_id":"ev.charging_current_l1","topic":"data/devices/ev/charging_current_l1","unit":"A"},"timestamp":1664272500}`

   `aggregated_data/e3c493d5347f/mqtt_consumer {"fields":{"value_mean":240},"name":"mqtt_consumer","tags":{"cofybox_id":"c17aec779eac4d92a29ab1a9ba7ce603","device":"ev","host":"e3c493d5347f","metric":"electricVehicleCharging","metricKind":"gauge","sensor_id":"ev.voltage_phase_l1","topic":"data/devices/ev/voltage_phase_l1","unit":"V"},"timestamp":1664272500}`

   `aggregated_data/e3c493d5347f/mqtt_consumer {"fields":{"value_mean":454094},"name":"mqtt_consumer","tags":{"cofybox_id":"c17aec779eac4d92a29ab1a9ba7ce603","device":"ev","host":"e3c493d5347f","metric":"electricVehicleCharging","metricKind":"cumulative","sensor_id":"ev.total_consumption","topic":"data/devices/ev/total_consumption","unit":"Wh"},"timestamp":1664272500}`

10. Once the CoFyBox is broadcasting the data, the final step is to ensure that CoFyCloud is able to receive it. Go to https://app.cofybox.io and find the relevant CoFyBox. The easiest way to do this is usually to search enrolments while filtering by connected for the box name. Once you see the box name, click device → Open portal (in the top right) → Settings (on the left in the new window). Use the location you noted in step 3 to search in the location box, under Device settings → General. Use the location to search, it doesn’t need to be exact. Once a location is set, click the bottom save button beneath the PV-forecasting parameters.

11. Wait around five minutes, and click sensors at the top left of the screen. If everything has worked, you will see sensors with names beginning “ev.” and green ticks next to them. Click on any, and it should show you a blank graph. The setup is complete.

### ¶ Troubleshooting

- The biggest cause of problems is typos in the glue code. If no data appears in step 9, check that the edited parts of glue_keys.json have been typed correctly.
- You can also verify that the charger is transmitting correctly by logging into the Balena management page for the box. In the terminal in the bottom right, start a session in the mosquitto service, and when it has loaded execute the command `mosquitto_sub -t ‘openevse-<uuid>/#’ -v` where is the four character identifier for that particular unit. It should not take longer than 30 seconds for information to appear. If information is appearing here, it’s most likely a typing problem.
- If the sensors appear in CoFyCloud, but have red exclamation marks next to their names, the first thing to check is that the location information for the box has saved properly, as in step 11. If location information is present and the problem persists, try restarting the box and waiting for up to ten minutes.
- If there are still problems it’s best to contact Carbon Co-op directly.

### ¶ Example glue_keys.json

    {
        "version": "202111120",
        "ingredients": {
            "shellyem_0_total_consumption": {
                "friendly_name": "Total energy consumed",
                "topic_in": "shellies/+/emeter/0/total",
                "json_template": null
            },
            "shellyem_0_total_injection": {
                "friendly_name": "Total energy injected",
                "topic_in": "shellies/+/emeter/0/total_returned",
                "json_template": null
            },
            "shellyem_0_total_power": {
                "friendly_name": "Total power",
                "topic_in": "shellies/+/emeter/0/power",
                "json_template": null
            },
            "shellyem_0_voltage": {
                "friendly_name": "Voltage",
                "topic_in": "shellies/+/emeter/0/voltage",
                "json_template": null
            },
            "shellyem_1_total_consumption": {
                "friendly_name": "Total energy consumed",
                "topic_in": "shellies/+/emeter/1/total",
                "json_template": null
            },
            "shellyem_1_total_injection": {
                "friendly_name": "Total energy injected",
                "topic_in": "shellies/+/emeter/1/total_returned",
                "json_template": null
            },
            "shellyem_1_total_power": {
                "friendly_name": "Total power",
                "topic_in": "shellies/+/emeter/1/power",
                "json_template": null
            },
            "shellyem_1_voltage": {
                "friendly_name": "Voltage",
                "topic_in": "shellies/+/emeter/1/voltage",
                "json_template": "{{foo}}"
            },
            "ev_voltage": {
                "friendly_name": "EV charging supply voltage",
                "topic_in": "openevse-2b9s/voltage",
                "json_template": null
            },
            "ev_charging_current": {
                "friendly_name": "EV charging current",
                "topic_in": "openevse-2b9s/amp",
                "json_template": "{{value / 1000.0}}"
            },
            "ev_charging_energy_consumption": {
                "friendly_name": "EV charging energy consumption total",
                "topic_in": "openevse-2b9s/wh",
                "json_template": null
            }
        },
        "recipes": {
            "total_consumed": {
                "friendly_name": "Total consumption",
                "topic_out": "data/devices/utility_meter/total_energy_consumed",
                "recipe": "{{shellyem_0_total_consumption}}",
                "entity": "utility_meter",
                "channel": "total_energy_consumed",
                "unit": "Wh",
                "metricKind": "cumulative",
                "metric": "electricityImport",
                "ignore_after": 300,
                "ignore": false
            },
            "total_injected": {
                "friendly_name": "Total injection",
                "topic_out": "data/devices/utility_meter/total_energy_injected",
                "recipe": "{{shellyem_0_total_injection}}",
                "entity": "utility_meter",
                "channel": "total_energy_injected",
                "unit": "Wh",
                "metricKind": "cumulative",
                "metric": "electricityImport",
                "ignore_after": 300,
                "ignore": false
            },
            "total_power": {
                "friendly_name": "Total active power",
                "topic_out": "data/devices/utility_meter/total_active_power",
                "recipe": "{{shellyem_0_total_power}}",
                "entity": "utility_meter",
                "channel": "total_active_power",
                "unit": "W",
                "metricKind": "gauge",
                "metric": "electricityImport",
                "ignore_after": 300,
                "ignore": false
            },
            "voltage_phase_l1": {
                "friendly_name": "Voltage phase 1",
                "topic_out": "data/devices/utility_meter/voltage_phase_l1",
                "recipe": "{{shellyem_0_voltage}}",
                "entity": "utility_meter",
                "channel": "voltage_phase_l1",
                "unit": "V",
                "metricKind": "gauge",
                "metric": "electricityImport",
                "ignore_after": 300,
                "ignore": false
            },
            "ev_voltage_phase_l1": {
                "friendly_name": "EV charging supply voltage",
                "topic_out": "data/devices/ev/voltage_phase_l1",
                "recipe": "{{ev_voltage}}",
                "entity": "ev",
                "channel": "voltage_phase_l1",
                "unit": "V",
                "metricKind": "gauge",
                "metric": "electricVehicleCharging",
                "ignore_after": 300,
                "ignore": false
            },
            "ev_current_l1": {
                "friendly_name": "EV charging current",
                "topic_out": "data/devices/ev/charging_current_l1",
                "recipe": "{{ev_charging_current}}",
                "entity": "ev",
                "channel": "charging_current_l1",
                "unit": "A",
                "metricKind": "gauge",
                "metric": "electricVehicleCharging",
                "ignore_after": 300,
                "ignore": false
            },
            "ev_charging_energy_consumption": {
                "friendly_name": "EV charging energy consumption total",
                "topic_out": "data/devices/ev/total_consumption",
                "recipe": "{{ev_charging_energy_consumption}}",
                "entity": "ev",
                "channel": "total_consumption",
                "unit": "Wh",
                "metricKind": "cumulative",
                "metric": "electricVehicleCharging",
                "ignore_after": 300,
                "ignore": false
            }
        }
    }