Standards#

Request topic#

Rules#

The request topic follows the format device/{deviceNo}/webrtc/{topic}/{version}; the signaling topic is an exception — it has no {topic} segment and is simply device/{deviceNo}/webrtc/v1:

Families and directions#

Example#

For example, device/asr-1/webrtc/v1 is a signaling topic that follows the rules; device/asr-1/webrtc/telemetry/v1 is an example with a business topic segment.

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, and the per-sub-command shapes of the signaling topic are in the signaling sub-command index below.
• 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 WebRTC service: device,{deviceNo},webrtc,{sessionId}
  • Device management service: device,{deviceNo},iot,{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": "ping",
3  "id": "user,admin,web,session-id-xxx",
4  "token": "token-xxx",
5  "reply": "user/user001/abcdefg/webrtc/v1"
6}

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/webrtc/v1 is a custom reply topic of the same shape as 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. For signaling replies, the response to ping takes pong (a paired sub-command, not an identical echo). 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": "pong",
3  "id": "device,asr-1,webrtc",
4  "status": 200,
5  "data": {
6    "status": "idle",
7    "id": "",
8    "room": 0,
9    "feed": 0,
10    "session_id": 0,
11    "handle_id": 0
12  }
13}

Signaling sub-command index and multi-round communication#

Signaling sub-command (sub) index#

The 7 signaling sub-commands of the signaling topic device/{deviceNo}/webrtc/v1 — the per-sub-command request and response shapes are in this service's contract v1-signaling.yaml (viewable via the Swagger view on this service's "List" page):

Room-state semantics (pong)#

The pong response to ping carries the device's current room state; integrators decide call actions by the room state:

• status is idle: the device is idle; a call can be sent to start a call;
• status is p2p: the device is occupied by a peer-to-peer session; id is the identifier of the occupant;
• status is sfu: the device is in SFU mode; room being 0 means the room is being created (cannot join yet), and greater than 0 means the room is established (can join).

retrieve and deliver pairing (ICE configuration)#

The device publishes a retrieval request to device/{deviceNo}/webrtc/retrieve/v1 (the reference example items contains only ice) and points reply at device/{deviceNo}/webrtc/deliver/v1; the server delivers the ICE server configuration via the deliver topic, with the envelope data keyed by retrieval item (sub is deliver).