Device Management

Device Topology Update

Topic: sys/product/{gateway_sn}/status

Direction: up

Method: update_topo

Data:

Column	Name	Type	constraint	Description
domain	Gateway device namespace	string
type	Gateway device product type	int
sub_type	Gateway sub-device product subtype	int
device_secret	Gateway device secret	text
nonce	nonce	text
thing_version	Gateway device thing model version	text
connect_type	Connection type	int	1 represents mcu 2 represents 1881
sub_devices	Sub-device list	array	{"size": 1, "item_type": struct}
»sn	Sub-device serial number (SN)	text
»domain	Sub-device namespace	string
»type	Sub-device product type	int
»sub_type	Sub-device product subtype	int
»index	Connection gateway device channel index	string
»device_secret	Sub-device secret	text
»nonce	nonce	text
»thing_version	Sub-device thing model version	text

Example:

 //sub_devices online  
{
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"method": "update_topo",
	"timestamp": 1234567890123,
	"data": {
		"domain": "3",
		"type": 119,
		"sub_type": 0,
		"device_secret": "secret",
		"nonce": "nonce",
		"thing_version": "1.1.2",
        "connect_type": 1,
		"sub_devices": [
			{
				"sn": "drone001",
				"domain": "0",
				"type": 60,
				"sub_type": 0,
				"index": "A",
				"device_secret": "secret",
				"nonce": "nonce",
				"thing_version": "1.1.2"
			}
		]
	}
}

 //sub_devices offline 
{
    "tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "method": "update_topo",
    "timestamp": 1234567890123,
    "data": {
        "domain": "3",
        "type": 119,
        "sub_type": 0,
        "device_secret":"secret",
        "nonce":"nonce",
        "thing_version": "1.1.2",
        "sub_devices":[]
    }
} 

Device Property Push

Topic: thing/product/{device_sn}/state Status data: Device reports when status changes

Topic: thing/product/{device_sn}/osd Periodic data: Device will report at 0.5HZ frequency

Direction: up

API Description: Payload property reporting refers to the property reporting of payloads mounted on the aircraft, such as camera property reporting. A payload is uniquely determined by payload index (payload index: product type-subtype-mount position {type-subtype-gimbalIndex}), type, subtype values Currently, protocols that involve payload property reporting include the gateway device's Device Property Push and the live streaming function's Live Streaming Capability Update. For Device Property Push, the payload property reporting content is camera information itself, such as gimbal pitch, yaw, roll angles, etc. For Live Streaming Capability Update, the payload property reporting content is more about camera capabilities during live streaming, such as maximum number of simultaneous streaming bitrates. Please refer to the example below for specific payload property structure. Note that the remote controller's device properties are reported in one message body, while the dock's device property push is sent in multiple messages.

Data:

Column	Name	Type	constraint	Description
data	Message content	text	{}	Content can refer to device's device properties
»camera_index	type-subtype-gimbalIndex	text	{}	gimbalIndex is camera position, type, sub_type

Example:

Topic: thing/product/{dock_sn}/state

Topic: thing/product/{dock_sn}/osd

{
    "bid": "e852fa28-955c-4510-8593-edcc67ee7d39",
    "data": {
        "air_conditioner": {
            "air_conditioner_state": 0
        },
        "alarm_state": 0,
        "alternate_land_point": {
            "latitude": 23.0358041,
            "longitude": 114.2302418,
            "safe_land_height": 4,
            "is_configured": 1
        },
        "backup_battery": {
            "remain_cap": 100,
            "temperature": 3131,
            "voltage": 2440,
            "switch": 1
        },
        "cover_state": 0,
        "drc_state": 0,
        "drone_charge_state": {
            "capacity_percent": 96,
            "state": 1
        },
        "drone_in_dock": 1,
        "emergency_stop_state": 0,
        "environment_humidity": 35.6,
        "environment_temperature": 37.3,
        "firmware_version": "1.4.0.43",
        "flighttask_step_code": 5,
        "height": 19.8307,
        "humidity": 42,
        "latitude": 23.035793,
        "live_status": [
            {
                "error_status": 0,
                "status": 0,
                "video_id": "drone-camera-0",
                "video_quality": 1,
                "video_type": "zoom"
            },
            {
                "error_status": 0,
                "status": 1,
                "video_id": "NM1923371002/nest-camera-out/normal",
                "video_quality": 1,
                "video_type": "normal"
            },
            {
                "error_status": 0,
                "status": 0,
                "video_id": "HMB923411183/drone-camera-0/normal",
                "video_quality": 1,
                "video_type": "zoom"
            }
        ],
        "longitude": 114.23022,
        "media_file_detail": {

        },
        "mode_code": 0,
        "network_state": {
            "type": 2
        },
        "position_state": {
            "is_fixed": 1
        },
        "pressure": 0,
        "putter_state": 0,
        "rainfall": 0,
        "rth_altitude": 30,
        "scram_status": 0,
        "storage": {
            "storage_type": 0,
            "total": 28156542976,
            "used": 4042371072
        },
        "supplement_light_state": 0,
        "takeoff_altitude": 30,
        "temperature": 31,
        "wind_speed": 0,
        "wireless_link": {

        }
    },
    "gateway": "NM1923371002",
    "tid": "16f959cf-9a13-4d2b-9804-a92674e89a43",
    "timestamp": 1715673626742
}

Topic: thing/product/{aircraft_sn}/state

Topic: thing/product/{aircraft_sn}/osd

{
    "bid": "2cb37f9f-bc25-41d4-aa7d-e07462491f1e",
    "data": {
        "activation_time": 1715676726534,
        "attitude_head": 0.0045256633,
        "attitude_pitch": 0.02032269723713398,
        "attitude_roll": 1.1378498077392578,
        "battery": {
            "capacity_percent": 96,
            "remain_flight_time": 2010
        },
        "cameras": [
            {
                "camera_mode": 1,
                "ir_zoom_factor": 1,
                "payload_index": "68-0-0",
                "zoom_factor": 1
            }
        ],
        "distance_limit_status": {
            "distance_limit": 100000,
            "state": 0,
            "is_near_distance_limit": 0
        },
        "elevation": 51.005,
        "height": 61.464,
        "height_limit": 800,
        "home_distance": 40.564087,
        "horizontal_speed": 0.040024992,
        "latitude": 23.035486,
        "longitude": 114.23,
        "mode_code": 9,
        "night_lights_state": 0,
        "obstacle_avoidance": {
            "downside": 0,
            "horizon": 1,
            "upside": 0
        },
        "position_state": {
            "calibration": 0,
            "coordinate_sys": 0,
            "fix_sta": 1,
            "gps_number": 9,
            "is_fixed": 2,
            "quality": 0,
            "rtk_number": 61,
            "rtk_hgt": 60.688499450683594,
            "rtk_inpos": 1,
            "rtk_lat": 23.03548820713067,
            "rtk_lon": 114.23000532515461,
            "rtk_used": 1
        },
        "rid_state": 0,
        "total_flight_time": 39825,
        "vertical_speed": 1.064,
        "alarm_status": 0,
        "ned_altitude": -51.005,
        "ned_latitude": -21.956568,
        "ned_longitude": -33.985134,
        "ntrip_status": "error",
        "pos_type": "50",
        "sn": "HMB923411183",
        "total_armed_time": 63,
        "vel_ned_x": 0.039,
        "vel_ned_y": 0.009,
        "vel_ned_z": 1.064,
        "wireless_link": {
            "4g_uav_quality": 34
        },
        "is_near_area_limit": 0,
        "is_near_height_limit": 0,
        "68-0-0": {
            "gimbal_pitch": 0,
            "gimbal_roll": 0,
            "gimbal_yaw": -0.14,
            "payload_index": "68-0-0",
            "zoom_factor": 0.5678233438485805
        }
    },
    "gateway": "NM1923371002",
    "tid": "ab688165-77f3-4070-aefc-15414d776aec",
    "timestamp": 1715676726534
}

Device Property Setting

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

Direction: down

Data:

Column	Name	Type	constraint	Description
data	Message content	text		Content can refer to device's device properties

RTK Account Setting:

Column	Name	Type	constraint	Description
data	Message content	struct
»rtk_acount	Dock RTK	struct
»»rtk_method	Method	text	ntrip
»»type	Type	int	0:Dock 1：Aircraft 4G
»»domain_name	Domain name	text
»»port	Port	text
»»mount_point	Mount point	text
»»user_name	Username	text
»»password	Password	text
»»is_default_on	Whether default use	int	0：Not default 1：Default

RTK Clear

Column	Name	Type	constraint	Description
data	Message content	struct
»rtk_acount_clear	Dock RTK	struct

RID Configuration

data	Message content	struct
»rid_config	RID configuration information dock RTK	struct
Column	Name	Type	constraint	Description
»»region	Region	int	0:UNKNOWN， 1:CN 2:US 3:EU 4:JP
»»flight_purpose	Flight destination, CN, US regions required	text
»»key	Key JP region required	text
»»pilot_id	Pilot ID	text
»»remote_id	RID JP region required	text

RID Configuration Clear:

Column	Name	Type	constraint	Description
data	Message content	struct
»rid_config_clear	Dock RTK	struct

4G Video Transmission Fusion Link Configuration

Column	Name	Type	constraint	Description
data	Message content	struct
»wireless_link_config	Link configuration	struct
link_work_mode	Link working mode	int	{"0":"SDR Mode","1":"4G Fusion Mode"}
4G_uav_link_addr	Aircraft 4G connection address	text	Required in 4G fusion mode
gnd_link_addr	Ground connection address	text	Required in 4G fusion mode

Set Takeoff and Return Home Altitude

Column	Name	Type	constraint	Description
data	Message content	struct
»takeoff_and_rth_altitude	Takeoff and return home altitude	struct
»»rth_altitude	Return home altitude	int
»»takeoff_altitude	Takeoff altitude	int

Example:

