基于openvela AI Agent的智能学习空间感知与自适应控制系统

本项目基于 openvela / Apache NuttX 与经典 ESP32 DevKitC，构建面向学习场景的端云协同 AI Agent。系统通过自然语言理解用户意图，在 ESP32 本地调用真实硬件 Tool，完成环境检测、个性化灯光控制和屏幕距离保护，并可通过飞书机器人远程交互。

核心功能

1. 学习环境检测与 RGB 指示

系统读取光照与 NTC 温度原始信号，根据 Skill 规则判断当前环境是否适合学习，并控制实体 RGB 指示灯：

• 绿色：环境适合学习；
• 蓝色：存在轻度不适宜条件；
• 红色：严重不适宜，例如光线过暗；
• 白色：传感器读取或判断失败。

主要 Tool：

• read_environment
• set_rgb_indicator

主要 Skill：

• study-environment-optimizer

2. 个性化灯光档案

GPIO32 PWM 小灯支持绝对亮度、相对调节和具名场景记忆。首次使用新场景时，系统进入试用状态；用户可以继续说“亮一点”或“暗一点”，只有明确说“可以”“满意”或“保存吧”后才保存档案。

实际状态流程：

start -> pending -> adjust -> confirm -> saved profile

主要 Tool：

• control_lamp_brightness
• manage_light_profile

主要 Skill：

• personalized-light-profile

3. 个性化屏幕距离保护

VL53L3CX ToF 传感器通过 /dev/tof0 与 uORB 数据通路提供真实距离。用户可以先记录舒适观看距离，后续系统重新采样并判断当前是否过近。

主要操作：

• calibrate：记录当前舒适距离；
• check：重新测距并判断是否过近；
• get：查询已保存基准；
• reset：删除基准。

主要 Tool：

• read_distance
• manage_screen_distance

主要 Skill：

• screen-distance-monitor

4. 基础知识问答

对于不涉及硬件的普通问题，Agent 直接通过大模型回答，不调用传感器、PWM 或 RGB Tool。例如：

请用一句话回答：什么是电阻？
请用一句话回答：什么是 ToF 测距？

硬件组成

• 经典 ESP32 DevKitC；
• VL53L3CX ToF 距离传感器；
• 光照模拟量传感器；
• NTC 温度模拟量传感器；
• GPIO32 PWM 小灯；
• RGB 状态指示灯；
• USB 串口连接。

软件环境

• Ubuntu Linux；
• openvela / Apache NuttX；
• Python 3；
• 飞书开放平台应用；
• DeepSeek API；
• esptool.py；
• picocom 或其他串口终端。

仓库结构

.
├── packages/ai_agent/           # Agent、Tool、Skill、TLS、uORB 与硬件适配
├── nuttx/                       # VL53L3CX 驱动与 ESP32 板级适配
├── apps/examples/https_client/  # HTTPS/TLS 验证示例
├── host/feishu_gateway/         # 飞书消息网关
├── configs/                     # 最终稳定配置
├── firmware/                    # 最终稳定固件
├── docs/                        # 项目说明书与演示材料
└── scripts/                     # 烧录和辅助脚本

快速开始

1. 烧录 ESP32 固件

仓库中已提供最终稳定固件：

firmware/nuttx.bin

使用脚本烧录：

cd /path/to/openvela-ai-learning-assistant
./scripts/flash_esp32.sh /dev/ttyUSB0 460800

也可以直接使用 esptool.py：

esptool.py \
  --chip esp32 \
  --port /dev/ttyUSB0 \
  --baud 460800 \
  write_flash \
  0x1000 firmware/nuttx.bin

2. 打开串口并启动 AI Agent

picocom -b 115200 /dev/ttyUSB0

进入 NuttShell 后执行：

ai_agent

出现 vela> 提示符后，说明 Agent 已启动。

首次配置大模型时执行：

set_llm deepseek <YOUR_DEEPSEEK_API_KEY>

不要在截图、日志或仓库中提交真实 API Key。

飞书网关配置

1. 创建配置目录

mkdir -p "$HOME/.config/vela-feishu-gateway"
chmod 700 "$HOME/.config/vela-feishu-gateway"

2. 创建环境变量文件

编辑：

nano "$HOME/.config/vela-feishu-gateway/env"

填写：

LARK_APP_ID=replace_with_your_app_id
LARK_APP_SECRET=replace_with_your_app_secret
VELA_SERIAL_PORT=/dev/ttyUSB0
VELA_SERIAL_BAUD=115200
VELA_AGENT_TIMEOUT=150

保存后设置权限：

chmod 600 "$HOME/.config/vela-feishu-gateway/env"

env 包含真实飞书凭据，严禁提交到 Git 仓库。仓库中只能保留 env.example。

3. 首次准备 Python 虚拟环境

仓库已经包含 .venv 时可跳过本步骤。需要重新创建时执行：

cd ~/openvela_workspace/openvela

python3 -m venv host/feishu_gateway/.venv

host/feishu_gateway/.venv/bin/python -m pip install --upgrade pip

if [ -f host/feishu_gateway/requirements.txt ]; then
  host/feishu_gateway/.venv/bin/pip install \
    -r host/feishu_gateway/requirements.txt
