IPC Notification Center

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.

ParameterTypeDescriptionRequired
event_listarray[string]Topic list, the following is allowed. “face_recog_event” is only supported by “FM020”.
[“face_recog_event”,”dynamic_detect_event”]
Y
http_callbackstringCallback url. The IPC will post a message to this url when something related happened.Y

Response Parameters

ParameterTypeDescription
codeintReturn 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&timestamp=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.

ParameterTypeDescriptionRequired
event_listarray[string]opic list, the following is allowed. “face_recog_event” is only supported by “FM020”.
[“face_recog_event”,”dynamic_detect_event”]
Y

Response Parameters

ParameterTypeDescription
codeintReturn 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&timestamp=15930292837&sign=IDKNFLK392038KDS932K&
event_list= [“dynamic_detect_event”, “face_recog_event”]

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

ParameterTypeDescription
codeintReturn code, represent the request result, possible return codes are 0, 1, 5, see Error Code for further details.
sub_eventarraySubscriber list
eventstringTopic
http_callbackarrayHttp callback of the topic
numstringNumber 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&timestamp=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.

ParameterTypeDescription
event_idlongEvent ID
event_type stringEvent Type
report_timelongTimestamp of event
detect_typeintType of dynamic detect:
0: Motion Detected
1: Audio Detected
2: Motion and Audio Detected
3: Detected Human
video_urlstringDownload url of the video
snstringSerial 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″,”cloud_faceid”:”8798765433″,”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.

ParameterTypeDescription
event_idlongEvent ID
event_typestringEvent Type
snstringSerial number of IPC which send this message
report_timelongTimestamp of event
faceidstringFace ID
cloud_faceidstringFace ID used in Sunmi Store
group_namestringName of group which the face belong to
ageintAge, if it’s blank, it means that the age of this face has not set yet
age_rangeintRange 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
genderintGender
0 — Undefined
1 — Male
2 — Female
arrive_timesintTotal times of arrival
pic_urlstringUrl of face picture
item1stringUser-defined attribute, only returned if exist
item2stringUser-defined attribute, only returned if exist
item3 stringUser-defined attribute, only returned if exist
item4stringUser-defined attribute, only returned if exist
item5stringUser-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

TypeValueDirectionDescription
Reserved0ProhibitReserved
CONNECT1Client to ServerClient send this message to establish connection
CONNACK2Server to ClientConnection acknowledge message sent by server, the content marks whether the connection is legal or not
PINGREQ3Client to ServerHeartbeat request
PINGRESP4Server to ClientHeartbeat response
SUBSCRIBE5Client to ServerClient send this message to subscribe events
SUBACK6Server to ClientConfirmation of subscription
UNSUBSCRIBE7CLient to ServerClient send this message to unsubscribe events
UNSUBACK8Server to ClientConfirm of unsubscription
PUBLISH9Client to Server, or Server to ClientOnly server can publish message to client for the moment
PUBACK10 Client to Server, or Server to Client Acknowledge to published message
DISCONNECT11 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.

NameTypeDescription
event_idlongEvent ID
event_typestringEvent Type
report_timelongTimestamp of the event
detect_typeintType of dynamic detect:
1: picture changed
2: voice changed
3: picture and voice changed
video_urlstringURL of video
snstringSerial 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",
    "cloud_faceid":"8798765433",
    "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.

NameTypeDescription
event_idlongEvent ID
event_typestringEvent Type
snstringSerial number of IPC which send this message
report_timelongTimestamp of event
faceidstringFace ID
cloud_faceidstring Face ID used in Sunmi Store
group_namestringName of group which the face belong to
ageintAge, if it’s blank, it means that the age of this face has not set yet
age_rangeintRange 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.
genderintGender
0– Undefined;
1– Male;
2– Female.
arrive_timesintTotal times of arrival
pic_urlstringUrl of face picture
item1stringUser-defined attribute, only returned if exist.
item2stringUser-defined attribute, only returned if exist.
item3stringUser-defined attribute, only returned if exist.
item4stringUser-defined attribute, only returned if exist.
item5stringUser-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.

NameTypeDescription
event_idlongEvent ID

2.6 Disconnect

The header of this message is 0x11, and the payload is empty.