文章目录
HBMQTT
本文介绍ngmqtt库的命令行方式,发布、订阅和启动broker的基本用法。
简介
开源的Mqtt客户端和broker,使用python标准异步库asyncio
实现,提供协程并发程序开发的直接API。
- GitHub:https://github.com/beerfactory/hbmqtt
- 文档:https://hbmqtt.readthedocs.io/en/latest/
Feature
HBMQTT实现了完整的MQTT 3.1.1协议规范,并提供了以下特性:
- Support QoS 0, QoS 1 and QoS 2 messages flow
- 客户端断线自动重连
- 通过密钥文件认证(其他方法可通过插件系统实现)
- 基础的
$SYS
topics 支持 - TCP 和 websocket 支持
- TCP 和 websocket 的 SSL 支持
- 插件系统
依赖
要求Python >=3.4.3
安装
pip install hbmqtt==0.9.6
命令行用法
用于在程序外进行测试
基本功能:
- 指定 topic 发送消息到外部 MQTT broker
- 订阅并接收发布的消息
- 搭建一个 MQTT broker
发布消息
hbmqtt_pub
是一个命令行工具,可以用于向 topic 发布一些消息。它需要一些参数,如:服务器地址、topic 主题、QoS 服务质量和要发送的数据。其他选项允许更复杂的用例。
hbmqtt_pub --version
hbmqtt_pub (-h | --help)
hbmqtt_pub --url BROKER_URL -t TOPIC (-f FILE | -l | -m MESSAGE | -n | -s) [-c CONFIG_FILE] [-i CLIENT_ID] [-d]
[-q | --qos QOS] [-d] [-k KEEP_ALIVE] [--clean-session]
[--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
[ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
[--extra-headers HEADER]
为了操作方便, hbmqtt_pub
的大部分参数跟 mosquitto_pub 一致.
参数详细介绍
参数 | 说明 |
---|---|
–version | HBMQTT版本信息 |
-h, --help | 显示帮助信息 |
-c | 设置客户端运行YAML配置文件 |
-d | 显示debug信息 |
–ca-file | 定义包含受信任的PEM编码CA证书的文件路径. 用于开启SSL加密通信. |
–ca-path | 定义包含受信任的PEM编码CA证书的文件夹路径,用于开启SSL加密通信. |
–ca-data | 设置受信任的经过PEM编码的CA证书 用于开启SSL加密通信. |
–clean-session | 如果提供该参数,将设置CONNECT 连接清除 session标志位 为True |
-f | 将文件的内容作为消息发送。该文件是逐行读取的,hbmqtt_pub 将读取的每一行作为一条消息。 |
-i | 客户端id,默认值为 hbmqtt/ + 随机字符 |
-l | 发送从stdin读取的消息。hbmqtt pub将为读取的每一行发布一条消息。不会发送空行。 |
-k | 设置客户端keep alive超时时间. |
-m | 发送的消息消息内容 |
-n | 发送一条空数据(长度为0) |
-q, --qos | 指定QoS消息服务质量,取值0,1和2,默认为0 |
-s | 发送从stdin读取的消息,将整个内容作为单个消息发送。 |
-t | 消息的topic |
–url | Broker的 URL,支持的格式参考下文。 |
–will-topic | 在客户端意外断开连接时,要发送的主题。 |
–will-message | 指定由broker存储并在此客户端意外断开连接时发送的消息。这个必须和--will-topic 参数一起使用。 |
–will-qos | 用于 Will的QoS。默认值为0。这个必须和--will-topic 参数一起使用。 |
–will-retain | 如果给定,如果客户端意外断开连接,发送出去的消息将被视为retain消息。这个必须和--will-topic 一起使用 |
–extra-headers | 指定一个JSON对象字符串,带有表示在初始连接上传输的附加头的键-值对,但仅在使用websocket连接时使用 |
配置文件
指定-c
参数,并传入一个 YAML文件路径,详细配置内容如下:
yaml字段 | 说明 |
---|---|
keep_alive | Keep-alive 超时时间,默认 10 s |
ping_delay | 在 keep-alive 超时之前发送的 Auto-ping 包的延迟,默认 1s,设置成 0 则表示禁用,但是会导致与 broker 断开连接 |
default_qos | 发布消息的默认 QoS。默认值为 0。 |
default_retain | 消息发布的默认 retain 值,默认为false |
auto_reconnect | 当与 broker 的连接中断,启用或禁用自动重新连接。默认值为 false |
reconnect_retries | 最大重连重试次数,默认为 2 次 |
reconnect_max_interval | 两次重连之间的最大间隔,默认为10s |
示例
以下示例可以跟 mosquitto_pub 的文档适配
示例一
发布数据 123 到 /test 主题上,QoS 1: :
hbmqtt_pub --url mqtt://test.mosquitto.org -t /test -m 123 -q 1
示例二
向远程主机的非标准端口上,发布时间戳和温度信息, QoS=0
hbmqtt_pub --url mqtt://192.168.1.1:1885 -t sensors/temperature -m "1266193804 32"
示例三
发送文件内容的两种方式
hbmqtt_pub --url mqtt://localhost -t my/topic -f ./data
hbmqtt_pub --url mqtt://localhost -t my/topic -s < ./data
发送 websocket 消息
将温度信息封装到websocket中,向localhost发布,添加额外header,QoS=1
hbmqtt_pub --url wss://localhost -t sensors/temperature -m 32 -q 1 --extra-headers '{"Authorization": "Bearer <token>"}'
管道符输入
hbmqtt_pub 可以从文件或 stdin 中读取数据,并将读取的数据作为消息载荷发送
$ some_command | hbmqtt_pub --url mqtt://localhost -t /test -l
订阅消息
hbmqtt_sub
是一个命令行工具,可用于订阅 broker 上的某些 pattern,并从其他 MQTT 客户机发布的与这些 patern 匹配的主题上的消息中获取日期。
基本用法
hbmqtt_sub --version
hbmqtt_sub (-h | --help)
hbmqtt_sub --url BROKER_URL -t TOPIC... [-n COUNT] [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d]
[-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
[ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
[--extra-headers HEADER]
为了操作方便, hbmqtt_sub 的大部分参数跟 mosquitto_sub 一致.
参数详细介绍
参数 | 说明 |
---|---|
–version | HBMQTT 版本信息 |
-h, --help | 显示帮助信息 |
-c | 设置客户端运行 YAML 配置文件 |
-d | 显示 debug 信息 |
–ca-file | 定义包含受信任的 PEM 编码 CA 证书的文件路径. 用于开启 SSL 加密通信. |
–ca-path | 定义包含受信任的 PEM 编码 CA 证书的文件夹路径,用于开启 SSL 加密通信. |
–ca-data | 设置受信任的经过 PEM 编码的 CA 证书 用于开启 SSL 加密通信. |
–clean-session | 如果提供该参数,将设置 CONNECT 连接清除 session 标志位 为 True |
-i | 客户端 id,默认值为 hbmqtt/ + 随机字符 |
-l | 发送从 stdin 读取的消息。hbmqtt pub 将为读取的每一行发布一条消息。不会发送空行。 |
-k | 设置客户端 keep alive 超时时间. |
-n | 在结束前接收的消息数量,默认不断接收 |
-q, --qos | 指定用于接收消息的服务质量。此 QoS 在订阅请求中发送。 |
-t | 订阅 Topic 的过滤器 |
–url | Broker 的 URL,支持的格式参考下文。 |
–will-topic | 在客户端意外断开连接时,要发送的主题。 |
–will-message | 指定由 broker 存储并在此客户端意外断开连接时发送的消息。这个必须和--will-topic 参数一起使用。 |
–will-qos | 用于 Will 的 QoS。默认值为 0。这个必须和--will-topic 参数一起使用。 |
–will-retain | 如果给定,如果客户端意外断开连接,发送出去的消息将被视为 retain 消息。这个必须和--will-topic 一起使用 |
–extra-headers | 指定一个 JSON 对象字符串,带有表示在初始连接上传输的附加头的键-值对,但仅在使用 websocket 连接时使用 |
配置文件
指定-c
参数,并传入一个 YAML 文件路径,详细配置内容如下:
yaml 字段 | 说明 |
---|---|
keep_alive | Keep-alive 超时时间,默认 10 s |
ping_delay | 在 keep-alive 超时之前发送的 Auto-ping 包的延迟,默认 1s,设置成 0 则表示禁用,但是会导致与 broker 断开连接 |
default_qos | 发布消息的默认 QoS。默认值为 0。 |
default_retain | 消息发布的默认 retain 值,默认为false |
auto_reconnect | 当与 broker 的连接中断,启用或禁用自动重新连接。默认值为 false |
reconnect_retries | 最大重连重试次数,默认为 2 次 |
reconnect_max_interval | 两次重连之间的最大间隔,默认为 10s |
示例
以下示例可以跟 mosquitto_sub 的文档适配
示例一
订阅 $SYS/: 下所有的消息, QoS=0
hbmqtt_sub --url mqtt://localhost -t '$SYS/#' -q 0
示例二
订阅 /# 下的 10 条消息, QoS=2
hbmqtt_sub --url mqtt://localhost -t /# -q 2 -n 10
示例三
订阅$SYS/ 下的所有通过 websocket 包装的消息,QoS=0,附加额外 headers
hbmqtt_sub --url wss://localhost -t '$SYS/#' -q 0 --extra-headers '{"Authorization": "Bearer <token>"}'
URL 格式
参数 --url 必须符合以下格式
[mqtt|ws][s]://[username][:password]@host.domain[:port]
比如:
mqtt://localhost
mqtt://localhost:1884
mqtt://user:password@localhost
ws://test.mosquitto.org
wss://user:password@localhost
运行 broker
hbmqtt
命令启动一个 broker
基本用法
hbmqtt --version
hbmqtt (-h | --help)
hbmqtt [-c <config_file> ] [-d]
选项
参数 | 说明 |
---|---|
–version | HBMQTT version information |
-h, --help | Display hbmqtt_sub usage help |
-c | Set the YAML configuration file to read and pass to the client runtime. |
读配置文件
(注意:文件中不要出现中文)
指定 -c
参数,传入一个 YAML 文件名,该文件应包含以下配置:
- listeners : 网络绑定列表
- timeout-disconnect-delay : 在 keep-alive 超时后客户端断开连接的时间
- auth : 认证配置
YAML 文件基础配置如下:
listeners:
default:
type: tcp
bind: 0.0.0.0:1883
sys_interval: 20
timeout-disconnect-delay: 2
auth:
plugins: ['auth.anonymous'] #注册认证插件列表
allow-anonymous: true
topic-check:
enabled: false # 禁用topic过滤器
以上配置说明:
- 在所有网络接口以 TCP 监听 1883 端口
- 发布
$SYS``_ update messages every ``
20 秒间隔 - 允许匿名登录,禁用topic检查
配置文件示例
listeners:
default:
max-connections: 50000
type: tcp
my-tcp-1:
bind: 127.0.0.1:1883
my-tcp-2:
bind: 1.2.3.4:1884
max-connections: 1000
my-tcp-ssl-1:
bind: 127.0.0.1:8885
ssl: on
cafile: /some/cafile
capath: /some/folder
capath: certificate data
certfile: /some/certfile
keyfile: /some/key
my-ws-1:
bind: 0.0.0.0:8080
type: ws
timeout-disconnect-delay: 2
auth:
plugins: ['auth.anonymous'] # 插件列表,在所有注册的插件中用于激活认证
allow-anonymous: true / false # 是否允许匿名
password-file: /some/passwd_file # 密码文件
topic-check:
enabled: true / false # 如果不需要 topic 过滤器,可以设为 false
plugins: ['topic_acl'] # 插件列表,用于所有注册的插件来激活topic过滤器
acl:
# username: [允许通过的 topic 列表]
username1: ['repositories/+/master', 'calendar/#', 'data/memes'] # List of topics on which client1 can publish and subscribe
username2: ...
anonymous: [] # List of topics on which an anonymous client can publish and subscribe
配置说明:
listeners 段定义了 4 个绑定配置
my-tcp-2
: 不安全的 TCP 监听端口 1884,允许同时连接 1000 个客户端my-tcp-ssl-1
: 安全的 TCP 监听端口 8885,开启 ssl 加密my-ws-1
: 不安全的 websocket 监听端口 8080
身份验证允许匿名登录和基于密码文件的身份验证。password-file 密码文件必须是文本文件,其中包含用户名和密码,形式为:
username:password
其中 password
应当加密, 使用mkpasswd -m sha-512
命令构建编码的口令。
密码文件示例:
# Test user with 'test' password encrypted with sha-512
test:$6$l4zQEHEcowc1Pnv4$HHrh8xnsZoLItQ8BmpFHM4r6q5UqK3DnXp2GaTm5zp5buQ7NheY3Xt9f6godVKbEtA.hOC7IEDwnok3pbAOip.