IPC消息中心

IPC设备产生的实时消息客户端可通过两种方式获得:一是用户通过订阅相关事件并给出回调地址,IPC产生相关消息时会向对应回调地址发送一个POST消息; 二是用户可通过与IPC建立长连接来传递 。

1. 消息推送

消息推送是客户端向IPC订阅相关的消息事件,当IPC产生消息事件是,会像订阅的回调地址发送一条http post消息,通知客户端,其实现的功能与消息通道一节一致。

1. 1 签名规则

签名规则一节一致。

1.2 订阅管理

1.2.1 订阅消息

描述

订阅消息接口用于向IPC设备端订阅相关的消息,一旦订阅了消息,当设备端产生了相关消息的时候,便会向订阅时传入的回调接口发送一个HTTP POST消息,从而达到通知订阅者的目的。

请求地址

https://192.168.0.1/openapi/hook/add,192.168.0.1需要替换成实际的IPC地址。

请求参数

这里只列出接口的私有参数,公共参数见公共参数一节描述。

参数名称类型描述是否必须
event_listarray[string]事件类型,可以是[“face_recog_event”,”dynamic_detect_event”]或者其中一个,其中” face_recog_event “仅FM020支持 Y
http_callbackstring回调含函数地址,当IPC产生相关消息时,会向该地址发送一个http post消息Y

响应参数

字段名称类型描述
codeint返回码,表示操作的结果;
本接口返回码有0、1、2、5、310、311,见错误码的描述

请求示例

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

返回示例

{
     ‘code’:          0,
}

1.2.2 取消已订阅消息

描述

用于取消已经向IPC设备端订阅过的消息,取消订阅后,当设备端产生相关消息时,便不会向对应的回调地址发送HTTP POST消息。

请求地址

https://192.168.0.1/openapi/hook/delete,192.168.0.1需要替换成实际的IPC地址。

请求参数

这里只列出接口的私有参数,公共参数见公共参数一节描述。

参数名称类型描述是否必须
event_listarray[string]事件类型,可以是[“face_recog_event”,”dynamic_detect_event”]或者其中一个,其中” face_recog_event “仅FM020支持 Y

响应参数

字段名称类型描述
codeint返回码,表示操作的结果;
本接口返回码有0、1、2、5、310,见错误码的描述

请求示例

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”]

返回示例

{
     ‘code’:          0,
}

1.2.3 查询所有已订阅消息

描述

用于查询IPC设备端所有订阅的消息,当设备端产生相关消息时,会向对应的回调地址发送HTTP POST消息。

请求地址

https://192.168.0.1/openapi/hook/query,192.168.0.1需要替换成实际的IPC地址。

请求参数

此接口不需要私有参数,公共参数见公共参数一节描述。

响应参数

字段名称类型 描述
code int 返回码,表示操作的结果; 本接口返回码有0、1、5,见错误码的描述
sub_event array 订阅列表
event string 订阅的事件类型
http_callback array 订阅该事件的所有回调地址列表
num string 订阅事件的个数

请求示例

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&

返回示例

