# stellar-iot-simulator

**Repository Path**: astong/stellar-iot-simulator

## Basic Information

- **Project Name**: stellar-iot-simulator
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Stellar MQTT Simulator

可视化、可配置、可观测的 **MQTT 设备模拟器**（Tauri 2 + Rust + Vue 3），
payload 与指令协议对齐 `stellar-iot` 接入层，用于能耗 / 照明 / 通用遥测联调测试。

## 功能

| 模块 | 能力 |
|---|---|
| 连接管理 | 多 Broker 连接并存、TLS、账号、ClientID、topic 前缀/项目/网关、启动自动连接、网关心跳 |
| 设备模拟 | 模板 CRUD（编码/名称模板 `{n}`、数量、间隔）、内置预设（能耗/照明/温湿度/传感器）、点位生成器可视化配置 |
| 上行格式 | `standard` / `simple` / `batch`（每 3 轮）/ `single`（层级 topic，需 HIERARCHICAL 订阅） |
| 实时监控 | 上行/下行/心跳/ack 消息日志（过滤/暂停/清空/原始报文）、设备实时状态、点位 ECharts 曲线 |
| 指令中心 | 自动/手动/不应答 三种 ack 策略、延迟与失败率注入、手动发送任意 topic、原始报文查看 |
| 设置 | 心跳间隔、配置 JSON 导入导出（含下载/剪贴板） |

## 点位生成器

`固定值` `随机整数` `随机小数` `随机游走` `正弦波` `斜坡` `单调递增(累计)` `枚举` `布尔随机` `状态翻转`

- 能耗：`meterReading`（单调递增，避免 VEE 判 BACKWARD）+ `power`（随机游走）等
- 照明：`switch` / `brightness` / `power`，**指令下发后状态覆盖并回环进后续遥测**
- 传感器：`occupancy`（状态翻转）/ `lux`

## 开发环境要求

- Rust ≥ 1.77（本机 1.96）+ MSVC 工具链
- Node ≥ 18（本机 25）+ npm
- WebView2（Windows 10/11 自带）

## 运行

```bash
npm install
npm run tauri dev      # 开发模式（Vite 1420 + Tauri 窗口）
npm run tauri build    # 打包（Windows: .msi/.exe）
```

仅前端/内核检查：

```bash
npm run build                      # vue-tsc + vite build
cd src-tauri && cargo check        # Rust 编译检查
```

## 使用流程

1. **连接管理** → 新增连接：填 Broker 地址/账号、`Topic 前缀`（默认 iot）、
   `项目编码`（必须等于 `auth_tenant_project.code`）、`网关编码`，保存后点「连接」
2. **设备模拟** → 「套用预设」选择 能耗电表 / 照明灯具 / 温湿度 / 传感器，
   设置设备数量与间隔，绑定连接后「启动」
3. **实时监控** → 查看上行报文、设备实时值与点位曲线；若有平台指令下发，
   日志中会出现 `command` 类型下行
4. **指令中心** → 配置 ack 策略（自动应答 / 手动确认 / 不回应用于测 TIMEOUT），
   可注入延迟（>30000ms 触发平台超时）与失败率（触发平台 FAILED+重试）
5. **设置** → 导出/导入完整配置 JSON

### 配置热更新

- 修改**已连接**的连接（prefix/项目/网关/主题方式/自定义 Topic/账号等）并保存 → **自动重连**，新 Topic 立即生效
- 运行中的模板会在每次 tick 读取最新连接配置，无需重启模板
- 修改**运行中**的模板（点位数/间隔/格式等）并保存 → 自动重启该模板生效

## 与 stellar-iot 的约定

| 项 | 值 |
|---|---|
| data topic | `{prefix}/{project}/{gateway}/data`（QoS 1） |
| command topic | `{prefix}/{project}/{gateway}/command`（平台下发，自动订阅） |
| ack topic | `{prefix}/{project}/{gateway}/ack`（QoS 1，`{commandId,deviceId,timestamp,success,message,data}`） |
| heartbeat topic | `{prefix}/{project}/{gateway}/heartbeat`（QoS 0） |
| LWT topic | `stellar/lwt/{gateway}` |
| 标准格式 | `{"deviceId","deviceName","timestamp","values":{...}}` |
| 简洁格式 | `{"device":{"id","name","type"}, <key>: value ...}` |
| 批量格式 | 标准格式 JSON 数组 |
| 单值格式 | `.../{gateway}/{deviceCode}/{pointKey}` + 裸值（**仅 HIERARCHICAL 模式生效**） |

### 主题方式（Topic Mode）与自定义 Topic

| 模式 | 上行 JSON | 单值上报 | 平台订阅 |
|---|---|---|---|
| `FLAT`（默认） | `{prefix}/{project}/{gateway}/data` | 不支持 | `.../data` |
| `HIERARCHICAL` | `{prefix}/{project}/{gateway}/{deviceCode}/data` | `.../{deviceCode}/{pointKey}`（裸值） | `.../+/+` |
| `CUSTOM` | 完全由 `dataTopic` 指定（支持 `{deviceCode}`） | 不适用 | 按实际 Topic |
| 自定义覆盖（任意模式） | `dataTopic` 非空时优先 | — | — |

对应平台优先级：**网关级自定义 Topic > 自动生成（FLAT/HIERARCHICAL）> 协议级自定义 Topic（topicMode 为空）**；
模拟器的 `CUSTOM` 即最后一种，四个 Topic 手工填写。

连接表单提供：
- **主题方式** 选择（FLAT / HIERARCHICAL / CUSTOM）
- **Topic 预览**：随 prefix/项目/网关/模式实时显示上行、单值、指令、应答、心跳 topic
- **自定义 Topic 覆盖**（高级折叠，CUSTOM 时自动展开）：数据/指令/应答/心跳四个 Topic；
  - 非 CUSTOM：留空按模式自动生成
  - CUSTOM：数据 Topic 必填；未配置的通道直接禁用（不订阅指令 / 不应答 / 不发心跳）

> 设备/点位会在平台侧自动注册；能耗结算与照明控制还需在平台建好
> 资产绑定、`biz_energy_meter`、回路/场景等业务数据（详见
> `stellar-iot/docs/mqtt-simulator-guide.md` 前置数据章节）。

## 目录结构

```
src-tauri/src/
├── model.rs              配置/模板/生成器/事件模型（serde camelCase）
├── store.rs              配置 JSON 持久化（应用配置目录）
├── state.rs              AppState（config/mqtt/sim/pending）
├── command.rs            指令解析（3 形态）+ ack 策略
├── commands.rs           Tauri 命令（前后端桥）
├── engine/
│   ├── generator.rs      10 种值生成器
│   ├── device.rs         运行态设备与点位
│   └── simulator.rs      模板启停 / tick 发布 / 指令覆盖
└── mqtt/manager.rs       rumqttc 多连接、订阅指令、心跳、发布与日志事件
src/
├── layouts/MainLayout.vue
├── views/                Connections / Templates / Monitor / Commands / Settings
├── components/           FormDrawer / EChart
├── api/tauri.ts          invoke + listen 封装
├── stores/               config / runtime（日志环形缓冲、曲线序列）
└── types.ts              与 Rust 模型对齐的 TS 类型 + 4 个内置档案预设
```