Skip to content

Latest commit

 

History

History
300 lines (212 loc) · 11.8 KB

README.md

File metadata and controls

300 lines (212 loc) · 11.8 KB
Raw

Zaptec EV charger component for Home Assistant

hacs GitHub Release License Downloads

Project Maintenance BuyMeCoffee

Project Maintenance BuyMeCoffee

Features

  • Integration for Home assistant for Zaptec Chargers through the Zaptec portal/cloud API
  • Provides start & stop of charging the EV
  • Supports basic authentication (native authentication)
  • Sensors for status, current, energy
  • Adjustable charging currents, all or individual three phase

To use this component, a user with access to Zaptec Portal is needed.

Compatibility

Confirmed to work with

  • Zaptec Go
  • Zaptec Home
  • Zaptec PRO

ℹ️ Please reach out if you have been able to make this component work with other Zaptec chargers.

‼️ Breaking change

⚠️ This release will BREAK your current automations

The Zaptec integration has been completely refactored. The way to interact with you Zaptec charger from Home Assistant has been changed. The Zaptec data is now represented as proper entities (like sensors, numbers, buttons, etc). This makes logging and interactions much simpler and it needs no additional templates.

The integration is set up as one devices for each of the detected Zaptec devices. Most users will have three devices: An installation device, a circuit and a charger and each provide different functionality.

The previous zaptec entities were named zaptec_charger_<uuid>, zaptec_installation_<uuid> and zaptec_circute_<uuid>. The full data were available as attributes in these objects, and they could be retried with the aid of manual templates. The same objects exists, but under the names <name> Installer, <name> Charger and <name> Circuit.

Installation and setup

This integration is available in HACS (Home Assistant Community Store).

Just search for Zaptec in the HACS list or click the badge below:

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

After adding it to HACS it must be added to HA.

  • Click Settings (left hand side menu at the bottom)
  • Click Devices & Services
  • Select Integrations pane
  • Press "+ Add integration" in the bottom right corner
  • In the search for dialog enter "Zaptec" and click it

Next the Zaptec setup dialog is presented. Fill in the form:

  • Username: Your Zaptec portal username
  • Password: Your Zaptec portal password
  • Optional prefix specifies if a prefix on all entities are wanted. Leave this blank unless there is a specific need for it. Its generally better to rename entities in HA than using this feature.
  • Scan interval indicates how many seconds between the cloud is polled for new data. Zaptec has rate limiting, so putting a too low value might cause problems. Default value is fine.
  • Manually select chargers will allow you to select which chargers that should be included into HA. This is useful for large installation that have many chargers. When selected a new dialog asking for which chargers to add will be selected.

Usage

ℹ️ This integration use the official Web API provided by Zaptec. However, this integration also use a few functions that are not officially supported by the API. Use at own risk and they might break at any time.

  • Setting authorization required
  • Circuit info
  • Setting charger min and max current
  • Authorize charging
  • Setting cable lock
  • Setting status light brightness

Zaptec device concept

The Zaptec cloud API use three levels of abstractions in their EVCP setup. These are represented as three devices in HA

  • Installation - This is the top-level entity and represents the entire site. This is where the current limit for the entire installation is set.

  • Circuit - An installation can have one or more (electrical) circuits. One circuit have one common circuit breaker. This device isn't directly used in HA.

  • Charger - This is the actual EV charge point connected to a circuit. Each circuit might have more than one charger. This is where the start & stop interaction is done and information about the charging and sessions.

Start & stop charging

Starting and stopping charging can be done by several methods. If the charger is configured to no require authentication, connecting the charger to the EV will by default start charging.

To start the charging from HA, this can be done in several ways:

  • Press the "Resume charging" button, or
  • Toggle the "Charging" switch, or
  • Send zaptec.restart_charger service call

Similarly, pausing the charging can be done by:

  • Pressing the "Stop charging" button, or
  • Turn off the "Charging" switch, or
  • Send zaptec.stop_pause_charging service call

ℹ️ NOTE: Zaptec will unlocks the cable when charging is paused unless it is permanently locked.

Prevent charging auto start