fi

4. 启动飞书网关

确保 ESP32 已连接到 /dev/ttyUSB0，并且没有其他串口程序占用该设备，然后执行：

cd ~/openvela_workspace/openvela || exit 1

set -a
source "$HOME/.config/vela-feishu-gateway/env"
set +a

PYTHONPATH=host/feishu_gateway \
host/feishu_gateway/.venv/bin/python \
  host/feishu_gateway/gateway.py

网关运行期间保持该终端窗口打开。

5. 停止网关

在运行网关的终端中按：

Ctrl+C

飞书网关启动脚本

为了避免每次手动输入，可创建脚本：

cat > "$HOME/start_vela_feishu_gateway.sh" <<'BASH'
#!/usr/bin/env bash

PROJECT="$HOME/openvela_workspace/openvela"
ENV_FILE="$HOME/.config/vela-feishu-gateway/env"
PYTHON="$PROJECT/host/feishu_gateway/.venv/bin/python"
GATEWAY="$PROJECT/host/feishu_gateway/gateway.py"

if [ ! -d "$PROJECT" ]; then
  echo "ERROR：工程目录不存在：$PROJECT"
  return 1 2>/dev/null || true
fi

if [ ! -f "$ENV_FILE" ]; then
  echo "ERROR：环境变量文件不存在：$ENV_FILE"
  return 1 2>/dev/null || true
fi

if [ ! -x "$PYTHON" ]; then
  echo "ERROR：Python 虚拟环境不存在：$PYTHON"
  return 1 2>/dev/null || true
fi

if [ ! -f "$GATEWAY" ]; then
  echo "ERROR：飞书网关程序不存在：$GATEWAY"
  return 1 2>/dev/null || true
fi

cd "$PROJECT" || return 1 2>/dev/null || true

set -a
source "$ENV_FILE"
set +a

export PYTHONPATH=host/feishu_gateway
exec "$PYTHON" "$GATEWAY"
BASH

chmod +x "$HOME/start_vela_feishu_gateway.sh"

以后直接运行：

bash "$HOME/start_vela_feishu_gateway.sh"

演示问题

环境检测

请检测现在适合学习吗？

遮挡光照传感器后再次发送同一句，可观察环境状态和 RGB 颜色变化。

个性化灯光

新建场景：

我要看电影，帮我调到看电影灯光
暗一点
可以

恢复场景：

使用看电影灯光

实际亮度以 Tool 返回值为准，不预设每次相对调节的固定步长。

屏幕距离保护

记录舒适距离：

记住我现在正常看屏幕的距离

查询基准：

我的屏幕观看距离基准是多少？

检查距离：

我现在是不是离屏幕太近了？

常见问题

1. 串口被占用

检查占用：

sudo fuser -v /dev/ttyUSB0

关闭占用进程：

sudo fuser -k /dev/ttyUSB0

然后重新启动飞书网关。

2. 没有串口权限

临时测试：

sudo chmod 666 /dev/ttyUSB0

长期配置建议将当前用户加入 dialout 组：

sudo usermod -aG dialout "$USER"

重新登录系统后生效。

3. 找不到 Python 模块

确认使用项目虚拟环境，并设置正确的 PYTHONPATH：

cd ~/openvela_workspace/openvela

PYTHONPATH=host/feishu_gateway \
host/feishu_gateway/.venv/bin/python \
  host/feishu_gateway/gateway.py

4. 飞书收不到回复

依次确认：

1. 飞书应用 ID 和 Secret 正确；
2. 机器人权限、事件订阅和发布状态正确；
3. 网关终端没有异常退出；
4. /dev/ttyUSB0 能正常访问；
5. ESP32 已启动 ai_agent；
6. ESP32 已连接网络并配置 DeepSeek。

5. 普通问答正常，但硬件不动作

查看网关和 ESP32 日志是否出现对应 Tool：

read_environment
set_rgb_indicator
control_lamp_brightness
manage_light_profile
read_distance
manage_screen_distance

只有 Tool 返回成功并且硬件实际变化，才视为任务执行成功。

安全说明

以下内容不得提交到公开仓库：

• $HOME/.config/vela-feishu-gateway/env；
• DeepSeek API Key；
• 飞书 App Secret；
• Wi-Fi 名称和密码；
• SSH 私钥；
• 包含真实凭据的日志和截图。

公开仓库只提供：

host/feishu_gateway/env.example

项目曾经使用过的飞书 Secret 如已在聊天、截图或日志中出现，应在飞书开放平台重新生成。 ##视频说明 我用夸克网盘给你分享了「openvela…感知视频」，点击链接或复制整段内容，打开「夸克网盘APP」即可获取。 /9bac3Zsd7g:/ 链接：https://pan.quark.cn/s/92af8261354b

第三方组件

本项目基于 openvela、Apache NuttX、Mbed TLS、cJSON 和 ST VL53L3CX 软件组件。第三方源代码保留其原始许可证和版权声明；团队原创或实质修改主要集中在 ESP32 平台适配、VL53L3CX NuttX/uORB 通路、硬件 Tool、三项 Skill、本地状态机、TLS 内存优化和飞书消息接入。