victron-mqtt

What it is and what it does

victron_mqtt is an async Python client for Victron Energy's Venus OS devices, which are energy management controllers used in solar, battery, and inverter systems. It connects to the device's built-in MQTT broker, discovers all attached hardware (solar chargers, batteries, inverters, etc.), and exposes them as typed Python objects with live-updating metrics. You can read sensor values in real time via callbacks, write control commands back to the device (turning switches on/off, adjusting setpoints), and browse the device hierarchy.

The library is built on aiohttp and paho-mqtt for non-blocking async operation, making it suitable for integration into Home Assistant, custom dashboards, or monitoring applications. It handles metric typing, unit conversion, computed values (like GPS location from raw coordinates), and enum translation. The package includes a tkinter GUI for browsing devices and metrics during development, and supports multiple operation modes (full control, read-only, or experimental features).

Use it for:

• Monitor solar charger yield, battery state-of-charge, and inverter power in real time from a Home Assistant dashboard.
• Automate energy management by reading grid power and battery voltage, then writing control commands to switch loads or adjust charging setpoints.
• Build a custom web or mobile app that displays live metrics from a Victron system with typed, unit-aware values.
• Log historical energy data by subscribing to metric updates and writing them to a database or time-series store.
• Integrate Victron hardware into a larger IoT system by exposing metrics and controls via MQTT callbacks.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

An asynchronous Python library for communicating with Victron Energy Venus OS devices via MQTT, mapping MQTT topics to typed Python objects with live-updating metrics and writable controls.

Yes. The library is actively maintained, has no known vulnerabilities, installs with low friction, and is licensed permissively under MIT. It fills a clear gap for Python developers integrating Victron hardware into automation or monitoring systems. The async design and typed object model make it well-suited for production use. Start with the quick-start example and verify your Venus OS device is reachable on the network.

Install

victron-mqtt on PyPI

pip install victron-mqtt

uv add victron-mqtt

poetry add victron-mqtt

Installing victron-mqtt

Before you install

Low install friction with a pure-Python wheel. Active maintenance with a recent release (2026-08-14) and steady development since June 2025. Depends on aiohttp and paho-mqtt, both widely-used async/MQTT libraries.

License in practice

MIT license permits commercial and private use with minimal restrictions—you may use, modify, and distribute this library freely as long as you include the license notice.

Quickstart

pip install victron_mqtt

import asyncio
import victron_mqtt

async def main():
    hub = victron_mqtt.Hub("venus.local", 1883, None, None, False)
    await hub.connect()
    await hub.wait_for_first_refresh()
    for device in hub.devices.values():
        print(f"{device.name}: {device.device_type}")
    await hub.disconnect()

asyncio.run(main())

Requires Python 3.11 or later; a Victron Venus OS device (CCGX, Cerbo GX, or Ekrano GX) with MQTT broker running on the network.

Verify before relying

• Whether the library handles automatic reconnection and recovery from network interruptions.
• Performance characteristics when monitoring large numbers of devices or metrics simultaneously.
• Compatibility with non-standard MQTT broker configurations or authentication schemes beyond username/password.

Package facts

Evidence: victron_mqtt-2026.8.3-py3-none-any.whl

Keywords: mqtt, venus os, victron

Tags

More Monitoring packages