跳到主要内容

Topic 定义

Topic 总览​

为了方便设备云平台区分不同属性的处理策略，将设备上报物模型属性分为 osd 和 state 两类，分别用不同的 topic 上报。

  • osd：设备定频上报的属性，对应 pushmode = 0。
  • state：设备事件性上报的物模型属性，对应 pushmode=1。

说明： 下表中的 {gateway_sn} 表示网关设备的 SN，{device_sn} 表示该物模型属性的所属设备的 SN 。对飞机上云来说，*{gateway_sn}*是虚拟机巢，只做为协议topic控制，是固定DOCK+飞机sn的组合，比如飞机sn是1748xx,那么虚拟机巢的sn就是DOCK1748xx

Topic Name发送者 -> 订阅者Message说明
thing/product/{device_sn}/osd设备 > 云平台osd message struct设备端定频向云平台推送的设备属性（properties），
具体内容范围参见物模型内容
thing/product/{device_sn}/state设备 > 云平台state message struct设备端按需上报向云平台推送的设备属性（properties），
具体内容范围参见物模型内容
thing/product/{gateway_sn}/services云平台 -> 设备services message struct云平台向设备发送的服务（具体service identifier 见物模型内容）。
thing/product/{gateway_sn}/services_reply设备 > 云平台services_reply message struct设备对 service 的回复、处理结果
thing/product/{gateway_sn}/events设备 > 云平台events message struct设备端向云平台发送的，需要关注和处理的事件。
（事件范围参见物模型内容）
thing/product/{gateway_sn}/events_reply云平台 -> 设备events_reply message struct云平台对设备事件的回复、处理结果
thing/product/{gateway_sn}/requests设备 > 云平台requests message struct设备端向云平台发送请求，为了获取一些信息，比如上传的临时凭证
thing/product/{gateway_sn}/requests_reply云平台 -> 设备requests_reply message struct云平台对设备请求的回复
sys/product/{gateway_sn}/status设备 > 云平台status message struct设备上下线、更新拓扑
sys/product/{gateway_sn}/status_reply云平台 -> 设备status_reply message struct平台响应
thing/product/{gateway_sn}/property/set云平台 -> 设备property set message struct设备属性设置。设备属性是否可以被修改，在设备属性章节通过“accessMode”标识符号判断，accessMode = rw 表示可被读写。
thing/product/{gateway_sn}/property/set_reply设备 > 云平台property set_reply message struct设备属性设置的响应
thing/product/{gateway_sn}/drc/up设备 > 云平台DRC message structDRC 协议上行
thing/product/{gateway_sn}/drc/down云平台 > 设备DRC message structDRC 协议下行

公共字段解释​

ColumnNameTypeDescription
tid事务uuidtext事务（Transaction）的 UUID：表征一次简单的消息通信，如：增/删/改/查，云台控制等，可以是：
1. 数据上报请求+数据上报响应
2. 握手认证请求+响应+ack
3.报警事件单向通知等，解决事务多并发和消息匹配的问题
bid业务uuidtext业务（Business）的 UUID：有些功能不是一次通信就能完成的，包含持续一段时间内的所有交互。
业务通常由多个原子事务组成，且持续时间较长;
解决业务多并发和重复请求的问题，便于所有模块的状态机管理。
timestamp毫秒时间戳int消息的发送时间
gateway网关设备的序列号text发送该消息的网关设备的序列号
data消息内容object消息内容

osd 结构示例 ​

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":  "DOCK1748",
          "tid":  "5866d2d3-e0fb-4345-bee6-c368564ee247",
          "timestamp":  1709125730481
}

state 结构示例 ​

topic: thing/product/{device_sn}/state

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

services 结构示例 ​

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": {}
}

services_reply 结构示例 ​

data中必填字段解释​

ColumnNameTypeconstraintDescription
result设备响应的结果码int非 0 代表错误
output设备消息内容struct设备响应服务端命令的消息内容
{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "gateway":"sn",
    "method": "some_method",
    "data": {
        "result": 0, 
    	"output": {}
    }  
}

events 结构示例 ​

topic: thing/product/{gateway_sn}/events

ColumnNameTypeconstraintDescription
need_reply服务端是否需要答复int服务端收到设备的events事件上报消息后，跟进need_reply来判断是否给予收到答复;0代表不需要，1代表需要
{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "need_reply": 0,
    "gateway":"sn",
    "method": "some_method",
    "data": {}
}

events_reply 结构示例 ​

topic: thing/product/{gateway_sn}/events_reply

data中必填字段解释​

ColumnNameTypeconstraintDescription
result服务端响应的结果码int非 0 代表错误
{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "gateway":"sn",
    "method": "some_method",
    "data": {
        "result": 0
    }
}

requests 结构示例 ​

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": {}
}

requests_reply 结构示例 ​

topic: thing/product/{gateway_sn}/requests_reply

data中必填字段解释​

ColumnNameTypeconstraintDescription
result服务端响应的结果码int非 0 代表错误
output服务消息内容struct服务端响应设备的消息内容
{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "gateway":"sn",
    "method": "some_method",
    "data": {
        "result": 0,
        "output":{}
    }
}

status 结构示例 ​

topic: sys/product/{gateway_sn}/status

## 网关设备+子设备上线
{
	"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
			}
		]
	}
}

子设备下线​

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

status_reply 结构示例 ​

topic: sys/product/{gateway_sn}/status_reply

data中必填字段解释​

ColumnNameTypeconstraintDescription
result结果码int非0代表错误
{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "method": "update_topo",
    "data": {
        "result": 0 
    }
}

property set 结构示例 ​

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

ColumnNameTypeconstraintDescription
some_property需要修改的属性keystring设备属性是否可以被修改，在设备属性章节通过“accessMode”标识符号判断，accessMode = rw 表示可被读写。
some_value需要修改的属性valuestring/int/float参考对应的设备属性
{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "data": {
      "some_property": some_value
    }
}

property set_reply 结构示例 ​

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

data中必填字段解释​

ColumnNameTypeconstraintDescription
some_property需要修改的属性keystring设备属性是否可以被修改，在设备属性章节通过“accessMode”标识符号判断，accessMode = rw 表示可被读写。
result对应属性的设置结果int0: 成功，1：失败，2：超时，其他参考错误码解释
{
    "tid":"6a7bfe89-c386-4043-b600-b518e10096cc",
    "bid":"42a19f36-5117-4520-bd13-fd61d818d52e",
    "timestamp": 1598411295123,
    "data": {
        "some_property": {
           "result": 0  // 0: 成功，1：失败，2：超时，其他参考错误码解释
        }
    }
}

drc up 结构示例 ​

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

data中必填字段解释​

ColumnNameTypeconstraintDescription
result服务端响应的结果码int非 0 代表错误
output服务消息内容struct服务端响应设备的消息内容
{
	"method": "drone_control",
	"data": {
		"result": 0,
		"output": {
			"seq": 1
		}
	}
}

drc down 结构示例 ​

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
	}
}