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)
+[](#hardware)
+[](#4-build-and-upload)
+[](#how-it-fits-together)
+[](#mqtt-topics)
+[](#home-assistant)
+[](#power-consumption)
+[](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
-```
-
+