Product Description

MQTT Protocol

MQTT Introduction

MQTT (Message Queuing Telemetry Transport, Message Queuing Telemetry Transport Protocol) is a "lightweight" communication protocol based on the publish/subscribe (publish/subscribe) model. The protocol is built on the TCP/IP protocol and was developed by IBM in 1999. Released in year. The biggest advantage of MQTT is that it can provide real-time and reliable messaging services for connecting remote devices with very little code and limited bandwidth. As a low-cost, low-bandwidth instant messaging protocol, it has wide applications in the Internet of Things, small devices, mobile applications, etc.

MQTT is a client-server based message publish/subscribe transport protocol. The MQTT protocol is lightweight, simple, open and easy to implement. These features make it applicable to a wide range of applications.

MQTT Protocol Implementation

Implementing the MQTT protocol requires communication between the client and the server. During the communication process, there are three identities in the MQTT protocol: publisher (Publish), agent (Broker) (server), and subscriber (Subscribe). Among them, the message publisher and subscriber are both clients, the message agent is the server, and the message publisher can be a subscriber at the same time.

The messages transmitted by MQTT are divided into two parts: topic and payload:

· Topic，It can be understood as the type of message. After a subscriber subscribes, he will receive the message content (payload) of the topic;

· payload，It can be understood as the content of the message, which refers to the specific content that the subscriber wants to use.

MQTT Client

An application or device that uses the MQTT protocol, which always establishes a network connection to the server. Clients can:

· Publish information to which other clients may subscribe;

· Subscribe to messages published by other clients;

· Unsubscribe or delete messages from the application;

· Disconnect from the server.

MQTT Server

The MQTT server is called a "message broker" (Broker), which can be an application or a device. It is located between message publishers and subscribers. It can:

· Accept network connections from customers;

· Accept application information posted by customers;

· Handle subscription and unsubscribe requests from clients;

· Forward application messages to subscribed clients.

Subscriptions, topics, and sessions in the MQTT protocol

Subscription

Subscriptions include topic filters and maximum quality of service (QoS). Subscriptions are associated with a session. A session can contain multiple subscriptions. Each subscription in each session has a different topic filter.

Session

After each client establishes a connection with the server, it is a session, and there is stateful interaction between the client and the server. A session exists between a network and may span multiple consecutive network connections between a client and a server.

Topic Name

Connect to a label for an application message that matches the server's subscription. The server sends the message to every client subscribed to the matching tag.

Topic Filter

A wildcard filter for topic names, used in subscription expressions to indicate multiple topics matched by the subscription.

Payload

The specific content received by message subscribers.

Face recognition all-in-one system architecture diagram based on MQTT protocol

From this picture you can see:

1.Mobile phones, PCs, servers, and all-in-one facial recognition machines are all clients in the MQTT protocol system, and they can all subscribe to and publish messages to specified topics.

2.MQTT Broker is a message proxy server that plays the role of forwarding messages.

Functionally analyzed:

1. As a server provider, the face recognition all-in-one machine subscribes to a topic (containing the ID that uniquely marks the face recognition all-in-one machine). Other clients (mobile phones, PCs, servers) need to operate a certain face recognition all-in-one machine. You must find the corresponding topic and publish the message to MQTT Broker according to the "Face Recognition All-in-one Machine MQTT Protocol API Document". MQTT Broker finds the corresponding subscriber through the topics published by other clients (mobile phones, PCs, servers), and sends the message Forwarded to the face recognition all-in-one machine, the purpose of operating the face recognition all-in-one machine through other clients (mobile phone, PC, server) can be achieved. There is a problem here. Under the same MQTT Broker, when two or more face recognition all-in-one machines subscribe to the same topic, when other clients (mobile phones, PCs, servers) publish operation messages to the topic, In fact, it will achieve the purpose of operating two devices at the same time. In the actual process, this situation is not allowed to happen, so different facial recognition all-in-one machines must subscribe to different topics. For specific topic design, please see "API Reference" 》In the topic definition chapter, at this time, the face recognition all-in-one machine acts as a subscriber, and other clients (mobile phones, PCs, servers) act as publishers. In this case, other clients need to know whether the operating device is correct, so at this time it is necessary Only by subscribing to a reply topic can you accept replies from the face recognition all-in-one machine. At this time, the face recognition all-in-one machine serves as the publisher and other clients serve as subscribers.

2. In addition to needing to be operated, the all-in-one face recognition machine also has the function of actively publishing messages to the outside world. For example, the all-in-one face recognition machine captures a picture, and then uses the picture to find the corresponding person information in the face database. Finally, Publish the person's information through the person's information. This function actually requires the client to subscribe to a topic, which is also uniquely owned by a certain face recognition all-in-one machine, and then the face recognition all-in-one machine publishes messages to the topic. Just the opposite of the situation described in Function 1. At this time, the face recognition all-in-one machine acts as a publisher and other clients (mobile phones, PCs, servers) act as subscribers. In this case, no other clients (mobile phones, PCs, etc.) are needed. server) publishes a reply message.

Basic Concept

Events: Events include blacklist, whitelist, and stranger events.

Device ID: Device ID is used to mark the uniqueness of the device in the MQTT protocol. If you want to operate a specified device, you must know the corresponding device ID.

Feature Overview

|Function Name|Function Description| | ------------ | ------------ | ----------- | ------------ | ------------ |------------ | |incident management|Events include blacklists, whitelists, and stranger events. After capturing the face information, the all-in-one machine will compare it with the person information in the face database, and then publish the results through the MQTT protocol.|

API Reference

Must read before use

Overview

Welcome to use the face recognition all-in-one machine MQTT service. The face recognition all-in-one machine MQTT service provides a lightweight, simple, open and easy-to-implement interface. Developers can use the API provided in this document to perform related operations on the face recognition all-in-one machine. , such as querying the face database, adding, deleting, modifying, querying the person information of the specified face database, authenticating the person information, and uploading stranger events, etc.

Call instructions

1. The face recognition all-in-one MQTT service uses json as the data exchange format at the application layer. This is a lightweight and cross-system and language platform text data exchange format. Data exchange is basically based on json, and the image content is Base64 encoded. .

MQTT Version

Developed based on MQTT3.0 version.

####Topic Format and Rules

The format of Topic is named in the form of URL. The Topic naming convention is as follows:

1. For topics that do not require a reply, the format is mqtt/ID/function, such as: publishing events, mqtt/1234/PublishEvent

2. The topic that needs to be replied is composed of two topics, one is mqtt/ID/function, the other is mqtt/ID/function/Ack, mqtt/1234/OperateDevice and mqtt/1234/OperateDevice/Ack

Topic definition rules:

1. Use different topics for different publishing directions. For example, publishing events from an all-in-one machine to "MQTT broken" and publishing commands for operating devices from a client (Phone/PC/server) to "MQTT broken" are two different directions. Topic is Different

2. For Topics that support replying, add the ack path at the end. For example, if the Topic is mqtt/1234/PublishEvent, then the corresponding reply Topic is mqtt/1234/PublishEvent/ack.

Message Format

For subscription operations, since it only interacts with the server, the data interaction format of the subscription operation depends on the specifications of the MQTT protocol.

For publishing operations, the data interaction format is as follows:

Post message style

{
    "operator": "Publish",
    "sessionId": "SID:1234567890-000001",
    "messageId": "MID:localhost-122334455667-12232323232323-000001",
    "info":
    {
        ……
    }
}

The parameters for publishing messages are described in the following table:

|Parameter|Description|Is it necessary| | ------------ | ------------ | ----------- | ------------ | ------------ |------------ | |operator|Operation flag|Yes| |sessionId|Session ID is used to distinguish each session. The session ID is composed of "SID:" mark, a 10-digit random value, and an accumulated value. The form is as follows：“SID:1234567890-000001”|Yes| |messageId|Message ID distinguishes each message. The message ID is composed of "MID:" tag, device unique tag, creation time, and accumulated value. The form is as follows“MID:localhost-122334455667-12232323232323-000001”|Yes| |info|Application layer data|No|

Post reply message style

{
    "operator": "Publish-Ack",
    "sessionId": "SID:1234567890-000001",
    "messageId": "MID:localhost-122334455667-12232323232323-000001",
    "info":
    {
          ……
    },
     "result":
    {
         "errorNo":"0",
          "description":"ok"
    }
}

The parameter description of publishing reply message is as follows:：

Notice：

1. For a certain publishing operation and publishing reply, sessionId and messageId are the same.

2. The publishing operation referred to here is not the same thing as the publishing event of the "Topic Definition" chapter. This is just an explanation of the operation with a reply on the application layer above MQTT, and the publishing of the "Topic Definition" chapter Events do not require the client to post a reply

3. Only the sessionId that has successfully logged in can operate the device and publish and reply to messages normally; the sessionId that has not logged in successfully cannot operate the device.

Basic Concept

Event

Events include blacklist, whitelist, and stranger events.

Device ID

