# Zendure Local Control System ---

Zendure Logo

# πŸ“– Documentation Navigator This project offers documentation in multiple languages. Choose the one you need: * πŸ‡¨πŸ‡³ [δΈ­ζ–‡ ](./docs/zh.md) * πŸ‡¬πŸ‡§ [English](./README.md) * πŸ‡©πŸ‡ͺ [Deutsch](./docs/de.md) * πŸ‡«πŸ‡· [FranΓ§ais](./docs/fr.md) --- # 🌟 Overview During the development of our previous [Device Data Report Project](https://github.com/Zendure/developer-device-data-report) we identified a strong need for improved local control.As a response, the team created the IoT framework **ZenSDK** and is now opening the **Local API** to help developers achieve: - Real-time device status & property retrieval - Event stream subscription - Remote function control - Integration of third-party MQTT clients (including [Home Assistant](https://www.home-assistant.io/integrations/mqtt/)) - Custom feature development through open APIs to enhance user experience Have an innovative idea for **Zendure** products? Feel free to reach out! --- # πŸ†• Updates - Update ZenSDK MQTT client connection to comply with EN 18031, using TLS to connect to the Zendure MQTT server. - Provide a user-configurable MQTT client that supports non-TLS only; port 8883 and mqtts:// are not supported. - Set local API receive length to 512 bytes. - Update and fix known issues. - Under EN 18031, HTTP requests are not supported by default. - To enable the local API, add HEMS and then exit to apply. --- # πŸ“Œ Supported Products | Model | Firmware Version | Status | |--------------------|------------------|-----------| | SolarFlow800 | Latest | supported | | SolarFlow800 Plus | Latest | supported | | SolarFlow800 Pro | Latest | supported | | SolarFlow1600 AC+ | Latest | supported | | SolarFlow2400 AC | Latest | supported | | SolarFlow2400 AC+ | Latest | supported | | SolarFlow2400 Pro | Latest | supported | | SmartMeter3CT | Latest | supported | | (More coming soon) | – | | --- # πŸš€ Core Architecture Local control is achieved via a combination of **mDNS service discovery** and **HTTP server communication**: ## 1. Device Discovery (mDNS) After connecting to the network, the device broadcasts its service information through **mDNS**: - Service name: `Zendure--`(e.g. `Zendure-SolarFlow800-WOB1NHMAMXXXXX3`) - IP address - HTTP service port Clients on the same LAN can listen for these broadcasts to automatically discover devices. ## 2. Device Communication (HTTP RESTful API) Each device hosts an internal HTTP server. ### Basic Operations | Method | Purpose | Example | | -------- | ------------------------------ | ------------------------------------------- | | `GET` | Query device status/properties | `GET /properties/report` (all properties) | | `POST` | Send control/config commands | `POST /properties/write` (set properties) | ### Data Format - **GET**: No body, response in JSON. - **POST**: JSON body must include device serial number `sn` (required). #### Example 1: Get device properties ```http GET /properties/report ``` #### Example 2: Send control/config command ```http POST /properties/write Content-Type: application/json { "sn": "WOB1NHMAMXXXXX3", // Required "properties": { "acMode": 2 // Writable property } } ``` #### Example 3: Check MQTT status ```http GET /rpc?method=HA.Mqtt.GetStatus ``` #### Example 4: Get MQTT configuration ```http GET /rpc?method=HA.Mqtt.GetConfig ``` #### Example 5: Set MQTT configuration ```http POST /rpc Content-Type: application/json { "sn": "WOB1NHMAMXXXXX3", "method": "HA.Mqtt.SetConfig", "params": { "config": { "enable": true, "server": "192.168.50.48", "port":1883, "protocol":"mqtt", "username": "zendure", "password": "zendure" } } } ``` --- # πŸ› οΈ Development Tools ## System-level mDNS discovery commands | OS | Command example | Description | | ------- | ------------------------------------------------------------ | ----------------------------------- | | Windows | `Get-Service \| Where-Object { $_.Name -like "*Bonjour*" }` | Check Bonjour service | | macOS | `dns-sd -B _zendure._tcp` | Browse Zendure devices | | Linux | `avahi-browse -r _zendure._tcp` | Discover `_zendure._tcp` services | ## Multi-language Samples - [C](./examples/C/demo.c) - [C#](./examples/C%23/demo.cs) - [Java](./examples/Java/demo.java) - [JavaScript](./examples/JavaScript/demo.js) - [openHAB](./examples/openHAB/zendure.things) - [PHP](./examples/PHP/demo.php) - [Python](./examples/Python/demo.py) - [ShellyScript](./examples/ShellyScript/demo.js) - [CLI quick test](#command-line-quick-test) ### Command-line quick test ```bash # Get all properties curl -X GET "http:///properties/report" # Query MQTT status curl -X GET "http:///rpc?method=HA.Mqtt.GetStatus" # Set acMode property curl -X POST "http:///properties/write" \ -H "Content-Type: application/json" \ -d '{"sn": "your_device_sn", "properties": { "acMode": 2 }}' ``` --- # πŸ“š Property Reference Detailed property definitions for each product: [SolarFlow Series Property Doc](./docs/en_properties.md) ---