消息服务接入指南

准备工作

在开始之前，您需要进行以下准备工作：

登录臻云极致并将设备绑定到您的账号下，参见快速体验，需要注意的是，您只能访问绑定到您账号及子账号下的设备。
在臻云极致管理控制台下创建AccessKey，参见签名认证。

请注意：H系列设备一般不会连接到臻云极致平台，如果需要对接，请前往CPS平台

获取MQTT客户端

消息服务是依托MQTT协议来实现的，推荐你先了解MQTT相关的知识。该功能的接入需要用到使用任意语言开发的MQTT客户端，主要有：

开发语言	推荐MQTT客户端
C	Eclipse Paho C
C++	Eclipse Paho C++
C#	Eclipse Paho C#
Java	Eclipse Paho Java
Android	Eclipse Paho Andriod
iOS	MQTT-Client Framework
Python	Eclipse Paho Python
Golang	Eclipse Paho Golang
PHP	Mosquitto-PHP
JavaScript	Eclipse Paho JavaScript

其他语言的MQTT客户端可以访问mqtt.github进行下载。

注意：

当前消息服务仅支持标准的MQTT v3.1.1协议，不兼容MQTT v5或MQTT V3。
支持通配符订阅，参见通配符订阅
支持共享订阅，参见共享订阅
不支持CleanSession=false，请在每次掉线后重新订阅设备消息
不支持保留消息，发布的消息请将Retained标志置为false
不支持遗嘱消息
不支持QoS2消息

获取MQTT连接信息

使用消息服务订阅设备消息或者发送消息给设备之前，需要先获取连接消息服务器的信息，参考获取MQTT连接信息。

连接消息服务器

选择适合你使用的开发语言的MQTT客户端，并使用服务器返回的登录信息设置以下参数（各种语言中设置方法可能不一样）：

broker: "tcp://[host]:[port]"
username: "[username]"
password: "[password]"
client id: "[clientid]"
clean session: true # 可选；开启后，当客户端异常掉线时可能会丢失消息
keep alive: 30 # 可选；单位为秒

注意事项：

必须使用获取到的MQTT连接信息进行MQTT的连接操作，不能改动任何一个值，否则您肯定连接不上。
不能将获取到的MQTT连接信息存起来重复使用，每次连接MQTT之前都应该使用此接口获取新的MQTT连接信息再使用，否则你很可能出现连接不上的问题，因为密码有过期时间。

订阅设备状态

MQTT连接成功后，订阅此topic可以立即收到设备的当前状态，当设备状态变更，也会立即收到通知。

订阅Topic

device/${sn}/event/state

消息示例

{
    "id": "", # 消息ID
    "sn": "12345678-87654321", # 设备SN
    "name": "online", # online是在线；offline是离线
    "will": false, # 是否是遗言消息（若不懂，请查询MQTT遗言机制）
    "proxy": "", # 不用管
    "timestamp": 1597281588 # 时间戳，若是遗言，此时间戳不是离线时间
}

订阅设备消息

您可以订阅设备提供的消息，但不同类型的设备提供的消息是不一样的，具体需要以提供的协议文档为主，下面以路侧产品（H系列）的订阅识别结果（ivs_result）为例进行说明。

订阅Topic

device/${sn}/message/up/${name}

{sn}为设备的序列号，无法订阅不属于您的设备消息
{name}为消息的名称，在此例子中就是ivs_result

在此例中，topic为device/12345678-87654321/message/up/ivs_result，若订阅成功，当设备产生识别结果时你将收到此数据。当订阅的设备不属于你，或者订阅的消息名称不正确，订阅将失败，按照MQTT协议，订阅失败将返回0x80错误码，请确保使用的MQTT客户端能够返回此错误码。

消息示例

