# icutool-esp-client

**Repository Path**: plusboy/icutool-esp-client

## Basic Information

- **Project Name**: icutool-esp-client
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-05-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🧩 项目名称

**icutool-esp-client（单片机网关服务）**

---

# 🎯 一、目标

构建一个 Windows 本地服务，具备：

* 接收单片机心跳（HTTP）
* 维护设备在线状态（5秒心跳）
* 采集本机 CPU / 内存信息
* 通过 MQTT 下发数据（仅在线设备）
* 提供一个**极简窗口**展示设备状态（IP + MAC + 在线状态）

---

# 🧱 二、总体架构

```text
+------------------------+
|       GUI（极简）       |
| 设备列表（IP/MAC/状态） |
+-----------+------------+
            |
            v
+------------------------+
|     核心服务（Rust）    |
|------------------------|
| 状态管理（HashMap）     |
| 心跳处理（HTTP）        |
| 在线检测（定时任务）    |
| MQTT发送模块           |
| 系统信息采集           |
+------------------------+
```

---

# 🧪 三、技术选型

| 功能      | 技术            |
| ------- | ------------- |
| HTTP服务  | `axum`        |
| MQTT    | `rumqttc`     |
| 系统信息    | `sysinfo`     |
| 定时任务    | `tokio`       |
| GUI（极简） | `eframe/egui` |
| 并发状态管理  | `DashMap`     |

👉 全部都是**轻量级库**

---

# 📦 四、依赖（Cargo.toml）

```toml
[dependencies]
tokio = { version = "1", features = ["full"] }

axum = "0.7"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

rumqttc = "0.24"

sysinfo = "0.30"

dashmap = "5"

eframe = "0.27"
egui = "0.27"
```

---

# 🧠 五、核心数据结构设计

## 1️⃣ 设备状态

```rust
use std::time::Instant;

#[derive(Clone)]
pub struct Device {
    pub ip: String,
    pub mac: String,
    pub last_seen: Instant,
    pub online: bool,
}
```

---

## 2️⃣ 全局状态池

```rust
use dashmap::DashMap;

type DeviceMap = DashMap<String, Device>; // key: mac
```

---

# 🌐 六、HTTP接口设计（单片机调用）

## 接口：心跳上报

```http
POST /heartbeat
Content-Type: application/json

{
  "ip": "192.168.1.10",
  "mac": "AA:BB:CC:DD:EE:FF"
}
```

---

# ⏱ 七、在线检测机制（关键逻辑）

## 规则

* 单片机每 **5秒上报**
* 超过 **15秒未上报 = 离线**

---

# 📡 八、MQTT发送逻辑

## 发送条件

```text
只有 device.online == true 才发送
```

HTTP = 只负责“设备是否在线”
MQTT = 只负责“数据下发”
---

# 🖥 九、GUI设计（极简）

👉 不搞复杂交互，只做：

| IP | MAC | 状态 |
| -- | --- | -- |

---

# 📡 十四、MQTT协议设计（正式规范）

## 1️⃣ 基础配置  写到exe文件同目录下的config/config.ini里去 不要硬编码

```text
Broker: 192.168.10.100:10018
Username: admin
Password: xtXT1234
ClientId: device-gateway-rs（建议动态）
QoS: 0（低延迟优先）
```

---

## 2️⃣ Topic 规划

```text
icutool/esp32s3-monitor/weather        // 天气
icutool/esp32s3-monitor/system/cpu     // CPU
icutool/esp32s3-monitor/system/memory  // 内存
icutool/esp32s3-monitor/news           // 新闻资讯
```

👉 特点：

* **按功能拆分 topic（推荐设计）**
* 单片机可以“按区域订阅”，减少刷新压力

---


## Topic 列表

| Topic                                   | 说明      |
| --------------------------------------- | ------- |
| `icutool/esp32s3-monitor/weather`       | 天气信息    |
| `icutool/esp32s3-monitor/system/cpu`    | CPU 使用率 |
| `icutool/esp32s3-monitor/system/memory` | 内存使用情况  |
| `icutool/esp32s3-monitor/news`          | 新闻/资讯   |

---

## 消息格式定义

---

## 1️⃣ 天气信息

### Topic

```
icutool/esp32s3-monitor/weather
```

### Payload 示例

```json
{
  "temp_cur": 26,
  "temp_high": 31,
  "temp_low": 22,
  "description": "Cloudy",
  "city": "Shenzhen",
  "base64Ico": "base64Ico内容"
}
```

### 字段说明

| 字段          | 类型     | 说明            |
| ----------- | ------ | ------------- |
| temp_cur    | int    | 当前温度（℃）       |
| temp_high   | int    | 最高温度          |
| temp_low    | int    | 最低温度          |
| description | string | 天气描述（英文或中文均可） |
| city        | string | 城市名称          |
| base64Ico   | string | 天气图标 base64 内容 |

---

## 2️⃣ CPU 使用率

### Topic

```
icutool/esp32s3-monitor/system/cpu
```

### Payload 示例

```json
{
  "percent": 35
}
```

### 字段说明

| 字段      | 类型  | 说明             |
| ------- | --- | -------------- |
| percent | int | CPU 使用率（0~100） |

### 数据来源说明

* 通过 Windows `GetSystemTimes` 计算
* 为**时间差计算值（非瞬时值）**

---

## 3️⃣ 内存信息

### Topic

```
icutool/esp32s3-monitor/system/memory
```

### Payload 示例

```json
{
  "percent": 68,
  "used_mb": 5432,
  "total_mb": 8192
}
```

### 字段说明

| 字段       | 类型  | 说明        |
| -------- | --- | --------- |
| percent  | int | 内存使用率     |
| used_mb  | int | 已使用内存（MB） |
| total_mb | int | 总内存（MB）   |

### 数据来源说明

* 使用 `GlobalMemoryStatusEx`
* 精度为 MB

---

## 4️⃣ 新闻 / 资讯

### Topic

```
icutool/esp32s3-monitor/news
```

### Payload 示例

```json
{
  "category": "TECH",
  "headline": "AI edge device dashboard switched to MQTT",
  "summary": "Each screen region now updates only when its own topic arrives.",
  "time_ago": "just now"
}
```

### 字段说明

| 字段       | 类型     | 说明          |
| -------- | ------ | ----------- |
| category | string | 分类          |
| headline | string | 标题          |
| summary  | string | 摘要          |
| time_ago | string | 相对时间（UI显示用） |

### category 建议枚举

| 值             | 含义 |
| ------------- | -- |
| TECH          | 科技 |
| WORLD         | 国际 |
| FINANCE       | 金融 |
| SPORTS        | 体育 |
| ENTERTAINMENT | 娱乐 |


---

天气 和 新闻 暂时使用mock数据 我后续切换为接口调用





# ⏱ 十七、MQTT发送策略

## 1️⃣ 发送周期
请从config/config.ini读取 不要硬编码不好修改
默认如下
| 类型  | 频率      |
| --- | ------- |
| CPU | 5秒      |
| 内存  | 5秒      |
| 新闻  | 30秒     |
| 天气  | 60秒     |


---

# ✅ 最终总结

```text
单片机 → HTTP心跳（5秒）

服务端：
    ↓
更新设备状态
    ↓
定时检测在线
    ↓
如果有设备在线：
    → 每x秒发送 CPU / 内存（MQTT） 
    → 每x秒发送新闻（MQTT）
    → 每x秒发送天气（MQTT）
```

---

cargo build --release