victron-ble2mqtt 0.7.7

Emit MQTT events from victron-ble

victron_ble2mqtt

Emit MQTT events from Victron Energy Smart Devices via victron-ble

Tested with:

• Solar Charger: SmartSolar MPPT 100/20
• Smart Battery Shunt
• Raspberry Pi Zero 2 W with Raspberry Pi OS Lite
• Mosquitto MQTT Broker
• Home Assistant MQTT integration

Scrrenshot from Home Assistant:

More screenshots here: https://github.com/jedie/jedie.github.io/blob/master/screenshots/victron-ble2mqtt/README.md

Usage

preperation

victron_ble used Bleak and the Linux backend of Bleak communicates with BlueZ over DBus. So you have to install this, e.g.:

~$ sudo apt install bluez

Bootstrap

Clone the sources and just call the CLI to create a Python Virtualenv, e.g.:

~$ git clone https://github.com/jedie/victron-ble2mqtt.git
~$ cd victron-ble2mqtt
~/victron-ble2mqtt$ ./cli.py --help

app CLI

usage: ./cli.py [-h] {debug-read,discover,edit-settings,print-settings,publish-loop,shell-completion,systemd-debug,systemd-logs,systemd-remove,systemd-setup,systemd-status,systemd-stop,update-readme-history,version}



╭─ options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ -h, --help        show this help message and exit                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                                                           │
│   • debug-read    Read data from devices and print them. Device keys are used from config file, if not given.        │
│   • discover      Discover Victron devices with Instant Readout                                                      │
│   • edit-settings                                                                                                    │
│                   Edit the settings file. On first call: Create the default one.                                     │
│   • print-settings                                                                                                   │
│                   Display (anonymized) MQTT server username and password                                             │
│   • publish-loop  Publish MQTT messages in endless loop (Entrypoint from systemd)                                    │
│   • shell-completion                                                                                                 │
│                   Setup shell completion for this CLI (Currently only for bash shell)                                │
│   • systemd-debug                                                                                                    │
│                   Print Systemd service template + context + rendered file content.                                  │
│   • systemd-logs  Display the systemd logs for this service. (May need sudo)                                         │
│   • systemd-remove                                                                                                   │
│                   Remove Systemd service file. (May need sudo)                                                       │
│   • systemd-setup                                                                                                    │
│                   Write Systemd service file, enable it and (re-)start the service. (May need sudo)                  │
│   • systemd-status                                                                                                   │
│                   Display status of systemd service. (May need sudo)                                                 │
│   • systemd-stop  Stops the systemd service. (May need sudo)                                                         │
│   • update-readme-history                                                                                            │
│                   Update project history base on git commits/tags in README.md Will be exited with 1 if the          │
│                   README.md was updated otherwise with 0.                                                            │
│                                                                                                                      │
│                   Also, callable via e.g.:                                                                           │
│                       python -m cli_base update-readme-history -v                                                    │
│   • version       Print version and exit                                                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

dev CLI

usage: ./dev-cli.py [-h] {coverage,install,lint,mypy,nox,pip-audit,publish,shell-completion,test,update,update-readme-history,update-test-snapshot-files,version}



╭─ options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ -h, --help     show this help message and exit                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                                                           │
│   • coverage   Run tests and show coverage report.                                                                   │
│   • install    Install requirements and 'victron_ble2mqtt' via pip as editable.                                      │
│   • lint       Check/fix code style by run: "ruff check --fix"                                                       │
│   • mypy       Run Mypy (configured in pyproject.toml)                                                               │
│   • nox        Run nox                                                                                               │
│   • pip-audit  Run pip-audit check against current requirements files                                                │
│   • publish    Build and upload this project to PyPi                                                                 │
│   • shell-completion                                                                                                 │
│                Setup shell completion for this CLI (Currently only for bash shell)                                   │
│   • test       Run unittests                                                                                         │
│   • update     Update dependencies (uv.lock) and git pre-commit hooks                                                │
│   • update-readme-history                                                                                            │
│                Update project history base on git commits/tags in README.md Will be exited with 1 if the README.md   │
│                was updated otherwise with 0.                                                                         │
│                                                                                                                      │
│                Also, callable via e.g.:                                                                              │
│                    python -m cli_base update-readme-history -v                                                       │
│   • update-test-snapshot-files                                                                                       │
│                Update all test snapshot files (by remove and recreate all snapshot files)                            │
│   • version    Print version and exit                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Setup Device

Detect your device first, e.g.:

~/victron-ble2mqtt$ ./cli.py discover
...
{
    'name': 'SmartSolar HQ2248AM79D',
    'address': 'E7:37:97:XX:XX:XX',
    'details': {
        'path': '/org/bluez/hci0/dev_E7_37_97_XX_XX_XX',
        'props': {
            'Address': 'E7:37:97:XX:XX:XX',
            'AddressType': 'random',
            'Name': 'SmartSolar HQ2248AM79D',
            'Alias': 'SmartSolar HQ2248AM79D',
            'Paired': False,
            'Trusted': False,
            'Blocked': False,
            'LegacyPairing': False,
            'RSSI': -89,
            'Connected': False,
            'UUIDs': [],
            'Adapter': '/org/bluez/hci0',
            'ManufacturerData': {737: bytearray(b'...')},
            'ServicesResolved': False
        }
    }
}
...
(Hit Ctrl-C to abort)

Device Keys

You need the device keys of all Victron Energy Smart Devices you want to monitor.

