# MqttTools

**Repository Path**: NetADs/MqttTools

## Basic Information

- **Project Name**: MqttTools
- **Description**: MQTT Tools
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MQTT Tools - 通用 MQTT 设备控制面板

基于 [MQTT.js](https://github.com/mqttjs/MQTT.js) 的**通用 Web 控制面板**。纯静态、零后端，浏览器通过 WebSocket（`ws://` / `wss://`）直连 MQTT broker，向设备下发指令并实时展示设备状态。

适用于需要远程管理 MQTT 设备（ESP32、智能硬件、传感器网关等）的场景，也方便在开发调试阶段代替手机 App 快速验证设备固件的 MQTT 收发能力。

## 目录结构

```
MqttTools/
├── index.html      # 页面结构
├── config.js       # 面板配置（协议/指令/设置项，适配设备只需改此文件）
├── app.js          # 面板逻辑（通用实现，通常无需修改）
└── mqtt.min.js     # MQTT.js 浏览器版
```

## 功能

- **连接配置**：broker 地址、用户名/密码、设备 ID、Client ID 均在页面填写，无需改代码
- **设备状态**：自动订阅 status 主题，JSON 字段映射为状态卡片（在线/IP/版本/连接状态等）
- **快捷指令**：一键下发预定义指令（获取状态/OTA/重启/恢复出厂等），高危操作带二次确认
- **自定义指令**：任意 JSON 下发到 cmd 主题，支持一键格式化
- **常用设置**：设置项表单逐项 `set` 到设备，设备返回 ACK 后提示结果
- **消息日志**：cmd / status 双向收发实时滚动展示，带时间戳与收发方向标记
- **自动重连**：连接中断后自动重连并重新订阅

## 快速开始

```bash
git clone https://gitee.com/NetADs/MqttTools.git
cd MqttTools
python3 -m http.server 8000 --directory .
```

浏览器打开 `http://<主机>:8000`，在页面填写：

1. **Broker 地址**：broker 的 WebSocket 地址，如 `wss://broker.example.com:8084/mqtt`
2. **设备 ID**：与设备 `device_id` 一致（默认 `weatherclock`）
3. **用户名/密码**：broker 有认证时填写
4. 点击「连接」

连接成功后页面自动订阅 status 主题并下发首个指令，设备状态即会出现在状态卡片中。

> **注意**：浏览器只能直连 WebSocket 端口。若 broker 原生端口为 1883/8883，需额外启用 WS 监听（常见 8083/8084 或 `/mqtt` 路径），详见下文「Broker 配置」。

## 配置适配

修改 `config.js` 即可适配不同设备/协议，无需改动 `app.js`。

| 配置字段 | 说明 |
|----------|------|
| `title` / `subtitle` | 页面标题与副标题 |
| `cmdTopic` | cmd 主题模板，`{device}` 会被替换为设备 ID |
| `statusTopic` | status 主题模板，`{device}` 同理 |
| `defaultDeviceId` | 设备 ID 输入框默认值 |
| `brokerPlaceholder` | broker 地址输入框占位提示 |
| `defaultPayload` | 连接成功后自动下发的首个指令 |
| `statusFields` | status JSON 字段 → 状态卡片映射 |
| `actions` | 快捷指令按钮定义 |
| `settings` | 常用设置表单定义 |

### statusFields 状态卡片

```js
statusFields: [
  { key: "device_id", label: "设备" },                     // 直接显示字符串
  { key: "status", label: "在线", map: { online: "在线" } }, // 值映射显示
  { key: "wifi", label: "WiFi", bool: true },               // 布尔 → 已连接/未连接
  { key: "version", label: "固件版本" }
]
```

- `bool: true`：`true/false` 显示为「已连接/未连接」，并自动配色
- `map`：字段值到显示文本的映射表
- `ok`：值到是否高亮（绿/红）的映射，如 `{ online: true }`

### actions 快捷指令

```js
actions: [
  { label: "获取状态", payload: { type: "get", key: "status" } },
  { label: "重启设备", payload: { type: "cmd", action: "restart" },
    confirm: "确认重启设备？", danger: true },
  { label: "触发 OTA 升级", payload: { type: "cmd", action: "ota" }, warn: true }
]
```

- `payload`：下发到 cmd 主题的 JSON（对象或字符串）
- `confirm`：有值则点击时弹二次确认框
- `danger`：红色按钮（高危操作）；`warn`：橙色按钮

### settings 常用设置

```js
settings: [
  { key: "qweather_location_id", label: "天气城市", placeholder: "101030100", type: "text" },
  { key: "api_key", label: "API Key", type: "password", group: "凭证" }
]
```

- `key`：发送 `{"type":"set","key":"...","value":"..."}` 时的配置键
- `type`：`text` / `password` / `number`
- `group`：可选，同组的设置项聚合显示

## 指令协议约定

面板默认按以下 JSON 协议与设备交互（可在 `actions`/`settings` 中按设备调整）：

| 指令 | 说明 |
|------|------|
| `{"type":"get","key":"status"}` | 获取设备状态汇总 |
| `{"type":"get","key":"<setting>"}` | 读取配置项 |
| `{"type":"set","key":"<setting>","value":"<v>"}` | 写入配置项（持久化到设备 NVS） |
| `{"type":"cmd","action":"ota"}` | 触发 OTA 升级 |
| `{"type":"cmd","action":"restart"}` | 重启设备 |
| `{"type":"cmd","action":"factory_reset"}` | 恢复出厂（擦除配置并进入配网模式） |

设备端需实现 cmd 订阅与 status 发布（ESP-IDF 可参考 `esp_mqtt_comm` 组件）。

## Broker 配置

浏览器只能直连 WebSocket 端口，需要在 broker 上启用 WS 监听：

**EMQX（`emqx.conf` 或 Dashboard → 配置）：**

```hocon
listeners.ws.default {
  bind = "0.0.0.0:8083"
  # TLS 监听则配置 listeners.wss.default bind = "0.0.0.0:8084"
}
```

**Mosquitto（`mosquitto.conf`）：**

```conf
listener 8083
protocol websockets
```

公网场景建议使用 `wss://`（TLS）+ 域名证书；面板支持 `wss://` 直连。

## 常见问题

**Q: 页面提示「浏览器需使用 ws:// 或 wss:// 地址」？**
浏览器不支持 `mqtt://` 原生协议，请填写 broker 的 WebSocket 地址（`ws://` 或 `wss://`）。

**Q: 连接成功但看不到设备状态？**
确认设备 `device_id` 与面板一致、设备已连上同一 broker，且设备固件已实现 status 主题发布。

**Q: 如何在自己固件项目里使用？**
面板与固件完全解耦，通过 broker 通信。设备侧实现 `devices/{id}/cmd` 订阅与 `devices/{id}/status` 发布即可，协议按上文约定。

## 相关项目

- [ESP32 智能天气时钟](https://gitee.com/N3t4Ds/dev_weatherclock.git)：本面板对应的设备端示例项目，固件通过 `esp_mqtt_comm` 组件实现 MQTT 收发。

## License

MIT