python3异步MQTT库HBMQTT(1) - 命令行用法

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 "}'

管道符输入

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 "}'

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  ] [-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.