{
    "bid":"00000000-0000-0000-0000-000000000000",
    "data":{
        "distance_limit_status": {"state": 1}
    },
    "tid":"00000000-0000-0000-0000-000000000000",
    "timestamp":1643268212187
}

Set takeoff and landing altitude
{
    "bid":"00000000-0000-0000-0000-000000000000",
    "data":{
        "takeoff_and_rth_altitude": {
            "rth_altitude": 100,
            "takeoff_altitude": 100,
        }
    },
    "tid":"00000000-0000-0000-0000-000000000000",
    "timestamp":1643268212187，
    "gateway" : "NM1923371002"
}

Set alternate landing point:
{
  "timestamp" : "1715675635202",
  "data" : {
    "set_nest_position" : {
      "height" : 10.393,
      "longitude" : 114.23022,
      "latitude" : 23.035793,
      "backupLon" : 114.2302418,
      "backupLat" : 23.0358041,
      "backupAlt" : 4.0
    }
  },
  "tid" : "60933e0c-e1e3-42de-8154-948fe688103f",
  "bid" : "6bb3acee-f9ed-4b31-812b-3ecf1e428cc7",
  "gateway" : "NM1923371002"
} 

Set RTK account
 {
  "timestamp" : "1715676027869",
  "data" : {
    "rtk_account" : {
      "type" : 0,
      "rtk_method" : "Ntrip",
      "domain_name" : "rtk.ntrip.qxwz.com",
      "port" : 8002,
      "mount_point" : "AUTO",
      "user_name" : "xxxxxxx",
      "password" : "xxxxx",
      "is_default_on" : 1
    }
  },
  "tid" : "4c334487-5dbf-4e1f-ab2e-295d1e578e52",
  "bid" : "2b989d27-c6e5-4660-bd29-d0289ce3fa7e",
  "gateway" : "NM1923371002"
}

Clear RTK account
 {
  "timestamp" : "1715676027869",
  "data" : {
    "rtk_acount_clear" : {
    }
  },
  "tid" : "4c334487-5dbf-4e1f-ab2e-295d1e578e52",
  "bid" : "2b989d27-c6e5-4660-bd29-d0289ce3fa7e",
  "gateway" : "NM1923371002"
}

Configure RID:
 {
  "timestamp" : "1715676027869",
  "data" : {
    "rid_config" : {
      "region" : 1,
      "flight_purpose" : "China",
      "key" : "xxxxxxxx",
      "pilot_id" : "xxxxxxx",
      "remote_id" : "xxxxxxxxx",
    }
  },
  "tid" : "4c334487-5dbf-4e1f-ab2e-295d1e578e52",
  "bid" : "2b989d27-c6e5-4660-bd29-d0289ce3fa7e",
  "gateway" : "NM1923371002"
}

Clear RID configuration
 {
  "timestamp" : "1715676027869",
  "data" : {
    "rid_config_clear" : {
    }
  },
  "tid" : "4c334487-5dbf-4e1f-ab2e-295d1e578e52",
  "bid" : "2b989d27-c6e5-4660-bd29-d0289ce3fa7e",
  "gateway" : "NM1923371002"
}

Whether air transfer:
 {
  "timestamp" : "1715676027869",
  "data" : {
    "air_transfer_enable" : 1
  },
  "tid" : "4c334487-5dbf-4e1f-ab2e-295d1e578e52",
  "bid" : "2b989d27-c6e5-4660-bd29-d0289ce3fa7e",
  "gateway" : "NM1923371002"
}

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

Direction: up

Data:

Column	Name	Type	constraint	Description
data	Message content	text		Content can refer to device's device properties

Example:

{
    "bid":"00000000-0000-0000-0000-000000000000",
    "data":{
        "distance_limit_status": {
            "state": {
                "result": 0  // 0: Success, 1: Failure, 2: Timeout, 0x123456 specific error reason code
                }
       }
    },
    "tid":"00000000-0000-0000-0000-000000000000",
    "timestamp":1643268212187
}

Reply to alternate landing point setting
{
    "tid": "60933e0c-e1e3-42de-8154-948fe688103f",
    "bid": "6bb3acee-f9ed-4b31-812b-3ecf1e428cc7",
    "timestamp": 1715675635239,
    "data": {
        "set_nest_position": {
            "result": 0
        }
    }
}

Reply to RTK account setting:
{
    "tid": "c9ecb956-931b-4cbf-bc8a-896b19963dfd",
    "bid": "53e5fbfd-84e8-4c76-9bb2-bafdfa3f7d03",
    "timestamp": 1715676627443,
    "data": {
        "rtk_account": {
            "result": 0
        }
    }
}

Reply to RID configuration
 {
  "timestamp" : "1715676027869",
  "data" : {
    "rid_config" : {
      "result" : 0
    }
  },
  "tid" : "4c334487-5dbf-4e1f-ab2e-295d1e578e52",
  "bid" : "2b989d27-c6e5-4660-bd29-d0289ce3fa7e",
  "gateway" : "NM1923371002"
}