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 一致.

参数详细介绍

参数说明
–versionHBMQTT版本信息
-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
–urlBroker的 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_aliveKeep-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 一致.

参数详细介绍

参数说明
–versionHBMQTT 版本信息
-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 的过滤器
–urlBroker 的 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_aliveKeep-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]

选项

参数说明
–versionHBMQTT version information
-h, --helpDisplay hbmqtt_sub usage help
-cSet 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.
  • 0
    点赞
  • 4
    收藏
    觉得还不错? 一键收藏
  • 1
    评论
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值