SmartHome AI Agent — 基于 openvela 智能体的智能家居控制系统

一、作品简介

SmartHome AI Agent 是一款运行在 openvela（NuttX RTOS 实时操作系统）上的 AI 驱动智能家居控制器。用户通过自然语言对话即可控制灯光、空调等家居设备，系统基于 cAGENT 框架实现 ReAct 推理循环，LLM 自主决定何时调用工具、查询设备状态，实现真正的智能决策。

核心亮点：

• 9 个 LLM 工具：灯光控制、空调控制、设备状态查询、天气查询、场景执行、定时器管理、Skill 读取
• 5 个领域技能：设备控制策略、安全规则、场景定义、定时器策略、天气感知
• 双模 UI：Console 命令行 + LVGL 图形界面（设备面板 / AI 对话 / 设置三页面）
• 多模型热切换：运行时切换 DeepSeek、Kimi、通义千问、OpenAI 后端，无需重编译
• 跨平台：QEMU 模拟器 + ESP32-S3-BOX-3 真机，一次开发多端部署

---

二、快速开始

2.1 环境准备

本仓库作为独立提交仓库使用，建议放在 openvela 工作区根目录下：

cd /home/arongw/openvela
git clone <your-openvela-smarthome-repo-url> openvela_smarthome
source build/envsetup.sh

拉取后将本仓库软链接到 openvela 标准构建位置：

cd /home/arongw/openvela

# 应用和 cAGENT
mkdir -p packages/demos
ln -sfnT ../../openvela_smarthome/demos/smart_home packages/demos/smart_home
ln -sfnT ../openvela_smarthome/packages/cAGENT packages/cAGENT

# Goldfish 模拟器 defconfig
mkdir -p vendor/openvela/boards/vela/configs/goldfish-smart_home
ln -sfn "$(pwd)/openvela_smarthome/board/goldfish-arm64/configs/smart_home/defconfig" \
  vendor/openvela/boards/vela/configs/goldfish-smart_home/defconfig

# ESP32-S3-BOX-3 defconfig
mkdir -p vendor/espressif/boards/esp32s3/esp32s3-box-3/configs/smart_home
ln -sfn "$(pwd)/openvela_smarthome/board/esp32s3-box-3/configs/smart_home/defconfig" \
  vendor/espressif/boards/esp32s3/esp32s3-box-3/configs/smart_home/defconfig

如果目标路径已经是普通目录或普通文件，请先确认里面没有本地改动，再手动备份或移走；上面的 ln -sfnT 适合目标不存在或已经是软链接的情况。

openvela 工作区中 apps/packages 通常是指向 ../packages 的软链接，因此 apps/packages/demos/smart_home 和 packages/demos/smart_home 最终等价。本文档统一使用 packages/demos/smart_home，更贴近 Kconfig 实际 source 的路径。

软链接验证：

readlink -f packages/demos/smart_home
readlink -f packages/cAGENT
readlink -f vendor/openvela/boards/vela/configs/goldfish-smart_home/defconfig
readlink -f vendor/espressif/boards/esp32s3/esp32s3-box-3/configs/smart_home/defconfig

本仓库包含：

• demos/smart_home/：smart_home demo 应用、资源和详细构建文档
• packages/cAGENT/：C 语言 Agent 框架
• board/：Goldfish 和 ESP32-S3-BOX-3 的参考板级配置
• scripts/：数据分区镜像、字体子集和 ESP32-S3 兼容性辅助脚本

构建命令需要在 openvela 工作区根目录执行。完成上述软链接后，可直接按下方命令构建；更完整的双平台说明见 demos/smart_home/docs/dual-platform-guide.md。

2.2 运行前配置

API Key 配置

修改 demos/smart_home/src/config/smart_home_config.h：

#define SMART_HOME_DEMO_API_KEY  "sk-your-api-key-here"

或在 LVGL UI 的 Settings 页面运行时修改（支持 DeepSeek/Kimi/通义千问/OpenAI/自定义）。首次联网调用模型前必须完成 API key 配置，不要把真实 key 提交到 Git。

WiFi 配置

Goldfish 模拟器使用 Ethernet eth0，不需要 WiFi 配置。ESP32-S3-BOX-3 真机需要在运行前完成 WiFi 配置：

echo '{"ssid":"你的WiFi名称","password":"你的WiFi密码"}' > /data/wapi.conf

或修改 Kconfig 默认值后重新构建：

CONFIG_SMART_HOME_WIFI_SSID="你的WiFi名称"
CONFIG_SMART_HOME_WIFI_PASSWORD="你的WiFi密码"

