# MQTT直连接入

本文档以MQTTX为例,介绍使用第三方软件以MQTT协议接入物联网平台。

# 下载并安装MQTTX

前往官网下载 (opens new window)安装

# 系统配置

# 操作步骤

1.登录Jetlinks物联网平台,进入协议管理菜单,上传协议。

获取协议包源码

2.进入网络组件菜单,配置MQTT服务类型的网络组件。

3.进入设备接入网关菜单,配置接入方式为MQTT直连的网关。
 (1)选择MQTT服务类型的网络
 (2)选择所需的协议包
 (3)填写设备接入网关名称

4.创建产品,并进入设备接入tab,选择所需的设备接入网关然后启用产品。

5.在设备接入tab页面中填写官方协议包认证信息;然后启用产品。

说明

不同协议包在设备接入界面所需要填写的方式不同。官方协议包,需要填写设备认证所需要的的账号密码

在设备接入tab页的MQTT认证配置项中填写 secureId为:admin secureKey为:admin。

6.创建设备,选择对应的所属产品,然后启用设备。

注意

需要先启用产品,才能基于产品创建设备

# 使用MQTTX模拟设备连接到平台

1.打开MQTTX软件,点击新建连接创建一个连接,设置连接参数

# 连接参数说明

参数 说明
Name 输入您的自定义名称。
Client ID 设备Id。必须与系统中设备的ID填写一致。
Host 连接域名。本地连接可直接填写 `127.0.0.1`,如为远程连接,请填写产品-设备接入页-连接信息显示的连接地址。
Port 请填写产品-设备接入页-连接信息显示的端口。
Username 填写接入账号
Password 填写接入密码

说明

使用JetLinks官方协议包接入设备,用户名和密码需要经过加密规则处理。
可使用账号密码自动生成器获取

注意

经过加密规则处理的账号密码超过5分钟后将不在可用,需重新生成

2.点击连接按钮,平台中设备状态变为在线

说明

如您在点击连接后遇到MQTTX提示异常信息或设备未上线等问题。可在设备详情-设备诊断页中,诊断设备未上线原因

# 设备数据上下行

设备连接上平台后,可进行一些基本的事件上报、属性读取等操作。

# 物模型创建

在产品详情-物模型tab页中分别创建属性、事件、功能三种物模型

创建属性 属性ID: temperature

创建功能 功能ID: playVoice

创建事件 事件ID: alarm_fire

# 读取设备属性

1.登录Jetlinks物联网平台,点击设备查看按钮,进入运行状态tab页。
2.点击设备运行状态中某个属性的获取属性值按钮。 MQTTX会收到平台下发指令消息

说明

复制好订阅该topic收到的消息中的messageId。此messageId将作为回复与平台设备属性的凭据之一。

3.回复平台设备读取消息
topic格式参考:JetLinks官方协议-读取设备属性
消息内容格式如下


{
  "deviceId": "设备Id",
  "messageId": "平台下发报文中的messageId",
  "properties":{
    "temperature": 35.6
  },
  "success": true
}

回复参数说明

参数 说明
messageId 平台下发报文中的messageId
deviceId 设备ID
success 成功标识
properties 设备属性值对象。例如: { "temperature":"50"}

点击消息发送按钮图标,向平台推送该消息。

4.平台收到MqttX推送的属性值后,将会实时展示到运行状态中。

注意

从在系统界面中点击刷新到MQTTX端回复消息,需在10秒内完成。否则平台会视为该次操作超时,导致读取属性值失败。

# 设备事件上报

MQTTX 推送设备事件消息到平台。

1.在MQTTX上,填写事件上报topic。topic格式参考JetLinks官方协议-设备事件上报
2.输入事件上报Topic和要发送的事件内容,点击"发送"按钮图标,向平台推送该事件消息。

设备事件上报数据

{
 "data":{
   "addr":"未来科技城 C2 栋",
  "time":"12-05-2012"
 }
}
参数 说明
data 对象类型的报文数据

上报成功后,在设备-运行状态tab页,可查看事件具体信息。

# 调用设备功能

1.在设备-设备功能tab页,选择设备功能模块,点击执行,向设备发送功能调用指令。 3.填写设备功能回复topic和报文。格式参考JetLinks官方协议-调用设备功能

设备功能回复报文

{
 "messageId":"平台下发报文中的messageId", 
 "output":true,
 "success":true
}
参数 说明
messageId 平台下发报文中的messageId
output 返回的对象类型执行结果
success 成功状态

设备功能调用成功后在设备-设备功能tab页显示调用回复结果。

# MQTT Broker接入

在某些场景,设备不是直接接入平台,而是通过第三方MQTT服务,如:emqx接入。 本文使用mqttx模拟设备端,通过emqx接入平台。

# 安装并启动EMQ

前往官网下载 (opens new window)安装

本文使用docker搭建

