# Zendure Local Control System
---
# π 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)
---