设置
Node-MQ内置Web服务提供可由浏览器访问的设置页面,用于设置网络参数、启动项、MQTT参数,以及初始化指令等系统配置数据。
初始状态或未配置Wi-Fi网络的Node-MQ将启动SoftAP模式,提供Wi-Fi接入点:
- SSID:
- node-******
- 密码:
- nodenode
搜索Wi-Fi网络,找到以node-为前缀的网络名称并连接,若出现“当前WLAN无法联网”的提示,请选择“保持连接”。
接入Node-MQ SoftAP热点后,使用浏览器访问IP地址192.168.4.1,即打开Node-MQ设置页面。对完成网络设置并成功接入本地网络的Node-MQ,请以Node-MQ的局域网IP访问设置页面(参考 快速入门)。

设置界面按功能划分为多个面板与标签组,各面板的设置可分别保存(Save),设置修改后需要重启(Reboot)。
General
General标签组包含网络及全局设置项。

Wi-Fi SSID - 局域网接入SSID。
指定Node-MQ要连接的本地路由器Wi-Fi网络名称(SSID)。Node-MQ将以STA模式接入Wi-Fi网络,IP地址由所连接的路由器分配,可以通过查看串口输出,或访问路由器管理界面获悉。当无法连接指定的SSID时,Node-MQ将切换回SoftAP模式。
注意
ESP32-S3不支持5 GHz Wi-Fi网络,此处必须设置2.4 GHz Wi-Fi网络对应的SSID与密码。
Wi-Fi Password - 对应 Wi-Fi SSID 的密码。
Log Level - 系统日志等级,默认
WARN。指定USB串口输出日志的等级。可选项:
INFO(信息)、WARN(警告)、ERROR(错误)、NONE(关闭)。Access Control - 访问控制开关,默认关闭。
启用访问控制后,系统将对设置页面或WebSocket接口的访问进行密码验证:
- 访问设置页面将跳转到 Login 页面,用户输入 Access Code 并验证通过后,返回目标页面。
- WebSocket连接创建后,客户端应首先发送 Access Code,若首帧数据非密码或密码验证失败,服务端将关闭连接。
Access Code - 对应 Access Control 的验证密码。
mDNS - 多播DNS开关,默认关闭。
启用mDNS后,在局域网内可以用mDNS主机名(mDNS Hostname)访问Node-MQ,而不必知道实际IP地址。如主机名为
node-mq,则访问地址为http://node-mq.local。该功能需要客户端操作系统支持mDNS协议。mDNS Hostname - 对应 mDNS 开关设置的主机名。
SNTP Client - 网络时间客户端开关,默认关闭。
该功能在Node-MQ接入局域网且可访问SNTP服务时有效。启用SNTP后,Node-MQ会自动获取网络时间作为系统时间。
MQTT Client - MQTT客户端开关,默认关闭。
控制Node-MQ是否启用MQTT指令通道。开启后,系统将按 MQTT 标签组的配置连接MQTT Broker,并接收来自MQTT通道的指令。
MQTT
MQTT标签组用于设置MQTT客户端的连接参数。在启用 MQTT Client 后,将以设置的参数连接MQTT Broker。

