Real-time Data Forwarding
SolisCloud supports obtaining device real-time data through general data forwarding methods, suitable for high-frequency real-time data acquisition scenarios. When the HTTP API rate limit (10 times/second) cannot meet business needs, this method is recommended (no rate limit).
Applicable Scenarios
- Need to obtain device data in real-time at second-level frequency
- HTTP API rate limits cannot meet business requirements
- Need to receive device status changes and alarm notifications in real-time
Supported Protocols
| Protocol | Description | Applicable Scenarios |
|---|---|---|
| RocketMQ | Message queue forwarding | High-throughput, reliable delivery |
| MQTT | MQTT protocol forwarding | IoT scenarios, lightweight |
| HTTP | HTTP callback forwarding | Simple integration, webhook mode |
Data Forwarding Flow
Activation Process
- Contact the SolisCloud integration team to apply for data forwarding service
- Provide forwarding configuration information (protocol type, receiving address, etc.)
- After configuration is completed, real-time data will be pushed to the specified address
Note
The data forwarding service must be applied for separately and is not included in the self-service API activation. Please contact the integration team for configuration support.
Forwarding Data Format
Regardless of the forwarding protocol used, the message body is in a unified JSON format. Each message is scoped to a single collector and contains real-time data for all inverters under that collector.
Data Example
json
{
"time": 1572315457000,
"sn": "10000",
"isRealtime": 0,
"collector1": {
"collectorVer": "211",
"type": 0,
"model": "4G",
"rssiLevel": 1,
"rssi": -90,
"lat": 30000000,
"lon": 120000000,
"dataUploadCycle": 300,
"currentWorkingTime": 86400,
"totalWorkingTime": 2592000
},
"inverter1": [
{
"inverterSn": "aa08fcb5aa08fcb5",
"inverterModel": "23",
"inverterVer": "2568",
"ratedPower": 15000,
"nationalCode": "13",
"national": "GN-380L",
"inverterTemp": 14.0,
"pac": 10017,
"reactivePower": 120,
"apparentPower": 10100,
"eToday": 3765.7,
"eMonth": 92343,
"eYear": 926474,
"eTotal": 3154573,
"pv": [
{ "u": 200.0, "i": 2.0 },
{ "u": 200.0, "i": 2.0 },
{ "u": 200.0, "i": 2.0 }
],
"mppt": [
{ "u": 400.0, "i": 6.0 },
{ "u": 400.0, "i": 6.0 }
],
"ac": [
{ "u": 220.1, "i": 2.1 },
{ "u": 200.2, "i": 2.2 },
{ "u": 200.3, "i": 2.3 }
],
"fac": 50.00,
"psum": -500,
"gridPurchasedTotalEnergy": 1200.5,
"gridSellTotalEnergy": 800.3,
"batteryPower": 0,
"batteryState": 0,
"batteryHealthSoh": 98.5,
"batteryCapacitySoc": 85.0,
"familyLoadPower": 3500,
"bypassLoadPower": 0,
"homeLoadTodayEnergy": 12.5,
"homeLoadTotalEnergy": 3650.0,
"state": "1245",
"subState": 0,
"alarmCn": "",
"alarmEn": ""
}
]
}Data Field Reference
Top-level Fields
| Field | Type | Description |
|---|---|---|
| time | Long | Data timestamp (milliseconds) |
| sn | String | Collector SN |
| isRealtime | Integer | Real-time flag: 0 = real-time, 1 = historical backfill |
Collector Information (collector1)
| Field | Type | Description |
|---|---|---|
| collectorVer | String | Collector firmware version |
| type | Integer | Connection type: 1=GPRS, 2=WIFI |
| model | String | Collector model: GPRS / WIFI / 4G / LAN / W4G, etc. |
| rssiLevel | Integer | Signal strength level (1-5) |
| rssi | Integer | Signal value: GPRS 1~31, WIFI -20~-100 |
| lat | Integer | Latitude (multiply by 0.000001 for actual value) |
| lon | Integer | Longitude (multiply by 0.000001 for actual value) |
| dataUploadCycle | Integer | Data upload interval (seconds) |
| currentWorkingTime | Long | Current session uptime (seconds) |
| totalWorkingTime | Long | Cumulative uptime (seconds) |
Inverter Information (inverter1 array)
Each inverter is an object containing the following fields:
Basic Information
| Field | Type | Description |
|---|---|---|
| inverterSn | String | Inverter SN |
| inverterModel | String | Inverter model code |
| inverterVer | String | Inverter firmware version |
| ratedPower | Double | Rated power (W) |
| nationalCode | String | Grid standard code |
| national | String | Grid standard name |
| inverterTemp | Double | Inverter temperature (℃) |
Generation Side
| Field | Type | Description |
|---|---|---|
| pac | Double | Real-time power (W) |
| reactivePower | Double | Reactive power (Var) |
| apparentPower | Double | Apparent power (VA) |
| eToday | Double | Today's energy (kWh) |
| eMonth | Double | This month's energy (kWh) |
| eYear | Double | This year's energy (kWh) |
| eTotal | Double | Cumulative energy (kWh) |
DC Side (pv array)
| Field | Type | Description |
|---|---|---|
| u | Double | DC voltage (V) |
| i | Double | DC current (A) |
MPPT Data (mppt array)
| Field | Type | Description |
|---|---|---|
| u | Double | MPPT voltage (V) |
| i | Double | MPPT current (A) |
AC Side (ac array)
| Field | Type | Description |
|---|---|---|
| u | Double | AC voltage (V) |
| i | Double | AC current (A) |
| fac | Double | Grid frequency (Hz) |
Grid Side
| Field | Type | Description |
|---|---|---|
| psum | Double | Total grid power (W), positive=selling, negative=buying |
| gridPurchasedTotalEnergy | Double | Cumulative grid purchase energy (kWh) |
| gridSellTotalEnergy | Double | Cumulative grid sell energy (kWh) |
Battery Side
| Field | Type | Description |
|---|---|---|
| batteryPower | Double | Battery power (W), positive=charging, negative=discharging |
| batteryState | Integer | Battery status: 0=normal, 1=offline, 2=fault |
| batteryHealthSoh | Double | Battery SOH (%) |
| batteryCapacitySoc | Double | Battery SOC (%) |
| batteryList | Array | Multi-battery list (each item contains the above battery fields) |
Load Side
| Field | Type | Description |
|---|---|---|
| familyLoadPower | Double | Home load power (W) |
| bypassLoadPower | Double | Bypass load power (W) |
| homeLoadTodayEnergy | Double | Today's load energy consumption (kWh) |
| homeLoadTotalEnergy | Double | Cumulative load energy consumption (kWh) |
Inverter Status
| Field | Type | Description |
|---|---|---|
| state | String | Inverter status code (decimal), see below |
| subState | Integer | Sub-status |
| alarmCn | String | Alarm message in Chinese (only present during alarm) |
| alarmEn | String | Alarm message in English (only present during alarm) |
Status Code Interpretation
A state decimal value greater than 4100 (hex greater than 1004) indicates an inverter alarm. Common alarm codes:
| Status Code (Hex) | Description |
|---|---|
| 1004H | Control off-grid |
| 1010H | Grid over voltage |
| 1011H | Grid under voltage |
| 1012H | Grid over frequency |
| 1013H | Grid under frequency |
| 1015H | No grid |
| 1020H | DC over voltage |
| 1032H | Over temperature protection |
| 1033H | PV insulation fault |
| 1034H | Leakage current protection |
| 2010H | Fail Safe |
| 2011H | Meter communication failure |
| 2012H | Battery communication failure |
Protocol Configuration
RocketMQ Configuration
| Parameter | Required | Description |
|---|---|---|
| namesrvAddr | Yes | RocketMQ NameServer address |
| topic | Yes | Message topic |
| consumerGroup | Yes | Consumer group |
| accessKey | No | Access key (required when ACL is enabled) |
| secretKey | No | Secret key (required when ACL is enabled) |
RocketMQ Best Practices
- Use cluster consumption mode to ensure no message loss
- Implement idempotent processing to prevent duplicate consumption
- Set a reasonable consumption timeout (default 30 seconds)
MQTT Configuration
| Parameter | Required | Description |
|---|---|---|
| brokerUrl | Yes | MQTT Broker address |
| topic | Yes | Subscription topic |
| clientId | Yes | Client ID (must be unique) |
| username | No | Username |
| password | No | Password |
MQTT Best Practices
- Use QoS 1 (at-least-once delivery)
- Ensure clientId uniqueness — duplicate connections will cause disconnections
- Implement automatic reconnection mechanism
HTTP Callback Configuration
| Parameter | Required | Description |
|---|---|---|
| callbackUrl | Yes | HTTP callback URL (must be publicly accessible) |
| method | No | Request method, fixed to POST |
| headers | No | Custom request headers (can be used for authentication) |
HTTP Callback Best Practices
- Callback URL should support HTTPS
- Receiver must return HTTP 200 within 5 seconds, otherwise the push is considered failed
- Automatic retry on failure (up to 3 attempts)
- Implement signature verification to validate request origin
Push Frequency
| Item | Description |
|---|---|
| Push frequency | Follows device reporting frequency, typically second-level |
| Rate limit | No limit |
| Message ordering | Messages for the same device are pushed in chronological order |
| Message reliability | RocketMQ/MQTT guarantee at-least-once delivery; HTTP retries on failure |
FAQ
What's the difference between forwarded data and HTTP API queries?
| Comparison | HTTP API | Real-time Forwarding |
|---|---|---|
| Data update frequency | 5 minutes | Second-level |
| Access pattern | Pull (active) | Push (passive) |
| Rate limit | 10 times/second | No limit |
| Use case | Low-frequency queries, reporting | Real-time monitoring, high-frequency analytics |
How do I distinguish real-time data from historical backfill?
Check the top-level field isRealtime:
0= real-time data1= historical backfill (data from periods when the device was offline, backfilled after reconnection)
What if some fields are missing from forwarded data?
Fields vary by device type:
- Grid-tied inverters: No battery-related fields (batteryPower, batteryCapacitySoc, etc.)
- Hybrid inverters: Include all fields
- Older collector models: May lack MPPT data
We recommend dynamically parsing fields based on inverterModel.