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

259
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
- 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
Victron's `victron-ble` Python library is excellent, and running it on a Raspberry Pi 4 works
perfectly — until you notice the Pi is idling at 3–5W purely to relay a few numbers off a
charge controller. On an off-grid system that's around **40Wh a night**, or 3–4Ah at 12V:
the monitoring was costing more than the thing it was monitoring.
This firmware does the same job on an ESP32 at roughly a fortieth of the power, and behaves
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
- ESP32 dev board (tested on ESP32 CH340 38-pin)
- Within BLE range of your Victron SmartSolar MPPT (~10m)
- WiFi network
- An ESP32 dev board — tested on the **ESP32 CH340 38-pin**
- Within BLE range of the SmartSolar MPPT (~10m)
- 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 the repo
### 1. Clone
```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
```
### 2. Install VS Code + PlatformIO
- Install [VS Code](https://code.visualstudio.com)
- Install the **PlatformIO IDE** extension from the marketplace
- Open the project folder — PlatformIO will detect `platformio.ini` and install dependencies automatically
Install [VS Code](https://code.visualstudio.com) and the **PlatformIO IDE** extension, then
open the project folder — PlatformIO reads `platformio.ini` and pulls dependencies itself.
### 3. Configure
Copy the example config and fill in your details:
```bash
cp include/example.config.h include/config.h
```
Edit `include/config.h`:
```cpp
#define WIFI_SSID "your_wifi_ssid"
#define WIFI_PASSWORD "your_wifi_password"
@ -61,32 +114,35 @@ Edit `include/config.h`:
#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
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. The MAC address is at the top of that page
5. Scroll to **Instant readout via Bluetooth** and tap **SHOW** for the encryption key
</details>
### 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
| Action | Shortcut |
|---|---|
| Build | `Ctrl+Alt+B` |
| Upload | `Ctrl+Alt+U` |
| Serial monitor | `Ctrl+Alt+S` |
---
## MQTT Topics
## MQTT topics
| Topic | Description |
|---|---|
| `solar/mppt/data` | JSON payload with all sensor values |
| `solar/mppt/status` | `online` / `offline` (retained LWT) |
### Example payload
```json
{
"battery_voltage": "12.98",
@ -95,11 +151,14 @@ Edit `include/config.h`:
"yield_today_wh": "350",
"charge_state": "bulk",
"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 |
|---|---|
@ -111,124 +170,70 @@ Edit `include/config.h`:
| 7 | Equalize |
| 245 | Starting |
| 252 | External control |
---
</details>
## 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)
- Battery Current (A)
- PV Power (W)
- Yield Today (Wh)
- Charge State
- Error Code
No manual YAML configuration required.
---
## Power Consumption
## Power consumption
| Device | Idle draw |
|---|---|
| Raspberry Pi 4 | ~3–5 W |
| 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.
---
## Project Structure
## Layout
```
├── include/
│ ├── config.h # Your config (excluded from git)
│ ├── example.config.h # Template — copy to config.h
│ └── victron_ble.h # BLE parser header
│ ├── 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
│ ├── main.cpp WiFi, MQTT, BLE scanning, FreeRTOS tasks
│ └── victron_ble.cpp AES decryption and MPPT data parser
├── 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
Managed automatically by PlatformIO:
PlatformIO handles all of these:
- [NimBLE-Arduino](https://github.com/h2zero/NimBLE-Arduino) — lightweight BLE stack
- [PubSubClient](https://github.com/knolleary/pubsubclient) — MQTT client
- [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) — Python library this is based on (great for Pi/Linux setups)
- [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
---
- [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_Advertising_example](https://github.com/hoberman/Victron_BLE_Advertising_example) — the original Arduino BLE example
## 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`.
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>
<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>