docs: rewrite README in house style with support link

This commit is contained in:
MrSossidge 2026-09-14 21:41:40 +01:00
parent 55496cf613
commit 9f459f0d97
1 changed files with 134 additions and 129 deletions

263
README.md
View File

@ -1,58 +1,111 @@
# Victron SmartSolar BLE to MQTT Bridge <div align="center">
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**. # 🔋 Victron SmartSolar BLE → MQTT
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. **"A Raspberry Pi 4 drawing 4W to read one MPPT is an absurd tax on a solar battery."**
ESP32 firmware that reads a **Victron SmartSolar MPPT** over Bluetooth LE, decrypts the
advertisement, and publishes it to MQTT with full Home Assistant auto-discovery — at
**~0.15W** instead of ~4W.
[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](#licence)
[![Board](https://img.shields.io/badge/board-ESP32%20CH340-e7352c.svg)](#hardware)
[![Built with](https://img.shields.io/badge/built%20with-PlatformIO-f5822a.svg?logo=platformio&logoColor=white)](#4-build-and-upload)
[![Crypto](https://img.shields.io/badge/crypto-AES--128--CTR-6f42c1.svg)](#how-it-fits-together)
[![MQTT](https://img.shields.io/badge/MQTT-auto--discovery-660066.svg?logo=mqtt&logoColor=white)](#mqtt-topics)
[![Home Assistant](https://img.shields.io/badge/Home%20Assistant-zero%20YAML-41bdf5.svg?logo=homeassistant&logoColor=white)](#home-assistant)
[![Idle draw](https://img.shields.io/badge/idle%20draw-~0.15W-brightgreen.svg)](#power-consumption)
[![Buy me a coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-ffdd00?logo=buymeacoffee&logoColor=black)](https://www.buymeacoffee.com/MrSossidge)
</div>
--- ---
## Features ## The problem
- Reads Victron SmartSolar MPPT BLE advertisements Victron's `victron-ble` Python library is excellent, and running it on a Raspberry Pi 4 works
- AES-128-CTR decryption matching the official Victron BLE protocol perfectly — until you notice the Pi is idling at 3–5W purely to relay a few numbers off a
- Publishes JSON data to MQTT every 10 seconds charge controller. On an off-grid system that's around **40Wh a night**, or 3–4Ah at 12V:
- Full Home Assistant MQTT auto-discovery — device appears automatically with all entities grouped the monitoring was costing more than the thing it was monitoring.
- LWT (Last Will and Testament) online/offline status
- Dual-core FreeRTOS — BLE scanning on core 1, WiFi/MQTT on core 0, no coexistence crashes This firmware does the same job on an ESP32 at roughly a fortieth of the power, and behaves
- Passive BLE scan — lower power draw better in Home Assistant while it's there.
## What you get
| | |
|---|---|
| 📶 **Reads the advertisement** | Passive BLE scan of the SmartSolar MPPT's broadcasts — no pairing, no connection, lower draw. |
| 🔐 **Real decryption** | AES-128-CTR exactly as the Victron BLE protocol specifies, matching the reference Python implementation bit for bit. |
| 📡 **MQTT every 10s** | One JSON payload with every value, plus a retained online/offline LWT topic. |
| 🏠 **Auto-discovery** | Appears in Home Assistant as a **Victron SmartSolar MPPT** device with entities grouped. No YAML. |
| 🧵 **Two cores, no crashes** | BLE scanning pinned to core 1, WiFi/MQTT to core 0 via FreeRTOS — sidesteps the radio coexistence crashes that come from sharing a core. |
| 🔌 **External load too** | The MPPT's load output current is published as amps, and multiplied by battery voltage to give watts — so the dashboard shows draw as well as charge. |
| 📊 **Dashboard included** | A ready-made Mushroom + Mini Graph dashboard card and optional template sensors. |
| 🪫 **0.15W idle** | The entire point. |
## How it fits together
```mermaid
flowchart LR
mppt["☀️ Victron SmartSolar MPPT<br/><i>BLE advertisement, encrypted</i>"]
subgraph esp["⚡ ESP32 · dual core"]
core1["Core 1 · NimBLE<br/><i>passive scan</i>"]
dec["victron_ble.cpp<br/><i>AES-128-CTR + bit unpack</i>"]
core0["Core 0 · WiFi + MQTT<br/><i>PubSubClient</i>"]
core1 --> dec --> core0
end
broker["Mosquitto<br/><i>solar/mppt/#</i>"]
ha["Home Assistant<br/><i>auto-discovered</i>"]
mppt -.->|"~every few seconds"| core1
core0 -->|"every 10s"| broker --> ha
style core1 fill:#e7352c,stroke:#e7352c,color:#fff
style dec fill:#6f42c1,stroke:#6f42c1,color:#fff
style core0 fill:#334155,stroke:#334155,color:#fff
style broker fill:#660066,stroke:#660066,color:#fff
style ha fill:#41bdf5,stroke:#41bdf5,color:#fff
```
SmartSolar MPPTs broadcast encrypted BLE advertisements every few seconds. Decryption uses
AES-128-CTR with your device's 32-character hex key, and a 16-bit nonce from the
advertisement used as the little-endian initial value of a 128-bit counter. The plaintext is
a bit-packed structure read LSB-first.
--- ---
## Hardware ## Hardware
- ESP32 dev board (tested on ESP32 CH340 38-pin) - An ESP32 dev board — tested on the **ESP32 CH340 38-pin**
- Within BLE range of your Victron SmartSolar MPPT (~10m) - Within BLE range of the SmartSolar MPPT (~10m)
- WiFi network - A 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. > The ESP32-C3 SuperMini also works, but needs the BOOT button held during flashing. The
> classic CH340 board is the easier one to live with.
--- ## Quick start
## Getting Started ### 1. Clone
### 1. Clone the repo
```bash ```bash
git clone https://github.com/mrsossidge/victron-esp32-ble-mqtt.git git clone https://github.com/MrSossidge/victron-esp32-ble-mqtt.git
cd victron-esp32-ble-mqtt cd victron-esp32-ble-mqtt
``` ```
### 2. Install VS Code + PlatformIO ### 2. Install VS Code + PlatformIO
- Install [VS Code](https://code.visualstudio.com) Install [VS Code](https://code.visualstudio.com) and the **PlatformIO IDE** extension, then
- Install the **PlatformIO IDE** extension from the marketplace open the project folder — PlatformIO reads `platformio.ini` and pulls dependencies itself.
- Open the project folder — PlatformIO will detect `platformio.ini` and install dependencies automatically
### 3. Configure ### 3. Configure
Copy the example config and fill in your details:
```bash ```bash
cp include/example.config.h include/config.h cp include/example.config.h include/config.h
``` ```
Edit `include/config.h`:
```cpp ```cpp
#define WIFI_SSID "your_wifi_ssid" #define WIFI_SSID "your_wifi_ssid"
#define WIFI_PASSWORD "your_wifi_password" #define WIFI_PASSWORD "your_wifi_password"
@ -61,32 +114,35 @@ Edit `include/config.h`:
#define VICTRON_ENC_KEY "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" // 32 hex chars #define VICTRON_ENC_KEY "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" // 32 hex chars
``` ```
#### Finding your Victron MAC and encryption key `config.h` is gitignored — your key does not end up in a commit.
<details>
<summary><b>Finding your MAC address and encryption key</b></summary>
1. Open the **Victron Connect** app 1. Open the **Victron Connect** app
2. Connect to your SmartSolar MPPT 2. Connect to your SmartSolar MPPT
3. Tap the **⋮ menu** → **Product Info** 3. Tap the **⋮ menu** → **Product Info**
4. Scroll down to **Instant readout via Bluetooth** 4. The MAC address is at the top of that page
5. Tap **SHOW** — your encryption key is displayed there 5. Scroll to **Instant readout via Bluetooth** and tap **SHOW** for the encryption key
6. The MAC address is shown at the top of the Product Info page </details>
### 4. Build and upload ### 4. Build and upload
- Press `Ctrl+Alt+B` to build | Action | Shortcut |
- Press `Ctrl+Alt+U` to upload |---|---|
- Open the serial monitor with `Ctrl+Alt+S` to verify it's running | Build | `Ctrl+Alt+B` |
| Upload | `Ctrl+Alt+U` |
| Serial monitor | `Ctrl+Alt+S` |
--- ---
## MQTT Topics ## MQTT topics
| Topic | Description | | Topic | Description |
|---|---| |---|---|
| `solar/mppt/data` | JSON payload with all sensor values | | `solar/mppt/data` | JSON payload with all sensor values |
| `solar/mppt/status` | `online` / `offline` (retained LWT) | | `solar/mppt/status` | `online` / `offline` (retained LWT) |
### Example payload
```json ```json
{ {
"battery_voltage": "12.98", "battery_voltage": "12.98",
@ -95,11 +151,14 @@ Edit `include/config.h`:
"yield_today_wh": "350", "yield_today_wh": "350",
"charge_state": "bulk", "charge_state": "bulk",
"charge_state_raw": 3, "charge_state_raw": 3,
"error_code": 0 "error_code": 0,
"external_load_a": "0.35",
"external_load_w": "4.5"
} }
``` ```
### Charge states <details>
<summary><b>Charge state values</b></summary>
| Value | State | | Value | State |
|---|---| |---|---|
@ -111,124 +170,70 @@ Edit `include/config.h`:
| 7 | Equalize | | 7 | Equalize |
| 245 | Starting | | 245 | Starting |
| 252 | External control | | 252 | External control |
</details>
---
## Home Assistant ## Home Assistant
The device auto-discovers in Home Assistant via MQTT discovery. Once the ESP32 is running, go to: Once the ESP32 is running, go to **Settings → Devices & Services → MQTT**. A **Victron
SmartSolar MPPT** device appears with Battery Voltage (V), Battery Current (A), PV Power (W),
Yield Today (Wh), Charge State, Error Code, External Load (A) and External Load Power (W). No
manual YAML.
**Settings → Devices & Services → MQTT** **Dashboard card** — [`dashboard.yaml`](dashboard.yaml) is ready to paste into
**Dashboard → Edit → Add Card → Manual**. It needs two HACS frontend plugins:
[Mushroom](https://github.com/piitaya/lovelace-mushroom) and
[Mini Graph Card](https://github.com/kalkih/mini-graph-card).
You should see a **Victron SmartSolar MPPT** device with these entities: **Template sensors** — [`configuration_template.yaml`](configuration_template.yaml) adds two
optional calculated sensors: **Garage Net Battery Power** (current × voltage in watts,
positive = charging) and **Garage Battery Status** (Charging / Discharging / Idle). Add the
`template:` block to your `configuration.yaml` and reload YAML.
- Battery Voltage (V) ## Power consumption
- Battery Current (A)
- PV Power (W)
- Yield Today (Wh)
- Charge State
- Error Code
No manual YAML configuration required.
---
## Power Consumption
| Device | Idle draw | | Device | Idle draw |
|---|---| |---|---|
| Raspberry Pi 4 | ~3–5W | | Raspberry Pi 4 | ~3–5 W |
| ESP32 (this firmware) | ~0.15W | | ESP32 (this firmware) | ~0.15 W |
Saving ~4W overnight adds up to ~40Wh per 10 hour night, or roughly 3–4Ah at 12V — meaningful for a solar battery system. ~4W saved overnight is ~40Wh per 10-hour night — roughly 3–4Ah at 12V, which is a real
fraction of a small leisure battery.
--- ## Layout
## Project Structure
``` ```
├── include/ ├── include/
│ ├── config.h # Your config (excluded from git) │ ├── example.config.h template — copy to config.h
│ ├── example.config.h # Template — copy to config.h │ └── victron_ble.h BLE parser header
│ └── victron_ble.h # BLE parser header
├── src/ ├── src/
│ ├── main.cpp # Main firmware — WiFi, MQTT, BLE scanning │ ├── main.cpp WiFi, MQTT, BLE scanning, FreeRTOS tasks
│ └── victron_ble.cpp # AES decryption and MPPT data parser │ └── victron_ble.cpp AES decryption and MPPT data parser
└── platformio.ini # PlatformIO build config ├── dashboard.yaml ready-made Home Assistant dashboard card
├── configuration_template.yaml optional template sensors
└── platformio.ini 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](https://github.com/keshavdv/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 ## Dependencies
Managed automatically by PlatformIO: PlatformIO handles all of these:
- [NimBLE-Arduino](https://github.com/h2zero/NimBLE-Arduino) — lightweight BLE stack - [NimBLE-Arduino](https://github.com/h2zero/NimBLE-Arduino) — lightweight BLE stack
- [PubSubClient](https://github.com/knolleary/pubsubclient) — MQTT client - [PubSubClient](https://github.com/knolleary/pubsubclient) — MQTT client
- [ArduinoJson](https://arduinojson.org) — JSON serialisation - [ArduinoJson](https://arduinojson.org) — JSON serialisation
- mbedtls — AES decryption (bundled with ESP32 Arduino core) - mbedtls — AES, bundled with the ESP32 Arduino core
--- ## Related projects
## Related Projects - [victron-ble](https://github.com/keshavdv/victron-ble) — the Python library this follows; still the right answer on a Pi or Linux box
- [esphome-victron_ble](https://github.com/Fabian-Schmidt/esphome-victron_ble) — ESPHome component, if you prefer YAML
- [victron-ble](https://github.com/keshavdv/victron-ble) — Python library this is based on (great for Pi/Linux setups) - [Victron_BLE_Advertising_example](https://github.com/hoberman/Victron_BLE_Advertising_example) — the original Arduino BLE example
- [esphome-victron_ble](https://github.com/Fabian-Schmidt/esphome-victron_ble) — ESPHome component if you prefer YAML config
- [Victron_BLE_Advertising_example](https://github.com/hoberman/Victron_BLE_Advertising_example) — original Arduino BLE example
---
## Licence ## Licence
MIT MIT.
--- ## Support
## Home Assistant Dashboard If this got a Raspberry Pi out of your solar setup, you can buy me a coffee.
A ready-made dashboard card is included in `home-assistant/dashboard.yaml`. <a href="https://www.buymeacoffee.com/MrSossidge"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me a Coffee" height="48"></a>
Requires these HACS frontend plugins:
- [Mushroom](https://github.com/piitaya/lovelace-mushroom)
- [Mini Graph Card](https://github.com/kalkih/mini-graph-card)
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
```
<a href="https://www.buymeacoffee.com/MrSossidge" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me a Coffee" style="height: 60px !important;width: 217px !important;" ></a>