NOOX AI硬件——插上设备，无需配置，让 AI 来处理工作

NOOX

NOOX 是一个即插即用的智能硬件助手，一根 USB 插上电脑，无需复杂操作，即可自动部署，跨端让 AI 自动帮你完成任务。

1. 项目介绍

NOOX 是一个面向“外接硬件 + 桌面自动化 + 大语言模型（LLM）”场景的开源智能硬件平台。它强调即插即用与可移植性，旨在通过一个基于 ESP32-S3 的设备，实现对主机计算机的智能控制和自动化操作。NOOX 将硬件控制、桌面自动化与AI 自主规划能力相结合，为用户提供一个强大的智能桌面助手和开发工具。

Frame 6.png

2. 功能特性

NOOX 平台具备以下核心功能特性：

USB 复合设备：设备通过 USB Type-C 接口连接主机，同时模拟 USB HID（键盘/鼠标）和 USB CDC（虚拟串口），实现与主机的双向通信和控制。
AI 集成与自主规划：
- 支持多种 LLM 提供商（OpenRouter / DeepSeek / OpenAI 兼容接口）。
- 在高级模式下，AI 能够基于上下文和命令输出进行多步规划、自动调用工具并迭代执行，直至达成用户目标。
- 支持对话历史管理，保持多轮对话上下文。
Web 控制台：内置 HTTP 和 WebSocket 服务器，提供直观的 Web UI 界面，用于设备配置（LLM 提供商、API 密钥、WiFi 设置）和实时AI对话。
主机代理自动引导：设备通过 USB HID 模拟键盘操作，在主机上自动打开 PowerShell，并使用 Invoke-WebRequest 从设备内置的 Web 服务器下载并执行跨平台的主机代理程序。
跨平台 Shell 交互：主机代理程序通过 USB CDC 与设备进行 JSON 交互，实现跨平台（powershell/pwsh/cmd/bash/sh 等）的 Shell 命令执行和结果反馈。
LLM 工具能力：LLM 可调用的工具包括：
- run_command：在主机上执行 Shell 命令。
- hid_keyboard_type：通过 HID 键盘输入文本。
- hid_keyboard_press：模拟按键组合或特殊键。
- hid_keyboard_macro：执行一系列键盘操作宏。
- gpio_set：控制 ESP32-S3 设备上的 GPIO/LED 引脚。
多通道交互：除了 Web 界面，设备还通过 OLED 屏幕和物理按键提供本地 UI 交互，显示状态信息和进行菜单导航。
动态配置管理：支持运行时通过 Web 界面修改 LLM 提供商、API 密钥和 WiFi 配置，并持久化存储。

3. 使用方法

NOOX 平台提供了多种交互方式，让用户能够灵活地与设备和 AI 进行互动。

3.1 Web 界面交互

通过浏览器访问设备的 IP 地址（可在 OLED 屏幕上查看），即可进入 Web 控制台。

聊天模式 (Chat Mode)：
- 在主界面的输入框中输入自然语言消息，点击“发送”或按回车键。
- AI 将以自然语言回复，并支持 Markdown 渲染，提供清晰的格式化信息。
- 通过顶部栏的“Chat”按钮切换到此模式。
高级模式 (Advanced Mode)：
- 通过顶部栏的“Advanced”按钮切换到此模式。
- 在此模式下，AI 能够自主规划并调用工具（如 run_command、hid_keyboard_type、gpio_set 等）来完成复杂任务。
- 用户可以观察 AI 的工具调用过程和结果，并继续输入指令。
设置管理：
- 点击顶部栏的“设置”按钮打开侧边栏。
- LLM 设置：配置 LLM 提供商、模型和 API Key。
- WiFi 管理：查看、连接、断开或删除已保存的 WiFi 网络。
- 添加/更新 WiFi：手动输入 SSID 和密码以保存新的 WiFi 网络。
- 所有更改需点击“保存并应用”按钮才能同步到设备。
GPIO 控制：
- 在高级模式面板中，可以直接通过开关控制设备上的 GPIO 1 和 GPIO 2。

3.2 USB Shell 交互

将设备的OTG-USB连接主机，设备会自动在主机上下载代理并启动代理程序，如果设备未连接局域网则会先自动尝试获取主机连接的局域网并连接。
注意：设备只会在开机初始化时尝试连接主机，所以需要在设备未启动前通过OTG-USB type-c连接主机设备以通电启动，若在设备初始化后连接主机，按RST键重新启动即可
在初始化成功后，用户可以在终端中直接与设备进行交互。

