victron-mqtt 2025.12.16

Python library for communicating with Victron Venus OS MQTT interface

🌟 Supercharge Your Victron Devices with victron_mqtt!

---

🚀 Welcome to victron_mqtt!

Are you ready to unlock the full potential of your Victron devices? victron_mqtt is here to make your Venus OS experience smoother, faster, and way more fun! Whether you're a seasoned developer or just starting your journey, this library is your gateway to seamless communication with Victron's Venus OS devices like the CCGX, Cerbo GX, and Ekrano GX. This package is the backend for the Home Assistant Victron Venus MQTT custom integration.

If you just want to browse the Victron MQTT definitions, please go to the documentation page.
You can consume the Victron MQTT definitions here.

Disclaimer: This is a third-party library and is not affiliated with Victron Energy.

🌟 Features

• ⚡ Asynchronous Communication: Built for modern Python applications, ensuring non-blocking operations.
• 🔍 Device Metrics Viewer: A Tk-based viewer application to inspect metrics and devices.
• 🛠️ Utility Tools: Includes utilities like dump_mqtt for exploring the MQTT structure.
• 📈 Extensibility: Easily extendable to support additional metrics and configurations.
• 🧮 Formula support: New formula metric support (e.g. FormulaMetric and helper utilities) allows composing, evaluating, and exposing derived metrics calculated from raw MQTT values — useful for unit conversions, computed power/energy values, or combining multiple sensors into a single derived metric.

📦 Installation

Getting started is as easy as pie! Just run:

pip install victron_mqtt

🧑‍💻 Usage

🎨 Viewer Application

Want to see your Victron devices in action? Fire up the viewer application written in Tk:

python3 -m victron_mqtt.utils.view_metrics

This viewer is not just functional—it's a great example of how to use the library in your own projects.

🕵️‍♂️ Dump MQTT Structure

Curious about the full MQTT structure from your device? Dive deep with the dump_mqtt utility:

# Dumps a full MQTT structure into fullvictrondump.txt
python3 -m victron_mqtt.utils.dump_mqtt > fullvictrondump.txt

# Command-line help for specifying connection details:
python3 -m victron_mqtt.utils.dump_mqtt --help

Help Needed!!

Please help with extending the library with more topics. See instructions here for how to contribute.

🐞 Logging Issues

Found a bug or need help? We're here for you! Log issues on GitHub.

To help us support your setup, you can attach the output of the dump_mqtt utility to your issue.

📜 License

victron_mqtt is distributed under the terms of the MIT license.

Acknowledgments

• Thanks to Johan du Plessis [e-mail] who started the original library this one is based on. It is not clear if the original library is still maintained, so I forked it and continue to make progress with it.
• Thanks to Victron Energy for their excellent hardware and documentation