Topic Definition

Topic Overview

To facilitate the cloud platform's differentiation of various property processing strategies, the device-reported object model properties are divided into two categories: osd and state, each reported using different topics.

osd: Properties reported at regular intervals by the device, corresponding to pushmode = 0.
state: Event-driven properties reported by the device, corresponding to pushmode = 1.

Note: In the table below, {gateway_sn} represents the gateway device's serial number (SN), and {device_sn} represents the SN of the device to which the object model properties belong.For the aircraft on the cloud, {gateway_sn} represents the virtual docking station, which is used solely for protocol topic control. It is a fixed combination of DOCK + aircraft serial number. For example, if the aircraft serial number is 1748xx, then the virtual docking station's serial number would be DOCK1748xx

Topic Name	Sender -> Subscriber	Message	Description
thing/product/`{device_sn}`/osd	Device > Cloud	osd message struct	Device properties reported at regular intervals to the cloud platform (see object model for detailed content).
thing/product/`{device_sn}`/state	Device > Cloud	state message struct	Device properties reported on demand to the cloud platform (see object model for detailed content).
thing/product/`{gateway_sn}`/services	Cloud > Device	services message struct	Services sent from the cloud platform to the device (see object model for service identifiers).
thing/product/`{gateway_sn}`/services_reply	Device > Cloud	services_reply message struct	Device's response or result of service processing.
thing/product/`{gateway_sn}`/events	Device > Cloud	events message struct	Events sent from the device to the cloud platform that require attention and processing (see object model for event scope).
thing/product/`{gateway_sn}`/events_reply	Cloud > Device	events_reply message struct	Cloud platform's response or result of event processing.
thing/product/`{gateway_sn}`/requests	Device > Cloud	requests message struct	Requests sent from the device to the cloud platform, such as requests for temporary upload credentials.
thing/product/`{gateway_sn}`/requests_reply	Cloud > Device	requests_reply message struct	Cloud platform's response to device requests.
sys/product/`{gateway_sn}`/status	Device > Cloud	status message struct	Device's online/offline status and topology updates.
sys/product/`{gateway_sn}`/status_reply	Cloud > Device	status_reply message struct	Cloud platform's response.
thing/product/`{gateway_sn}`/property/set	Cloud > Device	property set message struct	Device property settings. Whether properties can be modified is indicated by the "accessMode" identifier in the property section. If `accessMode = rw`, the property can be read and written.
thing/product/`{gateway_sn}`/property/set_reply	Device > Cloud	property set_reply message struct	Response to property settings from the device
thing/product/`{gateway_sn}`/drc/up	Device > Cloud	DRC message struct	DRC protocol uplink.
thing/product/`{gateway_sn}`/drc/down	Cloud > Device	DRC message struct	DRC protocol downlink.

Public Field Explanations

Column	Name	Type	Description
tid	Transaction UUID	text	The UUID of a transaction: represents a simple message communication, such as add/delete/modify/query, gimbal control, etc. It can be: 1. Data report request + data report response 2. Handshake authentication request + response + ack 3. One-way notification of alarm events, resolving the issue of handling multiple concurrent transactions and message matching.
bid	Business UUID	text	The UUID of a business: some functions cannot be completed with just one communication and involve all interactions over a period of time. A business usually consists of multiple atomic transactions and lasts for a longer duration. It helps to handle multiple concurrent businesses and repeated requests, facilitating state machine management across all modules.
timestamp	Millisecond Timestamp	int	The time the message was sent.
gateway	Gateway Device Serial Number	text	The serial number of the gateway device that sent the message.
data	Message Content	object	The content of the message.

Example of OSD Structure

topic: thing/product/{device_sn}/osd

{
          "bid":  "ec33feab-3cfd-43e1-b2a3-bf762f3cede1",
          "data":  {
                    "activation_time":  1709125730482,
                    "attitude_head":  -0.92977506,
                    "attitude_pitch":  0.16601522266864777,
                    "attitude_roll":  -0.1496429443359375,
                    "battery":  {
                              "capacity_percent":  100
                    },
                    "cameras":  [
                              {
                                        "camera_mode":  1,
                                        "payload_index":  "68-0-0",
                                        "zoom_factor":  6.67
                              }
                    ],
                    "distance_limit_status":  {
                              "distance_limit":  15,
                              "state":  1,
                              "is_near_distance_limit":  0
                    },
                    "elevation":  0,
                    "height":  0,
                    "height_limit":  700,
                    "home_distance":  0,
                    "horizontal_speed":  0,
                    "latitude":  22.595598,
                    "longitude":  113.99777,
                    "mode_code":  0,
                    "night_lights_state":  0,
                    "obstacle_avoidance":  {
                              "downside":  0,
                              "horizon":  1,
                              "upside":  0
                    },
                    "position_state":  {

                    },
                    "rid_state":  0,
                    "vertical_speed":  0,
                    "alarm_status":  0,
                    "ned_altitude":  0,
                    "ned_latitude":  0,
                    "ned_longitude":  0,
                    "ntrip_status":  "error",
                    "pos_type":  "null",
                    "sn":  "HMA923359003",
                    "total_armed_time":  0,
                    "vel_ned_x":  0,
                    "vel_ned_y":  0,
                    "vel_ned_z":  0,
                    "wireless_link":  {
                              "4g_uav_quality":  53
                    },
                    "is_near_area_limit":  0,
                    "is_near_height_limit":  0,
                    "68-0-0":  {
                              "gimbal_pitch":  0,
                              "gimbal_roll":  0,
                              "gimbal_yaw":  -0.92999995,
                              "payload_index":  "68-0-0",
                              "zoom_factor":  0.5678233438485805
                    }
          },
          "gateway":  "NM1923261001",
          "tid":  "5866d2d3-e0fb-4345-bee6-c368564ee247",
          "timestamp":  1709125730481
}