自然语言对话：
- 在代理程序运行的终端中输入自然语言指令，设备会将输入转发给 LLM 进行处理。
- LLM 的回复和工具执行结果将直接显示在终端中。
AI 自主规划：
- LLM 会根据用户指令和 Shell 命令的输出，自动选择并执行 run_command 等工具，实现桌面自动化。
- 例如，您可以要求 AI“在桌面新建一个 README.txt 并写入内容”，AI 将自动规划并执行相应的 Shell 命令。

提示：web界面和USB Shell的AI对话信息互通，因此可通过web界面跨端指示AI主机端的shell操作。

3.3 OLED 屏幕与按键交互

设备上的 OLED 屏幕和物理按键提供了一个本地的、无需主机连接的交互界面。

状态显示：
- OLED 屏幕会显示当前 LLM 模式、使用的模型、WiFi SSID、IP 地址和DRAM内存使用情况。
菜单导航：
- 通过按键可以在不同的菜单项之间切换，例如进入 WiFi 设置菜单或查看系统信息。
- 在 WiFi 设置菜单中，可以查看已保存的网络,进行连接/断开操作。

4. Web 界面特征

NOOX 的 Web 界面（index.html, style.css, script.js）提供了一个现代、响应式的用户体验，主要包括：

顶部栏：显示项目名称 "NOOX"，并包含模式切换按钮（Chat Mode / Advanced Mode）和设置按钮。
聊天区域：主界面，用于显示用户输入和 AI 响应。支持 Markdown 渲染，AI 消息具有脉冲动画效果。
输入框：用户输入消息的文本区域和发送按钮，支持回车发送（Shift+Enter 换行）。
高级模式面板：在高级模式下显示，包含功能模块，如：
- Shell 交互：命令行终端模拟的模块横幅。
- HID 操作：键盘鼠标控制的模块横幅。
- GPIO 操作：交互式模块，提供 GPIO 1 和 GPIO 2 的开关控制。
Toast 通知系统：在页面右上角显示成功、错误或信息提示。
设置侧边栏：从左侧滑出，提供详细的配置选项：
- LLM 设置：选择 LLM 提供商和模型，输入 API Key。
- WiFi 管理：显示已保存的 WiFi 网络列表，提供连接、断开和删除（忘记）网络的功能。
- 添加/更新 WiFi：输入新的 SSID 和密码以保存网络。
- 保存并应用：将所有设置保存到设备并立即应用。

界面设计采用深色主题，优雅简洁。

Frame 3.png

5. 软硬件技术细节

5.1 硬件

主控：ESP32-S3-WROOM-1 模组，双核 32 位 CPU @ 240 MHz，内置 16 MB Flash 和 8 MB PSRAM。支持 WiFi (802.11 b/g/n 2.4 GHz) 和 USB 2.0 OTG。
显示：0.96 英寸 128x64 像素 OLED 屏幕 (SSD1315 驱动，I2C 接口，GPIO4-SDA, GPIO5-SCL)。
输入：三个高电平触发的物理按键 (GPIO47-OK, GPIO21-Up, GPIO38-Down)，配置为内部下拉输入。
输出：三个高电平点亮的单色 LED (GPIO41, GPIO40, GPIO39) 和一个 WS2812 RGB LED (GPIO48)。
扩展接口：预留 I2C (GPIO1-SDA, GPIO2-SCL)、SPI (TF 卡，GPIO6-CS, GPIO15-SCK, GPIO16-MISO, GPIO7-MOSI) 和 UART (GPIO17-TX, GPIO18-RX) 接口，以及三个通用 GPIO (GPIO8, GPIO9, GPIO10)。
电源：USB Type-C 接口供电 (5V)和聚合物锂电池(4.2V)供电可自动切换。

电路细节分析

这是一个经典的双电源自动切换电路，当设备接入USB时，PMOS管截止，即便有体二极管电流流过，但是因为VUSB会比 Vbat 电压高，PMOS的Vgs>0 ,所以PMOS体二极管截止，负载由 VUSB(5V) 供电，同时为锂电池充电；当V设备断开USB，PMOS导通，负载由 VBat 供电；
注意： 需要将设备上的开关Q1打开，才可启动蓄电池供电。

5.2 软件

开发框架：Arduino Framework。
集成开发环境 (IDE)：PlatformIO (VS Code 插件)。
实时操作系统 (RTOS)：FreeRTOS (ESP-IDF 内置)。
文件系统：LittleFS，用于存储配置文件 (config.json)、Web 静态文件 (index.html.gz, style.css.gz, script.js.gz) 和主机代理程序。
核心库依赖：
- U8g2：OLED 显示驱动。
- FastLED：RGB LED 控制。
- AsyncTCP 和 ESPAsyncWebServer：异步 TCP 和 Web 服务器。
- WebSockets：WebSocket 通信支持。
- ArduinoJson：JSON 数据的序列化和反序列化。
主机代理程序：使用 Go 语言开发，编译为自包含的原生可执行文件，实现跨平台 Shell 命令执行。

