How to add OVMS (open vehicles) to Home Assistant

OVMS (Open Vehicles) is a great hardware module that connects to my Nissan LEAF and allows me to perform remote functions like turning on the climate control, checking charge status, range, etc. I’m also a big fan of Home Assistant, and have almost everything in my house hooked up to it. There is no official (or unofficial) integration for OVMS to Home Assistant. However, OVMS has a HTTP API, and Home Assistant supports generic RESTful sensors.

Read on to find out how to hook up your OVMS module to Home Assistant!

Getting Started

Firstly, you’ll need your OVMS module to be hooked up, configured correctly, and working with the default OVMS app. Once your app is connected to your OVMS module and you can see live data coming through, it’s time to move on.

Generating an API Token

You’ll need to generate an API Token from the openvehicles.com API. To do this, you’ll need to open up the Terminal on your computer. Once there, type the command below and hit enter, replacing <USERNAME> and <PASSWORD> with your OVMS username/password that you use to login to openvehicles.com.

curl --location --request POST 'https://api.openvehicles.com:6869/api/token?username=<USERNAME>&password=<PASSWORD>'

After you run that command, you will see an output on your screen similar to the one below. You’ll need to copy your API Token (highlighted in bold) to a safe place.

{"application":"notspecified","owner":"<YOUR_USERNAME>","permit":"auth","purpose":"notspecified","token":"RiVINShnbS0wNG5tJUlNYUZJbUNeR1NcYSdwM0l7aDpWOyE2QkQxSCwrLWh8Ow"}

Find your list of metrics

Now you need to find a list of all the metrics that you want available in home assistant. There are 3 main collections of metrics that the OVMS API makes available. These are Status, Charging, and Location. If you have a 2012 era Nissan LEAF like I do, skip below and copy my config file. Otherwise, read on.

To find all of the available metrics, run the following commands in your terminal. Make a note of all the metrics that you want available in Home Assistant. Be sure to replace <USERNAME> with your username, <VEHICLE_ID> with your OVMS vehicle ID, and <YOUR_API_TOKEN> with the token you retrieved earlier.

Status

curl --location --request GET 'https://api.openvehicles.com:6869/api/status/<VEHICLE_ID>?username=<USERNAME>&password=<YOUR_API_TOKEN>'

Charging

curl --location --request GET 'https://api.openvehicles.com:6869/api/charge/<VEHICLE_ID>?username=<USERNAME>&password=<YOUR_API_TOKEN>'

Location

curl --location --request GET 'https://api.openvehicles.com:6869/api/charge/<VEHICLE_ID>?username=<USERNAME>&password=<YOUR_API_TOKEN>'

Home Assistant Configuration

Now you’ll need to configure Home Assistant to retrieve data from the OVMS API and pull out the metrics that you want. Add a configuration to your configuration.yaml in the sensor section like below. You can update the scan_interval to whatever you’d like, but be considerate and don’t go lower than when your OVMS sends updates, or at a minimum every 60 seconds.

sensor:
  - platform: rest
    scan_interval: 120
    name: car_status
    resource: https://api.openvehicles.com:6869/api/status/<VEHICLE_ID>?username=<USERNAME>&password=<YOUR_API_KEY>
    value_template: "{{ value_json.soc }}"
    json_attributes:
      - soh
      - soc
      - etc...

  - platform: rest
    scan_interval: 120
    name: car_location
    resource: https://api.openvehicles.com:6869/api/location/<VEHICLE_ID>?username=<USERNAME>&password=<YOUR_API_KEY>
    value_template: "{{ value_json.longitude }},{{ value_json.latitude }}"
    json_attributes:
      - longitude
      - latitude
      - etc...

  - platform: rest
    scan_interval: 60
    name: car_charging
    resource: https://api.openvehicles.com:6869/api/charge/<VEHICLE_ID>?username=<USERNAME>&password=<YOUR_API_KEY>
    value_template: "{{ value_json.chargestate }}"
    json_attributes:
      - battvoltage
      - cac100
      - carawake
      - caron
      - etc...

Save and validate

Save the new configuration, and use the handy “Check Configuration” button on the Configuration > Server Controls page. If there are no errors, then restart your home assistant server.

When the server starts back up, you should see some new entities called sensor.car_status, sensor.car_location, and sensor.car_charging. Use this in your automations or expose them via HomeKit like I did! Check below for my full configuration, including HomeKit friendly template sensors (although HomeKit does not support this very well as it doesn’t have native EV support).