2.3 QEMU 模拟器运行（推荐先用此方式验证）

# 编译 goldfish-arm64 版本（Console UI）
cd /home/arongw/openvela
source build/envsetup.sh
./build.sh vendor/openvela/boards/vela/configs/goldfish-smart_home/ -j8

# in-tree build 产物需要整理到 emulator.sh 期望的目录
mkdir -p cmake_out/vela_goldfish-arm64-v8a-ap
cp nuttx/.config cmake_out/vela_goldfish-arm64-v8a-ap/
cp nuttx/vela_*.bin cmake_out/vela_goldfish-arm64-v8a-ap/
ln -sf ../../nuttx/nuttx cmake_out/vela_goldfish-arm64-v8a-ap/nuttx

# 启动模拟器并部署资源
./emulator.sh cmake_out/vela_goldfish-arm64-v8a-ap
adb push packages/demos/smart_home/res /data/

# 在 NSH 中运行
nsh> ifup eth0
nsh> renew eth0
nsh> smart_home "打开客厅灯"        # 单次命令模式
nsh> smart_home                     # LVGL UI 或 Console 交互模式

2.4 ESP32-S3-BOX-3 真机部署

# 编译 BOX-3 版本（LVGL UI）
cd /home/arongw/openvela
source build/envsetup.sh
rm -f nuttx/.config
./build.sh vendor/espressif/boards/esp32s3/esp32s3-box-3/configs/smart_home/ -j8

# 烧录固件
cd nuttx
make flash ESPTOOL_PORT=/dev/ttyACM0 ESPTOOL_BAUD=921600
cd ..

# 制作并烧录数据分区（含字体、图标、技能文件）
WITH_ICONS=1 bash openvela_smarthome/scripts/make_box3_littlefs_data_image.sh
esptool --chip esp32s3 --port /dev/ttyACM0 --baud 921600 \
  write-flash 0xe00000 out/box3_littlefs_data/data_lfs.bin

---

三、项目结构

openvela_smarthome/
├── README.md                    # 本文档
├── LICENSE                      # Apache License 2.0
├── NOTICE                       # 版权声明
├── THIRD-PARTY-NOTICES          # 第三方依赖许可声明
├── .gitignore
│
├── demos/
│   └── smart_home/              # ★ 主应用：智能家居 AI Agent
│       ├── README.md            # demo 级说明、文档索引、构建运行流程
│       ├── src/
│       │   ├── app/             # 程序入口 (smart_home_main.c)
│       │   ├── agent/           # AI Agent 封装 (cAGENT 集成)
│       │   ├── config/          # 模型配置 & 多后端预设
│       │   ├── device/          # 虚拟设备层 (灯光/空调/场景/环境)
│       │   ├── tools/           # 9 个 LLM 工具实现
│       │   ├── skills/          # 技能加载器 + 5 个技能文件
│       │   ├── net/             # WiFi/网络状态管理
│       │   ├── voice/           # 语音接口 (预留桩)
│       │   └── ui/
│       │       ├── smart_home_ui.c  # Console UI (REPL)
│       │       └── lvgl/            # LVGL 图形 UI
│       ├── res/
│       │   ├── fonts/           # 可选字体资源
│       │   ├── icons/           # 图标资源
│       │   └── skills/          # 5 个技能 Markdown
│       ├── docs/                # 双平台、BOX-3、UI、环境模拟、多模型等专题文档
│       ├── Kconfig              # NuttX 配置入口
│       ├── Makefile             # NuttX apps 构建规则
│       ├── Make.defs            # NuttX apps 构建片段
│       └── CMakeLists.txt       # CMake 构建规则
│
├── packages/
│   └── cAGENT/                  # 自研 AI Agent 框架
│       ├── README.md
│       ├── include/             # 公共 API 头文件 (agent.h, cagent/*.h)
│       ├── src/
│       │   ├── core/            # Agent 核心：ReAct 循环、上下文构建
│       │   ├── llm/             # LLM 适配：OpenAI 兼容协议、Mock 模型
│       │   ├── memory/          # 会话与记忆管理
│       │   ├── skills/          # 技能注册与注入
│       │   ├── tools/           # 工具注册、JSON Schema、安全守卫
│       │   └── runtime/         # 平台抽象 (NuttX/ESP-IDF/STM32)
│       ├── docs/                # 架构、API、context budget、skill 设计等说明
│       ├── Kconfig
│       ├── Makefile / Make.defs
│       └── CMakeLists.txt
│
├── board/
│   ├── esp32s3-box-3/           # ESP32-S3-BOX-3 BSP
│   │   ├── README.md
│   │   ├── Kconfig
│   │   ├── configs/smart_home/defconfig
│   │   ├── include/             # board.h, board_memorymap.h
│   │   ├── src/                 # LCD ILI9342C、触摸 GT911、SPI、音频
│   │   └── scripts/
│   └── goldfish-arm64/          # QEMU 模拟器配置
│       └── configs/smart_home/defconfig
│
├── scripts/                     # 构建辅助脚本
│   ├── fix_box3_mbedtls_*.sh    # ESP32 mbedTLS 兼容性修复
│   ├── make_box3_littlefs_data_image.sh  # LittleFS 数据镜像
│   ├── subset_font.sh           # 字体子集化
│   └── readme.md                # 脚本使用说明
│
├── docs/
│   ├── contest_problem.md       # 赛题说明
│   └── deliverable_preliminary.md  # 初赛交付物详细文档
│
└── logs/                        # 开发日志与演示材料
    ├── README.md                # AI Coding 日志导出/提交说明
    ├── 演示.gif                 # 演示动图
    └── 演示视频.webm            # 演示视频
    # 真实开发日志按 logs/<github_login>/... 放置

