Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
213 lines (135 loc) · 7.27 KB

DEVELOPMENT.md

File metadata and controls

213 lines (135 loc) · 7.27 KB

Development of the Zaptec HA integration

This document intends to contain various documentation and tips & tricks for developing the integration.

Guidelines

This is a collection of guidelines that should be considered when working with:

  • Use ruff format to autoformat the sources. This is what HA is using and it's best if this integration is doing the same.

  • When adding a new entity, check that it's a "state" variable. The state vars are polled much more frequently than any of the others. Some vars exist in either under slightly different names and then the state variant should be preferred.

  • Use the HA quality scale guidelines: https://developers.home-assistant.io/docs/core/integration-quality-scale/rules

Linting and formatting

The codebase in this project should be aligned with the formatting and linting rules of Home Assistant. ruff is being used as the choice of linter.

The ruff settings are not precisely the same as HA because HA has a very extensive rule list. When encountering linting errors in this project, it might be that the rule is too strict. If HA has added an exception for the rule, we should be inclined to follow suit.

Logging

The Zaptec integration has a number of internal ways to increase debug logging for developers.

  • const.REDACT_LOGS - Enables or disables the redaction of sensitive data from api.py.

  • const.REDACT_DUMP_ON_STARTUP - Enables or disables the printing of the redaction database on HA initialization.

  • api.DEBUG_API_CALLS - Enables the logging of the API calls that are made. They have the @@@ marker in the logs.

  • api.DEBUG_API_DATA - Set this to True to print verbose data and headers about every REST call and response.

  • api.DEBUG_API_EXCEPTIONS - With this enabled, every unexpected response from the API cloud will be logged, including TB.

Setup development environment

This section goes through the steps of setting up the development environment using VSCode and Dev containers.

Prerequisites

GitHub fork

If you are going to make contributions to Zaptec, you need to fork a copy of the Zaptec repo.

  1. Log in or create a GitHub user

  2. Navigate to https://github.com/custom-components/zaptec

  3. Fork the repo, by pressing the "Fork" button

  4. Press the green "<> Code" button and copy the URL.

You now have your own copy, a fork, of the repo. This is going to be the basis for developing from. You can use either HTTPS or SSH URL of your choice. Please see the documentation for git on how to set that up.

Setting up the dev container

  1. Check out Zaptec at a suitable location

    # Here you can use your own fork address of zaptec
git clone https://github.com/custom-components/zaptec.git

  2. Open VS Code and select "Open folder" (Ctrl+K Ctrl+O) and navigate to the directory with the zaptec integration

  3. If VS Code asks "There is a Dev Container configuration available for this repository. Reopen folder to develop in a container (learn more)." then press "Reopen in container". Otherwise press F1 to open the command prompt and enter "Dev Containers: Rebuild and reopen in container"

  4. If this is the first time VS Code will ask: "Dev Container requires Docker to run. Do you want to install Docker in WSL?" press yes.

This process takes quite a long time the first time. When complete, you now have a development environment that is set up for developing. VS Code is set up with the proper Python, the proper IntelliSense and the proper linting rules.

More info about dev containers:

Running Home Assistant

To run Home Assistant, the task is simple:

  1. Press F1 and select "Tasks: Run Task" and press enter.

  2. Select "Run Home Assistant on port 8123". Wait a few minutes until it reads "Home Assistant started" in the logs.

  3. Open a web browser of choice and open "http://localhost:8123"

  4. The first time you need to fill in a few questions to configure HA.

  5. To enable Zaptec, you need to set it up the same way any new integration is done: Settings -> Devices & Services -> + Add integration (blue button) and then write "Zaptec".

The Zaptec integration is running in debug mode, so the log output will contain a lot of info.

Running tests

To run tests and check test coverage:

  1. Run ./scripts/test to generate the test- and coverage-reports

  2. Either open htmlcov/index.html in a browser to view the html coverage report, or enable the "Coverage Gutters" extension to view the coverage directly in VSCode.

HA requires 95% coverage for all core integration modules, and while HACS doesn't have the same requirements, reaching this level is still a goal for this integration.

Zaptec model and behaviors

This section describes various behaviors of the Zaptec API that might have an impact on the implementation.

Zaptec constants

The Zaptec API relies on a constants file which is used to look up settings and number to string tables. This can be downloaded either from

https://api.zaptec.com/api/constants

Or by the snippet:

import json
async with Zaptec(username, password) as zaptec:
    with open("constants.json", "w") as fp:
        json.dump(await zaptec.request("constants"), fp, indent=2)

Resume charging when authorization required

When authorization required is enabled the restart of charging takes two steps instead of one.

State: Connected_Finished --> Command: ResumeCharging (507) --> State: Connected_Requesting --> Command: AuthorizeCharge --> State: Connected_Charging

Last observed Jul 2025

Command DeAuthorizeAndStop (10001) fails with 500

Currently issuing the command DeauthorizeAndStop (code 10001 or "deauthorize_and_stop" in this integration) results in the HTTP error 500 Internal server error. Despite the error, the command will be executed.

Last observed Jul 2025

Error codes on 500 Internal server error

When the Zaptec cloud returns HTTP error 500 Internal server error, the payload will contain additional information. See the discussion about 500 errors

{"Code":528,"Details":null,"StackTrace":null}

It seems the error code can be looked up in constants under ErrorCodes, where 528 corresponds to DeviceCommandRejected.

Last observed Jul 2025

SignedMeterValue

The field SignedMeterValue and CompletedSession.SignedSession are using the Open Charge Metering Format, which can be read here: