上云API

Topic 定义

2024-11-01
暂无评分
Github Edit open in new window

Topic 总览

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

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

说明： 下表中的 {gateway_sn} 表示网关设备的 SN，{device_sn} 表示该物模型属性的所属设备的 SN 。

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设备端向云平台发送的，需要关注和处理的事件。
比如SD满了，飞机解禁禁飞区等信息（事件范围参见物模型内容）
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

{
    "tid": "65717bf1-aee7-4abb-8ea3-9b1908548d74",
    "bid": "cf5ad2e6-2f32-4b59-980e-d5c9ee412805",
    "timestamp": 1667220873846,
    "data": {
        "job_number": 492,
        "acc_time": 1859010,
        "activation_time": 0,
        "maintain_status": {
            "maintain_status_array": [
                {
                    "state": 0,
                    "last_maintain_type": 17,
                    "last_maintain_time": 0,
                    "last_maintain_work_sorties": 0
                }
            ]
        },
        "electric_supply_voltage": 231,
        "working_voltage": 25440,
        "working_current": 1120,
        "backup_battery": {
            "voltage": 26631,
            "temperature": 27.9,
            "switch": 1
        },
        "drone_battery_maintenance_info": {
            "maintenance_state": 0,
            "maintenance_time_left": 0
        }
    },
    "gateway": "dock_sn"
} 

{
    "bid": "d6cfcea4-c6ca-439b-948f-b17d88fc308f",
    "data": {
        "flighttask_step_code": 255,
        "media_file_detail": {
            "remain_upload": 0
        },
        "wireless_link": {
            "4g_freq_band": 2.4,
            "4g_gnd_quality": 0,
            "4g_link_state": 0,
            "4g_quality": 0,
            "4g_uav_quality": 0,
            "dongle_number": 0,
            "link_workmode": 0,
            "sdr_freq_band": 2.4,
            "sdr_link_state": 0,
            "sdr_quality": 0
        }
    },
    "tid": "e4c15182-776b-4c13-9973-3fc76848ca15",
    "timestamp": 1667220881576,
    "gateway": "dock_sn"
}

{
    "tid": "43d2e632-1558-4c4e-83d2-eeb51b7a377a",
    "bid": "7578f2ac-1f12-4d47-9ab6-5de146ed7b8a",
    "timestamp": 1667220916697,
    "data": {
        "network_state": {
            "type": 2,
            "quality": 0,
            "rate": 5.0970001220703125
        },
        "drone_charge_state": {
            "state": 0,
            "capacity_percent": 100
        },
        "drone_in_dock": 1,
        "rainfall": 0,
        "wind_speed": 0,
        "environment_temperature": 24,
        "temperature": 24.9,
        "humidity": 62,
        "latitude": 22.907809968,
        "longitude": 113.703482143,
        "height": 34.174125671386719,
        "alternate_land_point": {
            "latitude": 22.907898319908661,
            "longitude": 113.70347329676635,
            "safe_land_height": 0,
            "is_configured": 1
        },
        "first_power_on": 1631945855969,
        "position_state": {
            "is_calibration": 1,
            "is_fixed": 2,
            "quality": 5,
            "gps_number": 6,
            "rtk_number": 25
        },
        "storage": {
            "total": 82045336,
            "used": 51772
        },
        "mode_code": 1,
        "cover_state": 0,
        "supplement_light_state": 0,
        "emergency_stop_state": 0,
        "air_conditioner_mode": 0,
        "battery_store_mode": 1,
        "alarm_state": 0,
        "putter_state": 0,
        "sub_device": {
            "device_sn": "1581F5BKD225D00BP891",
            "device_model_key": "0-67-0",
            "device_online_status": 0,
            "device_paired": 1
        }
    },
    "gateway": "dock_sn"
}

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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "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参考设备管理-设备属性设置open in new window
设备属性是否可以被修改，在设备属性章节通过“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参考设备管理-设备属性设置open in new window
设备属性是否可以被修改，在设备属性章节通过“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
	}
}
请问您的文档阅读体验如何？
若您对文档有意见或疑惑，点击可快速反馈，我们会与您联系。