Python全栈项目--手机语音远程控制智能家居系统（含嵌入式控制）

Python全栈项目–手机语音远程控制智能家居系统（含嵌入式控制）

一、项目简介

本项目是一个面向智能家居物联网场景的 Python 全栈实战项目。系统支持在手机端网页中点击麦克风输入语音，例如说出“打开客厅主灯”“卧室空调温度调到25”“我回来了”，前端会调用浏览器 Web Speech API 将语音转换成文字，FastAPI 后端完成指令解析、设备匹配、场景联动、日志记录，并把控制命令下发给 ESP32/STM32/树莓派等嵌入式控制端。

本项目实现了完整移动端语音输入能力和硬件控制链路：

手机网页语音输入 → Vue 前端 → FastAPI 鉴权接口 → 指令解析 → 设备/场景控制
                                                      ↓
                                            嵌入式命令队列 / HTTP直推
                                                      ↓
                                      ESP32/STM32 控制继电器、PWM、红外、窗帘电机

项目同时保留完整用户注册、登录、JWT 鉴权、设备管理、场景模式、日志审计功能，适合用于课程设计、毕业设计原型和物联网项目二次开发。

二、技术栈

• 后端：FastAPI、SQLAlchemy、Pydantic、JWT、Passlib
• 数据库：SQLite
• 前端：Vue 3 + Vite
• 手机语音：Web Speech API（SpeechRecognition / webkitSpeechRecognition）
• 嵌入式控制：ESP32 Arduino 示例、HTTP 轮询、HTTP 回执、继电器/PWM 控制
• 接口风格：RESTful API
• 认证方式：OAuth2 Password Form + Bearer Token
• 部署方式：后端 Uvicorn，前端 Vite 开发服务器或静态构建部署

三、系统架构

手机 / 平板 / PC 浏览器
  ├─ 登录/注册页面
  ├─ 移动端语音按钮
  ├─ 设备管理页面
  ├─ 场景与日志页面
  └─ 嵌入式命令队列页面
        │ HTTP + JWT
FastAPI 后端
  ├─ Auth 认证模块
  ├─ Device 设备模块
  ├─ Scene 场景模块
  ├─ Voice Command 指令解析模块
  ├─ Embedded Gateway 命令下发模块
  └─ CommandLog 日志模块
        │ ORM
SQLite 数据库
        │
        ├─ polling：ESP32 定时拉取 pending 命令
        └─ http：后端直接 POST 到嵌入式网关 endpoint

前端负责用户交互、手机语音识别和状态展示；后端负责认证、权限控制、语义解析、设备状态变更、场景联动、命令队列和数据持久化；嵌入式端负责把后端命令转换成真实硬件动作。

四、功能模块

1. 用户认证模块

• 用户注册
• 用户登录
• 密码哈希存储
• JWT token 生成与校验
• 业务接口鉴权保护
• 不同用户的设备、场景、日志互相隔离

2. 手机端语音输入模块

前端 App.vue 中封装浏览器语音识别能力：

const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition
recognition = new SpeechRecognition()
recognition.lang = 'zh-CN'
recognition.continuous = false
recognition.interimResults = true
recognition.onresult = (event) => {
  const text = Array.from(event.results).map(result => result[0].transcript).join('')
  voiceText.value = text
  const last = event.results[event.results.length - 1]
  if (last.isFinal) sendVoice()
}

用户可以在手机浏览器点击“按住/点击说话”，识别结果会自动填入输入框，并在最终识别完成后调用后端 /api/voice/command。

3. 智能设备模块

设备不仅保存名称、房间、类型、状态、数值，还增加了硬件控制字段：

支持的设备类型包括灯光、空调、窗帘、插座、风扇、传感器等。

4. 语音指令解析模块

后端接收语音识别文本后进行规则解析：

• “打开/开启/on” → 开启设备
• “关闭/关掉/off” → 关闭设备
• “调到/设置/温度/亮度/开度” + 数字 → 设置设备数值
• 精确命中场景口令 → 执行场景动作

核心代码逻辑：

def _detect_action(text: str):
    normalized = text.strip().lower()
    if any(word in normalized or word in text for word in ["打开", "开启", "启动", "on"]):
        return "on", None
    if any(word in normalized or word in text for word in ["关闭", "关掉", "off"]):
        return "off", None
    if any(word in text for word in ["调到", "设置", "温度", "亮度", "开度"]):
        nums = re.findall(r"\d+(?:\.\d+)?", text)
        if nums:
            return "set", float(nums[0])
    return "unknown", None

5. 嵌入式控制模块

后端在设备状态改变时，会创建一条 EmbeddedCommand 记录。命令包含 hardware_id、action、value、payload、status 等字段。

payload = {
    "command_id": command.id,
    "hardware_id": device.hardware_id,
    "device_name": device.name,
    "room": device.room,
    "type": device.device_type,
    "action": action,
    "status": bool(device.status),
    "value": float(device.value or 0),
    "unit": device.unit,
    "source": source,
}

下发模式有两种：

