ricariel/solarflow-topic-mapper repository overview

⁠Solarflow Bluetooth Manager

A tool that talks to a Zendure Solarflow hub over Bluetooth Low Energy to read telemetry and to control which MQTT broker the hub reports to — Zendure's cloud, or one of your own.

Fork of reinhard-brandstaedter/solarflow-bt-manager⁠. See Fork Changes⁠ for what differs.

⁠Supported Devices

Set SF_PRODUCT_ID for anything other than the Hub 1200.

⁠Why Take the Hub Off the Cloud

• Finer control than the app offers, for example arbitrary output limits.
• No dependency on a cloud service, and no round-trip latency.
• Usage data stays local.
• Direct integration with a home automation system.

⁠Requirements

• A Bluetooth LE capable machine with Python 3 — a Raspberry Pi in range of the hub is the usual choice.
• pip3 install -r src/requirements.txt (bleak, paho-mqtt)

The script scans for a Bluetooth device whose name starts with Zen and connects to the first one it finds. With several Zendure devices in range, which one it picks is not predictable.

⁠Operating Modes

⁠Proxy Mode

The hub keeps its cloud connection for device data, but live telemetry is collected over Bluetooth by this tool and republished to your own broker. The app keeps working, including schedules.

This needs the tool running permanently as a service on a BLE-capable machine within range. The Bluetooth link can drop and not recover on its own; recovering means dropping the connection on either side.

⁠Offline Mode

The hub is reconfigured to talk to your MQTT broker instead of Zendure's. It stays on WiFi but no longer reaches the cloud at all.

Nothing needs to run locally afterwards except the broker. In exchange the app shows no telemetry and cannot control the hub — every setting change has to be made by publishing the right MQTT message.

⁠Usage

⁠Reading Hub Information

python3 src/solarflow-bt-manager.py -i

Connects, prints the GATT services, the device ID and the serial number, then exits after a few seconds. Note down the device ID — the disconnect and reconnect steps need it.

⁠Telemetry to a Local Broker

python3 src/solarflow-bt-manager.py -i -b <broker-host>:1883

Telemetry is published under solarflow-hub/telemetry.

⁠Disconnecting the Hub from the Cloud

The hub's WiFi connection is reinitialised and pointed at a different broker:

export WIFI_PWD="..."
export SF_DEVICE_ID="..."
export SF_PRODUCT_ID="73bkTV"
export MQTT_USER="..."
export MQTT_PWD="..."
python3 src/solarflow-bt-manager.py -d -w <wifi-ssid> -b <broker-host>

Afterwards the hub publishes under /<product-id>/<device-id>/#.

Once the hub is offline it can be driven by solarflow-control⁠ and solarflow-statuspage⁠ in offline mode.

Notes on this step:

• The hub authenticates with its own built-in credentials, not the ones above, so the target broker has to accept them — in practice that means allowing anonymous connections.
• For the AIO 2400, reset the network connection manually first by holding the connection button for about three seconds.
• It can help to move the hub to a different WiFi network before joining the target network.

⁠Reconnecting the Hub to the Cloud

Needed for firmware updates, among other things:

export WIFI_PWD="..."
export SF_DEVICE_ID="..."
export SF_PRODUCT_ID="73bkTV"
python3 src/solarflow-bt-manager.py -c -w <wifi-ssid>

⁠Options and Environment

-d refuses to run unless SSID, broker, WiFi password, device ID and product ID are all present.

⁠Topic Mapper

src/solarflow-topic-mapper.py subscribes to the hub's native report topic and republishes it in a flatter, more readable structure.

This is obsolete with current versions of solarflow-control⁠, which reads the native topics directly.

The Dockerfile packages only the topic mapper, not the BT manager — the manager needs host Bluetooth access and is meant to run outside a container. Its Python dependencies come from src/topic-mapper-requirements.txt, not from src/requirements.txt, which also lists bleak for the BT manager.

docker build -t solarflow-topic-mapper .

⁠Fork Changes

fabrice.patch records the change carried on top of upstream: for SF_PRODUCT_ID=A8yh63 (Hub 2000) the product class is zenh1_72 rather than upstream's zenh. The hardware revision determines the right value; zenh1_76 is the alternative and is kept as a comment in the source.

The product class ends up in the BLE payload that reconfigures the hub. A wrong value means the hub ignores the command.

⁠Related Projects

• solarflow-control⁠
• solarflow-statuspage⁠

⁠Donations

From the upstream author: if you are happy with the solarflow tools and they help you, donations are welcome — so that destroying the only Solarflow system while hacking on its internals does not end the project.