Add README
This commit is contained in:
parent
8de1704adc
commit
27a362b5b3
|
|
@ -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
|
||||||
|
|
@ -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
|
|
||||||
Loading…
Reference in New Issue