{
  "id": "c9uKOgYZqIeSgRI4", # 消息ID
  "bv": 12309, # 设备board_version
  "sn": "12345678-87654321", # 设备序列号
  "name": "ivs_result", # 消息名称
  "version": "1.0", # 消息版本
  "payload": {
    "alarm_info": {
      "alarm_status": 0
    },
    "bg_img": [
      {
        "image": "bg_image_0",
        "image_length": 950541,
        "image_send_flag": 1,
        "key": 92,
        "path": "aW1ncy9iZTAzNDUzYS0xMGU5MTkwYy8yMDIwMDgxMy8xNTk3Mjg1ODY0XzFfMF9mdWxsLmpwZw=="
      }
    ],
    "chnlid": 0,
    "feture_img": [
      {
        "image": "feture_image_0",
        "image_length": 5522,
        "image_send_flag": 1,
        "key": 93,
        "path": "aW1ncy9iZTAzNDUzYS0xMGU5MTkwYy8yMDIwMDgxMy8xNTk3Mjg1ODY0XzFfMF9jbGlwLmpwZw=="
      }
    ],
    "product_h": {
      "car_pos": {
        "loc": {
          "bottom": 0,
          "left": 0,
          "right": 0,
          "top": 0
        },
        "pos": 0
      },
      "parking": {
        "parking_state": 8,
        "zone_id": 1,
        "zone_name": "WUItMDAy"
      },
      "plate": {
        "color": 0,
        "confidence": null,
        "loc": {
          "bottom": 607,
          "left": 1522,
          "right": 1826,
          "top": 903
        },
        "plate": "X1/ml6BfXw==",
        "type": 0
      },
      "reco": {
        "group_id": -1,
        "reco_flag": 1,
        "reco_id": 92,
        "reco_time": "2020-08-13 10:31:04"
      }
    },
    "reco_id": 92,
    "serial": 75644590,
    "time_s": 1597285864,
    "trigger_type": 8
  },
  "timestamp": 1597285865  # 时间戳
}

此处的结果样式可能与实际不同，具体协议请参见不同产品的协议文档。

向设备发送消息

您可以向设备发送消息，同样，不同类型的设备提供的消息是不一样的，具体需要以提供的协议文档为主，下面以路侧产品（H系列）的发送手动触发消息（ivs_trigger）为例进行说明。

发布Topic

device/${sn}/message/down/${name}

{sn}为设备的序列号，无法向不属于您的设备发送消息
{name}为消息的名称，在此例子中就是ivs_trigger

在此例中，发布topic为device/12345678-87654321/message/down/ivs_trigger，由于MQTT协议的原因，您无法得知发送是否成功，更无从得知消息是否被指定设备接收，为了解决此问题，我们提供了订阅发送消息回执的方式。

订阅回执Topic

device/${sn}/message/down/${name}/reply

如果您需要知道设备是否收到发送的消息以及是否处理结果，您可以订阅回执消息，在此例中，订阅回执Topic为device/12345678-87654321/message/down/ivs_trigger/reply。

注意事项：

如果要订阅发布消息的回执，请一定在发布消息之前订阅回执Topic。
发布消息和回执消息的id字段相同，通过此字段。
如果要发送的设备不属于你或者发布的消息设备不支持，此消息是不会到达设备的。
建议订阅消息的回执，这样在超过一定时间（比如10s）还没有收到回执消息，即可判定发送失败。

消息示例

发布消息示例

{
    "id": "NYGtiXpPy5ratyzU", # 消息ID，用于关联具体消息
    "sn": "12345678-87654321", # 设备序列号
    "name": "ivs_trigger", # 消息名称
    "version": "1.0", # 消息版本，目前都填 1.0
    "payload": null, # 消息数据，视具体消息而定
    "timestamp": 1597285865 # 时间戳
}

回执消息示例

{
    "id": "NYGtiXpPy5ratyzU", # 消息ID，用于关联具体消息
    "sn": "12345678-87654321", # 设备序列号
    "name": "ivs_trigger", # 消息名称
    "code": 200,  # 设备是否处理成功，200成功，非200失败
    "version": "1.0", # 消息版本，目前都填 1.0
    "payload": null, # 消息数据，视具体消息而定
    "timestamp": 1597285865 # 时间戳
}

获取图片

某些协议(比如ivs_result)，需要传输图片，在我们提供的所有MQTT协议中，都不直接携带图片数据，而是只携带一个BASE64编码的图片路径，比如像下面这样：

{
  "id": "c9uKOgYZqIeSgRI4", # 消息ID
  "bv": 12309, # 设备board_version
  "sn": "12345678-87654321", # 设备序列号
  "name": "ivs_result", # 消息名称
  "version": "1.0", # 消息版本
  "payload": {
    ...
    "bg_img": [
      {
        "image": "bg_image_0",
        "image_length": 950541,
        "image_send_flag": 1,
        "key": 92,
        "path": "aW1ncy9iZTAzNDUzYS0xMGU5MTkwYy8yMDIwMDgxMy8xNTk3Mjg1ODY0XzFfMF9mdWxsLmpwZw=="
      }
    ]
    ...
  }
  ...
}

将path字段BASE64解码后：

imgs/be03453a-10e9190c/20200813/1597285864_1_0_full.jpg

然后参见下载图片去获取此图片的数据。

接入指南

消息服务接入指南

准备工作

获取MQTT客户端

获取MQTT连接信息

连接消息服务器

订阅设备状态

订阅Topic

消息示例

订阅设备消息

订阅Topic

消息示例

向设备发送消息

发布Topic

订阅回执Topic

消息示例

发布消息示例

回执消息示例

获取图片

results matching ""

No results matching ""