evse-hub 0.7.1
Solar monitoring and control daemons
Requires Python: >=3.11

# evse-hub

Solar monitoring and control daemons for Modbus-based EVSE (Electric Vehicle Supply Equipment) and energy monitoring, including polling, status tracking, MQTT integration, and InfluxDB data persistence.

## Structure

```
evse_hub/
├── cli/
│   ├── evse_online.py
│   ├── evse_poll.py
│   ├── evse_scan.py
│   ├── mqtt_power_logger.py
│   ├── runtime.py
│   ├── status.py
│   └── supervisor.py
├── influx/
│   ├── influx_client.py
│   └── influx_writes.py
├── modbus/
│   ├── etrel/
│   │   ├── etrel.py
│   │   ├── modbus_reads.py
│   │   └── modbus_writes.py
│   └── modbus_device.py
├── mqtt/
│   ├── interface.py
│   └── parsers.py
├── ops/
│   └── heartbeat.py
└── tools/
    ├── async_tools.py
    ├── config.py
    ├── device_config.py
    └── wifi.py
```

## Main Components

### CLI Tools (`evse_hub/cli/`)

- **evse_online.py**: Service for tracking online status of EVSE endpoints and writing status to JSON.
- **evse_poll.py**: Polls Modbus devices for master/charger data and writes to InfluxDB.
- **evse_scan.py**: Scans a network for Modbus TCP devices.
- **mqtt_power_logger.py**: Async MQTT power logger with InfluxDB integration for monitoring power data from MQTT topics.
- **runtime.py**: Defines `EndpointRuntime`, which holds runtime state for a Modbus endpoint.
- **status.py**: Defines `StatusSnapshot` and utilities for loading endpoint status from JSON.
- **supervisor.py**: Orchestrates polling tasks for all endpoints, starting/stopping them based on online status.

### Modbus Support (`evse_hub/modbus/`)

- **modbus_device.py**: Abstraction for Modbus TCP client connections and polling.
- **etrel/modbus_reads.py**: Functions for reading Etrel-specific Modbus registers.
- **etrel/modbus_writes.py**: Functions for writing to Etrel Modbus registers.

### MQTT Support (`evse_hub/mqtt/`)

- **interface.py**: MQTT configuration dataclasses and topic state tracking for power monitoring.
- **parsers.py**: Message parsers for different MQTT formats (Frient impulse loggers, Shelly Pro 3EM three-phase power).

### InfluxDB Integration (`evse_hub/influx/`)

- **influx_client.py**: Singleton InfluxDB client manager with connection pooling for persistent database connections.
- **influx_writes.py**: Functions for writing EVSE and master data to InfluxDB.

### Utilities (`evse_hub/tools/`)

- **async_tools.py**: Async helpers for running blocking code.
- **config.py**: Configuration loading utilities.
- **device_config.py**: Endpoint configuration dataclasses and YAML loading.
- **wifi.py**: WiFi-related utilities.

## Example: Polling and Supervising Endpoints

- Use `evse_online.py` to maintain a status file of which endpoints are online.
- Use `supervisor.py` to start/stop polling tasks for each endpoint based on their online status.
- Polled data is written to InfluxDB using the routines in `influx_writes.py`.

## Key Classes

- `EndpointRuntime`: Holds runtime state for a single Modbus endpoint (config, client, locks, task, etc).
- `StatusSnapshot`: Immutable snapshot of endpoint online status at a given timestamp.

## Key Functions

- `poll_endpoint`: Polls a single endpoint for its configured roles.
- `supervisor`: Orchestrates the lifecycle of all endpoint runtime objects and manages their polling tasks.

---

This README is auto-generated from the code and docstrings in `src/evse_hub/`. For details on each module, see the source files and their docstrings.