Device Management

Device Topology Update

Topic: sys/product/{gateway_sn}/status

Direction: up

Method: update_topo

Data:

Column	Name	Type	constraint
domain	Namespace of the gateway device	string
type	Product type of the gateway	int
sub_type	Sub-type of the gateway device	int
device_secret	Gateway device secret	text
nonce	nonce	text
thing_version	Model version of the gateway	text
sub_devices	List of sub-devices	array	{"size": 1, "item_type": struct}
»sn	Serial number of the sub-device (SN)	text
»domain	Namespace of the sub-device	string
»type	Product type of the sub-device	int
»sub_type	Sub-type of the sub-device	int
»index	Channel index connecting the gateway	string
»device_secret	Secret of the sub-device	text
»nonce	nonce	text
»thing_version	Model version of the sub-device	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",
		"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 Attribute Push

Topic: thing/product/{device_sn}/state State data: device reports when the status changes

Topic: thing/product/{device_sn}/osd Regular data: device reports data at a frequency of 0.5HZ

Direction: up

API Explanation： Payload attribute reporting refers to reporting the attributes of payloads mounted on drones, such as camera attributes. Each payload is uniquely identified by its payload index (payload index: product type-subtype-mounting position {type-subtype-gimbalIndex}), with type and subtype values. Currently, the protocols involved in payload attribute reporting include the gateway device's Device Attribute Push and the live streaming feature's Live Capability Update. For Device Attribute Push, the payload attribute reports information about the camera itself, such as the pitch, yaw, and roll angles of the gimbal. For Live Capability Update, the payload attribute reports more about the camera's capabilities during live streaming, such as the maximum number of streams that can be pushed simultaneously. Refer to the example below for the specific structure of payload attributes. It is important to note that the remote controller's device attributes are reported in a single message, while the airport device attributes are reported in multiple messages.

Data:

Column	Name	Type	constraint	Description
data	Message Content	text	{}	For details, refer to the device properties of the device.
»camera_index	type-subtype-gimbalIndex	text	{}	gimbalIndex is the 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 Settings

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

Direction: down

Data:

Column	Name	Type	constraint	Description
data	Message Content	text		For details, refer to the device properties of the device.

RTK Account Settings:

Column	Name	Type	constraint
data	Message Content	struct
»rtk_acount	Dock RTK	struct
»»rtk_method	Method	text	ntrip
»»type	Type	int	0: Dock 1: Drone 4G
»»domain_name	Domain Name	text
»»port	Port	text
»»mount_point	Mount Point	text
»»user_name	Username	text
»»password	Password	text
»»is_default_on	Default Usage	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 for drone 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, required for CN and US regions	text
»»key	Key, required for JP region	text
»»pilot_id	Pilot ID	text
»»remote_id	RID, required for JP region	text

RID Configuration Clearing：

Column	Name	Type	constraint	Description
data	Message Content	struct
»rid_config_clear	Drone dock RTK	struct

4G Video Transmission Fusion Link Configuration

Column	Name	Type	constraint
data	Message Content	struct
»wireless_link_config	Link Configuration	struct
link_work_mode	Link Work Mode	int	{"0":"SDR Mode","1":"4G Fusion Mode"}
4G_uav_link_addr	UAV 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-to-Home Altitude

Column	Name	Type
data	Message Content	struct
»takeoff_and_rth_altitude	Takeoff and RTH Altitude	struct
»»rth_altitude	RTH 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 up 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 to transmit back in the air:

 {
  "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		For details, refer to the device properties of the device.

Example:

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

Reply to alternate 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 settings:

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

Device Topology Update​

Device Attribute Push​

#Device Property Settings​

Device Topology Update

Device Attribute Push

#Device Property Settings