victron-venus
02 · Architecture
How the system fits together
Venus OS models devices on its local D-Bus. Bridges and companion applications use MQTT, HTTP or WebSockets according to their own integration contracts. The repository map is not a live deployment inventory.
The five layers
1 · Hardware & sensing
ESP32s, Tasmota plugs, CT clamps, Emporia Vue submeters, EV chargers and water tanks/pumps provide readings through firmware or configured Home Assistant entities. esphome-jbd-bms-mqttdbus-esphome-grid-sensordbus-evdbus-pump
2 · D-Bus services
Translators running on the GX: MQTT→D-Bus for the audited battery and Tasmota PV bridges, and Home Assistant→D-Bus for Emporia, EV, charger and pump measurements. Third-party hardware appears as Victron device services. dbus-mqtt-batterydbus-tasmota-pvdbus-emporia-vue
3 · Control & policy
inverter-control calculates setpoints and applies its configured validity, limit and watchdog policies before D-Bus writes. It consumes EV data published by the Home Assistant bridges. The archived venus-os-governance project does not gate this deployed path, and no dbus-event-log service was running on the audited GX. These repositories must not be treated as an installed authorization or audit layer. inverter-controlvenus-os-governancedbus-event-logdbus-ev
4 · MQTT distribution
State leaves the GX over MQTT topics. fastapi-mqtt-gateway adds REST/WebSocket access for clients that can't speak MQTT natively. fastapi-mqtt-gateway
5 · Consumption
Dashboards (Go binary on-GX, Python/Docker, Vue SPA, Tauri desktop), Home Assistant, observability stacks and optional forecasting tools. Verify each configured caller before assuming forecasts affect controller decisions. inverter-dashboard-gosolar-forecast-langgraphvenus-os-observabilityinverter-monitoring
Thermostat integration
inverter-climate spans the D-Bus and control layers. A native supervised service on Venus OS reads local system energy, publishes room temperature, and exchanges thermostat state and commands with Home Assistant. HA owns the existing Google Nest connection and authentication.
The stock GUI v2 Switch pane and VRM Remote Console can show its optional temperature slider and Heat/Off selector through the Switchable Output API on the same temperature device. Observation is the default; manual controls and automatic preheating are enabled separately. HA requests run outside the D-Bus loop and the separate ESS controller.
The native path needs no companion gateway or GUI patch, while Nest still relies on HA and its cloud integration. For a gas furnace, the configured heating-power estimate describes electrical demand; it does not measure heat or gas and is not published as another AC load. See the installation and control guide.
Why two buses instead of one
D-Bus is how Venus OS models batteries, PV inverters and grid meters as
com.victronenergy.* services. The ESS controller reads and writes that local bus.
Companion dashboards, Home Assistant, Grafana and forecasters use MQTT, HTTP or WebSockets according to their integration contracts. Thermostat commands from inverter-climate reach Home Assistant over its REST API, while the GX-facing temperature device and GUI controls use D-Bus. Validate freshness and command acknowledgements at each boundary.
Control path vs telemetry path
| Control path (amber) | Telemetry path (cyan) | |
|---|---|---|
| Protocol | D-Bus for ESS; HA REST for thermostats | MQTT / REST / WebSocket |
| Writers | Configured controller and native Venus services | Per-service publishers and gateways |
| Audit | Verify actual logging; event-log is an optional integration | Configured metrics and logs |
| Timing | ESS cadence and D-Bus latency; HA/cloud latency and observed confirmation for thermostats | Source-specific freshness limits |
| Failure mode | ESS validity, hold and watchdog policy; thermostat availability and journaled uncertain outcomes | Mark unavailable inputs; stale telemetry can affect control |
Cross-cutting concerns
- Forecasting: optional forecast consumers need a configured, tested control contract; repository availability alone does not close a control loop.
- AI access: mcp-venus-os provides its own validation and write-confirmation rules. Verify its deployment and transport separately from the controller.
- EV data path: dbus-ev publishes vehicle telemetry from Mercedes or Home Assistant and can own the Mercedes charger service. The standalone charger repository is archived. Follow the migration guide, retain a single charger owner, and preserve unavailable-value handling during source outages.
- Testing: broker and simulated D-Bus integration tests complement installer checks and device observation. Firmware compatibility and cold-boot recovery need target-device validation.