From 9f459f0d97a51269c92f095194562bf953ace60c Mon Sep 17 00:00:00 2001 From: MrSossidge <52222140+MrSossidge@users.noreply.github.com> Date: Mon, 14 Sep 2026 21:41:40 +0100 Subject: [PATCH] docs: rewrite README in house style with support link --- README.md | 263 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 134 insertions(+), 129 deletions(-) diff --git a/README.md b/README.md index b24d092..7e0316a 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,111 @@ -# 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**. +# ๐Ÿ”‹ 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) + +
--- -## 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
BLE advertisement, encrypted"] + + subgraph esp["โšก ESP32 ยท dual core"] + core1["Core 1 ยท NimBLE
passive scan"] + dec["victron_ble.cpp
AES-128-CTR + bit unpack"] + core0["Core 0 ยท WiFi + MQTT
PubSubClient"] + core1 --> dec --> core0 + end + + broker["Mosquitto
solar/mppt/#"] + ha["Home Assistant
auto-discovered"] + + 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. + +
+Finding your MAC address 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. The MAC address is at the top of that page +5. Scroll to **Instant readout via Bluetooth** and tap **SHOW** for the encryption key +
### 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 +
+Charge state values | Value | State | |---|---| @@ -111,124 +170,70 @@ Edit `include/config.h`: | 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: +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โ€“5W | -| ESP32 (this firmware) | ~0.15W | +| 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 -``` -Buy Me a Coffee +Buy Me a Coffee