Zaptec will by default start charging as soon as everything is ready under the following conditions; (1) Cable connected to car, (2) Car is ready to charge, (3) authentication is given (optional).

If auto start is not wanted, e.g. for delayed start or energy control, one of the following will prevent auto start:

  • Delay authorization of the charger
  • Set the available charge current to 0 A. There are two ways to do it
    • "Available current" in the installation object
    • "Charger max current" in the charger object

ℹ️ NOTE! The "Available current" is the official way to control the charge current. However, it will affect all chargers connected to the installation.

Setting charging current

The "Available current" number entity in the installation device will set the maximum current the EV can use. This slider will set all 3 phases at the same time.

ℹ️ NOTE! This entity is adjusting the available current for the entire installation. If the installation has several chargers installed, changing this value will affect all.

ℹ️ NOTE! Many EVs doesn't like getting too frequent changes to the available charge current. Zaptec recommends not changing the values more often than 15 minutes.

3 phase current adjustment

The service call limit_current can be used with the arguments available_current_phase1, available_current_phase2 and available_current_phase3 to set the available current on individual phases.

Require charging authorization

Many users wants to setup their charger to require authorization before giving power to charge any EV. This integration does not offer any options to configure authorization. Please use the official Zaptec portal or app.

If the charger has been setup with authorization required, the car will go into Waiting mode when the cable is inserted. Authentication must be presented before being able to charge. This can be RFID tags, the Zaptec app and more.

If the installation is configured for native authentication it is possible to authorize charging from Home Assistant using the "Authorize charging" button. It stays authorized until either the cable is removed or the button "Deauthorize charging" is pressed.

ℹ️ INFO: Please note that Zaptec unlocks the cable when charging is paused unless it is permanently locked.

ℹ️ INFO: Charge authorization from HA only works when the installation is set with Authentication Type set to Native authentication in Zaptec portal.

Templates

The special diagnostics entities named "x Installation", "x Circuit" and "x Charger" contains all attributes from the Zaptec API for each of these devices. This corresponds to the old zaptec_installation_*, zaptec_circuit_* and zaptec_charger_* objects. These attributes can be used with template sensors to retrieve additional or missing information.

Example: Add the following to your configuration.yaml

template:
  - sensor:
     - name: Charger Humidity
       unique_id: charger_humidity
       unit_of_measurement: '%Humidity'
       state: >
        {{ state_attr('binary_sensor.X_charger', 'humidity') | round(0) }}
       # Replace "X_charger" with actual entity name

The list of attributes can be found by looking at the attributes for the entities. Note that the names cannot contain spaces. Replace captal letters with small case and spaces with underscore (_). E.g. The attribute "Charger max current" is charger_max_current in the template.

Diagnostics

The integration supports downloading of diagnostics data. This can be reached by Settings -> Devices & Services -> <one of your zaptec devices> and then press the "Download diagnostics". The file downloaded is anonymized and should not contain any personal information. Please double check that the file doesn't contain any personal information before sharing.

Debugging

Debug log for Zaptec can be enabled by going to Settings -> Devices & Services -> Integration (pane) -> Zaptec EV Charger -> Enable debug logging.

The most interesting stuff happens when the integration is started, so in the same view press ... under Integration entries and press "reload". When the button Enable debug logging is turned off the browser will download the debug logs.

Alternatively, debug can be enabled by manually adding the following to configuration.yaml:

logger:
  logs:
    custom_components.zaptec: debug

⚠️ IMPORTANT! The debug logs will contain identifiable information about your Zaptec setup such as login and password. Do not share logs without filtering them.

ℹ️ NOTE! The Zaptec integration logs massive amounts in debug. This is nice for finding errors, but it will generate large amount of data if left enabled for long. Do not use in production setups.

Using the integration

Load balancing your charger

By using the Zaptec Load Balancing blueprint you'll get automatic load balancing for your charger (i.e. the charger limit is updated constantly to avoid fuse overload).

The automation created with the blueprint manages current limiting. If charging is enabled and possible without tripping fuses it will manage the limit over the charging session.

How to setup the automation, how the logic works and what all settings mean is documented in the blueprint readme.