victron-esp32-ble-mqtt/README.md

6.9 KiB
Raw Blame History

Victron SmartSolar BLE to MQTT Bridge

An ESP32 firmware that reads a Victron SmartSolar MPPT charge controller via Bluetooth LE and publishes data to an MQTT broker, with full Home Assistant auto-discovery.

Built as a low-power replacement for a Raspberry Pi 4 running the Python victron-ble library — dropping idle power consumption from ~4W to ~0.15W.


Features

  • Reads Victron SmartSolar MPPT BLE advertisements
  • AES-128-CTR decryption matching the official Victron BLE protocol
  • Publishes JSON data to MQTT every 10 seconds
  • Full Home Assistant MQTT auto-discovery — device appears automatically with all entities grouped
  • LWT (Last Will and Testament) online/offline status
  • Dual-core FreeRTOS — BLE scanning on core 1, WiFi/MQTT on core 0, no coexistence crashes
  • Passive BLE scan — lower power draw

Hardware

  • ESP32 dev board (tested on ESP32 CH340 38-pin)
  • Within BLE range of your Victron SmartSolar MPPT (~10m)
  • WiFi network

Note: The ESP32-C3 Super Mini should also work but requires the BOOT button to be held during flashing — the CH340 classic ESP32 is easier to work with.


Getting Started

1. Clone the repo

git clone https://github.com/mrsossidge/victron-esp32-ble-mqtt.git
cd victron-esp32-ble-mqtt

2. Install VS Code + PlatformIO

  • Install VS Code
  • Install the PlatformIO IDE extension from the marketplace
  • Open the project folder — PlatformIO will detect platformio.ini and install dependencies automatically

3. Configure

Copy the example config and fill in your details:

cp include/example.config.h include/config.h

Edit include/config.h:

#define WIFI_SSID       "your_wifi_ssid"
#define WIFI_PASSWORD   "your_wifi_password"
#define MQTT_HOST       "192.168.1.x"        // your MQTT broker IP
#define VICTRON_MAC     "xx:xx:xx:xx:xx:xx"  // lowercase, colon-separated
#define VICTRON_ENC_KEY "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  // 32 hex chars

Finding your Victron MAC and encryption key

  1. Open the Victron Connect app
  2. Connect to your SmartSolar MPPT
  3. Tap the ⋮ menu → Product Info
  4. Scroll down to Instant readout via Bluetooth
  5. Tap SHOW — your encryption key is displayed there
  6. The MAC address is shown at the top of the Product Info page

4. Build and upload

  • Press Ctrl+Alt+B to build
  • Press Ctrl+Alt+U to upload
  • Open the serial monitor with Ctrl+Alt+S to verify it's running

MQTT Topics

Topic Description
solar/mppt/data JSON payload with all sensor values
solar/mppt/status online / offline (retained LWT)

Example payload

{
  "battery_voltage": "12.98",
  "battery_current": "-0.20",
  "pv_power": "8.0",
  "yield_today_wh": "350",
  "charge_state": "bulk",
  "charge_state_raw": 3,
  "error_code": 0
}

Charge states

Value State
0 Off
2 Fault
3 Bulk
4 Absorption
5 Float
7 Equalize
245 Starting
252 External control

Home Assistant

The device auto-discovers in Home Assistant via MQTT discovery. Once the ESP32 is running, go to:

Settings → Devices & Services → MQTT

You should see a Victron SmartSolar MPPT device with these entities:

  • Battery Voltage (V)
  • Battery Current (A)
  • PV Power (W)
  • Yield Today (Wh)
  • Charge State
  • Error Code

No manual YAML configuration required.


Power Consumption

Device Idle draw
Raspberry Pi 4 ~3–5W
ESP32 (this firmware) ~0.15W

Saving ~4W overnight adds up to ~40Wh per 10 hour night, or roughly 3–4Ah at 12V — meaningful for a solar battery system.


Project Structure

├── include/
│   ├── config.h          # Your config (excluded from git)
│   ├── example.config.h  # Template — copy to config.h
│   └── victron_ble.h     # BLE parser header
├── src/
│   ├── main.cpp          # Main firmware — WiFi, MQTT, BLE scanning
│   └── victron_ble.cpp   # AES decryption and MPPT data parser
└── platformio.ini        # PlatformIO build config

How it works

Victron SmartSolar MPPTs broadcast BLE advertisements every few seconds containing encrypted sensor data. The encryption uses AES-128-CTR with:

  • Key: your device's 32-character hex encryption key
  • IV: a 16-bit nonce from the advertisement, used as a 128-bit little-endian counter initial value

Once decrypted, the payload is a bit-packed structure read LSB-first — this implementation matches the victron-ble Python library exactly.

The ESP32 runs BLE scanning on core 1 and WiFi/MQTT on core 0 using FreeRTOS tasks, avoiding the radio coexistence issues that cause crashes when both run on the same core.


Dependencies

Managed automatically by PlatformIO:



Licence

MIT


Home Assistant Dashboard

A ready-made dashboard card is included in home-assistant/dashboard.yaml.

Requires these HACS frontend plugins:

To use: Dashboard → Edit → Add Card → Manual and paste the contents.

Template Sensors

Optional calculated sensors are in home-assistant/configuration_template.yaml:

  • Garage Net Battery Power — battery current × voltage in watts (positive = charging)
  • Garage Battery Status — Charging / Discharging / Idle text sensor

Add the template: block to your configuration.yaml and reload YAML.

Project Structure

├── home-assistant/
│   ├── dashboard.yaml               # Ready-made HA dashboard card
│   └── configuration_template.yaml  # Optional template sensors
├── include/
│   ├── config.h                     # Your config (excluded from git)
│   ├── example.config.h             # Template — copy to config.h
│   └── victron_ble.h                # BLE parser header
├── src/
│   ├── main.cpp                     # Main firmware
│   └── victron_ble.cpp              # AES decryption and parser
└── platformio.ini                   # PlatformIO build config