1. polling 模式：ESP32 定时调用后端接口拉取 pending 命令，执行后 ack。
2. http 模式：后端直接向设备 endpoint POST JSON，如果推送失败则保留 pending 队列，等待轮询补偿。

6. 场景联动模块

用户可以创建场景口令，例如“我回来了”。当前端提交该口令后，后端会匹配场景并批量执行设备动作，同时给每个受影响设备生成嵌入式控制命令。

7. 日志与网关队列模块

• command_logs 保存用户每次语音/文本指令和执行结果
• embedded_commands 保存每条下发到硬件的命令及状态
• 前端提供“嵌入式下发队列”页面，便于查看 pending、sent、ack、failed 状态

五、数据库/数据模型设计

主要数据表如下：

设备模型节选：

class Device(Base):
    __tablename__ = "devices"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(100), nullable=False)
    device_type = Column(String(50), nullable=False)
    room = Column(String(80), nullable=False)
    status = Column(Boolean, default=False)
    value = Column(Float, default=0)
    unit = Column(String(20), default="")
    hardware_id = Column(String(80), default="")
    hardware_key = Column(String(80), default="")
    protocol = Column(String(30), default="polling")
    endpoint = Column(String(255), default="")
    last_command_at = Column(DateTime, nullable=True)
    owner_id = Column(Integer, ForeignKey("users.id"), nullable=False)

六、后端接口设计

七、前端页面设计

前端使用 Vue 3 + Vite，主要页面区域包括：

1. 移动端连接设置：手机端配置后端局域网 API 地址。
2. 登录/注册卡片：未登录时显示，登录成功后保存 token。
3. 手机语音控制台：点击麦克风识别语音，也支持手动输入。
4. 添加设备表单：录入设备名、房间、类型、数值单位和硬件参数。
5. 设备列表：展示设备状态，支持开启、关闭、设置数值、删除。
6. 场景模式：创建场景口令并绑定设备动作。
7. 嵌入式下发队列：查看命令下发和 ack 状态。
8. 指令日志：展示最近执行记录。

移动端 API 地址不能固定为 127.0.0.1，因此 api.js 根据当前页面 hostname 自动生成默认后端地址：

const DEFAULT_BASE = `${window.location.protocol}//${window.location.hostname}:8000/api`
const API_BASE = localStorage.getItem('smart_home_api_base') || DEFAULT_BASE

如果前后端部署在不同机器，可以在页面“移动端连接设置”里手动保存 API 地址。

八、嵌入式实现说明

项目提供 ESP32 示例：

project/embedded/esp32_voice_home_controller.ino

核心流程：

ESP32 连接 WiFi
    ↓
定时 GET /api/embedded/commands/{hardware_id}?hardware_key=xxx
    ↓
解析 action=on/off/set
    ↓
控制 GPIO 继电器或 PWM 输出
    ↓
POST /api/embedded/commands/{id}/ack 回传执行结果

默认硬件映射：

• GPIO26：继电器输出，可控制灯、插座、电机
• GPIO27：PWM 输出，可控制灯光亮度或风扇速度

后续扩展方向：

• 使用红外 LED 发送空调遥控码
• 使用 RS485/Modbus 控制智能开关面板
• 使用 MQTT 接入 Home Assistant
• 使用设备证书或签名提升安全性
• 使用 HTTPS 或内网穿透支持公网远程控制

九、部署与运行步骤

1. 运行后端

cd project/backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

后端默认地址：http://127.0.0.1:8000

2. 运行前端

cd project/frontend
npm install
npm run dev -- --host 0.0.0.0

电脑访问：http://127.0.0.1:5173

手机访问：http://电脑局域网IP:5173

3. 配置手机端 API 地址

手机打开前端页面后，在“移动端连接设置”里填写：

http://电脑局域网IP:8000/api

例如：

http://192.168.1.8:8000/api

4. 使用流程

1. 注册账号并登录。
2. 点击初始化演示设备，或手动添加设备。
3. 如果使用 ESP32，将代码中的 API_BASE、HARDWARE_ID、HARDWARE_KEY 改成和设备表一致。
4. 手机点击麦克风，说“打开客厅主灯”。
5. 后端更新数据库状态，并生成 embedded command。
6. ESP32 轮询到命令后控制继电器/PWM，并回传 ack。
7. 前端查看“嵌入式下发队列”和“指令日志”。

十、项目总结

本项目完整实现了一个“手机端语音输入 + Python 后端解析 + 嵌入式远程控制”的智能家居系统。前端不再只是简单文本框，而是加入移动端语音识别和手机访问配置；后端不只更新数据库状态，还会把控制动作转换成硬件命令队列，并支持 ESP32 轮询、回执和 HTTP 直推；数据库保存用户、设备、场景、日志和硬件命令，形成了完整的全栈业务闭环。

该项目可以作为真实智能家居系统的基础版本继续扩展：加入大模型意图识别、ASR 云服务、MQTT 网关、Home Assistant、红外空调控制、设备证书、HTTPS、公网远程访问等能力。

项目代码

下载链接