victron-ble

This project follows a modular Python project structure designed for simplicity and low dependency. Key components include:

• victron_ble/: The main Python package containing the core logic.
• victron_ble/VERSION: A static text file containing the project version.
• setup.py: Used for installation and packaging via Setuptools.
• requirements.txt: Holds project dependencies (initially empty in this template).
• requirements-test.txt: Contains dependencies required for development and testing.
• tests/: Directory for unit tests, including conftest.py for pytest fixtures.
• Makefile: A collection of utility commands to manage the project.
• Containerfile: Used to build a container image via buildah or docker.
• docs/: Documentation source files.

On macOS, the VictronConnect app uses Bluetooth UUIDs instead of MAC addresses. You can extract the UUID and advertisement key directly from the app's local SQLite database using the following command (requires sqlite3 installed via Homebrew):

sqlite3 ~/Library/Containers/com.victronenergy.victronconnect.mac/Data/Library/Application\ Support/Victron\ Energy/Victron\ Connect/d25b6546b47ebb21a04ff86a2c4fbb76.sqlite 'select address,advertisementKey from advertisementKeys inner join macAddresses on advertisementKeys.macAddress == macAddresses.macAddress'

To decrypt advertisement data, you must obtain the per-device encryption key and the MAC address (or UUID on macOS) from the official VictronConnect app:

1. Install and pair with your device in the VictronConnect app.
2. Go to Settings (gear icon) for the device.
3. Select Product Info.
4. Ensure Instant Readout via Bluetooth is enabled.
5. Click Show next to Instant Readout Details.
6. Copy the MAC address and the advertisement key.

Install the library using pip to begin parsing Victron Instant Readout advertisement data.

pip install victron_ble

While the project defaults to setup.py and setuptools for simplicity and compatibility with direct Git installations (e.g., pip install https://github.com/...), you can switch to the Poetry package manager by running the following command:

make switch-to-poetry

If you want to add specific framework support (like Flask, FastAPI, Click, or Typer) to the project, use the make init command. This will prompt you to choose a template and then download and apply it to your project structure.

$ make init
Which template do you want to apply? [flask, fastapi, click, typer]? > flask
Generating a new project with Flask ...

You can integrate the library into your own Python code by using detect_device_type to identify the correct parser for a given advertisement payload, then calling that parser with the device's encryption key.

from victron_ble.devices import detect_device_type

data = <ble advertisement data>
parser = detect_device_type(data)
parsed_data = parser(<key>).parse(<ble advertisement data>)

When reading from a Smart Battery Sense device, the output is a JSON object containing temperature and voltage readings.

{
  "temperature": 29.565,
  "voltage": 12.22
}

When reading from a SmartShunt device, the output is a JSON object containing battery metrics.

Note that the aux_mode field determines if additional properties are present in the output:

• 0: Includes starter_voltage
• 1: Includes midpoint_voltage
• 2: Includes temperature
• 3: No additional properties (Disabled)

{
  "aux_mode": "temperature",
  "consumed_ah": 0.0,
  "current": 0.0,
  "high_starter_battery_voltage_alarm": false,
  "high_temperature_alarm": false,
  "high_voltage_alarm": false,
  "low_soc_alarm": false,
  "low_starter_battery_voltage_alarm": false,
  "low_temperature_alarm": false,
  "low_voltage_alarm": false,
  "midpoint_deviation_alarm": false,
  "remaining_mins": 65535,
  "soc": 100.0,
  "temperature": 382.2,
  "voltage": 12.5
}

The project provides a standalone CLI for interacting with Victron devices.

Discover devices

List all discovered Victron devices with Instant Readout enabled, showing their names and IDs:

victron-ble discover

Read decrypted data

To parse and print data for a specific device, use the read command with the format ID@KEY:

victron-ble read "<DEVICE_ID>@<ADVERTISEMENT_KEY>"

Dump raw advertisements

To collect raw advertisement data for debugging or supporting new devices, use the dump command with the device ID:

victron-ble dump <DEVICE_ID>

# Discover devices
victron-ble discover

# Read data (replace ID and key)
victron-ble read "763aeff5-1334-e64a-ab30-a0f478s20fe1@0df4d0395b7d1a876c0c33ecb9e70dcd"

# Dump raw data for debugging
victron-ble dump "763aeff5-1334-e64a-ab30-a0f478s20fe1"

Use the victron-ble read command to parse and display data from specific Victron devices using their keys. You can provide one or more DEVICE_KEYS as positional arguments.

victron-ble read [DEVICE_KEYS]...