docker run -d --name emqx -p 18083:18083 -p 1883:1883 emqx/emqx:latest

# 访问EMQX Dashboard

在浏览器中输入 http://127.0.0.1:18083 ,默认账号密码为用户名:admin 密码:public。

# 系统配置

# 操作步骤

1.登录Jetlinks物联网平台,进入网络组件菜单,创建MQTT客户端网络组件。

如EMQX服务在本机电脑启用,MQTT客户端网络组件填写参数参考下图填写即可

网络组件填写参数说明

参数 说明
远程地址 emqx启动所在服务的IP地址,emq本机启动的可填写127.0.0.1
远程端口 emqx启动的服务端口
clientId 连接到emqx的客户端Id
用户名 连接到emqx时需要的用户名
密码 连接到emqx时需要的密码
最大消息长度 单次收发消息的最大长度,单位:字节;

2.进入协议管理菜单,上传协议包。

获取协议包源码

3.进入设备接入网关,创建MQTT Broker类型的接入网关。

网关创建完成后,可在emqx客户端中的“Subscriptions”菜单中看到订阅列表

4.创建产品,并选中接入方式为MQTT Broker类型的设备接入网关。

5 创建物模型

在产品详情-物模型tab页中创建温度属性物模型,属性ID:temperature

5.创建设备,选择第4步中创建的产品。

注意

需要先启用产品,才能基于产品创建设备

# 使用MQTTX模拟设备与平台进行交互

下载并安装MQTTX。 可前往官网下载 (opens new window)安装

1.打开MQTTX软件,点击新建连接创建一个连接

2.设置连接参数。连接到EMQX

如EMQX服务在本机电脑启用,连接参数参数参考下图填写即可

连接参数说明

参数 说明
Name 自定义名称
Client ID 注册到EMQX的客户端Id。可自定义填写任意字符串
Host 填写启动EMQX服务的IP地址
Port EMQX启动的服务端口

# 物模型属性上报

推送物模型属性消息到EMQX。实现平台设备上线与消息接收

推送设备上报属性topic格式和报文参考:JetLinks官方协议-读取设备属性

topic:/产品Id/设备Id/properties/report

{
    "properties":{"temperature":36.8}
}

进入平台设备详情界面,此时设备以变成在线状态,且收到了刚刚的温度属性消息

# 物模型属性读取回复

1.在MQTTX中点击订阅添加按钮

2.添加订阅设备读取属性topic:/+/+/properties/read。格式参考:JetLinks官方协议-读取设备属性

后续操作参考读取设备属性

# HTTP接入

# 系统配置

1.登录Jetlinks物联网平台,进入网络组件菜单,创建HTTP服务网络组件。
2.进入协议管理菜单,上传协议包。
3.进入设备接入网关,创建HTTP推送接入类型的接入网关。
4.创建产品,并选中接入方式为HTTP推送类型的设备接入网关。
5.创建设备,所属产品选择HTTP推送接入类型的产品。

# 推送消息

此处使用postman模拟设备请求。

# 模拟设备上报属性

说明

请求时路径中带的/report-property相当于mqtt中的topic,在demo协议将中根据路径来判断消息类型。

上报后,在设备-运行状态中进行查看。

# 模拟设备事件上报

说明

请求时路径中带的/fire-alarm相当于mqtt中的topic,在demo协议将中根据路径来判断消息类型。

上报后,在设备-运行状态中,点击左侧菜单,切换至对应事件,进行查看。

# 指令下发

由于http是短链接,无法直接下发指令,可以在消息拦截器中或者编码时通过将消息设置到device.setConfig中,在收到 http请求拉取消息时,通过device.getSelfConfig获取配置,并返回。

# 使用CoAP服务接入

本文档使用coap-cli (opens new window)模拟设备接入平台。

提示

本功能仅在企业版中提供。

# 系统配置

1.登录Jetlinks物联网平台,进入网络组件菜单,创建CoAP服务网络组件。
2.进入协议管理菜单,上传协议包。
3.进入设备接入网关,创建CoAP接入类型的接入网关。
4.创建产品,并选中接入方式为CoAP接入类型的设备接入网关。
5.创建设备,所属产品选择CoAP接入类型的产品。

# 使用coap-cli模拟客户端接入

1.下载并安装coap-cli

npm install coap-cli -g

2.模拟设备设备属性上报

echo -n '{"deviceId":"coap-test-001","properties":{"temperature":36.5}}' | coap post coap://localhost:8009/report-property

设备-运行状态中可以看到温度属性已发生变化。
3.模拟设备上报事件

echo -n '{"deviceId":"coap-test-001","pname":"智能温控","aid":105,"a_name":"未来科技城","b_name":"C2 栋","l_name":"12-05-201","timestamp":"2019-11-06 16:28:50","alarm_type":1,"alarm_describe":"火灾报警","event_id":1,"event_count":1}' | coap post coap://localhost:8009/fire_alarm

