First a quick disclaimer, I’m literally writing this 3 days after the installation of my Home Assistant setup so I have little experience with that. Therefor many of the configuration details could be lacking. Also I still have at least 2 known issues that I’m working on. One is that the numbers received aren’t numeric (and my value_template didn’t fix that), the other is that for now I’m still using an Android phone in between. I’d like to replace that by some headless thing that stays on the bike soon.

Prepare Home Assistant

If that didn’t stop you from reading how I managed, here goes my first attempt at documenting this. Let’s begin with the Home Assistant integration and configurations that were needed to get this working. And they aren’t that complicated to be honest. All I really needed was a way to receive data from the bike. I opted for the MQTT integration which is an official HA feature. Follow the link for the proper full on documentation. I only entered my HA network location in the config and it was up and running. From the integrations tab you can select the MQTT integration and hit configure to send and receive some test messages.

Now in order to create the sensors that will receive our push messages we need to go into the config/configuration.yaml file to create some definitions. Personally I have an ssh/terminal add on for home assistant that allows me to edit the config yaml file from my browser or remotely over SSH. The minimal sensor config you’ll need looks like this

mqtt:
  sensor:
    - state_topic: "energica/soc"
      name: “Energica SOC”
    - state_topic: “energica/odo”
      name: “Energica ODO”

MQTT requires a topic and a payload, optionally you can add a retain flag and a QoS (Quality of Service) level to each message. The retain flag is desired so that you can always see the last values instead of some default “unknown” or “unavailable” tags when the bike isn’t powered on. If you’ll use my Android app to test pushing data you can just take over my config. You’ll notice that I’ve added more topics and for each topic I’ve added a device_class and unit_of_measurement that helps with displaying the sensor values.

TODO my full MQTT config here as text for copy paste

That value_template I have on the first sensor was added in an attempt to fix the error I get when I create history graph or other specific visualisations that require a numeric sensor value. It didn’t work though so I’ll have to update this how to as soon as I’ve resolved that issue.

Pushing some test data

The neat thing about MQTT is that it’s a very lightweight protocol and on top HA provides a REST API so you can very easily push data with some very simple requests. If you don’t want to use the MQTT integration helper for this you can push data from a terminal with the following curl command.

$ curl -X POST \
    -H "Authorization: Bearer ABCDEFGH" \
    -H "Content-Type: application/json" \
    -d '{"payload": "90", "topic": "energica/soc", "retain": 1, "dos": 1}' \
    http://IP_ADDRESS:8123/api/services/mqtt/publish

Just replace IP_ADDRESS with your HA network location and ABCDEFGH with the long term token you can create in your HA installation from your profile settings. There is no need to configure specific MQTT users or anything, just that long term token. Later on in the app you’ll also have to provide these 2 details in order for it to work.

Connecting with any Energica Motorcycle

Then comes the final step where we will populate the dashboard with data coming from our bikes. For this you can get the latest version of my Android app that can connect with Energica using either native BLE communication or a Bluetooth connection with an elm327 chipset OBDII dongle on the bike. Both options work equally well, there are some small changes in the availability of data though. See overview from project website below

energica/soc
energica/range        // only for BLE connection
energica/odo          // onlyy for BLE conn. and Generic OBDII data
energica/reserve      // only for BLE connection
energica/temp/ambient // not pushed yet, for generic OBDII and BLE
energica/temp/battery
energica/current
energica/voltage

Those are all the topics we’ve configured on our Home Assistant installation. If you don’t want to display them just don’t add any of these sensor values on the dashboards you use. Or completely remove the sensor from config will also work. The app will ignore topics that don’t exist (or rather it will still send them but ignore any lack of response).

From the project website you can find more details on how this technically works and how to set up the app and the bike. You will need app version 3.18 or higher for this MQTT integration to be available. Once the app is installed you go to the settings screen using the 3 dots on top right corner.

On that screen scroll to the bottom for all the MQTT related features. Toggle the Push data using MQTT toggle to the ON position. Tap the MQTT Server URL option to provide a server address. The default value is http://homeassistant.local:8123/api/services/mqtt/publish and depending on your install and network that might just work. If not try with an explicit IP address instead. And then finally hit the MQTT token option and provide the long term token you’ve generated using HA in the previous steps.

Once all this is configured you can either connect from the OBDII data screen or from the BLE screen and everything received should be pushed to Home Assistant. If nothing shows up you can check the device logs from the same 3 dots menu for errors.

How to connect this app to your bike is also defined on the project website. For OBDII you can create a Bluetooth connection in the device bluetooth settings and then select that from the dropdown menu. For BLE you need to reset the BLE connection on the bike first and then on startup it should recognise the bike by itself. If that fails you can also remove the pairing from the app settings to try again.

Future Improvements

So obviously I would now like to tackle some of the shortcomings first. The non numeric values received could be as simple as an updated payload including numeric values (instead of one string) and then an updated value_pattern to convert to numeric. Something I need to play with.

The other change to come soon is that I don’t want to have that smartphone in between. It should keep its service running and reconnect as soon as the bike is back in reach after a ride. Or you could even take the phone with you and it will only push all the data, including that from the ride, once back in reach of the network (or you could expose your HA installation). Below is a phone screenshot of the dashboard I’ve created for my bike.

But ideally I’d like to have some headless thing on top of the inverter underneath the tank panels that is always connected to the bike and powers up and down together with the bike. It could also just cache data for when HA is out of reach like the phone already does. But at least there is no more need of a phone to keep charged and connected.

Update1: I’ve just pushed version 3.18 of the Android app including this MQTT integration.

Update2: I’ve also published info on how I use this in my garage with a headless setup using a raspberry pi and python code.