HomeKit Example

You can see what this looks like in the screenshot from my iPhone below. I’ve configured the SoC as a humidity sensor so it reads as a percentage, and the range as an illuminance sensor. Unfortunately, HomeKit lacks an EV entity type, so this is the best I could come up with.

If you name the sensors something appropriate, you can even ask Siri to tell you the state of charge or range, if you can deal with the annoying response as it thinks they’re different types of sensors. Hopefully Apple adds an EV entity to HomeKit in the future, so a proper integration can be made!

Example config for a 2012 Nissan LEAF

- sensor:
    - name: car_soc_homekit
      state: "{{ state_attr('sensor.car_status', 'soc') }}"
      icon: "mdi:car-electric"
      device_class: humidity
      unit_of_measurement: "%"

    - name: car_range_homekit
      state: '{{ (float(state_attr("sensor.car_status", "estimatedrange")) * 1.25) | int }}'
      icon: "mdi:speedometer-slow"
      device_class: illuminance

    - name: car_soc
      state: "{[ state_attr('sensor.car_status', 'soc') }}"
      icon: "mdi:car-electric"
      device_class: battery

    - name: car_range
      state: '{{ (float(state_attr("sensor.car_status", "estimatedrange")) * 1.25) | int }}'
      icon: "mdi:speedometer-slow"

- binary_sensor:
    - name: car_charging
      state: "{{ state_attr('sensor.car_status', 'charging') }}"
      icon: "mdi:ev-station"

- platform: rest
  scan_interval: 60
  name: car_status
  resource: https://api.openvehicles.com:6869/api/status/<VEHICLE_ID>?username=<USERNAME>&password=<YOUR_API_KEY>
  value_template: "{{ value_json.soc }}"
  json_attributes:
    - alarmsounding
    - bt_open
    - cac100
    - carawake
    - carlocked
    - caron
    - chargestate
    - charging
    - charging_12v
    - cooldown_active
    - cp_dooropen
    - estimatedrange
    - fl_dooropen
    - fr_dooropen
    - handbrake
    - idealrange
    - idealrange_max
    - mode
    - odometer
    - parkingtimer
    - pilotpresent
    - soc
    - soh
    - speed
    - staleambient
    - staletemps
    - temperature_ambient
    - temperature_battery
    - temperature_charger
    - temperature_motor
    - temperature_pem
    - tr_open
    - tripmeter
    - units
    - valetmode
    - vehicle12v
    - vehicle12v_current
    - vehicle12v_ref

- platform: rest
  scan_interval: 60
  name: car_location
  resource: https://api.openvehicles.com:6869/api/location/<VEHICLE_ID>?username=<USERNAME>&password=<YOUR_API_KEY>
  value_template: "{{ value_json.longitude }},{{ value_json.latitude }}"
  json_attributes:
    - altitude
    - direction
    - drivemode
    - energyrecd
    - energyused
    - gpslock
    - invefficiency
    - invpower
    - latitude
    - longitude
    - power
    - speed
    - stalegps
    - tripmeter

- platform: rest
  scan_interval: 30
  name: car_charging
  resource: https://api.openvehicles.com:6869/api/status/<VEHICLE_ID>?username=<USERNAME>&password=<YOUR_API_KEY>
  value_template: "{{ value_json.chargestate }}"
  json_attributes:
    - battvoltage
    - cac100
    - carawake
    - caron
    - charge_estimate
    - charge_etr_full
    - charge_etr_limit
    - charge_etr_range
    - charge_etr_soc
    - charge_limit_range
    - charge_limit_soc
    - chargeb4
    - chargecurrent
    - chargeduration
    - chargekwh
    - chargelimit
    - chargepower
    - chargepowerinput
    - chargerefficiency
    - chargestarttime
    - chargestate
    - chargesubstate
    - chargetimermode
    - chargetimerstale
    - chargetype
    - charging
    - charging_12v
    - cooldown_active
    - cooldown_tbattery
    - cooldown_timelimit
    - cp_dooropen
    - estimatedrange
    - idealrange
    - idealrange_max
    - linevoltage
    - mode
    - pilotpresent
    - soc
    - soh
    - staleambient
    - staletemps
    - temperature_ambient
    - temperature_battery
    - temperature_charger
    - temperature_motor
    - temperature_pem
    - units
    - vehicle12v
    - vehicle12v_current
    - vehicle12v_ref