Development Process

Clone the repository

Clone the HEMS repository:

git clone https://gitlab.com/carboncoop/hems.git

This contains the source code, configuration, and docker files needed to run the system on your laptop or a balenaOS device.

hems
    |
    |-> homeassistant/
    |     |-> custom_components/
    |     |     |->openadr_ven
    |     |     |->shelly
    |     |     |->emonevse
    |     |     |->scheduler
    |     |     |->balena
    |     |     |->der
    |     |-> config/
    |     |-> docker/
    |-> docker-compose.yml
    |-> docker/
    |-> provisioning/

Hierachical diagram of software components

homeassistant/

Root of HA distribution. Source files and configuration for HA container.

homeassistant/custom_components/

Folder containing custom components.

homeassistant/config/

Folder containing standard HA runtime configuration files.

homeassistant/docker/

Folder containing docker files for building HA (note this cannot be moved into a folder in the root of the repository due to the way balena deploy/push works).

docker-compose.yml

This is the compose file used by balena deploy/push. Balena expects a file with this name to be present in the root of the repository.

docker/

This contains docker compose files which can be used for building the HEMS software and running it locally (see below).

provisioning/

This contains a set of scripts for provisioning of devices. They will download the SD images generated by the build pipeline, create devices on balena cloud, write device-specific configuration, burn the final SD images to an SD card, and generate output information that can be used to create labels etc.

Debugging while running HEMS locally in Docker

A Python debugger can be attached to a local HEMS container, as described in the Home Assistant documentation <https://www.home-assistant.io/integrations/debugpy/>, using the debugpy package. Remember to expose port 5678 in the Docker Compose file.

Source code must be mapped between your development environment and the running HEMS instance. An example of this in VSCode for debugging a custom component is below:

{
        // Example of attaching to local debug server
        "name": "Python: Attach to Docker",
        "type": "python",
        "request": "attach",
        "port": 5678,
        "host": "localhost",
        "pathMappings": [
            {
                "localRoot": "${workspaceFolder}/homeassistant/custom_components/OctopusAgile",
                "remoteRoot": "/config/custom_components/OctopusAgile"
            }
        ],
    }