Standards#

Request topic#

Rules#

The request topic follows the format device/{deviceNo}/iot/{topic}/{version}, where:

Families and directions#

Example#

For example, device/asr-1/iot/configs/v1 is a topic that follows the rules.

Request structure (Api request)#

Rules#

• sub: Sub-topic, used only in relatively complex bidirectional communication scenarios; left empty otherwise. It distinguishes different business operations when the topic is the same; the sub values of each topic in this domain are listed in the family-and-direction table above.
• id: Session ID as a unique identifier used to distinguish different clients; an MQTT client ID must be supplied. The MQTT client ID generation rules are as follows:
  • Device management service: device,{deviceNo},iot,{sessionId}
  • Device WebRTC service: device,{deviceNo},webrtc,{sessionId}
  • Web client: user,{username},web,{sessionId}
  • App client: user,{username},app,{sessionId}
  • Center or collection server data service: server,{serverNo},iot,{sessionId}
  • Center server device service: server,{serverNo},device,{sessionId}
  • Collection server file service: server,{serverNo},file,{sessionId}
• reply: MQTT response message topic path. This is an optional field, set only when response data is required; the responder returns the response data via this topic. This design makes third-party integration easier — third-party systems can subscribe to topics according to their own conventions and use their own topic-definition rules. This field exists for compatibility with clients that do not support MQTT 5.0 features (corresponds to Response Topic in MQTT 5.0).
• replyNumberMax: Maximum reply count. This is an optional field, set only when response data must be returned more than once. The server restricts the range to 1 - 10; if empty, the default is 1.
• replyInterval: Reply interval (seconds). This is an optional field, set only when response data must be returned more than once. The server restricts the range to 1 - 10 seconds; if empty, the default is 1 second.
• token: Authentication token, used only for HTTP interface permission checks; the MQTT pipeline does not read this field (the device-side validation semantics of this field are unverified).
• params: Parameters. This is an optional field, set only when there are parameters to pass; the concrete shape depends on the sub value — see each topic contract.

Example#

1{
2  "sub": "get",
3  "id": "user,admin,web,session-id-xxx",
4  "token": "token-xxx",
5  "reply": "user/user001/abcdefg/iot/configs/v1",
6  "params": {
7    "structs": ["BATTERY_INFO_S"]
8  }
9}

Response topic#

Rules#

Specified by the reply field in the request structure; if that field is empty, no reply is sent. The reply topic is defined by the requester; third-party systems can subscribe according to their own topic conventions.

Example#

For example, user/user001/abcdefg/iot/configs/v1 is the custom reply topic shape from the reference documentation example.

Response structure (Api response)#

Rules#

• sub: Business sub-command echo — the response envelope in this domain carries sub, echoing the business sub-command of the request (such as get or retrieve). This differs from the center-server domain convention of "responses do not echo sub"; the two domains have their own contract facts — do not mix them when parsing responses.
• id: In response envelopes the id is the responder's outbound MQTT client ID (a fixed three-segment form, e.g. server,center-server-1,iot in the sample environment), which differs from the caller-supplied id.
• status: Response status code; the default is 200. It gives a quick indication of the overall result of the request.
  • 200: The request was executed successfully without any errors.
  • 400: Object validation failed: request parameters missing, over-length, or malformed; see the error field for details.
  • 401: Authentication failed: wrong credentials, invalid or expired token, or missing authentication information.
  • 403: Access denied: authenticated but lacking permission for the target resource.
  • 422: Business logic validation failed: the request is well-formed but a business condition is not met (e.g., target data not found); see the error field for details.
  • 500: Internal server error: the UI only shows "System Error"; details are recorded in server-side logs.
  • 1000: Message conversion failed: the request body cannot be parsed into the target object or the response body cannot be serialized (data format mismatch).
  • 1001: Controller parameter validation failed: form fields missing, over-length, or malformed; see the error field for details.
• error: Error description; optional, returned only when an exception occurs, so the caller can clearly understand the specific cause.
• data: Response data; optional, present only when there is data to return.
• replyNumber: Reply count, corresponding to replyNumberMax in the request structure; it indicates how many replies were made for this request.

Example#

1{
2  "sub": "retrieve",
3  "id": "server,center-server-1,iot",
4  "status": 200,
5  "data": {
6    "ice": [
7      { "urls": "stun:example.invalid:3478" },
8      { "urls": "turn:example.invalid:3478", "username": "xxx", "credential": "xxx" }
9    ]
10  }
11}

Telemetry cadence and retrieve pairing#

Telemetry collection and reporting cadence#

• Battery level: collected on change, reported once per change;
• GPS: valid fixes are accumulated and reported every 15 seconds;
• Disk capacity: collected on change, reported once per change;
• Unified reporting interval: 5 minutes (determined by business needs).

When sub is status, state changes are reported immediately; when sub is event, events are reported (time is a number); when sub is data, historical data is reported in batches grouped by time-string keys (the two time types differ; recorded as in the reference documentation).

retrieve and deliver pairing#

The device publishes a retrieval request to device/{deviceNo}/iot/retrieve/v1 (params.items specifies the retrieval items) and points reply at device/{deviceNo}/iot/deliver/v1; the server delivers the retrieval results via the deliver topic, with the envelope data keyed by retrieval item (sub is deliver).