{
    “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 推送消息

IPC通过HTTP POST的方式推送消息,会提交form表单,Content-Type为multipart/form-data,消息内容封装在payload中。

动态侦测消息

动态侦测消息如下:

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–

消息有效载荷在payload中,各字段内容如下:

参数名称 类型 描述
event_id long 事件ID
event_type string 事件类型
report_time long 事件发生的时间戳
detect_type int 动态侦测检测到的类型,1表示画面变化,2表示声音变化,3表示既有画面变化,也有声音变化
video_url string 视频下载路径
sn string 发出此消息的IPC序列号

人脸识别消息

人脸识别消息如下:

POST / HTTP/1.1
Host: 10.10.61.206:8000
User-Agent: libcurl/7.52.1 OpenSSL/1.0.2p
Accept: */*
Content-Length: 754
Expect: 100-continue
Content-Type: multipart/form-data; boundary=————————5f23be055fbf1892
 
————————–5f23be055fbf1892
Content-Disposition: form-data; name=”app_id”
 
123
————————–5f23be055fbf1892
Content-Disposition: form-data; name=”random”
 
961393
————————–5f23be055fbf1892
Content-Disposition: form-data; name=”timestamp”
 
1579164100
————————–5f23be055fbf1892
Content-Disposition: form-data; name=”sign”
 
C6271C57FA269CCBCCD0225EF37D0AC3
————————–5f23be055fbf1892
Content-Disposition: form-data; name=”payload”
 
{“event_id”:2,”faceid”:”3″,”group_name”:”stranger”,”age”:0,”age_range”:5,”gender”:1,”arrive_times”:1,”event_type”:”face_recog_event”,”sn”:”FS101D8BS00080″,”report_time”:1579164100}
————————–5f23be055fbf1892–

消息有效载荷在payload中,各字段内容如下:

参数名称 类型 描述
event_id long 事件ID
event_type string 事件类型
sn string 发出此消息的IPC序列号
report_time long 事件发生的时间戳
faceid string 人脸ID
group_name string 所在分组名称
age int 年龄,为空则表示用户没有设置过此人脸的年龄
age_range int 所属年龄段,1表示1~6岁,2表示7~12岁,3表示13~18岁,4表示19~28岁,5表示29~35岁,6表示36~45岁,7表示45~55岁,8表示55岁~100
gender int 性别,0表示未知,1表示男性,2表示女性
arrive_times int 到达过的总次数
item1 string 自定义属性1,用户添加过才会返回
item2 string 自定义属性2,用户添加过才会返回
item3 string 自定义属性3,用户添加过才会返回
item4 string 自定义属性4,用户添加过才会返回
item5 string 自定义属性5,用户添加过才会返回

2. 消息通道

消息通道是客户端与IPC设备维持的一条长连接,用于IPC设备主动向客户端实时推送消息事件。其实现的功能与消息推送一节一致。

2.1. 消息协议

通信协议端口

通信协议采用TCP连接,同时为了保证数据的安全性,采用SSL套接字,是C/S模式,IPC设备是Server。Server端的端口暂时固定为10021。

通信格式

本节简述报文格式,主要由头部、载荷和CRC校验和构成;如下图所示。

  • 头部

Flag

为协议标识符,暂定为0xFF3E3EFF。

Version

本协议的版本号,目前为0x01,高版本兼容低版本。

Packet Type

包类型,目前支持如下:

类型 方向 描述
保留 0 禁止 保留
CONNECT 1 客户端到服务端 客户端发起建立消息通道的报文
CONNACK 2 服务端到客户端 连接确认报文,报文内容会标志连接是否合法
PINGREQ 3 客户端到服务端 心跳请求
PINGRESP 4 服务端到客户端 心跳响应
SUBSCRIBE 5 客户端到服务端 客户端订阅消息事件
SUBACK 6 服务端到客户端 订阅请求确认
UNSUBSCRIBE 7 客户端到服务端 客户端取消订阅消息事件
UNSUBACK 8 服务端到客户端 取消订阅请求确认
PUBLISH 9 两个方向都可以 目前来说只支持服务端到客户端的消息发布
PUBACK 10 两个方向都可以 发布消息收到确认
DISCONNECT 11 客户端到服务端 断开连接

Length

为载荷长度,范围是0 ~ N,N最大是65535。

  • 载荷Payload

载荷就是实际的报文内容,采用json格式。根据Packet Type的不同而不一样。

  • CRC校验和

是Payload的CRC校验和,占用4B。

2.2 建立连接

由客户端发起到IPC服务端的连接。

  • 发起连接

报头包类型为0x01,报文载荷格式如下,客户端带上一些参数,并用secret key做签名,详见签名规则一节的介绍。服务端会采用同样的规则来检查客户端的连接是否合法。

{
“app_id”:”mdk923idkf”,
“timestamp”:”15930292837″,
“random”:”289192″,
“sign”:”IDKNFLK392038KDS932K”,
“keep_alive”:30
}

keep_alive:心跳包的周期,以秒为单位,有客户端根据实际情况指定心跳周期。

  • 响应连接

报头包类型为0x02,报文内容如下。code 为返回码,表示操作的结果。本接口返回码有 0、1、2、3、5、7,见错误码描述。

{
“code”:0
}

2.3 心跳

客户端根据预定好的心跳周期,周期性地向服务端发送心跳报文,服务端会在3次都没有收到心跳报文后,断开连接。

  • 心跳请求

报头类型为0x03,没有载荷。

  • 心跳响应

报头类型为0x04,没有载荷。

2.4 订阅消息

由客户端向服务端订阅消息事件。

  • 发起订阅(或取消订阅)

报头类型为0x05(或0x07),载荷内容如下:

{
“event_list”:[
“dynamic_detect_event”,
“face_recog_event”
]
}

字段解释如下

参数名称 类型 描述
event_list string 需要订阅的消息事件列表

目前支持事件列表如下

事件类型 描述
dynamic_detect_event 动态侦测消息
face_recog_event 人脸识别消息(仅FM020支持)
  • 响应订阅(或响应取消订阅)

报头类型为0x06(或0x07),载荷内容如下。code 为返回码,表示操作的结果。本接口返回码有 0、1、2、3、5、7、310、311,见错误码描述。

{
“code”:0
}

2.5 发布消息

  • 发布消息

由IPC服务端推送消息到客户端,报头类型为0x09,内容因事件类型不同而有所不同。

  • 动态侦测消息

报文载荷内容如下:

{
“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″
}

各字段如下:

参数名称 类型 描述
event_id long 事件ID
event_type string 事件类型
report_time long 事件发生的时间戳
detect_type int 动态侦测检测到的类型,1表示画面变化,2表示声音变化,3表示既有画面变化,也有声音变化
video_url string 视频下载路径
sn string 发出此消息的IPC序列号
  • 人脸识别消息

报文内容如下:

{
“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,
“vip_level”:”1″, //自定义属性,用户定义了才会有,这里是举例
“hobby”:”tennis”, //自定义属性
“weight”:”60″, //自定义属性
“height”:”180″ //自定义属性
}

各字段描述如下

参数名称 类型 描述
event_id long 事件ID
event_type string 事件类型
sn string 发出此消息的IPC序列号
report_time long 事件发生的时间戳
faceid string 人脸ID
group_name string 所在分组名称
age int 年龄,为空则表示用户没有设置过此人脸的年龄
age_range int 所属年龄段,1表示1~6岁,2表示7~12岁,3表示13~18岁,4表示19~28岁,
5表示29~35岁,6表示36~45岁,7表示45~55岁,8表示55岁~100
gender int 性别,0表示未知,1表示男性,2表示女性
arrive_times int 到达过的总次数
item1 string 自定义属性1,用户添加过才会返回
item2 string 自定义属性2,用户添加过才会返回
item3 string 自定义属性3,用户添加过才会返回
item4 string 自定义属性4,用户添加过才会返回
item5 string 自定义属性5,用户添加过才会返回
  • 发布消息确认

如果订阅者收到此消息,则返回确认。报头类型为0x0a,内容如下。

{
“event_id”:1
}

报文字段描述如下:

参数名称 类型 描述
event_id long 正常接收的消息ID

2.6 断开连接

报头类型为0x11,载荷内容为空。