The easiest way to get the keys: Install the official Victron Smartphone App and copy&paste the keys:

• Click on your device
• Go to detail page about the SmartSolar Bluetooth Interface
• Click on SHOW at Instant readout via Bluetooth / Encryption data
• Copy the Connectionkey by click on the key

(I send the key via Signal as "my note" and use the Desktop Signal app to receive the key on my Computer)

See also: https://community.victronenergy.com/questions/187303/victron-bluetooth-advertising-protocol.html

setting

Just call edit-settings command, e.g.:

~/victron-ble2mqtt$ ./cli.py edit-settings

At least insert your MQTT settings and all devices keys.

Test

Start publish MQTT endless look, just call publish-loop command, e.g.:

~/victron-ble2mqtt$ ./cli.py publish-loop -vv

setup systemd services

Check systemd setup:

~/victron-ble2mqtt$ ./cli.py systemd-debug

Setup services:

~/victron-ble2mqtt$ ./cli.py systemd-setup

After this the MQTT publising runs and will be started on boot.

Check the services:

~/victron-ble2mqtt$ ./cli.py systemd-status

start development

At least uv is needed. Install e.g.: via pipx:

apt-get install pipx
pipx install uv

Clone the project and just start the CLI help commands. A virtual environment will be created/updated automatically.

~$ git clone https://github.com/jedie/victron-ble2mqtt.git
~$ cd victron-ble2mqtt
~/victron-ble2mqtt$ ./cli.py --help
~/victron-ble2mqtt$ ./dev-cli.py --help

Backwards-incompatible changes

0.4.0

You must edit your settings:

• device_address (The Device MAC address) was removed
• device_key is replaced by device_keys a list of device keys

Just insert the keys of all Victron Energy Smart Devices you want to monitor.

History

• v0.7.7
  • 2026-03-14 - Fix #51 API changes in victron-ble v0.9.3
• v0.7.6
  • 2026-03-14 - Don't install dev dependencies by cli.py
• v0.7.5
  • 2026-03-14 - Apply code style changes
  • 2026-03-14 - Update requirements
• v0.7.4
  • 2026-02-08 - Apply manageproject updates: Set min. Python to v3.12

Expand older history entries ...

• v0.7.3
  • 2025-12-09 - update README
  • 2025-12-09 - Apply manageprojects update
  • 2025-12-09 - Update requirements
  • 2025-10-15 - Revert debugging
  • 2025-10-15 - Add support for temperature for shunt
  • 2025-09-25 - Fix SolarChargerHandler "yield_today" sensor
  • 2025-09-25 - Tweak 'Consumed Ah' because "Ah" is not supported in HA.
• v0.7.2
  • 2025-09-24 - remove obsolete .flake8 config + add/update PyCharm run configs
  • 2025-09-24 - Remaining Minutes: set device_class='duration'
  • 2025-09-24 - cleanup
  • 2025-09-24 - Apply manageproject updates + update requirements
  • 2025-09-24 - Update sensor units to those supported by the device class
• v0.7.1
  • 2025-09-13 - fix wrong links in README
  • 2025-09-13 - Add PyCharm run config files
  • 2025-09-13 - Apply manageprojects updates
  • 2025-08-19 - Bugfix "consumed_ah" sensor: "electricity" -> "energy"
• v0.7.0
  • 2025-08-19 - NEW: "./cli.py systemd-logs"
  • 2025-08-19 - Add new setting: publish_throttle_seconds for #31
  • 2025-08-19 - Update requirements
  • 2025-06-17 - Limit sensor values
• v0.6.0
  • 2025-04-08 - Remove own Wifi info stuff
• v0.5.1
  • 2025-04-08 - pip-tools -> uv
• v0.5.0
  • 2024-09-25 - NEW: Midpoint Shift (absolut + percent) in BatteryMonitor
• v0.4.1
  • 2024-09-24 - Bugfix delay data: Never, never use time.sleep() in a async context
• v0.4.0
  • 2024-09-24 - Update README.md
  • 2024-09-22 - Use device keys and refactor MQTT sensors: Support BatteryMonitor
  • 2024-09-22 - Bugfix Pi installation
  • 2024-09-22 - Move pip-compile switches into pyproject.toml
  • 2024-09-22 - Update requirements
• v0.3.0
  • 2024-09-20 - bugfix publish
  • 2024-09-20 - Add help pages into README
  • 2024-04-16 - Update to new ha-services version and update project setup
  • 2024-03-23 - Update README.md
  • 2024-03-10 - Disable verbose print as default
  • 2024-03-10 - Expose WiFi quality values to MQTT
• v0.1.0
  • 2024-03-09 - Remove 3.9 from test matrix
  • 2024-03-09 - requires-python = ">=3.10"
  • 2024-03-09 - Update README.md
  • 2024-03-09 - Add Hostname + sys load to MQTT
  • 2024-03-09 - Add info about systemd to README
  • 2024-03-09 - Remove deprecation warning about RSSI
  • 2024-03-09 - Bugfix systemd "exec_start" value
  • 2024-03-09 - Add systemd commands
  • 2024-03-09 - Publish value to MQTT
  • 2024-03-09 - Add user settings and "debug-read" CLI command
  • 2024-03-09 - Add "discover" to app CLI
  • 2024-03-08 - More info in README
  • 2024-03-08 - Add "victron-ble" and "ha-services"
  • 2024-03-08 - Init from https://github.com/jedie/cookiecutter_templates