Device ID is used to mark the uniqueness of a device in the MQTT protocol. If you want to operate a specified device, you must know the corresponding device ID.

ISO8601 Standard Introduction

The international standard ISO 8601 of the International Organization for Standardization is the representation method of date and time. Its full name is "Data Storage and Exchange Forms·Information Exchange·Representation Method of Date and Time". The latest version is currently ISO8601:2004, the third edition, the first edition is ISO8601:1988, and the second edition is ISO8601:2000.

Date Representation

The year consists of 4 digits. The year 1 AD is 0001, the year 1 BC is 0000, the year 2 BC is -0001, and so on. The application of other chronology requires conversion to the Gregorian calendar, but if both parties sending and receiving information have mutually agreed other chronology, they can apply it themselves.

Calendar Date Representation

The year is a 4-digit number, the month is a 2-digit number, and the day of the month is a 2-digit number. For example, May 3, 2004 can be written as 2004-05-03 or 20040503.

Sequential Date Representation

The number of days in a year can be expressed directly, with 365 days in an ordinary year and 366 days in a leap year. For example, May 3, 2004 can be expressed as 2004-157 or 2004157

Calendar week and day representation

You can use 2 digits to indicate the calendar week of the year, plus one digit to indicate the day of the calendar week, but a capital letter W must be added before the calendar week. For example, May 3, 2004 can be written as 2004 -W17-3 or 2004W173. But 2004-W011 starts on January 5, 2004, and the first few days belong to the 54th calendar week of the previous year. Each calendar week starts on Monday, and Sunday is the 7th day.

Day time representation

Hours, minutes, and seconds are all represented by 2 digits. UTC time is represented by a capital letter Z at the end. Other time zones are represented by the actual time plus the time difference. For example, 2:30 minutes and 5 seconds of UTC time is expressed as 14:30:05Z or 143005Z, and the Beijing time at that time is expressed as 22:30:05+08:00 or 223005+0800, which can also be simplified to 223005+08.

Combined representation of date and time

When expressing the combination, add a capital letter T in front of the time. If you want to express 5:30 minutes and 8 seconds on May 3, 2004 Beijing time, you can write it as 2004-05-03T17:30:08+08:00 or 20040503T093008 +08.

Time period representation

If you want to express a certain time period as a period of time, add a capital letter P in front of it, but add the corresponding capital letter representing time after the time period. For example, within one year, three months, five days, six hours, seven minutes and thirty seconds, it can be written as P1Y3M5DT6H7M30S.

Repetition time notation

Add a capital letter R in front. If you want to repeat half a year, 5 days and 3 hours from 1 pm Beijing time on May 6, 2004, and repeat it 3 times, it can be expressed as R3/20040506T130000+08/P0Y6M5DT3H0M0S.

Topic definition

Client operation all-in-one machineTopic

Post request

Mqtt/ID/OperateDevice

Post request response

Mqtt/ID/OperateDevice/Ack

All-in-one machine release event topic

Post request

Mqtt/ID/PublishEvent

Post request response None, the client does not need to publish a reply event

Heartbeat Event Topic

Post request

Same as publishing event Topic

Post request response

None, the client does not need to publish a reply event

How to call API

API

Agreement

1. For all API introductions, unless otherwise specified, the request/response message format refers to the application layer data format without the MQTT protocol field.

2. The request/response message parameters only explain the content of the info field. For other fields, please refer to the chapter on message format.

Verify

Features

Users can verify the client through this interface and obtain a legal sessionId. Once obtained, the sessionId will always exist until the user actively calls logout or the connection between the device and the server is disconnected, or the device is restarted. In addition, do not try to use different methods multiple times. Use sessionId to log in without logging out, because the device has a limit on the number of logins. The current limit is to allow up to 4 different sessionIds to log in.

Request message style

{
    "operator": "login",
    "sessionId": "SID:1234567890-000001",
    "messageId": "MID:localhost-122334455667-12232323232323-000001",
    "info":
    {
        "userName":"admin",
        "password":""
    }

}

Request message parameters

|Message field name|Description|Is it required| | ------------ | ------------ | ----------- | ------------ | ------------ |------------ | |userName|user name|Yes| |password|password|Yes|

Response message style

{ "operator":"login-Ack", "sessionId": "SID:1234567890-000001", "messageId": "MID:localhost-122334455667-12232323232323-000001", "result": { "errorNo":0, "description":"ok" } }

Response message parameters

None

Logout

Features

Users can log out of a sessionId through this interface.

Request message style