Example of State Structure

topic: thing/product/{device_sn}/state

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "gateway":"sn",
    "data":{},
}

Example of Services Structure

topic: thing/product/{gateway_sn}/services

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "gateway":"sn",
    "method": "some_method",
    "data": {}
}

Example of Services Reply Structure

Explanation of required fields in data

Column	Name	Type	constraint	Description
result	Device response code	int		Non-zero indicates an error
output	Device message content	struct		The content of the device's response to the server's command

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "gateway":"sn",
    "method": "some_method",
    "data": {
        "result": 0, 
    	"output": {}
    }  
}

Example of Event Structure

topic: thing/product/{gateway_sn}/events

Column	Name	Type	constraint	Description
need_reply	Does the server need to respond	int		After the server receives the events report message from the device, it checks need_reply to determine whether a response is required; 0 means no response is needed, 1 means a response is needed

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "need_reply": 0,
    "gateway":"sn",
    "method": "some_method",
    "data": {}
}

Example of Event Reply Structure

topic: thing/product/{gateway_sn}/events_reply

Explanation of required fields in data

Column	Name	Type	constraint	Description
result	The result code from the server's response	int		Non-zero indicates an error

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "gateway":"sn",
    "method": "some_method",
    "data": {
        "result": 0
    }
}

Example of Requests Structure

topic: thing/product/{gateway_sn}/requests

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "gateway":"sn",
    "method": "some_method",
    "data": {}
}

Example of Requests Reply Structure

topic: thing/product/{gateway_sn}/requests_reply

Explanation of required fields in data

Column	Name	Type	constraint	Description
result	Server response result code	int		A non-zero value indicates an error
output	Service message content	struct		The content of the server's response to the device's message

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "gateway":"sn",
    "method": "some_method",
    "data": {
        "result": 0,
        "output":{}
    }
}

Example of Status Structure

topic: sys/product/{gateway_sn}/status

## Gateway device + sub-device online
{
	"tid": "tid001",
	"bid": "bid001",
	"method": "update_topo",
	"timestamp": 1234567890123,
	"data": {
		"type": 98,
		"sub_type": 0,
		"device_secret": "secret",
		"nonce": "nonce",
		"version": 1,
		"sub_devices": [
			{
				"sn": "drone001",
				"type": 116,
				"sub_type": 0,
				"index": "A",
				"device_secret": "secret",
				"nonce": "nonce",
				"version": 1
			}
		]
	}
}

## Sub-device offline
{
    "tid": "tid001",
    "bid": "bid001",
    "method": "update_topo",
    "timestamp": 1234567890123,
    "data": {
        "type": 98,
        "sub_type": 0,
        "device_secret":"secret",
        "nonce":"nonce",
        "version": 1,
        "sub_devices":[]
    }
}

Example of Status Reply Structure

topic: sys/product/{gateway_sn}/status_reply

Explanation of required fields in data

Column	Name	Type	constraint	Description
result	Result code	int		Non-zero indicates an error

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "method": "update_topo",
    "data": {
        "result": 0 
    }
}

Example of Property Set Structure

topic: thing/product/{gateway_sn}/property/set

Column	Name	Type	constraint	Description
some_property	The attribute key that needs modification	string		Whether the device attribute can be modified is determined by the "accessMode" indicator in the device attribute section. If accessMode = rw, it indicates that the attribute is readable and writable.
some_value	The attribute value that needs modification	string/int/float		Refer to the corresponding device attributes

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "data": {
      "some_property": some_value
    }
}

Example of Property Set Reply Structure

topic: thing/product/{gateway_sn}/property/set_reply

Explanation of required fields in data

Column	Name	Type	constraint	Description
some_property	The key of the attribute that needs to be modified	string		Whether the device attribute can be modified is determined by the "accessMode" identifier in the device attribute section. If accessMode = rw, it indicates that the attribute can be read and written.
result	The result of setting the corresponding attribute	int		0: Success, 1: Failure, 2: Timeout, for others refer to error code explanations

{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "data": {
        "some_property": {
           "result": 0  // 0: Success, 1: Failure, 2: Timeout, refer to error code explanation for other values
        }
    }
}

Example of DRC Up Structure

topic: thing/product/{gateway_sn}/drc/up

Explanation of required fields in data

Column	Name	Type	constraint	Description
result	Server response result code	int		Non-zero represents an error
output	Server response result code	struct		The message content from the server in response to the device

{
	"method": "drone_control",
	"data": {
		"result": 0,
		"output": {
			"seq": 1
		}
	}
}

Example of DRC Down Structure

topic: thing/product/{gateway_sn}/drc/down

{
	"method": "drone_control",
	"data": {
		"seq": 1,
		"x": 2.34,
		"y": -2.45,
		"h": 2.76,
		"w": 2.86
	}
}

Topic Overview​

Public Field Explanations​

Explanation of required fields in data​

Explanation of required fields in data​

Explanation of required fields in data​

Explanation of required fields in data​

Explanation of required fields in data​

Explanation of required fields in data​

Topic Overview

Public Field Explanations

Explanation of required fields in data

Explanation of required fields in data

Explanation of required fields in data

Explanation of required fields in data

Explanation of required fields in data

Explanation of required fields in data