# golles/ha-kamstrup_403 architecture

> Architecture diagram of the GitHub repository golles/ha-kamstrup_403, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/golles/ha-kamstrup_403
- Repository: https://github.com/golles/ha-kamstrup_403

## Overview

##### Project Type & Purpose
- This is a Home Assistant custom integration (Python package) to read data from a Kamstrup heat meter via an optical eye (serial or socket).
- It lives under `custom_components/kamstrup_403/` and includes a helper library (`pykamstrup`), config flow, coordinator, entities (sensors), diagnostics, and translations.

##### Main Components
a. Home Assistant Core
– The host application that loads integrations, runs the event loop, scheduler, entity registry, UI, energy dashboard, and logger.
b. Custom Component Package (`kamstrup_403`)
– manifest.json: declares metadata (domain, requirements, config entries).
– config_flow.py: implements the UI setup (Config Entry flow).
– coordinator.py: DataUpdateCoordinator subclass that handles polling.
– sensor.py: defines sensor entities.
– diagnostics.py: implements diagnostics endpoint for HA.
– const.py: shared constants and configuration defaults.
– translations/*.json: UI translations for entity names, errors.
c. Helper Library (`pykamstrup`)
– kamstrup.py: low-level protocol implementation to talk to meter over serial/socket.
– const.py: protocol constants.
d. External Hardware
– Optical eye device (FTDI‐based USB cable or remote ser2net socket).
– Physical Kamstrup meter.
e. Home Assistant Energy Dashboard & Logger
– Integrates sensor entities into the energy dashboard.
– Logger integration for debug output of `custom_components.kamstrup_403`.

##### Component Interactions & Data Flow
1. **Configuration Flow**
– User opens HA UI → triggers `config_flow` → user enters serial port or socket URL, scan interval, sensor selections → ConfigEntry persists these settings.
2. **Coordinator Polling**
– HA scheduler & DataUpdateCoordinator: every `scan_interval` seconds → calls `pykamstrup` methods to fetch up to 8 sensor readings in one session.
3. **Protocol Communication**
– `pykamstrup.kamstrup.read_*` uses `pyserial` or socket to send IR commands → optical eye → meter → reads response → parsed into Python primitives.
4. **Entity Update**
– Coordinator stores latest data → calls `sensor.async_write_ha_state()` on each sensor entity → updates HA state machine.
5. **Dashboard & Logging**
– Heat Energy (GJ) entity becomes available for Energy Dashboard.
– If enabled, diagnostics endpoint and debug logging (`logger: custom_components.kamstrup_403: debug`) can be used for troubleshooting.

##### Architectural Patterns & Principles
– **Asynchronous I/O & Event Loop**: uses HA’s asyncio-based core.
– **DataUpdateCoordinator**: central polling pattern in HA integrations.
– **Config Entry & Entity Registry**: dynamic registration of devices and sensors.
– **Separation of Concerns**:
- `config_flow.py` for setup UI
- `coordinator.py` for polling logic
- `sensor.py` for state representation
- `pykamstrup` submodule for protocol

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & UI Layer
    subgraph "User & UI Layer"
        HA_Core["Home Assistant Core"]:::frontend
        HA_UI["HA Frontend UI"]:::frontend
        Energy_Dashboard["Energy Dashboard"]:::frontend
    end

    %% Integration Logic Layer
    subgraph "Integration Logic Layer"
        MF["manifest.json"]:::integration
        CF["config_flow.py"]:::integration
        CONST["const.py"]:::integration
        COORD["coordinator.py"]:::integration
        SENSOR["sensor.py"]:::integration
        DIAG["diagnostics.py"]:::integration
        subgraph "Translations"
            EN["en.json"]:::integration
            NL["nl.json"]:::integration
        end
    end

    %% Hardware/Protocol Layer
    subgraph "Hardware / Protocol Layer"
        PY_LIB["pykamstrup"]:::protocol
        PYLIB_CONST["const.py"]:::protocol
        KAM_LIB["kamstrup.py"]:::protocol
        Socket["Serial / Socket"]:::protocol
        Optical["Optical Eye"]:::protocol
        Meter["Kamstrup Meter"]:::protocol
    end

    %% CI / Dev Tools
    subgraph "CI / Dev & Testing" 
        subgraph "GitHub Workflows"
            CI1["ci.yaml"]:::tools
            CI2["release.yaml"]:::tools
            CI3["validate.yaml"]:::tools
            CI4["codeql.yaml"]:::tools
            CI5["license.yaml"]:::tools
            CI6["stale.yaml"]:::tools
        end
        subgraph "DevContainer"
            DC1["devcontainer.json"]:::tools
            DC2["configuration.yaml"]:::tools
            DC3["README.md"]:::tools
        end
        subgraph "Tests"
            T1["test_config_flow.py"]:::tools
            T2["test_coordinator.py"]:::tools
            T3["test_diagnostics.py"]:::tools
            T4["test_manifest.py"]:::tools
            T5["test_sensor.py"]:::tools
            T6["conftest.py"]:::tools
            T7["const.py"]:::tools
            T8["test_init.py"]:::tools
        end
    end

    %% Connections
    HA_UI -->|"triggers config_flow()"| CF
    CF -->|"writes metadata"| MF
    MF -->|"defines defaults"| CONST
    HA_Core -->|"schedules poll()"| COORD
    COORD -->|"uses protocol"| KAM_LIB
    COORD -->|"stores data"| SENSOR
    SENSOR -->|"provides state"| HA_Core
    SENSOR -->|"feeds"| Energy_Dashboard
    COORD -->|"exposes diagnostics"| DIAG
    HA_Core -->|"calls diagnostics"| DIAG
    KAM_LIB -->|"reads constants"| PYLIB_CONST
    KAM_LIB -->|"opens port"| Socket
    Socket -->|"connects to"| Optical
    Optical -->|"reads meter"| Meter
    DIAG -->|"UI endpoint"| HA_UI

    %% Click Events
    click MF "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/manifest.json"
    click CF "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/config_flow.py"
    click CONST "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/const.py"
    click COORD "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/coordinator.py"
    click SENSOR "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/sensor.py"
    click DIAG "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/diagnostics.py"
    click EN "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/translations/en.json"
    click NL "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/translations/nl.json"
    click KAM_LIB "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/pykamstrup/kamstrup.py"
    click PYLIB_CONST "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/pykamstrup/const.py"
    click PY_LIB "https://github.com/golles/ha-kamstrup_403/blob/main/custom_components/kamstrup_403/pykamstrup/README.md"
    click CI1 "https://github.com/golles/ha-kamstrup_403/blob/main/.github/workflows/ci.yaml"
    click CI2 "https://github.com/golles/ha-kamstrup_403/blob/main/.github/workflows/release.yaml"
    click CI3 "https://github.com/golles/ha-kamstrup_403/blob/main/.github/workflows/validate.yaml"
    click CI4 "https://github.com/golles/ha-kamstrup_403/blob/main/.github/workflows/codeql.yaml"
    click CI5 "https://github.com/golles/ha-kamstrup_403/blob/main/.github/workflows/license.yaml"
    click CI6 "https://github.com/golles/ha-kamstrup_403/blob/main/.github/workflows/stale.yaml"
    click DC1 "https://github.com/golles/ha-kamstrup_403/blob/main/.devcontainer/devcontainer.json"
    click DC2 "https://github.com/golles/ha-kamstrup_403/blob/main/.devcontainer/configuration.yaml"
    click DC3 "https://github.com/golles/ha-kamstrup_403/blob/main/.devcontainer/README.md"
    click T1 "https://github.com/golles/ha-kamstrup_403/blob/main/tests/test_config_flow.py"
    click T2 "https://github.com/golles/ha-kamstrup_403/blob/main/tests/test_coordinator.py"
    click T3 "https://github.com/golles/ha-kamstrup_403/blob/main/tests/test_diagnostics.py"
    click T4 "https://github.com/golles/ha-kamstrup_403/blob/main/tests/test_manifest.py"
    click T5 "https://github.com/golles/ha-kamstrup_403/blob/main/tests/test_sensor.py"
    click T6 "https://github.com/golles/ha-kamstrup_403/blob/main/tests/conftest.py"
    click T7 "https://github.com/golles/ha-kamstrup_403/blob/main/tests/const.py"
    click T8 "https://github.com/golles/ha-kamstrup_403/blob/main/tests/test_init.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef integration fill:#90EE90,stroke:#333,stroke-width:1px
    classDef protocol fill:#FFA500,stroke:#333,stroke-width:1px,stroke-dasharray: 3 3
    classDef tools fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
