leaf2mqtt

:warning: olderCanada and olderUSA support may break at anytime because Nissan keep changing the API key. Thank you Nissan for working against your customers.

:warning: If you're not using the Leaf frequently, stop the container or drastically reduce the update frequency, or you could well end up with a flat 12V battery.

This works for my Canadian made in 2018 LEAF 40kWh. It was also reported to be working on a newer than May 2019 Leaf.

You must have a working MQTT broker on your LAN.

Should work with multiple Leafs, but it is untested. Please open an issue with feedback if possible.

• Setup
  • Pre-built images
  • Building the image
  • Running the image
• Status and Commands
  • General
  • Status
  • Commands
  • Battery
  • Status
  • Commands
  • Climate
  • Status
  • Commands
  • Stats
  • Status
  • Commands
  • Location
  • Status
  • Commands
  • Cockpit Status
  • Status
  • Commands
• Home Assistant Integration
  • Sensor examples
  • Recommended Battery Status Update Script
• Credits

Setup

Home Assistant add-on

Click the icon below to add this repository to your Home Assistant instance or follow the procedure highlighted on the Home Assistant website.

Pre-built images

You can use pre-built images from here: https://hub.docker.com/r/kamikac/leaf2mqtt

tag example: kamikac/leaf2mqtt:latest

Building the image

docker build --tag leaf2mqtt .

     -- OR --

cp local_settings.env.tmpl local_settings.env
docker-compose build

Running the image

Example:

docker run --restart always -e LEAF_USERNAME="myusername@somewhere.com" -e LEAF_PASSWORD="Some P4ssword!" -e LEAF_TYPE="newerThanMay2019" -e MQTT_HOST=192.168.1.111 -e UPDATE_INTERVAL_MINUTES=1440 -e COMMAND_ATTEMPTS=5 --name leaf2mqtt leaf2mqtt

     -- OR --

Edit local_settings.env
docker-compose up -d

:information_source:* The CHARGING_UPDATE_INTERVAL_MINUTES value will only be used after the ongoing UPDATE_INTERVAL_MINUTES is elapsed and the Leaf is charging.

Status and Commands

In these examples, the MQTT_BASE_TOPIC is set to the default (leaf).

General

Status

Commands

Battery

Status

Commands

Climate

Status

Commands

Stats

{TimeRange} must be daily or monthly.

Status

Commands

Location

Status

Commands

Cockpit Status

Status

Commands

:information_source: The status and commands for the first Leaf in the account are also supported by using the same topic without the {vin}.

:warning: Not all status and commands are supported for a given leaf type due to Carwings, NissanConnectNA or NissanConnect api limitations.

Home Assistant Integration

Sensor examples

mqtt:
  sensor:
    - name: leaf_battery_level
      # Since VIN is not specified, it will represent the state from the first vehicle in the account.
      state_topic: "leaf/battery/percentage"
      unit_of_measurement: "%"
      device_class: battery

    - name: leaf_battery_last_updated
      # Since VIN is not specified, it will represent the state from the first Leaf in the account.
      state_topic: "leaf/battery/lastUpdatedDateTimeUtc"
      device_class: timestamp

    - name: leaf_battery_last_received
      # You can specify the vin if you prefer or if you have more than one Leaf.
      state_topic: "leaf/XXXXXSOMEXVINXXXXX/battery/lastReceivedDateTimeUtc"
      device_class: timestamp

Recommended Battery Status Update Script

In Home Assistant, calling a script like this - service: script.some_script_name within another script or automation will actually stop the execution of the calling script until script.some_script_name terminates, unlike using script.turn_on. Knowing this, you can ensure you have the latest state for your leaf before continuing an automation using a script like this:

update_leaf_battery:
  # Using queued will ensure you do not update twice at the same time and will prevent
  # subsequent invocations from asking an update right away because of the while's conditions.
  # All the callers will also wait for the result.
  mode: queued
  sequence:
    - repeat:
        while:
          # Used with the sensors in the section above, this condition will
          # ensure we continue until the states are really updated.
          # It will also prevent subsequent calls from unnecessarily requesting
          # an update before the current state is 10 minutes old.
          - >
            {{ as_timestamp(now()) -
              as_timestamp(states('sensor.leaf_battery_last_updated')) > 600 }}

          # We also stop the loop after 4 tries since Nissan servers can send the same
          # old data many times in a row. I think this happens when the state did not really changed
          # or the Leaf is unreachable. 
          - "{{ repeat.index <= 4 }}"

        sequence:
          # We publish the update command for the car. 
          # You can also ommit the VIN to target the first Leaf in the account.
          # You can also request update for every state for one Leaf by removing the /battery section
          - service: mqtt.publish
            data:
              topic: "leaf/XXXXXSOMEXVINXXXXX/command/battery"
              payload: "update"
          # We now wait until we actually have received a response or if we timed out.
          # This does not mean that the received data is the latest. This is why
          # we check sensor.leaf_battery_last_updated in the while condition.
          - wait_for_trigger:
              - platform: state
                entity_id: sensor.leaf_battery_last_received
            timeout: 600
    # Let's have a cool down to give time to Home Assistant to update all the states.
    - delay: "00:00:10"

OpenHAB integration

Once you configure and start application you can configure OpenHAB to get data for your Leaf. Example config file is here and documentation is here

Credits

• Forked from Troon/leaf2mqtt. Thank you for the inspiration!
• Using libraries from Tobias Westergaard Kjeldsen to connect with the nissan leaf's APIs. Those libraries are also used for his MyLeaf app.