- 1. Post Message
- 2. Message Channel
- 2.1 Protocol
- 2.2 Connection Establishment
- 2.3 Hartbeat
- 2.4 Subscribe
- 2.5 Publish Message
- 2.6 Disconnect
There are two ways to get IPC message. Firstly, if some event is subscribed, the IPC will post a message to related callback url. Secondly, we can maintain a TCP connection to get related message.
1. Post Message
We can subscribe some topic to IPC, and the IPC will post a http message to the subscribers when something relative happened. It has the same function as Message Channel.
1. 1 Signature
Refer to Sign Rules.
1.2 Subscribe
1.2.1 Subscribe
Description
This API is used to subscribe some topic to IPC. The IPC will post a http message to the callback url passed in by this API when something related happened, thus the subscribe is informed.
Request link
https://192.168.0.1/openapi/hook/add, 192.168.0.1 needs to be replaced by the IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
| Parameter | Type | Description | Required |
| event_list | array[string] | Topic list, the following is allowed. “face_recog_event” is only supported by “FM020”. [“face_recog_event”,”dynamic_detect_event”] | Y |
| http_callback | string | Callback url. The IPC will post a message to this url when something related happened. | Y |
Response Parameters
| Parameter | Type | Description |
| code | int | Return code, represent the request result, possible return codes are 0, 1, 2, 5, 310, 311, see Error Code for further details. |
Request Example
| POST openapi/hook/add HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K& event_list=[“face_recog_event”,”dynamic_detect_event”]&http_callback=http://192.168.0.100/msg |
Response Example
{
"code": 0
}1.2.2 Unsubscribe
Description
This api is used to unsubscribe some topic that is already subscribed. The subscriber will not receive relative messages once relative topic unsubscribed.
Request link
https://192.168.0.1/openapi/hook/delete, 192.168.0.1 needs to be replaced by the IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
| Parameter | Type | Description | Required |
| event_list | array[string] | opic list, the following is allowed. “face_recog_event” is only supported by “FM020”. [“face_recog_event”,”dynamic_detect_event”] | Y |
| http_callback | string | Callback url. The IPC will only unsubscribe the topic that is already subscribed with this url. |
Response Parameters
| Parameter | Type | Description |
| code | int | Return code, represent the request result, possible return codes are 0, 1, 2, 5, 310, see Error Code for further details. |
Request Example
| POST openapi/hook/delete HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K& event_list=[“dynamic_detect_event”,”face_recog_event”]&http_callback=http://192.168.0.100/msg |
Response Example
{
"code": 0
}1.2.3 Query subscribed message
Description
This API is used to query all topics and callbacks that subscribed to the IPC. When something related happened, the IPC will post a http message to relative callback urls.
Request link
https://192.168.0.1/openapi/hook/query, needs to be replaced by the IP address of IPC.
Request Parameters
No private parameter for this API, please refer to Public Parameters for more details.
Response Parameters
| Parameter | Type | Description |
| code | int | Return code, represent the request result, possible return codes are 0, 1, 5, see Error Code for further details. |
| sub_event | array | Subscriber list |
| event | string | Topic |
| http_callback | array | Http callback of the topic |
| num | string | Number of the subscriber of the topic |
Request Example
| POST openapi/hook/query HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K& |
Response Example
{
"data": {
"num": 2,
"sub_event": [
{
"event": "face_recog_event",
"http_callback": [
"10.10.61.206:8000"
]
},
{
"event": "dynamic_detect_event",
"http_callback": [
"10.10.61.206:8000"
]
}
]
},
"code": 0
}1.3 Post
The IPC will post a http message to inform subscribers. The http post is formed in form table, the “Content-Type” is “multipart/form-data”, the payload of message is packaged in “payload”.
Dynamic Detect Message
The payload is formatted as follow：
| POST / HTTP/1.1 Host: 10.10.61.206:8000 User-Agent: libcurl/7.52.1 OpenSSL/1.0.2p Accept: */* Content-Length: 826 Expect: 100-continue Content-Type: multipart/form-data; boundary=————————c83c36cd4ee4082f ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”app_id” 123 ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”random” 692777 ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”timestamp” 1579158766 ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”sign” 372F669601E8347737744FFC88B74665 ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”payload” {“event_id”:1,”detect_type”:2,”video_url”:”https://10.10.63.19/mnt/sd-card/sunmi_video/video_detect/1579158761.flv?auth_key=1579158765-d701e761fecf0df84853440d4dbc3fe1″,”event_type”:”dynamic_detect_event”,”sn”:”SS101D8BS00080″,”report_time”:1579158765} ————————–c83c36cd4ee4082f– |
The fields of the payload is described as follow.
| Parameter | Type | Description |
| event_id | long | Event ID |
| event_type | string | Event Type |
| report_time | long | Timestamp of event |
| detect_type | int | Type of dynamic detect: 0: Motion Detected 1: Audio Detected 2: Motion and Audio Detected 3: Detected Human |
| video_url | string | Download url of the video |
| sn | string | Serial number of IPC which send this message |
Face Recognize Message
The payload is formatted as follow.
| POST / HTTP/1.1 Host: 192.168.103.173:8010 User-Agent: libcurl/7.52.1 OpenSSL/1.0.2p Accept: */* Content-Length: 906 Content-Type: multipart/form-data; boundary=————————7faeecefd4fb5aaf ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”app_id” KJQJ89V956U9O9UI ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”random” 956429 ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”timestamp” 1597894809 ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”sign” 004B3CD3FACB562E06CC04A0935410A5 ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”payload” {“event_id”:2,”faceid”:”358526″,”group_name”:”db_0″,”age”:0,”age_range”:5,”gender”:0,”arrive_times”:3,”pic_url”:”https://192.168.103.117/mnt/sd-card/sunmi_image/snap/1597894624456_7.jpg?auth_key=1597894624-f88c2f9a6e69834430648c2f4931ffae”,”event_type”:”face_recog_event”,”sn”:”FS101D8BS00080″,”report_time”:1597894809} ————————–7faeecefd4fb5aaf– |
The payload is formatted as follow.
| Parameter | Type | Description |
| event_id | long | Event ID |
| event_type | string | Event Type |
| sn | string | Serial number of IPC which send this message |
| report_time | long | Timestamp of event |
| faceid | string | Face ID |
| group_name | string | Name of group which the face belong to |
| age | int | Age, if it’s blank, it means that the age of this face has not set yet |
| age_range | int | Range of age 1 — 1 to 6 years old 2 — 7 to 12 years old 3 — 13 to 18 years old 4 — 19 to 28 years old 5 — 29 to 35 years old 6 — 36 to 45 years old 7 — 45 to 55 years old 8 — 55 to 100 years old |
| gender | int | Gender 0 — Undefined 1 — Male 2 — Female |
| arrive_times | int | Total times of arrival |
| pic_url | string | Url of face picture |
| item1 | string | User-defined attribute, only returned if exist |
| item2 | string | User-defined attribute, only returned if exist |
| item3 | string | User-defined attribute, only returned if exist |
| item4 | string | User-defined attribute, only returned if exist |
| item5 | string | User-defined attribute, only returned if exist |
2. Message Channel
Message channel allows user to maintain a tcp connect with IPC to communicate with IPC, it has the same function as Post Message.
2.1. Protocol
Protocol
The message channel use TCP connection with SSL to ensure the security of data. The protocol is implemented as Client/Server mode where the IPC is the server on port 10021.
Protocol Format
The protocol message, which consists of header, payload and CRC checksum, is described briefly in this section, as shown in the figure below.
- Header
Flag
The “Flag” is fixed to 0xFF3E3EFF indicating it is using message channel.
Version
The “Version” describes the version of the protocol, it’s 0x01 for the moment. The protocol is backward compatible.
Packet Type
| Type | Value | Direction | Description |
|---|---|---|---|
| Reserved | 0 | Prohibit | Reserved |
| CONNECT | 1 | Client to Server | Client send this message to establish connection |
| CONNACK | 2 | Server to Client | Connection acknowledge message sent by server, the content marks whether the connection is legal or not |
| PINGREQ | 3 | Client to Server | Heartbeat request |
| PINGRESP | 4 | Server to Client | Heartbeat response |
| SUBSCRIBE | 5 | Client to Server | Client send this message to subscribe events |
| SUBACK | 6 | Server to Client | Confirmation of subscription |
| UNSUBSCRIBE | 7 | CLient to Server | Client send this message to unsubscribe events |
| UNSUBACK | 8 | Server to Client | Confirm of unsubscription |
| PUBLISH | 9 | Client to Server, or Server to Client | Only server can publish message to client for the moment |
| PUBACK | 10 | Client to Server, or Server to Client | Acknowledge to published message |
| DISCONNECT | 11 | Client to Server, or Server to Client | Disconnect |
Length
“Length” is the length of the payload, which range from 0 to 65535.
- Payload
“Payload” is the actual content of the message, which formatted with json. The payload is different for each packet type.
- CRC Checksum
“CRC” is the CRC(Cyclic Redundancy Check) checksum of payload, which occupies 4 bytes.
2.2 Connection Establishment
The connection is initiated by client, and IPC act as server.
- Initiate connection
The Packet Type of the message is 0x01, and the payload is formatted as bellow. The client will insert some parameters in payload, and sign the payload with secret key. The signature rule is described in Sign Rules section. The server check whether the content is legal with the same signature rule.
{
"app_id": "mdk923idkf",
"timestamp": "15930292837",
"random": "289192",
"sign": "IDKNFLK392038KDS932K",
"keep_alive": 30
}keep_alive: The period of heartbeat in unit of second, which can be specified by client.
- Acknowledge to connection
The Packet Type of the message is 0x02, and the payload is formatted as bellow. The “code” represents the request result, possible return codes are 0, 1, 2, 3, 5, 7, refer to Error Code for more details.
{
"code": 0
}2.3 Heartbeat
The client send heartbeat message to server with specified period, and the server will disconnect after 3 heartbeat messages.
- Heartbeat request
The header of the message is 0x03, and the payload is empty.
- Heartbeat response
The header of the message is 0x04, and the payload is empty.
2.4 Subscribe
The client subscribes message to server.
- Subscribe or unsubscribe
The header of the message is 0x05 or 0x07, and the payload is formatted as bellow.
{
"event_list": [
"dynamic_detect_event",
"face_recog_event"
]
}The fields of the payload is described as bellow.
| Parameter | Type | Description |
| event_list | string | List of events to be subscribed |
The supported events is listed bellow.
| Event Type | Description |
| dynamic_detect_event | Dynamic detect event |
| face_recog_event | Face recognition event |
- Response of subscribe or unsubscribe
The header of the message is 0x06 or 0x07, and the payload is formatted as follow. The “code” represents the request result, possible return codes are 0, 1, 2, 3, 5, 7, 310, 311, refer to Error Code for more details.
{
"code": 0
}2.5 Publish message
- Publish
The IPC server publishe messages to client. The header of the message is 0x09, and the payload is different with event.
- Dynamic detect message
The payload is formatted as follow.
{
"event_id": 1,
"event_type": "dynamic_detect_event",
"sn": "FS101D8BS00106",
"report_time": 15930292837,
"detect_type": 1,
"video_url": "https://192.168.0.1/mnt/sd-card/sunmi_video/video_detect/1565535983.flv?auth_key=1564129415215f61f3c5f552c5bf8f43ccef5c66a9"
}The fields of the payload is described as follow.
| Name | Type | Description |
|---|---|---|
| event_id | long | Event ID |
| event_type | string | Event Type |
| report_time | long | Timestamp of the event |
| detect_type | int | Type of dynamic detect: 1: picture changed 2: voice changed 3: picture and voice changed |
| video_url | string | URL of video |
| sn | string | Serial number of the IPC which send this message |
- Face recognize message
The payload is formatted as follow.
{
"event_id": 2,
"event_type": "face_recog_event",
"sn": "FS101D8BS00106",
"report_time": 15930292837,
"group_name": "vip",
"faceid": "00000001",
"age": 10,
"gender": 2,
"arrive_times": 4,
"pic_url":"https://192.168.103.117/mnt/sd-card/sunmi_image/snap/1597894624456_7.jpg?auth_key=1597894624-f88c2f9a6e69834430648c2f4931ffae",
"vip_level": "1",
"hobby": "tennis",
"weight": "60",
"height": "180"
}The fields of the payload is described as follow.
| Name | Type | Description |
|---|---|---|
| event_id | long | Event ID |
| event_type | string | Event Type |
| sn | string | Serial number of IPC which send this message |
| report_time | long | Timestamp of event |
| faceid | string | Face ID |
| group_name | string | Name of group which the face belong to |
| age | int | Age, if it’s blank, it means that the age of this face has not set yet |
| age_range | int | Range of age 1– 1 to 6 yeares old; 2– 7 to 12 years old; 3– 13 to 18 years old; 4– 19 to 28 years old; 5– 29 to 35 years old; 6– 36 to 45 years old; 7– 45 to 55 years old; 8– 55 to 100 years old. |
| gender | int | Gender 0– Undefined; 1– Male; 2– Female. |
| arrive_times | int | Total times of arrival |
| pic_url | string | Url of face picture |
| item1 | string | User-defined attribute, only returned if exist. |
| item2 | string | User-defined attribute, only returned if exist. |
| item3 | string | User-defined attribute, only returned if exist. |
| item4 | string | User-defined attribute, only returned if exist. |
| item5 | string | User-defined attribute, only returned if exist. |
- Acknowledge to publish
If the subscriber received this message, it should return acknowledge. The header of the message is 0x0a, and the payload is formatted as fellow.
{
"event_id": 1
}The fields of the payload is described as follow.
| Name | Type | Description |
|---|---|---|
| event_id | long | Event ID |
2.6 Disconnect
The header of this message is 0x11, and the payload is empty.