---

四、系统架构

┌──────────────────────────────────────────────────────┐
│                    用户交互层                         │
│  ┌─────────────┐  ┌─────────────────────────────────┐│
│  │ Console UI  │  │         LVGL UI                 ││
│  │  (REPL)     │  │  Panel │ Chat │ Settings        ││
│  └──────┬──────┘  └────────┴────┬───────────────────┘│
│         │                       │  (pthread + async) │
├─────────┴───────────────────────┴────────────────────┤
│                   AI Agent 层 (cAGENT)               │
│  ┌──────────┐ ┌──────────┐ ┌────────────────────┐   │
│  │ ReAct    │ │ Context  │ │ Event Callback     │   │
│  │ Agent    │ │ Builder  │ │ System             │   │
│  │ Loop     │ │          │ │                    │   │
│  └──────────┘ └──────────┘ └────────────────────┘   │
├──────────────────────────────────────────────────────┤
│                  能力注册层                           │
│  ┌────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│  │ 9 Tools    │ │ 5 Skills    │ │ Context Provider│ │
│  │ 设备控制   │ │ 领域知识    │ │ 设备状态注入    │ │
│  │ 天气查询   │ │ 安全策略    │ │ 环境传感器      │ │
│  │ 场景执行   │ │ 场景定义    │ │                 │ │
│  │ 定时器管理 │ │ 定时策略    │ │                 │ │
│  └────────────┘ └─────────────┘ └─────────────────┘ │
├──────────────────────────────────────────────────────┤
│                   设备抽象层                         │
│  Virtual Device Table (8 devices max)                │
│  • 灯光: on/off + 亮度(0-100%)                       │
│  • 空调: on/off + 模式 + 风速 + 温度(16-30°C)       │
│  • 场景: sleep/movie/away/home                       │
│  • 环境: 温度/湿度/光照 模拟传感器                   │
├──────────────────────────────────────────────────────┤
│                   基础设施层                         │
│  WiFi(WPA2) │ TLS/HTTPS │ JSON解析 │ NuttX RTOS    │
└──────────────────────────────────────────────────────┘

---

五、功能说明

5.1 自定义工具（9 个，满足评分要求：至少 2 个）

工具名	功能	参数	读写属性
get_home_status	查询全部设备和环境状态	无	只读
get_weather	查询模拟天气数据	location	只读
set_light	控制灯光开关和亮度	room, on, brightness	读写
set_ac	控制空调模式/风速/温度	room, on, mode, temperature, fan_speed	读写
run_scene	执行预设场景	scene (sleep/movie/away/home)	读写
set_timer	创建定时器/提醒	delay_seconds, message, name	读写
list_timers	列出活跃定时器	无	只读
cancel_timer	取消定时器	id	读写
read_skill	读取领域 Skill 完整策略	name	只读

5.2 自然语言控制闭环（满足评分要求：意图→工具→反馈）

完整链路示例：

用户输入: "我要睡觉了"
    ↓ 意图理解
Agent 推理: 用户想进入睡眠场景
    ↓ 工具调用
调用 run_scene(scene="sleep")
    → 客厅灯关闭、卧室灯亮度10%、卧室空调26°C制冷
    ↓ 结果反馈