{
    "operator": "logout",
    "sessionId": "SID:1234567890-000001",
    "messageId": "MID:localhost-122334455667-12232323232323-000001",
    "info":"none"
}

Response message parameters

None

Response message style

{
        "operator":"logout-Ack",
        "sessionId": "SID:1234567890-000001",
        "messageId": "MID:localhost-122334455667-12232323232323-000001",
        "result":
        {
        "errorNo":0,
        "description":"ok"
        }
}

Response message parameters

None

Transparent transmission of CGI configuration

Features

　　Users can transparently transmit CGI configuration through MQTT through this request.

#####Request message style

{
    "operator": "transportCGIConfig",
    "sessionId": "SID:1234567890-000001",
    "messageId": "MID:localhost-122334455667-12232323232323-000001",
    "info": {
        "request": "GET /System/DeviceCap"
    }
}

Response message parameters

Message field name	Description	Is it required
request	Transparently transmitted cgi configuration information	Yes

Response message style

{
    "operator": "transportCGIConfig-Ack",
    "sessionId": "SID:1234567890-000001",
    "messageId": "MID:localhost-122334455667-12232323232323-000001",
    "info": "none",
    "result": {
        "errorNo": 0,
        "description": "ok"
    }
}

Response message parameters

Message field name	Description	Is it required
info	CGI request reply information	Yes

Cloud Upgrade

Configure the cloud upgrade server and upgrade firmware information

Features

Users can use this request to upgrade the device.

Request message style

{
    "operator": "setCloudUpgradeConfig",
    "sessionId": "SID:1234567890-000001",
    "messageId": "MID:localhost-122334455667-12232323232323-000001",
    "info": {
        "serverConfig": {
            "port": 21,
            "host": "139.9.6.140",
            "userName": "dWZ0cA==",
            "password": "ZWNobzEyMw==",
            "protocol": "ftp",
            "path": "/download/DAP-2020SSA_3200_6200/C007V001/"
        },
        "fileInfo": {
            "firmwareName": "DAP-2020SSA_V1.3.2_20200702.bin ",
            "md5sum": "434092e44c45b65ba66ea086f697fc02",
            "upgradeFileSize": 66143
        }
    }
}

Request message parameters

Message field name	Description	Is it required
serverConfig		Yes
port	Server Port	Yes
hostIp	Server domain name or IP	Yes
userName	Username, base64 encoded	Yes
password	Password, base64 encoded	Yes
protocol	Protocol, values http and ftp	Yes
path	url	Yes
fileInfo		Yes
passPort	Upgrade process credentials	Yes
firmwareName	firmware name	Yes
md5sum	The md5 value of the file is used for verification	Yes
upgradeFileSize	The size of the file, in bytes, used for verification	Yes

Description: The fields protocol, hostIp, port, path, and firmwareName together form the accessible upgrade firmware team members. userName and password ensure the security of the upgrade. md5sum and upgradeFileSize prevent the file from being tampered with.

Response message style

{
    "operator":"setCloudUpgradeConfig-Ack",
    "sessionId": "SID:1234567890-000001",
    "messageId": "MID:localhost-122334455667-12232323232323-000001",
    "info":"none",
     "result":
    {
      "errorNo":0,
      "description":"ok"
    }
}

Response message parameters

None

Product Description

MQTT Protocol

MQTT Introduction

MQTT Protocol Implementation

MQTT Client

MQTT Server

Subscriptions, topics, and sessions in the MQTT protocol

Subscription

Session

Topic Name

Topic Filter

Payload

Face recognition all-in-one system architecture diagram based on MQTT protocol

Basic Concept

Feature Overview

API Reference

Must read before use

Overview

Call instructions

MQTT Version

Topic definition rules:

Message Format

Post message style

The parameters for publishing messages are described in the following table:

Post reply message style

The parameter description of publishing reply message is as follows:：

Basic Concept

Event

Device ID

ISO8601 Standard Introduction

Date Representation

Calendar Date Representation

Sequential Date Representation

Calendar week and day representation

Day time representation

Combined representation of date and time

Time period representation

Repetition time notation

Topic definition

Client operation all-in-one machineTopic

All-in-one machine release event topic

Heartbeat Event Topic

How to call API

API

Agreement

Verify

Login

Features

Request message parameters

Response message style

Response message parameters

Logout

Features

Request message style

Response message parameters

Response message style

Response message parameters

Transparent transmission of CGI configuration

Features

Response message parameters

Response message style

Response message parameters

Cloud Upgrade

Configure the cloud upgrade server and upgrade firmware information

Features

Users can use this request to upgrade the device.

Request message style