# lavron/docker-voltronic-mqtt architecture

> Architecture diagram of the GitHub repository lavron/docker-voltronic-mqtt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lavron/docker-voltronic-mqtt
- Repository: https://github.com/lavron/docker-voltronic-mqtt

## Overview

##### Project type and purpose
- This is a containerized IoT gateway application written in Python.
- It reads data from Voltronic solar inverters over a serial/USB interface, decodes inverter-specific protocols (PI30 and PI41), and publishes sensor readings to an MQTT broker.
- It’s intended to run as a Docker container (or via docker-compose) and integrate directly with Home Assistant (through the provided ha-sensors.yaml).

##### File structure
- Top-level:
- Dockerfile / docker-compose.yml – packaging and runtime orchestration
- requirements.txt – Python dependencies
- ha-sensors.yaml – Home Assistant configuration snippet
- src/ – Python source code
- src/ breakdown:
- main.py – application entrypoint
- serial_port.py – low-level adapter for /dev/ttyUSB* interface
- voltronic.py – protocol handler (PI30 & PI41 parsing, CRC, frame decode)
- mqtt.py – MQTT client wrapper (connect, publish)
- sensors.json – sensor metadata (IDs, names, units)
- No database or web server—just a pipeline: serial → parsing → MQTT.

##### README for additional insights
- Environment variables (MQTT_SERVER, MQTT_USER/PASSWORD, SERIAL_PORT) configure connections
- Image is “lavron/voltronic-mqtt:latest” on Docker Hub
- Supports dynamic discovery in Home Assistant via the YAML snippet

##### Elements
- “SerialPort Adapter”
- “Voltronic Protocol Handler”
- “MQTT Publisher”
- “MQTT Broker”
- “Home Assistant”
- “Solar Inverter”
- Data from inverter to adapter to handler to publisher to broker to HA

##### Detail & coverage
- Docker Compose linking container to host-device mapping (/dev:/dev)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Hardware
    SI["Solar Inverter"]:::external

    %% Docker Container and Internal Modules
    subgraph "Docker Container: Voltronic-MQTT"
        direction TB
        Env["Env Vars: MQTT_SERVER, MQTT_USER, MQTT_PASSWORD, SERIAL_PORT"]:::config
        SP["SerialPort Adapter"]:::containerModule
        VP["Voltronic Protocol Handler"]:::containerModule
        SD["Sensor Definitions"]:::config
        MA["Application Entrypoint"]:::containerModule
        MP["MQTT Publisher"]:::containerModule
    end

    %% External Services
    Broker["MQTT Broker"]:::external
    HA["Home Assistant"]:::external

    %% Project Configuration Files
    subgraph "Project Config"
        direction TB
        Dockerfile["Dockerfile"]:::config
        Compose["docker-compose.yml"]:::config
        Req["requirements.txt"]:::config
        HAConf["ha-sensors.yaml"]:::config
        README["README.md"]:::config
        License["LICENSE"]:::config
    end

    %% Data Flow
    SI -->|"RS-232/PI30, PI41"| SP
    SP -->|"raw frames"| VP
    VP -->|"parsed data"| MA
    SD -->|"metadata"| MA
    MA -->|"payload"| MP
    MP -->|"JSON over MQTT"| Broker
    Broker -->|"MQTT subscriptions"| HA

    %% Container Relations
    Dockerfile -->|builds| SP
    Compose -->|orchestrates| SP
    Env -->|configures| SP

    %% Click Events
    click SP "https://github.com/lavron/docker-voltronic-mqtt/blob/main/src/serial_port.py"
    click VP "https://github.com/lavron/docker-voltronic-mqtt/blob/main/src/voltronic.py"
    click MP "https://github.com/lavron/docker-voltronic-mqtt/blob/main/src/mqtt.py"
    click SD "https://github.com/lavron/docker-voltronic-mqtt/blob/main/src/sensors.json"
    click MA "https://github.com/lavron/docker-voltronic-mqtt/blob/main/src/main.py"
    click Dockerfile "https://github.com/lavron/docker-voltronic-mqtt/tree/main/Dockerfile"
    click Compose "https://github.com/lavron/docker-voltronic-mqtt/blob/main/docker-compose.yml"
    click HAConf "https://github.com/lavron/docker-voltronic-mqtt/blob/main/ha-sensors.yaml"
    click Req "https://github.com/lavron/docker-voltronic-mqtt/blob/main/requirements.txt"
    click README "https://github.com/lavron/docker-voltronic-mqtt/blob/main/README.md"
    click License "https://github.com/lavron/docker-voltronic-mqtt/tree/main/LICENSE"

    %% Styles
    classDef containerModule fill:#AFFFAF,stroke:#333,stroke-width:1px
    classDef external fill:#FFDDDD,stroke:#333,stroke-width:1px
    classDef config fill:#FFFFAA,stroke:#333,stroke-width:1px
```
