Device Management Tutorial

Feature Introduction

The Device Management module covers the full life cycle management of devices in FlightHub 2 On-Premises version from network access to O&M, including:

Device List Management: Device inventory at the two dimensions of organization / project, device topology (three-layer relationship of dock / remote controller / drone), and switching of device-project work binding relationships.

Device Configuration: HMS health event pulling and maintenance, device thing model property query and dispatch (device shadow) / NTP / network speed detection / dock network / 4G APN, SIM card plans, RTK network account, custom RTK calibration, pairing and relay scan, project-level device parameter read/write, and the "general command channel" for sending custom configuration commands to devices.

Devices first access the network into the organization, then bind to specific projects; the same device can only belong to one work project at the same time.

Most control / configuration / O&M commands go through the IoT asynchronous channel: after dispatching, the caller obtains a task identifier and needs to poll Query Organization Device Command Execution Progress (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/cmds/{method}) to check the execution result.

Scenarios such as device offline, unstable network, command timeout, etc. will return corresponding error codes. See Error Codes.

Interface Usage Flow

Capability overview of the Device Management module (typical chain with "lens switching / video transmission quality setting / real-time control command dispatch / custom RTK calibration" as entry points):

In the above diagram, "control authority acquisition / drone lens switching / video transmission quality setting" actually belong to the Real-time Control module. This module is responsible for topology, status, and configuration; for commands that trigger hardware changes on the drone source side, please read the Real-time Control tutorial together.

Device inventory and project binding (device list management):

HMS health events + device shadow dispatch:

Device configuration command dispatch and execution progress query (general cmds channel):

Network management and RTK calibration:

Call steps:

Device inventory and project binding: First obtain the organization device inventory via Query Organization Device O&M List (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices), switch the device to the target project as needed with Modify Organization Device's Current Work Project (PUT /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/active-project) (only switch one at a time, body {device_sn, active_project_uuid}, pass active_project_uuid: "" to unbind), then use Get Project Current Topology List (GET /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies) and Get Project Device List (GET /openapi/v2.0/manage/api/v1/projects/{uuid}/devices) to render the project-dimension device view.

HMS health events: Periodically call Get Organization Device HMS Event List (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/hms) to pull new alerts. After the user views, call Update Organization Device HMS Read Time (PUT /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/hms) to mark as read; for project-dimension queries, use Batch Get Project Device HMS Events (POST /openapi/v2.0/manage/api/v1/projects/{uuid}/topologies/hms/batch-get).

Device shadow dispatch: Call Update Organization Device Shadow Config (POST /openapi/v2.0/manage/api/v1/organizations/{org_uuid}/manage-devices/shadows) (or the project version POST /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies/shadows) to dispatch thing model property changes, then use Query Organization Device Thing Model Property Current Value (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/shadows/{property}) to get the latest value.

Network management / RTK / SIM / pairing: Complete through the corresponding "configuration" interfaces; among them, NTP / dock network / 4G APN / relay scan results go through the manage-devices/cmds/{method} asynchronous channel, call Query Organization Device Command Execution Progress (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/cmds/{method}) to get the result.

General configuration command channel: The spec has removed a batch of V1.0 "dedicated query cmds endpoints" (device_check / fileupload_list / storage_config_get / get_operator_gps / ai_box_app_* / load_ai_model_progress / flight_areas_get / offline_map_get*, etc.). The retained "configuration commands" go uniformly through Send Custom Command to Organization Device (POST /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/cmds/{method}); the {method} value is determined by the device thing model, subject to the SDK documentation.

Device Shadow Thing Model Dispatch

Feature Introduction

The Device Shadow module is used to cache the "desired value" of device thing model properties on the cloud and dispatch them to the device. It is applicable to NTP server configuration, network parameters, camera default settings, and other configuration items that need to be maintained for a long time. The dispatch is an asynchronous channel (IoT); after the cloud persists the "desired value", the device pulls it for effect when it goes online / receives the command.

For organization dimension, use Update Organization Device Shadow Config (POST /openapi/v2.0/manage/api/v1/organizations/{org_uuid}/manage-devices/shadows) to dispatch to any device in the organization; for project dimension, use Update Project Device Shadow Config (POST /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies/shadows) to dispatch only to devices in the project topology.

To query the latest value of a single thing model property, use Query Organization Device Thing Model Property Current Value (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/shadows/{property}), where {property} is the thing model property name.

Interface Usage Flow

Call steps:

Prepare the "desired value" of the thing model property (specific property names and values are determined by the device model thing model, subject to the SDK documentation).

Call Update Organization Device Shadow Config (POST /openapi/v2.0/manage/api/v1/organizations/{org_uuid}/manage-devices/shadows) (or the project version) to dispatch; the interface returns immediately, which does not mean the device has taken effect.

Poll the latest value of a single property via Query Organization Device Thing Model Property Current Value (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/shadows/{property}) to confirm that the device has pulled the desired value.

RTK Network Account and Custom RTK Calibration

Feature Introduction

The RTK Configuration module is used to query the RTK network account information of devices and to trigger custom network RTK calibration (the user manually inputs precise coordinates to let the device complete high-precision position calibration).

Custom RTK calibration requires that the distance between the user-input calibration coordinates and the device satellite positioning coordinates is ≤ 50 meters; exceeding this distance will return error code 210262 ("Calibration failed, manual calibration coordinates and satellite positioning coordinates are too far apart"). The coordinates must be re-checked before retrying.

Interface Usage Flow

Call steps:

Confirm that the RTK account of the device has been configured via Query Device's RTK Network Account Info (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/devices/{sn}/rtk_account_info).

The user selects on the map / manually inputs precise coordinates, call Custom Network RTK Calibration (POST /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/rtk_calibration) to initiate calibration.

Handle the calibration result: success displays completion directly; failure handled by error code (210262 distance too far requires the user to re-select the point; 210263 position not converged recommends waiting for the device GPS to stabilize before retrying).

Feature Introduction#

Interface Usage Flow#

Device Shadow Thing Model Dispatch#

Feature Introduction#

Interface Usage Flow#

RTK Network Account and Custom RTK Calibration#

Feature Introduction#

Interface Usage Flow#

Feature Introduction

Interface Usage Flow

Device Shadow Thing Model Dispatch

Feature Introduction

Interface Usage Flow

RTK Network Account and Custom RTK Calibration

Feature Introduction

Interface Usage Flow