How golles/ha-kamstrup_403 works
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