Victron VE.Direct HEX Protocol Python Library

A Python script for communicating with Victron VE.Direct devices (such as BlueSolar and SmartSolar MPPT charge controllers) using the HEX protocol via a UART (serial) connection. This implementation is based on the official documentation: BlueSolar-HEX-protocol.pdf (Rev 18). Tested with MPPT 100/50.

• Features
• Requirements
• Quick Start
• Supported Registers
• Technical Details
• Electrical Connection

• Construct Library: Utilizes the construct tool for declarative building and parsing of binary data frames.
• HEX Validation: Handles frame formatting, automatic checksum calculation, and response verification.
• Register Abstraction:
  • get_register(): Automatically handles decoding, scaling, and value mapping (e.g., 3 -> "Bulk").
  • set_register(): Safely writes values to the device with full error code handling.

Install the required dependencies using the pip package manager:

pip install pyserial construct

The library offers an extended class called vedirectDEV, which includes pre-built methods for the most common MPPT device parameters.

from vedirect import vedirectDEV

# Initialize the device (specify the correct serial port)
mppt = vedirectDEV("/dev/ttyAMA0", baudrate=19200, debug=False)

try:
    print(f"Model: {mppt.get_model_name()}")
    print(f"Charger Voltage: {mppt.get_charger_voltage()} V")
    print(f"Panel Power: {mppt.get_panel_power()} W")
    print(f"Current State: {mppt.get_device_state()}")
finally:
    mppt.disconnect()

# Turn on the Load Output
mppt.set_load_output_control("ON")

# Set External Control mode (for remote voltage/current control)
mppt.set_device_in_external_control_mode()

Below is a table of selected registers supported by the module:

The device verifies every frame for consistency. The sum of all binary bytes (command + data + checksum) modulo 256 must equal $0x55$

$$\left( \sum_{i=1}^{n} \text{byte}_i + \text{checksum} \right) \bmod 256 = 0x55$$

Image below shows electrical serial connection.

Tested with 3.3V UART on Raspberry Pi 5. MPPT 100/50 uses 5V UART therefore there is a need of Logic Level Converter 3,3V/5V. Tested with the cheapest one and works fine.

                                UART
┌────────────┐              ┌──────────┐                ┌────────────┐
│          3 │<-----TX ---->│          │<----- RX ----->│ 10         │
│ Victron  2 │<-----RX ---->│  LOGIC   │<----- TX ----->│ 8   RPI 5  │
│   DEV    4 │<---- 5V ---->│  Level   │<----- 3.3V---->│ 1   GPIO   │
│          1 │<--- GND ---->│converter │<----- GND  --->│ 6          │
│            │              │          │                │            │
└────────────┘              └──────────┘                └────────────┘