├── .gitignore ├── README.md ├── home_assistant.png ├── pom.xml └── src └── main ├── java └── org │ └── zendure │ └── examples │ ├── api │ ├── DeveloperApiSample.cs │ └── DeveloperApiSample.java │ └── mqtt │ └── SubscribeSample.java └── resources └── application.properties /.gitignore: -------------------------------------------------------------------------------- 1 | # maven # 2 | target 3 | 4 | logs 5 | 6 | # windows # 7 | Thumbs.db 8 | 9 | # Mac # 10 | .DS_Store 11 | 12 | # eclipse # 13 | .settings 14 | .project 15 | .classpath 16 | .log 17 | *.class 18 | 19 | # idea # 20 | .idea 21 | *.iml 22 | 23 | # Package Files # 24 | *.jar 25 | *.war 26 | *.ear 27 | /target 28 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Zendure Operating System v1.0.0 2 | 3 | This document serves as a guide for developers who want to subscribe to device uplink data for Zendure products. By subscribing to the Zendure MQTT Broker, developers can access device information and receive data from the device, similar to the official app. 4 | 5 |

6 | 7 | Logo 8 |

9 | 10 | ## Overview 11 | 12 | This report provides a guide for developers to subscribe to device uplink data for Zendure products. By subscribing to the Zendure MQTT Broker, developers can obtain device information and receive data from the device, similar to the official app. 13 | 14 | ## Purpose 15 | 16 | The purpose of this project is to offer access to device data for all Zendure app users. Developers can follow the steps outlined in the report to obtain device information. 17 | 18 | ## Features 19 | 20 | 1. API call example for applying to become a developer. 21 | 2. Example of creating an MQTT client and device message subscription. 22 | 3. Configuration information for the MQTT Broker endpoint. 23 | 24 | ## Steps to Subscribe to Device Data 25 | 26 | ### Apply to be a developer 27 | 28 | 1. Register an account in the Zendure App. 29 | * iOS: [https://apps.apple.com/us/app/zendure/id1592645038](https://apps.apple.com/us/app/zendure/id1592645038) 30 | * Android: [https://play.google.com/store/apps/details?id=com.zendure.iot&pli=1](https://play.google.com/store/apps/details?id=com.zendure.iot&pli=1) 31 | * Web: [https://app.zendure.com/download/](https://app.zendure.com/download/) 32 | 33 | 2. Familiarize yourself with the MQTT protocol and client message subscription. 34 | * MQTT Endpoint: Obtain the MQTT connection address and port number from the API results after applying to become a developer. 35 | 36 | 3. Call the REST API to obtain the client configuration by providing the device serial number (SN) and Zendure App account. (Connect your device to WiFi and use the official mobile app to register a Zendure account and bind your device. If multiple devices are bound, randomly select the SN of one of them.) 37 | * Endpoint(Golbal): `https://app.zendure.tech/v2/developer/api/apply` 38 | * Endpoint(Europe): `https://app.zendure.tech/eu/developer/api/apply` 39 | * Request Method: POST 40 | * Required parameters: 41 | * snNumber - the device serial number 42 | * account - Zendure App account username 43 | 44 | Example request body: 45 | 46 | ```json 47 | { 48 | "snNumber": "VU5D99F74021B04", 49 | "account": "dev@zendure.com" 50 | } 51 | ``` 52 | ``` 53 | Api Response: 54 | ```java 55 | { 56 | "code":200, 57 | "success":true, 58 | "data":{ 59 | "appKey":"zendure", 60 | "secret":"zendureSecret", 61 | "mqttUrl":"mqtt.zen-iot.com", 62 | "port":1883 63 | }, 64 | "msg":"Successful operation" 65 | } 66 | ``` 67 | 68 | ## Supported products 69 | Currently supports devices connected to WIFI 70 | - SuperBase V 71 | - 6400 72 | - 4600 73 | - Satellite Battery 74 | - 6400 75 | - 4600 76 | - SolarFlow 77 | ### Integrated Home Assistant 78 | 79 | ![image](https://zendure-oss.oss-cn-shenzhen.aliyuncs.com/app/github/homeassistant.png) 80 | 81 | 1. Select devices and services in Home Assistant, and add MQTT integration services. Use `appKey` as the username and `appSecret` as the password to connect to the MQTT broker. 82 | 2. Replace the integrated Mqtt Discovery prefix with your appKey. 83 | 3. For more information about the MQTT protocol, please refer to [https://mqtt.org/](https://mqtt.org/). 84 | 4. For more information on Home Assistant, please visit [https://www.home-assistant.io/](https://www.home-assistant.io/). 85 | 5. All possible metric names and their values sent by the device to the MQTT Zendure Broker are reported via JSON object key/value pairs. For example: device power, remaining discharge time. 86 | 87 | ```json 88 | { 89 | "electricLevel": 99, 90 | "remainOutTime": 9999, 91 | "socSet": 80 92 | } 93 | ``` 94 | ### Device report data list 95 | 96 | #### SuperBase V 97 | | Field | Description | device_class | 98 | | --- | --- | --- | 99 | | electricLevel | Device battery percentage | sensor | 100 | | remainOutTime | Remaining discharge time | sensor | 101 | | remainInputTime | Remaining charging time | sensor | 102 | | socSet | Charge Capacity Limitation | sensor | 103 | | batterCapacity | battery capacity | sensor | 104 | | acInputLimit | AC input limit | sensor | 105 | | slowChargePower | Slow charging power | sensor | 106 | | inputPower | total input power | sensor | 107 | | acSwitch | AC switch | switch | 108 | | acInputMode | AC input mode(1: Power grid 2: Charging cable) | sensor | 109 | | acInputPower | AC input power | sensor | 110 | | acHz | AC input frequency | sensor | 111 | | acInputVoltage | ac input voltage | sensor | 112 | | acOutputMode | AC output mode（1:UPS 2:120V 3:120V和240V） | sensor | 113 | | acOutputPower | AC output power | sensor | 114 | | acOutputVoltage | AC output voltage | sensor | 115 | | acOutputFactor | AC output load factor | sensor | 116 | | dcSwitch | DC switch | switch | 117 | | dcInputMode | DC input mode(1: car charger 2: solar energy) | sensor | 118 | | dcInputPower | DC input power | sensor | 119 | | outputPower | total output power | sensor | 120 | | dcOutputPower | DC output power | sensor | 121 | | circleOutputPower | circle output power | sensor | 122 | | usb1OutputPower | USB1 output power | sensor | 123 | | usb2OutputPower | USB2 output power | sensor | 124 | | typec1Power | TypeC1 output power | sensor | 125 | | typec2Power | TypeC2 output power | sensor | 126 | | typec3Power | TypeC3 output power | sensor | 127 | | typec4Power | TypeC4 output power | sensor | 128 | | andersonPower | Anderson output power | sensor | 129 | | ambientSwitch | Ambient light switch | switch | 130 | | ambientLightMode | Ambient light mode | sensor | 131 | | ambientLightColor | Ambient light color | sensor | 132 | | ambientLightNess | Ambient light brightness | sensor | 133 | | buzzerSwitch | buzzer switch | switch | 134 | | masterSwitch | master switch | switch | 135 | | childLock | child lock switch | switch | 136 | | assistSwitch | power wheel switch | switch | 137 | | assistAngle | Power wheel angle | sensor | 138 | | lampSwitch | light switch | switch | 139 | | lampMode | light mode | sensor | 140 | | upsMode | UPS mode | sensor | 141 | | machineStandTime | automatic shutdown time | sensor | 142 | | screenStandTime | automatic screen off time | sensor | 143 | | wifiSwitch | wifi switch | switch | 144 | | wifiSignalLevel | wifi signal level | sensor | 145 | | blueState | blue state | sensor | 146 | | wifiState | wifi state | sensor | 147 | | silentInput | Silent charging mode (sleep mode) | sensor | 148 | | ampUp | constant power mode | sensor | 149 | | dcHardwareVersion | DC Hardware version | sensor | 150 | | acHardwareVersion | AC hardware version | sensor | 151 | | bmsHardwareVersion | BMS hardware version | sensor | 152 | | masterHardwareVersion | MASTER hardware version | sensor | 153 | | typecHardwareVersion | TYPEC hardware version | sensor | 154 | | electricFanState | fan status | sensor | 155 | | batteryNum | battery num | sensor | 156 | | temperature | device temperature | sensor | 157 | | solarWorkMode | Solar working mode | sensor | 158 | | solarWorkOutputVoltage | Solar output voltage | sensor | 159 | | solarOutputPower | Solar output power | sensor | 160 | | assistDoubleFlash | Power wheel double flash switch | switch | 161 | | seriesMode | series mode | sensor | 162 | | parallelMode | parallel mode | sensor | 163 | 164 | #### SolarFlow 165 | | Field | Description | device_class | 166 | | --- | --- | --- | 167 | | electricLevel | Device battery percentage | sensor | 168 | | remainOutTime | Remaining discharge time | sensor | 169 | | remainInputTime | Remaining charging time | sensor | 170 | | socSet | Charge Capacity Limitation | sensor | 171 | | outputLimit | output limit | sensor | 172 | | solarInputPower | solar input power | sensor | 173 | | packInputPower | pack input power | sensor | 174 | | outputPackPower | output to pack power | sensor | 175 | | outputHomePower | output to home power | sensor | 176 | | packNum | pack num | sensor | 177 | | packState | pack state(0:standby 1:input 2:output) | sensor | 178 | | buzzerSwitch | buzzer switch | switch | 179 | | masterSwitch | master switch | switch | 180 | | solarPower1 | Solar1 Input Power | sensor | 181 | | solarPower2 | Solar2 Input Power | sensor | 182 | | passMode | Bypass Mode 0：auto 1:always off 2:always on | sensor | 183 | | autoRecover | Automatic recovery of bypass mode settings 0:off 1:on | sensor | 184 | | packData | pack Data | sensor | 185 | | maxVol | The highest voltage among all cells, calculated as 'value * 0.01', unit: V | sensor | 186 | | minVol | The lowest voltage among all cells, calculated as 'value * 0.01', unit: V | sensor | 187 | | totalVol | The total voltage, which is the sum of all cells' voltages, calculated as 'value * 0.01', unit: V | sensor | 188 | | maxTemp | The maximum temperature, which represents the highest temperature value among all battery cells at the current (real-time) moment, unit: Kelvi| sensor | 189 | | socLevel | Current battery capacity of the battery pack | sensor | 190 | | sn |Current battery pack battery code | sensor | 191 | | hubState | Hub output status(0: stop output standby 1: stop output and shut down) | sensor | 192 | #### The Fields Extended By Hyper 2000 & Ace 1500 Based On SolarFlow 193 | | Field | Description | device_class | 194 | | --- | --- | --- | 195 | | gridInputPower | grid input power | sensor | 196 | | acOutputPower | ac output power(Hyper 2000) | sensor | 197 | | dcOutputPower | dc output power(Ace 1500) | sensor | 198 | | acSwitch | ac switch | switch | 199 | | dcSwitch | dc switch(Ace 1500) | switch | 200 | 201 | 202 | ## Future Plans 203 | 1. Support data downlink and device control. 204 | 2. Support device LAN communication. 205 | 3. Integration of other Home Assistant plugins. 206 | 207 | ## Contact Us 208 | If you have any questions or feedback, please feel free to contact us via the following methods. We welcome your feedback and suggestions and look forward to working with you: 209 | * Email: [dev@zendure.com](mailto:dev@zendure.com) 210 | -------------------------------------------------------------------------------- /home_assistant.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Zendure/developer-device-data-report/0c9d65a9336f061bc2cb30a1b4dae68d8bb357fb/home_assistant.png -------------------------------------------------------------------------------- /pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | 4.0.0 6 | 7 | org.example 8 | developer-demo 9 | 1.0-SNAPSHOT 10 | 11 | 12 | 8 13 | 8 14 | 15 | 16 | 17 | 18 | org.eclipse.paho 19 | org.eclipse.paho.client.mqttv3 20 | 1.2.0 21 | 22 | 23 | 24 | 25 | 26 | cn.hutool 27 | hutool-all 28 | 5.7.9 29 | 30 | 31 | -------------------------------------------------------------------------------- /src/main/java/org/zendure/examples/api/DeveloperApiSample.cs: -------------------------------------------------------------------------------- 1 | using System; 2 | using System.IO; 3 | using System.Net; 4 | using System.Text; 5 | 6 | namespace ZendureMQTT 7 | { 8 | internal class Program 9 | { 10 | static void Main(string[] args) 11 | { 12 | var client = new HttpClient(); 13 | 14 | var url = "https://app.zendure.tech/v2/developer/api/apply"; 15 | 16 | var paramMap = new Dictionary 17 | { 18 | { "snNumber", "VU5D99F74021B04" }, 19 | { "account", "dev@zendure.com" } 20 | }; 21 | 22 | var json = JsonConvert.SerializeObject(paramMap); 23 | 24 | var postData = new StringContent(json, Encoding.UTF8, "application/json"); 25 | 26 | var response = client.PostAsync(url, postData).Result; 27 | var content = response.Content.ReadAsStringAsync().Result; 28 | 29 | Console.WriteLine(content); 30 | Console.ReadLine(); 31 | } 32 | } 33 | } 34 | -------------------------------------------------------------------------------- /src/main/java/org/zendure/examples/api/DeveloperApiSample.java: -------------------------------------------------------------------------------- 1 | package org.zendure.examples.api; 2 | 3 | import cn.hutool.http.HttpUtil; 4 | import cn.hutool.json.JSONUtil; 5 | 6 | import java.util.HashMap; 7 | 8 | public class DeveloperApiSample { 9 | 10 | public static void main(String[] args) { 11 | HashMap paramMap = new HashMap<>(); 12 | paramMap.put("snNumber", "VU5D99F74021B04"); 13 | paramMap.put("account", "dev@zendure.com"); 14 | String response = HttpUtil.createPost("https://app.zendure.tech/v2/developer/api/apply") 15 | .contentType("application/json") 16 | .body(JSONUtil.toJsonStr(paramMap)).execute().body(); 17 | System.out.println("The Response Of Api:"+response); 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /src/main/java/org/zendure/examples/mqtt/SubscribeSample.java: -------------------------------------------------------------------------------- 1 | package org.zendure.examples.mqtt; 2 | 3 | import org.eclipse.paho.client.mqttv3.*; 4 | 5 | import java.util.UUID; 6 | 7 | 8 | public class SubscribeSample { 9 | 10 | public static void main(String[] args) { 11 | // mqttUrl and port assigned by the platform 12 | String host = "tcp://mqtt.zen-iot.com:1883"; 13 | 14 | String topic = "{appKey}/sensor/device/acSwitch/config"; 15 | String clientId = UUID.randomUUID().toString(); 16 | // appKey assigned by the platform 17 | String userName = ""; 18 | // secret assigned by the platform 19 | String passWord = ""; 20 | try { 21 | MqttClient client = new MqttClient(host, clientId); 22 | // Connection settings for MQTT 23 | MqttConnectOptions options = new MqttConnectOptions(); 24 | // Set whether to clear the session. If it is set to false, it means that the server will keep the connection record of the client. If it is set to true, it means that it will connect with a new identity every time it connects to the server. 25 | options.setCleanSession(true); 26 | // Set the username for the connection 27 | options.setUserName(userName); 28 | // Set the password for the connection 29 | options.setPassword(passWord.toCharArray()); 30 | // Set the timeout time in seconds 31 | options.setConnectionTimeout(30); 32 | // Set the session heartbeat time in seconds The server will send a message to the client every 1.5*20 seconds to determine whether the client is online, but this method does not have a reconnection mechanism 33 | options.setKeepAliveInterval(20); 34 | // Set callback function 35 | client.setCallback(new MqttCallback() { 36 | public void connectionLost(Throwable cause) { 37 | System.out.println("connectionLost"); 38 | } 39 | public void messageArrived(String topic, MqttMessage message) throws Exception { 40 | System.out.println("topic:"+topic); 41 | System.out.println("Qos:"+message.getQos()); 42 | System.out.println("message content:"+new String(message.getPayload())); 43 | } 44 | public void deliveryComplete(IMqttDeliveryToken token) { 45 | System.out.println("deliveryComplete---------"+ token.isComplete()); 46 | } 47 | }); 48 | client.connect(options); 49 | // subscribe news 50 | client.subscribe(topic); 51 | System.out.println("Mqtt client created successfully"); 52 | } catch (Exception e) { 53 | e.printStackTrace(); 54 | } 55 | } 56 | } 57 | -------------------------------------------------------------------------------- /src/main/resources/application.properties: -------------------------------------------------------------------------------- 1 | # mqtt endpoint config 2 | mqtt.url = mqtt.zen-iot.com 3 | mqtt.port = 1883 4 | 5 | # rest api endpoint 6 | http.url = https://app.zendure.tech/v2/developer/api/apply --------------------------------------------------------------------------------