From 27a362b5b3575910016bae99dffcfb5bcb9d43fe Mon Sep 17 00:00:00 2001 From: MrSossidge Date: Sun, 17 May 2026 20:41:37 +0100 Subject: [PATCH] Add README --- README.md | 196 +++++++++++++++++++++++++++++++++++++++++++++++++ include/README | 37 ---------- 2 files changed, 196 insertions(+), 37 deletions(-) create mode 100644 README.md delete mode 100644 include/README diff --git a/README.md b/README.md new file mode 100644 index 0000000..09f1b51 --- /dev/null +++ b/README.md @@ -0,0 +1,196 @@ +# 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 + +```bash +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 + +### 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" +#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 + +```json +{ + "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](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: + +- [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) + +--- + +## 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 + +--- + +## Licence + +MIT \ No newline at end of file diff --git a/include/README b/include/README deleted file mode 100644 index 49819c0..0000000 --- a/include/README +++ /dev/null @@ -1,37 +0,0 @@ - -This directory is intended for project header files. - -A header file is a file containing C declarations and macro definitions -to be shared between several project source files. You request the use of a -header file in your project source file (C, C++, etc) located in `src` folder -by including it, with the C preprocessing directive `#include'. - -```src/main.c - -#include "header.h" - -int main (void) -{ - ... -} -``` - -Including a header file produces the same results as copying the header file -into each source file that needs it. Such copying would be time-consuming -and error-prone. With a header file, the related declarations appear -in only one place. If they need to be changed, they can be changed in one -place, and programs that include the header file will automatically use the -new version when next recompiled. The header file eliminates the labor of -finding and changing all the copies as well as the risk that a failure to -find one copy will result in inconsistencies within a program. - -In C, the convention is to give header files names that end with `.h'. - -Read more about using header files in official GCC documentation: - -* Include Syntax -* Include Operation -* Once-Only Headers -* Computed Includes - -https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html