Method B · Gateway-to-Server (MQTT / TCP)

1 · Gateway MQTT Topics

deviceid is the gateway MAC address. Payloads carry the full Gateway API command/response package.

Broker address, ACLs and per-project credentials are issued by our engineering team with the full MQTT Topic Definition document.

2 · TCP Frame Protocol

Prefer a plain socket? The gateway keeps a persistent TCP connection to your server and solves the message-boundary problem with an explicit frame:

# Application-layer framing on the TCP stream
0x02 (STX) + UTF-8 JSON payload + 0x03 (ETX)

# Example — temperature report
0x02 {"type":"update","command":"temp",
      "argument":{"ieee":"F7220100007A1300","ep":1,"temp":2200}} 0x03

# Rules
- Bare 0x02 / 0x03 bytes are forbidden inside the JSON;
  encode binary content as Base64 or Hex first.
- Receiver: buffer the stream, cut frames between STX and ETX.
- ETX without STX -> discard; timeout without complete frame
  -> clear buffer; JSON parse failure -> send an error reply.

3 · Heartbeat & Time Sync

One 60-second connect message keeps the link alive and lets the device sync its clock from the server reply:

# Keep-alive + clock sync: every 60 seconds
-> 0x02 {
     "type":"server","command":"connect",
     "argument":{"mac":"000D6F000D743E53",
       "name":"Your account","version":"X3_HA_V2.5.8_20180317",
       "country":"China","state":"Fujian","zipcode":"361000"}
   } 0x03

<- 0x02 {
     "result":true,"type":"server","command":"connect",
     "response":{"utc":579315025,"mac":"000D6F000D743E53"}
   } 0x03

# Device calibrates its RTC from "utc".
# No response N >= 3 times -> treat link as dead and reconnect.

4 · Meters & Thermostats Direct to Your Broker

Wi-Fi models (e.g. MQTT-series power meters, PCT-series thermostats) speak MQTT natively — they can publish telemetry and accept commands from your broker without a gateway at all:

# Meters & thermostats can also publish straight to YOUR broker
# (no OWON cloud at all) — Wi-Fi models such as PC3xx-W-MQTT:

Device  --MQTT over TCP-->  Your broker (EMQX / Mosquitto /
                            VerneMQ / AWS IoT Core)
                              ^
Your server subscribes to device topics and publishes commands

# Configure the broker address on the device with the
# "X5 Config Tool" app (App Store) — or build your own
# configurator with our Configuration API.
# 5 steps: prepare broker -> configure device -> device
# publishes -> server subscribes -> server commands back.

5 · Identifying Devices in Payloads

Payloads reference devices by ieee (device MAC) + ep (endpoint), and type by devModel. Our device-model mapping table — 90+ models across meters, thermostats, HVAC controls, sleep/fall sensors, locks — defines the canonical devModel → model name pairs and ships with the integration package.