Agent 回复: "已为您开启睡眠模式：客厅灯已关闭，卧室灯调至10%，空调设为26°C制冷。"

更多示例：

• “打开客厅灯” → set_light(room="living_room", on=true, brightness=60)
• “现在室温多少度” → get_home_status() → 返回环境温度
• “上海今天天气怎么样” → get_weather(location="Shanghai")
• “5分钟后提醒我喝水” → set_timer(delay_seconds=300, message="喝水")

5.3 领域技能（5 个 Markdown 文件）

技能文件	功能	关键规则
smart_home_device_control.md	设备控制策略	亮度默认60%、温度>28°C建议制冷、光照<80lx建议开灯
smart_home_safety.md	安全规则	必须通过工具操作、尊重参数边界(亮度0-100, 温度16-30°C)
smart_home_scenes.md	场景定义	sleep/movie/away/home 四场景的设备预设
smart_home_timer.md	定时器策略	定时器仅内存存储，重启后丢失
smart_home_weather.md	天气策略	基于天气条件智能建议空调设置

5.4 异常处理（满足评分要求）

异常场景	处理方式
WiFi 连接失败	自动重试 3 次，失败后继续运行（使用现有网络）
API 超时	默认 30 秒超时，返回错误提示用户重试
工具调用失败	返回 JSON 错误信息，Agent 据此回复用户
设备未找到	返回 AGENT_ERROR_NOTFOUND，Agent 告知用户
参数越界	自动 clamp（亮度0-100，温度16-30°C）
API Key 无效	401 错误提示，可在 Settings 页面修改
内存不足	返回 AGENT_ERROR_NOMEM，清理后退出

---

六、多 LLM 后端支持

后端	API 地址	默认模型
DeepSeek	api.deepseek.com/v1	deepseek-v4-flash
Kimi（月之暗面）	api.moonshot.cn/v1	moonshot-v1-8k
通义千问	dashscope.aliyuncs.com/compatible-mode/v1	qwen-plus
OpenAI	api.openai.com/v1	gpt-4o-mini
自定义	用户指定	用户指定

切换方式：LVGL UI Settings 页面下拉选择，或修改 smart_home_config.h 重编译。

---

七、技术栈

层次	技术
操作系统	openvela (NuttX RTOS)
AI 框架	cAGENT（自研，ReAct Agent，纯 C 语言，32KB 核心栈）
LLM 接口	OpenAI Compatible API (HTTP + TLS)
默认模型	DeepSeek V4 Flash
图形界面	LVGL 9.x + FreeType + MiSans 字体
网络协议	WPA2 + DHCP + DNS + HTTPS
硬件目标	ESP32-S3-BOX-3 (240MHz, 8MB PSRAM, 320×240 LCD)
模拟器	QEMU goldfish-arm64

---

八、开源协议与合规

文件	说明
LICENSE	Apache License 2.0
NOTICE	版权归属声明
THIRD-PARTY-NOTICES	所有第三方依赖的许可声明（cAGENT、LVGL、libuv、cJSON、mbedTLS、FreeType、MiSans、lodepng/libpng）

所有自研代码采用 Apache 2.0 协议。第三方依赖许可兼容性已验证：

• Apache 2.0（cAGENT、mbedTLS）✓
• MIT（LVGL、libuv、cJSON、lodepng）✓
• FTL/GPL-2.0（FreeType）✓
• MiSans 字体许可 ✓

---

九、演示与日志

运行演示

Console UI 交互示例：

=== Smart Home Agent Demo ===
backend: api.deepseek.com/v1/chat/completions model=deepseek-v4-flash
type 'quit' to exit

home> 打开客厅灯
[Agent] 正在调用 set_light...
[Result] {"ok":true,"room":"living_room","on":true,"brightness":60}
已为您打开客厅灯，亮度设为60%。

home> 我要睡觉了
[Agent] 正在调用 run_scene...
[Result] {"ok":true,...}
已开启睡眠模式：客厅灯关闭，卧室灯调至10%，空调26°C制冷。

LVGL UI 三页面：

• Panel：设备卡片网格 + 房间筛选 + 控制弹窗（滑块/下拉）
• Chat：气泡对话 + 工具调用追踪卡片 + 屏幕键盘
• Settings：模型后端切换 + API 配置

AI Coding 日志

完整对话日志见 logs/ 目录，记录了 AI 辅助开发全过程：

• 架构设计讨论
• 代码生成与审查
• LVGL UI 开发
• 编译错误调试
• 文档编写