Introduction

DJI Cloud API part of the interface using the IoT common MQTT5.0 protocol standard, the specific MQTT5.0 protocol details can refer to the link: MQTT5.0.

MQTT is a publish/subscribe model message transmission protocol for the client-server architecture. Its design ideas are light, open, simple, and standardized, so it is easy to implement. These features make it a good choice for many scenarios, including constrained environments such as machine-to-machine communication (M2M) and Internet of Things (IoT) environments that require small code encapsulation or very high network bandwidth expensive.

This protocol runs over TCP/IP, or other network connections that provide an orderly, reliable, bidirectional connection. It has the following features:

• Using the publish/subscribe message mode, it provides one-to-many message distribution and decoupling between applications.
• Message transmission does not need to know the payload content.
• Provides three levels of Quality of Service (QoS):
  1. "At most once": Distribute messages to the best of the operating environment's ability to provide. Messages may be lost. For example, this level can be used for environmental sensor data, a single loss of data does not matter, because it will be sent again shortly after.
  2. "At least once": The message is guaranteed to arrive, but it may be repeated.
  3. "Only Once": The message is guaranteed to arrive only once. For example, this level could be used in a billing system where duplicate or lost messages would result in incorrect billing.
• Small transmission consumption and protocol data exchange, minimizing network traffic.
• When abnormal connection disconnection occurs, relevant parties can be notified.

MQTT Term

Application Message The MQTT protocol transmits application data over the network. When application messages are transmitted over MQTT, they have an associated quality of service (QoS) and topic (Topic).

Client Client A program or device that uses MQTT. The client always connects to the server over the network. it can:

• Open a network connection to the server
• Publish application messages to other related clients
• Subscribe to request to receive relevant app messages
• Unsubscribe to remove the request to accept app messages
• close the network connection to the server

Server Server A program or device that acts as an intermediary between a client sending a message and a client requesting a subscription. Server

• Accept network connections from clients
• Accept application messages published by clients
• Handle client's subscribe and unsubscribe requests
• Forward application messages to eligible subscribed clients
• Close the network connection from the client

Session Session State interaction between client and server. Some sessions last as long as a network connection, others can be extended across multiple consecutive network connections on the client and server.

Subscription Subscriptions contain a Topic Filter and a maximum Quality of Service (QoS) level. Subscriptions are associated with a single session (Session). A session can contain more than one subscription. Each subscription to a session has a different topic filter.

Shared Subscription A shared subscription contains a topic filter (Topic Filter) and a maximum quality of service (QoS) level. A shared subscription can be associated with multiple subscription sessions, facilitating support for a wide range of message exchange patterns. An application message with a matching topic is sent to only one of the sessions associated with this shared subscription. A session can include multiple shared subscriptions and can contain both shared and non-shared subscriptions.

Wildcard Subscription A wildcard subscription is a subscription whose topic filter (Topic Filter) contains one or more wildcards. Wildcard subscriptions allow a subscription to match multiple Topic Names. Section 4.7 describes wildcards in topic filters.

Topic Name A tag is attached to the application message, known to the server and matched the subscription. The server sends a copy of the application message to each matching client subscription.

Topic Filter An expression included in the subscription that represents one or more topics of interest. Topic filters can use wildcards.

MQTT Control Packet Packets of information are sent over a network connection. The MQTT specification defines fourteen different types of MQTT control messages, one of which (PUBLISH message) is used to transmit application messages.

Invalid Packet Malformed Packet Control packets that cannot be correctly parsed according to the specification.

Protocol Error Errors containing data not permitted by the protocol or inconsistent with the current state of the client or server were found after packet parsing.

Will Message Application messages are published by the server when the network connection is closed abnormally.

MQTT Message Model

The MQTT message model is a Pub/Sub architecture. All devices connected to the cloud are a Client in the message model.

Variable	Description
Client	In the message model, all devices that establish connections with the centralized Broker are Clients.
Broker	Message gateway, in the message model, there are message producers and consumers, similar to buyers and sellers in the real estate industry, brokers must facilitate the transaction between the two, that is, complete the function of message transfer from producers to consumers.
Topic	Multiple clients subscribe based on the same topic, and then send and consume information based on the topic. Also known as Subject or Channel in some message model schemes. The delimiter DJI drone cloud platform is layered with a forward slash (/), such as /sys/device/register.
Message	The content of the message sent is based on the topic.
Subscription	After the Client connects to the Broker, it needs to subscribe to the Topic to receive all messages under the Topic, otherwise, it will not receive any messages from other Clients.

Message Model

Whether it is DJI Dock, DJI Pilot 2 or a Web page, they all establish a persistent connection with the Broker as a Client, and the information is precisely published to each client through the Broker. For example, the Pilot publishes the device status information to the Broker and displays it in real-time through two Web clients.

Broker is the server for connecting message routing. Through the Broker, the Client subscribed to a certain topic can receive the information published by the topic in time.

MQTT Topic Format

List of Topic prefixes

Category	Topic prefix	Explanation	Remark
Basic Topic	sys/	Any device has common cloud functionality, such as device registration, device lifecycle status updates and so on.
Thing Model Topic	thing/	The Topic that supports the implementation of the functions defined by each device thing model mainly revolves around Property, Service, and Event.

message(payload) format

{
	"tid": "xxxx",			# The tid of the message, which is used for the reply listener.
	"bid": "xxxx",			# Listen to the message id of the service result, asynchronous methods in service do not need to 								# listen.
	"method": "xxx",		# The identifier of the service in the thing model file.
	"data": {				# Payload specific information.
		"properties": {},	# Used to indicate device properties.
		"result": {},		# Used to indicate the result of the event in the ack message (whether it was successful or not).
		"output": {},		# It is used to indicate additional information attached to an upstream event or service, which is 								# part of the extention content.
		"event": {}			# Used to represent device events, which are used in the event topics of the thing model.
	},
	"timestamp": xxxx		# 13-bit Unit timestamp (milliseconds) when the message was sent. 
}