Transport - 连接MQTT Broker的网络传输方式。可选项:
TCP- 使用MQTT over TCP连接。SSL- 使用TLS加密的MQTT over TCP连接。WS- 使用WebSocket连接。WSS- 使用TLS加密的WebSocket连接。
当选择
SSL或WSS时,需要配置Broker的CA证书信息(MQTT Certificate)。Protocol Version - MQTT协议版本。
当前广泛支持的MQTT版本为
3.1.1。可选项:3.1.1、3.1。Hostname - MQTT Broker主机名(地址)。
可填写域名或IP地址,例如:
mqtt.example.com或192.168.1.100。不要在字段中包含协议前缀(如mqtt://、ws://)或端口号。Port - MQTT服务端口号。
Path - WebSocket连接的URI路径。
该设置仅适用于
WS和WSS传输方式(如/mqtt、/wss)。TCP或SSL传输方式通常不需要设置此项。Username - MQTT Broker访问控制用户名。
如果Broker未启用用户名认证,可以留空。
Password - 对应访问控制用户名的密码。
如果Broker未启用用户名认证,可以留空。
Client ID - 客户端ID。
用于在MQTT Broker中标识当前客户端。
Subscribe Topic - 订阅主题。
Node-MQ从该主题接收指令(action)。默认主题为
node/action。Publish Topic - 发布主题。
Node-MQ以该主题发布指令结果的应答消息,或通知消息。默认主题为
node/post。Subscribe QoS - 订阅主题时的请求QoS等级。可选项:
0- 最多一次(At Most Once)1- 至少一次(At Least Once)2- 恰好一次(Exactly Once)
QoS等级越高,传输越可靠,但通信开销越大。默认值为
0。Node-MQ接收到的消息,其实际QoS等级由消息发布方的QoS和Node-MQ订阅时请求的QoS共同决定,实际传输QoS为两者中的较小值。
Publish QoS - 发布消息使用的QoS等级。可选项:
0- 最多一次(At Most Once)1- 至少一次(At Least Once)2- 恰好一次(Exactly Once)
QoS等级越高,传输越可靠,但通信开销越大。默认值为
0。Node-MQ发布消息时使用此QoS等级。消息最终由Broker发送给订阅者时的实际QoS还受订阅者请求的QoS等级限制。
Last Will - 遗嘱消息开关,默认关闭。
启用遗嘱消息后,Node-MQ会在Broker以发布主题注册
type-offline消息,当Broker检测到Node-MQ异常断连时,将以发布主题向订阅者发送type-offline消息。Broker需要约1.5倍keepalive时长才能检测到异常断连。MQTT客户端的keepalive时长默认为120秒,即Broker在异常断连后约180秒发送
type-offline消息。
MQTT Certificate
当MQTT设置项 Transport 选择SSL或WSS时,设置界面将展开 MQTT Certificate 面板,需要配置Broker的CA证书信息。
MQTT Broker通常提供可下载的CA证书文件,证书内容为PEM格式的数据文本。若要使用自签证书搭建本地加密MQTT Broker(如 Eclipse Mosquitto),请参考 Mosquitto Broker设置。

将CA证书的文本内容完整复制并粘贴到 MQTT Certificate 文本框中,点击 Save 保存即可。
Initial Actions
Node-MQ的指令除了能在运行时动态执行,还可以设置为在系统启动后自动运行(实现特定的初始化资源配置)。Initial Actions 即系统启动后自动运行的指令集合,所有指令均可作为 Initial Actions 指令设置。Node-MQ的指令以JSON格式定义,每条指令表示为一个JSON对象,Initial Actions 可以是一个指令JSON对象,也可以是多条指令组成的JSON对象数组(按顺序执行)。参考 指令说明。

Action Channel - 指令通道。
在运行时,Node-MQ由指令通道接收指令,并将执行结果以相同的通道反馈给调用者。Initial Actions 的不同在于,这些指令以系统配置的形式保存,由系统自动读取并执行,而并非由某个指令通道获取。因此,指令的执行结果(如果有)应该如何反馈需要单独定义。此处即定义 Initial Actions 使用的指令通道,指令的执行结果将由该通道反馈。可选项:
MQTT- 使用MQTT通道,由发布主题反馈结果(需要启用 MQTT Client)。WebSocket- 使用WebSocket通道反馈结果。选择该通道后,界面将展开WebSocket Feedback显示区,并自动连接WebSocket接口。连接成功后(标题指示绿灯),指令的测试(Test)结果将实时输出到显示区。UART0- 使用UART0通道反馈结果(需要由config指令启用)。UART1- 使用UART1通道反馈结果(需要由config指令启用)。UART2- 使用UART2通道反馈结果(需要由config指令启用)。
Format - 格式化输入的JSON指令。
将输入的JSON指令格式化为规范的易读形式,也可校验输入的JSON格式是否正确。
Test - 测试执行输入的JSON指令。
测试执行用于验证指令的有效性,不会保存指令。指令的执行结果将反馈到指定的 Action Channel。
Save - 保存输入的JSON指令。重新启动后系统将自动执行保存的指令。