5.3 架构

架构图

架构图.png
由gpt5.1-codex生成，仅供参考
看不清的话，请移步GitHub

总体架构：系统由 ESP32-S3 设备、主机计算机（运行 NOOX Host Agent 和 Shell）、Web 浏览器（Web Client）和云端 LLM 提供商组成。
模块职责：
- ConfigManager：管理配置文件读写和 LittleFS。
- HardwareManager：控制 GPIO、OLED、LED 和按键。
- WiFiManager：管理 WiFi 连接和网络状态。
- LLMManager：核心模块，负责 LLM API 调用、对话历史、工具调用解析和执行、双模式切换。
- UIManager：管理 OLED 显示、按键输入和菜单导航。
- HIDManager：模拟 USB 键盘/鼠标，实现快捷键和宏操作。
- WebManager：提供 Web 服务器、WebSocket 通信、静态文件托管和配置更新。
- UsbShellManager：处理 USB CDC 串口通信、JSON 消息和 Shell 命令转发。
任务调度：利用 FreeRTOS 多任务调度，将网络任务（WebTask，LLMTask）分配到 Core 0，计算任务（UITask, USBTask）分配到 Core 1，以优化性能。
内存管理：充分利用 ESP32-S3 的 8 MB PSRAM 存储 LLM 响应、对话历史和大型 JSON 文档，以避免 DRAM 碎片化和内存溢出。采用明确的内存所有权和统一的分配/释放函数，防止内存泄漏。

5.4 通信协议

WebSocket 协议：Web 客户端与 ESP32 设备之间通过 /ws 端点进行双向通信，传输聊天消息、LLM 模式设置、对话历史清除和 GPIO 控制等。
USB CDC 协议：主机代理程序与 ESP32 设备之间通过虚拟串口进行通信，所有消息均为单行 JSON + 换行符。包括用户输入、链路测试、Shell 命令执行结果、请求执行 Shell 命令和 AI 响应等。WiFi 凭证通过特殊文本格式 "SSID|Password" 发送。
详情请阅读源码中的TECHNICAL_SPECIFICATION.md文档。

代理下载与启动时序图

代理下载与启动时序_手绘.png
gpt5.1-codex生成，仅供参考

LLM API 协议：ESP32 设备通过 HTTPS 调用 DeepSeek、OpenRouter 和 OpenAI 等兼容 OpenAI API 的 LLM 提供商。请求和响应均采用 JSON 格式，高级模式下包含工具定义和工具调用。
详情请阅读TECHNICAL_SPECIFICATION.md文档。

LLM交互时序图

shell时序_手绘.png
gpt5.1-codex生成，仅供参考

6. 快速开始

准备环境：
- 安装 VS Code 和 PlatformIO 插件。
- 安装 Python 3 (用于运行打包脚本)。
添加配置：
- 在config_manager.cpp中使用自己的API key和WiFi信息替换掉占位符。
- 添加需要的模型名称（可选）
拉取依赖并编译固件：
- 在 VS Code/PlatformIO 中打开工程。
- 构建固件：pio run。
准备 LittleFS 数据：
- 运行 python compress_files.py 生成 data/ 目录下的压缩 Web 文件，并复制/压缩主机代理到 data/agent/。
- 上传 LittleFS 文件系统：pio run --target uploadfs。
烧录固件并连接设备：
- 上传固件：pio run --target upload。
- 通过 Type-C 连接到主机，系统会识别为 HID + CDC 设备。
配置 WiFi：
- 首次启动时，设备会通过 HID 注入脚本，引导主机获取并填入 WiFi 凭证。
- 首次连接成功后，可打开浏览器访问设备 IP（OLED 状态页可查看），进入 Web UI 配置 WiFi。
自动下载并运行主机代理：
- 设备通过 HID 打开 PowerShell，执行 Invoke-WebRequest 从 http://<设备IP>/api/agent/download?platform=windows 下载代理到临时目录并启动。
- 代理与设备通过 USB CDC 建立 JSON 信道，开始交互。

7. 安全与风险

NOOX 平台提供强大的自动化能力，但 LLM 在高级模式下可发起 run_command（任意 Shell 命令）以及 HID 操作（模拟键盘/快捷键）。这意味着在某些情况下，设备可能执行危险操作（如删除文件、网络渗透、数据外传等）。请务必在标准用户会话中运行 Agent，避免以管理员/root 身份运行。请谨慎使用并自担风险。建议在隔离、可回滚的环境中评估后再使用。