# MQTT单片机通讯管理系统

**Repository Path**: twohagitee/mqtt-microcontroller

## Basic Information

- **Project Name**: MQTT单片机通讯管理系统
- **Description**: MQTT单片机通讯管理系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-06
- **Last Updated**: 2026-01-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 单片机 MQTT 通讯管理系统

## 项目概述
基于 FastAPI + Vue + SQLite 的单片机上位机 MQTT 通讯管理系统，实现设备管理、MQTT 服务配置和双向通讯功能。

## 技术栈
- 后端：FastAPI、SQLAlchemy、SQLite
- 前端：Vue 3、Element Plus、Vite
- 通讯：MQTT（paho-mqtt）
- 数据库：SQLite（本地开发环境）

## 目录结构
```
microcontroller/
├── backend/                 # FastAPI 后端
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py          # FastAPI 应用入口
│   │   ├── models/          # 数据库模型
│   │   ├── routers/         # API 路由
│   │   ├── services/        # 业务逻辑服务
│   │   ├── schemas/         # Pydantic 模型
│   │   ├── config.py        # 配置文件
│   │   └── microcontroller.db # SQLite 数据库（开发环境）
│   ├── microcontroller.db   # 可能的数据库副本（开发环境）
│   └── requirements.txt     # Python 依赖
├── frontend/                # Vue 前端
│   ├── src/
│   │   ├── components/      # Vue 组件
│   │   ├── views/           # 页面视图
│   │   ├── services/        # API 服务
│   │   ├── stores/          # 状态管理
│   │   ├── styles/          # 样式
│   │   └── main.js          # 应用入口
│   ├── index.html
│   └── package.json         # Node.js 依赖
├── mosquitto.conf           # Mosquitto 配置
├── mosquitto_data/          # Mosquitto 持久化数据（忽略提交）
└── test_scripts/            # MQTT 测试与模拟脚本
```

## 快速开始

### 前置要求
- Python 3.10（当前后端环境：`3.10.11`）
- Node.js（建议 18+）
- Mosquitto MQTT `2.0.22`

### 启动 MQTT 服务器
```bash
mosquitto -c mosquitto.conf -v
```

### 启动后端（FastAPI）
```bash
cd backend/app
pip install -r ../requirements.txt
python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
（或在 `backend` 目录下执行：`uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload`）

### 启动前端（Vite）
```bash
cd frontend
npm install
npm run dev
```
访问：`http://127.0.0.1:3000/`

### 简单连通性测试
```bash
curl http://127.0.0.1:8000/
curl "http://127.0.0.1:8000/api/messages/stats/summary"
curl "http://127.0.0.1:8000/api/messages/?limit=20&offset=0&device_id=ESP32_001"
```

## API 速览
- `GET /api/devices/`：设备列表
- `GET /api/mqtt/status`：MQTT 连接状态
- `GET /api/messages/`：消息列表（`device_id` 支持设备标识字符串或数据库 ID）
- `GET /api/messages/stats/summary`：消息统计（可选 `device_id`）
- 其他：`/api/messages/recent`、`/api/messages/topics/list`、`DELETE /api/messages` 等

## 测试脚本
- `python test_scripts/mqtt_client_test.py --host localhost --port 1883 --interactive`
- 主题规范：设备命令发布到 `devices/{device_id}/command`；设备上报 `devices/{device_id}/status|data|response`

## 常见问题
- 前端 `ECONNREFUSED 127.0.0.1:8000`：请确认后端已启动并在 8000 端口监听。
- `device_id` 类型不匹配：后端已支持设备标识字符串（如 `ESP32_001`），内部自动转换为数据库外键。
- SQLite 数据库：建议本地开发使用，生产环境按需替换为持久化数据库。

## 推送到远程仓库
本地仓库已初始化，首次提交后可按以下步骤推送到远程：
```bash
git remote add origin <你的远程仓库URL>
git branch -M main
git push -u origin main
```
如使用 Gitee，请在 Gitee 创建空仓库后，复制 HTTPS/SSH 地址替换 `<你的远程仓库URL>`。