设备-运行状态中点击左侧菜单,切换至对应事件,进行查看。

# 使用UDP接入

提示

本功能仅在企业版中提供。

# 系统配置

1.登录Jetlinks物联网平台,进入网络组件菜单,创建UDP网络组件。
2.进入协议管理菜单,上传协议包。
3.进入设备接入网关,创建UDP接入类型的接入网关。
4.创建产品,并选中接入方式为UDP接入类型的设备接入网关。
5.创建设备,所属产品选择UDP接入类型的产品。

# 使用UDP模拟工具接入

1.下载并安装SocketTool4

说明

此处以json方式传输数据。

2.创建udp客户端。

3.模拟设备设备属性上报
在SocketTool4工具的数据发送窗口填写发送的报文。
此处使用的报文为:

{
  "properties":{
      "temperature":36.5 //温度属性
     },
  "messageType": "REPORT_PROPERTY",//org.jetlinks.core.message.MessageType
  "deviceId": "udp-test-001",//设备id
  "key": "admin"//udp认证配置,udp_auth_key	
}

单击发送数据按钮发起发送数据。 收到上报的消息后平台中设备状态将变为上线,在设备-运行状态中可以看到温度属性已发生变化。

4.模拟设备上报事件
在SocketTool4工具的数据发送窗口填写发送的报文。
此处使用的报文为:

{
    "data": {
          "pname":"智能温控",
          "aid":105,
          "a_name":"未来科技城",
          "b_name":"C2 栋",
          "l_name":"12-05-201",
          "timestamp":"2019-11-06 16:28:50",
          "alarm_type":1,
          "alarm_describe":"火灾报警",
          "event_id":1,
          "event_count":1
    },
    "event": "fire_alarm",//事件标识
    "messageType": "EVENT",//org.jetlinks.core.message.MessageType
    "deviceId": "udp-test-001",//设备id
    "key": "admin"//udp认证配置,udp_auth_key	
}

单击发送数据按钮发起发送数据。
设备-运行状态中点击左侧菜单,切换至对应事件,进行查看。

# TCP、MQTT短连接接入

默认情况下,使用tcp和mqtt方式接入时,当连接断开时,则认为设备已离线。 但是在某些场景(如:低功率设备)下,无法使用长连接进行通信,可以通过指定特定配置使平台保持设备在线状态。

说明

以下功能及API在jetlinks 1.4.0 后提供。

# 保持在线

在自定义协议包解码出消息时,可通过在消息中添加头keepOnline来进行设置。如:


message.addHeader(Headers.keepOnline,true); //设置让会话强制在线
message.addHeader(Headers.keepOnlineTimeoutSeconds,600);//设置超时时间(可选,默认10分钟),如果超过这个时间没有收到任何消息则认为离线。

说明

MQTT接入时添加到任意消息即可。TCP接入时添加到DeviceOnlineMessage即可。

如果服务重启,将不会保存在线状态!

# 缓存下发消息

在进行消息下发时,因为会话是强制保持在线的,所以消息会直接通过session下发,但是此时设备可能已经断开了连接, 将会抛出异常DeviceOperationException(ErrorCode.CLIENT_OFFLINE)。这时候可以通过将消息缓存起来,等待下次设备 连接上来后再下发指令。

一、在自定义协议包中使用消息拦截器拦截异常

support.addMessageSenderInterceptor(new DeviceMessageSenderInterceptor() {
    @Override
    public <R extends DeviceMessage> Flux<R> afterSent(DeviceOperator device, DeviceMessage message, Flux<R> reply) {

        return reply.onErrorResume(DeviceOperationException.class, err -> {
            if (err.getCode() == ErrorCode.CLIENT_OFFLINE) {
                return device
                    .setConfig("will-msg", message) //设置到配置中
                    .thenReturn(((RepayableDeviceMessage<?>) message)
                        .newReply()
                        .code(ErrorCode.REQUEST_HANDLING.name())
                        .message("设备处理中...")
                        .success()
                    )
                    .map(r -> (R) r);
            }
            return Mono.error(err);
        });
    }
});

二、获取缓存的消息

在收到设备指令后进行解码时,可以先获取是否有缓存到消息,然后发送到设备。

伪代码如下:


@Override
public Mono<? extends Message> decode(MessageDecodeContext context) {

    return context.getDevice()
        .getAndRemoveConfig("will-msg")
        .map(val -> val.as(DeviceMessage.class))
        .flatMap((msg) -> {
            return ((FromDeviceMessageContext) context)
                .getSession()
                .send(doEncode(msg)); //编码并发送给设备
        })
        .thenReturn(doDecode(context)); //解码收到的消息

}

说明

以上代码仅作为演示功能逻辑,请根据实际情况进行相应的处理。