基于WizFi360构建AI运行状态指示器

最近我接触到了不少类似的产品，有些是交通信号灯造型，有些则采用极简圆盘设计。这些产品本质上都是为了帮助开发者解放视线，避免需要盯着终端等待AI完成任务。而我自己早在很久以前就开始着手开发这类产品——一款专为Claude Code设计的桌面状态装饰品，该系统从最初的蓝牙版本逐步演进至当前的WiFi版本。

完成项目后，我将完整代码上传至LCSC开源硬件平台及开源中国社区，所有软件与硬件文件均完全公开，毫无保留。令我惊讶的是，获得了非常积极的反馈：许多DIY爱好者按照教程搭建了设备，也有不少人提出了优化建议，这实际上帮助我进一步完善解决方案，使其更加完整。

说实话，这个工具最初只是为我自己使用而开发的，因此我非常惊讶它竟然得到了这么多人的认可。

当我们把它带到浦东软件园黑客马拉松现场时，引起了相当多的关注。许多试用过的人表示，终于不再需要每隔十几秒就回到终端去查看状态了。

在本文中，我们将从零开始详细解析并讨论整个实现过程，包括为何选择WizFi360-EVB-Pico作为核心设备、WiFi TCP方案中遇到的种种问题，以及如何协调固件与主机计算机的使用。所有代码、原理图和3D文件均完全开源，任何希望复制此项目的人都可以按照说明自行搭建。

一、项目简介

简单来说，这是一个通过Wi-Fi连接到你电脑上守护进程的桌面状态指示器。每当Claude执行操作——比如读取文件、运行命令或搜索代码——其状态就会实时推送到这个小型设备上。

不同的状态对应不同的灯光提示：蓝色表示空闲和待机，青色流动的灯光表示正在执行，慢速闪烁的黄色灯表示待审批，快速闪烁的绿色灯表示任务已完成，交替闪烁的红色灯则表示发生错误。每个状态还配有TTS语音播报功能，可调节音调和语速。

它为何如此实用?运行批量任务时，你可以随意离开去喝杯咖啡或放松一下，只需听到“任务完成”的提示音后返回即可。当你切换到其他窗口查看信息时，黄色灯光会亮起，并伴有语音提示“请检查终端”，提醒你返回确认。如果你深夜在编程，又不想屏幕太亮，仍可通过聆听语音通知来实时掌握进度。

简单来说，它将AI的工作范围从鼠标点击扩展到了你的周边视野以及耳朵所听到的声音之中。

2。核心硬件拆解

本项目的核心是原厂厂商WIZnet推出的集成开发板WizFi360-EVB-Pico，该板将RP2040双核主控器与工业级WizFi360 WiFi模块集成于同一块电路板上。这种设计省去了单独配对WiFi模块、布线及射频调试的麻烦，非常适合用于构建物联网桌面设备。

板载硬件核心参数：

• RP2040主控单元：双核Cortex-M0+，最高时钟频率为133MHz，集成2MB闪存和264KB高速SRAM，原生支持MicroPython，具备极低的刷写阈值;长按BOOTSEL按钮并插入USB，即可直接将.uf2固件拖入弹出的虚拟USB驱动器中完成刷写，无需额外工具如esptool。

• 内置WizFi360 WiFi模块：通过UART AT命令进行通信，波特率为115200。RP2040仅需通过串口发送指令，即可完成网络配置、TCP服务器/客户端创建以及数据收发，相当于将WiFi功能外包给模块，使主控单元专注于服务逻辑。

• 硬件扩展资源：40针标准DIP接口，完整的SPI/I2S/UART外设，工业级宽温范围-40℃至85℃，支持多链路TCP Server/Client/UDP，内置唯一出厂MAC地址，并兼容局域网静态IP固定方案。

这是官方完整的 MicroPython 开发支持仓库，内置了 AT 命令封装、TCP 通信功能，并提供完整的 WiFi 网络配置示例代码。本项目中的 WiFi 连接和帧解析逻辑均为基于该官方库的二次开发，其兼容性和稳定性由原始制造商保证。

此板搭载的 WizFi360 是一款低成本工业级串口 WiFi 模块，支持 2.4G 802.11 b/g/n，兼容 Station/SoftAP/Blend 模式，最多可同时支持 5 个 TCP/UDP 持久连接，串口最高波特率可达 2Mbps。其最大优势在于完全通过 AT 命令驱动：无需主控器运行复杂的 TCP 协议栈，所有网络握手、数据转发、保持连接以及 DHCP IP 获取等流程均由模块自身完成。它支持OTA远程升级、保持心跳连接以及PING网络检测，可长时间稳定地保持在本地局域网中在线，完全满足我们对TCP端口57321进行7×24小时监控的需求。

整个设备的完整硬件工程包(包括原理图、PCB、BOM和3D外壳模型)已全面开源，并根据MIT开源许可证上传至OSHWHub(LCSC开源平台)，任何人都可自由下载、复制并进行二次修改。

整个设备电路基于WizFi360-EVB-Pico设计，支持外设扩展，电路模块划分如下：

• 主控通信单元：将WizFi360模块的串口连接至RP2040的GP4/GP5引脚，复位引脚连接至GP20;配置了一个8192字节的预留串行接收缓冲区，以解决WiFi大容量数据包丢失的问题;

• 状态指示灯单元：GP16配备WS2812双RGB灯，用于显示眼镜的两种颜色状态指示。

• I2S音频单元：配备MAX98357A音频功率放大器，I2S时钟引脚GP11/GP12/GP13，并支持通过外接3W扬声器进行TTS语音提示;

• 交互反馈单元：GP18振动传感器、GP17振动马达，支持触碰触发的语音和振动提醒以响应状态变化;

• 电源单元：内置充放电管理模块+硬件电源开关，支持锂电池离线供电。本项目已完成V1.0和V1.1两个版本迭代，优化了引脚分配与线路阻抗，解决了串口通信干扰及音频背景噪声问题。

该设备配备了全套3D打印外壳模型，采用标志性的卡通人物造型设计。外壳由上盖和下盖组成，预设了扬声器音频接口、透光窗口、电源开关、振动电机安装位置以及与PCB板精确对齐的螺丝孔，使得打印后无需二次模具修改即可完成组装。

组装过程极为简便：首先将扬声器和振动电机焊接至PCB板上的预留端子，将WizFi360-EVB-Pico固定在主板的定位槽中，连接可充电电池，然后将3D打印外壳卡入并拧紧M3固定螺丝，即可完成整个设备的组装，即使是初学者也能快速完成。

组装完成后，它便成为一款桌面装饰品。放置在工作台面上，通电并连接网络后，WS2812灯带会实时同步显示“克洛德代码”的运行状态，并通过语音和振动实现多维度提醒，无需频繁切换电脑窗口查看终端信息。

3. 软件工作原理

市场上大多数类似的人工智能状态显示设备采用BLE蓝牙解决方案，存在传输距离短、被墙体遮挡时断连以及需要计算机主动广播和扫描等缺点。而这款WiFi版本则完全采用TCP长连接架构，并对逻辑进行了反向重新设计：设备端的WizFi360在开机后作为TCP服务器，固定监听57321端口;计算机端的守护进程则作为TCP客户端，主动发起连接。只要两方处于同一局域网内，即可稳定地接收整个房屋内任何位置的状态信号。整个通信链路职责分工明确：

1. Claude Code 触发多种工具钩子事件，并输出标准的 JSON 数据流;

2. PC ble_daemon.py 用于聚合和限流守护进程状态，并通过 TCP 进行转发;

3. WizFi360 WiFi 模块接收网络数据，并通过 UART AT 命令将其转发至 RP2040 主控制器。

4. RP2040 用于解析数据，并驱动 WS2812 颜色灯带、TTS 语音模块和振动电机，以完成状态反馈。

为说明设备联网的核心逻辑，在 transport.py 文件中，connect() 函数封装了 WizFi360 网络配置的整个过程，以及启用 TCP 服务器所需的 AT 命令流程：

设备上电后，会自动执行网络配置的 AT 命令，读取本地静态 IP 地址，并启动多连接的 TCP 服务。整个过程由 MicroPython 异步调度，不会阻塞照明和语音任务。

主要设计亮点：RP2040 本身不处理任何网络协议栈;所有 WiFi 网络配置、TCP 连接以及数据传输/接收均由 WizFi360 模块作为代理进行处理。主控制器只需发送 AT 命令即可完成全部网络操作，显著降低了固件开发的复杂度。

硬件串口连接方式：RP2040 的 UART1(GP4/GP5)连接至 WizFi360，波特率固定为 115200。外设输出依赖于GP16的双通道WS2812 LED灯、I2S音频功率放大器以及振动电机，以实现多感官提醒功能。

项目代码本质上分为两个主要模块：PC端守护进程和设备端RP2040 MicroPython固件。通过编译条件VARIANT=="wizfi360"实现形式隔离。WiFi版本会自动跳过与BLE相关的代码，以减小固件体积。

• ① PC端守护进程

○ ble_daemon.py：主有限状态机，以5Hz频率汇总所有Claude会话状态，并进行优先级限流，避免屏幕频繁闪烁;

○ hook_bridge.py：接收原生Claude Hook JSON数据，并以标准化方式封装为v2通信信封;

○ WifiTransport：TCP客户端通信层，主动连接硬件设备的57321端口;

○ pair_device.py：用于局域网设备扫描和IP配对的工具;

○ smoke.py：用于设备在线自检和Smoke测试的脚本。

• ② 设备端RP2040固件

○ main.py：程序入口，负责硬件初始化以及发射器和渲染器的调度;

○ transport.py：封装WizFi360的AT命令，作为TCP服务器创建和网络帧解析的核心模块;

○ protocol.py：V6数据线通信协议解析及ACK响应逻辑;

○ state.py：设备端有限状态机，定义5种模式：空闲 / 运行 / 等待批准 / 完成 / 错误。

○ light_renderer.py：渲染动态灯光效果，并以20FPS同步刷新状态指示灯;

○ voice_task.py：一个TTS语音广播任务，通过PCM音频驱动扬声器;

○ vibration.py：控制振动电机，为状态变化提供触觉反馈;

○ lib/wizfiatcontrol/：WizFi360的完整AT命令驱动库。

从Claude执行工具调用到桌面装饰灯亮起的那一刻，所有数据需经过六层转换，逐步封装和解析数据格式：原生Hook JSON → v2标准化信封 → v6线缆二进制帧 → WizFi360 AT + IPD数据帧 → RP2040状态枚举 → 灯光/语音动态效果

1. 事件生成：Claude 内置钩子可捕获 8 种类型的事件，包括 PreToolUse、PostToolUse 和 Stop，并通过标准输入推送输出 JSON。

2. 标准化封装：hook_bridge 被统一封装为 v2 封装数据包，以掩盖不同工具之间事件格式的差异;

3. 状态聚合限流：守护进程每5秒刷新一次全局会话状态，并设置优先级(错误报告 > 待审批 > 运行中 > 空闲)，以防止短时间内大量事件导致屏幕信息过载。

4. 序列化推送：状态每200毫秒打包一次，通过v6线缆轻量协议发送，并以单向模式经TCP推送到硬件。

5. WiFi硬件实现分析：WizFi360接收TCP数据包，并通过IPD串行端口帧将其转发至RP2040;代码从杂乱的AT串行端口回波中提取有效载荷，并解析链路编号和状态数据。

6. 多感官呈现：状态信息被发送至渲染器，同步输出RGB灯光动画、文本转语音(TTS)语音以及振动反馈。

该系统定义了5种标准业务状态，每种状态对应特定的灯光颜色、动态效果和语音提示：

• 空闲(IDLE)：缓慢的蓝色呼吸灯，设备处于待机状态;

• 运行(WORKING)：青色渐变流动，表示AI正在执行代码或读取文件;

• 待审批(PENDING)：缓慢的黄色闪烁，并伴有语音提示“请检查终端”;

• 完成(COMPLETE)：绿色指示灯连续快速闪烁3次，同时语音播报“任务完成!”;

• 错误(ERROR)：红蓝交替闪烁，并由电机同步触发振动报警。

设备配备完整的有限状态机，严格定义了状态转换逻辑与优先级：ERROR > PENDING > WORKING > IDLE > CELEBRATE。

• 若在运行过程中收到审批事件，状态将直接跳转至待审批状态;

• 在任何阶段捕获错误并强制触发高优先级的错误警报。

• 完成后，工具会自动进入“完成”庆祝动画，并在动画结束后恢复为待机状态。

• 长时间无事件推送时，系统将自动进入睡眠模式，以降低功耗。

整个解决方案基于开源的 claude-buddy-plugin 实现自动钩子注册，无需手动修改 Claude 配置文件：

1. 在线安装：直接从Claude扩展市场拉取插件仓库，一键完成部署;

2. 离线安装：您可以在无网络的环境中克隆项目源代码，并在Claude终端中运行本地安装命令;插件安装完成后，事件转发逻辑将自动启用，所有AI操作将在整个过程中实时推送到本地守护进程，无需额外配置。

4. 支持工具

为何要单独开发一个专用的一键式图形界面配置工具?

• 降低复制门槛，消除跨平台差异。本项目可同时支持四种硬件方案(WizFi360 WiFi版本、ESP32-C3时钟版本、ESP32-S3屏幕面板/D-Shell版本)，这些方案在主控制器、通信协议和刷写方式上均存在显著差异：RP2040依赖拖放uf2文件，ESP32依赖esptool，WiFi需要网络配置和静态IP分配，BLE则需蓝牙扫描与配对，导致初学者手动输入命令时极易出错。统一的图形界面工具将多种硬件的不同操作整合在一起，无需区分命令行或查阅编程指南，全程支持可视化的一键点击操作。

• 自动化繁琐的预处理任务，避免不必要的错误

该项目包含大量重复性操作，例如TTS语音PCM创意生成、像素级字符动画资源处理、WiFi静态IP分配、串口扫描以及TCP配对验证。如果所有操作均需手动完成：

○ 您需要自行调用Doubao API来处理语音文件，转换其采样率，并将其放置到指定的资源目录中;

○ 对于Wi-Fi版本，您需手动检查局域网中的空闲IP地址，并将其配置到设备中;

○ 每次升级固件时，需区分初始刷机与增量升级，并选择相应的清除选项;工具可自动完成所有操作，避免因文件错位、IP冲突或音频采样率不兼容等问题导致的频繁故障。

• 集成闭环工作流可实现“编程 + 配对 + 桥接调试”的一站式完成流程;

○ 完整使用流程：硬件选型 → 语音/字符创意生成 → 固件刷写 → 局域网TCP配对 → 后端桥接启动 → 日志调试。所有功能集成在一个单一的可执行程序中，无需同时打开多个终端、串口工具和语音合成网页。

○ 该工具还内置设备日志读取功能。当照明/语音功能无法正常工作时，可直接捕获运行日志以进行故障排查，无需使用串口调试工具。

• 支持初学者和开发者，提供两种使用模式：

○ 完全适合新手：仅通过鼠标点击操作，无需预先设置Python环境或掌握命令行技术;

○ 高级用户：底层保留Python脚本入口，可通过命令行输入python -m setup_tool启动，用于自定义二次开发自动化编程脚本。

该工具的整体设计逻辑如下：

采用分层模块化设计，流程线性递进：项目目录选择 → 硬件外形规格选择 → 资源创意生成/导入 → 灯光参数配置 → 一键刷机 → 设备配对 → 桥接操作与调试。针对不同硬件类型，实现了分支和分流功能：选择WizFi360时，系统将自动切换至WiFi TCP链路，并禁用与BLE相关的逻辑;选择ESP32系列时，系统将自动切换至串口刷机和蓝牙配对流程，相关配置项将在界面中自动隐藏，以减少信息干扰。

提取项目的开源仓库，然后双击 Claude_Assistant_Setup.exe 启动图形化工具。在第一步中，您需要选择仓库内的设备固件文件夹;程序将自动读取内置的固件和语音资源目录，验证项目完整性，当确认目录有效后，界面会显示绿色勾选标记。

当您在硬件无线电按钮中选择“WizFi360 (RP2040+ WiFi TCP)”时，界面将自动切换至WiFi配置面板。输入家庭路由器的WiFi名称和密码，工具将在刷写阶段自动将WiFi凭据写入设备固件。通信模式将自动锁定为以太网WiFi，且蓝牙相关配置项将被禁用，其运行逻辑与ESP32蓝牙版本有所不同。

该项目的灯光和语音提示功能依赖于采样率固定的PCM音频文件。该工具已预装Doubao语音合成插件：输入Open Platform密钥后，即可自由切换男声和女声，调节语速与语调，一键生成广播音频，音频将自动保存至固件资源文件夹，无需手动转换音频格式。

设备重启并连接网络后，点击左下角的[配对设备]按钮：

1. 该工具会自动扫描整个局域网的57321端口，以检测在线的WizFi360硬件。

2. 自动过滤未占用的静态IP，并将其写入设备配置，使设备在每次重启时无需重新搜索即可永久固定该IP。

3. TCP连接检查通过后，IP和端口配置将保存到本地计算机的JSON文件中，下次启动工具时会自动读取该文件，从而无需重复配对。

配对完成后，点击[开始桥接]，嵌入GUI的守护进程将在后台持续运行：

• Wi-Fi版本持续接收Claude Code通过TCP端口57321推送的Hook状态信息;

• 以5Hz频率实时向硬件传输状态数据，并同步驱动灯光、音频和振动效果;

• 界面实时显示桥接连接状态以及当前活跃的AI会话数量;

• 支持随时停止桥接，并可读取设备操作日志以进行故障排查;当软件窗口关闭时，后台守护进程将自动终止，不会留下任何残留进程占用后台端口。

五、结语与扩展

最初只是为了解决自己“每十几秒就更换终端”的小问题而尝试，最终发展成了一套完整的支持WiFi功能的解决方案。在开发过程中，我遇到了大量硬件和软件方面的陷阱，同时也积累了一些关于构建此类桌面AI状态设备的通用经验。本文汇总了设计思路、应避免的误区以及可能的扩展方向，无论你是想复制并修改现有设计，还是从零开始打造类似产品，都能为你节省不少弯路。

5.1 核心设计理念：本质上是一种“减轻注意力负担的工具”

开发此类产品时最常见的误区，就是过度堆砌功能和规格，最终却得到一个全能型产品，却无法真正胜任任何一项任务。事实上，其核心定位非常明确：将屏幕上的数字状态转化为摆放在你桌面上的实体形式，以最低的认知负担传递信息。围绕这一核心，有若干不可妥协的设计原则需要遵循：

1. 极简状态设计，便于即时识别：避免创建十几个不同的状态或复杂的灯光模式。用户应能通过周边视觉一眼区分“运行中/待审批/已完成/错误”。由于颜色是区分最有效的方式，我们仅保留5种核心状态，采用纯色搭配简单的动画效果进行区分。

2. 多感官冗余功能可适应不同场景：光、声、振动的三种反馈方式并非花招，而是针对不同情境的补充。专注编程时可查看灯光，切换到查找信息时聆听语音，深夜加班时开启振动提醒以避免打扰他人——总有一种方式能不干扰你的工作节奏。

3. 统一的连接逻辑，降低学习成本：从最早的蓝牙版本到当前的WiFi版本，我们始终遵循“电脑主动连接设备”的逻辑，因此用户在切换版本时无需调整操作习惯。即使底层通信协议从BLE改为TCP，用户端的操作流程也几乎保持不变。

4. 隐私底线绝不能被触碰：所有状态数据仅在本地局域网内流通，绝不上传至云端，没有后端服务器，也未收集任何用户数据。对开发者群体而言，这比添加十个额外功能更为重要。

5.2 开发实现与经验总结及常见陷阱规避

从零到一的实际实施过程中，细节层面隐藏的陷阱远比预期更多。让我从几个最关键的角度来拆解：

硬件开发中的常见陷阱规避：

1. 串口WiFi模块的解析必须具备容错能力：对于基于AT命令的WiFi模块(如WizFi360)，通过串口输出的数据并非干净的报文，而是混杂着AT应答、冗余字节和数据包粘连，同时在多个TCP链路中还会出现链路编号竞争。我们最初就遇到了数据包丢失和解析混乱的问题，直到将串口接收缓冲区扩展至8192字节，并实现完整的头部和尾部校验以及异常丢弃逻辑后，才最终实现了稳定且长期的连接。

2. 静态IP是优质WiFi使用体验的基础：如果默认使用DHCP，设备每次重启时IP地址都可能发生变动，导致用户每次使用都需要重新发现并配对设备，从而彻底破坏使用体验。因此，在刷机过程中必须自动扫描子网、分配一个可用的IP地址，并将其写入设备固件，以锁定该地址，确保只需配对一次即可永久有效。

3. 二合一开发板可省去从零开始设计电路的麻烦：不必为购买主控器和WiFi模块分别花费额外费用，来设计自己的PCB。若缺乏相关经验，射频走线和天线匹配等隐藏问题可能需要半个月才能调试完成。像WizFi360-EVB-Pico这样的官方集成板已证明其稳定性，因此对于小型项目和开源项目，应优先选择成熟方案，并将精力集中在核心功能上。

软件开发注意事项：

1. 必须对状态更新进行节流和防抖处理：Claude's Hook 事件触发频率极高，若不进行节流，指示灯每秒会闪烁数次，导致严重的眼疲劳。我们实现了5Hz的状态聚合，并结合了优先级排序(错误 > 待审批 > 运行中 > 空闲)，高优先级事件可直接插入队列，不仅确保重要提醒不会延迟，还能避免指示灯随机闪烁的问题。

2. 注意固件大小：RP2040 的闪存空间有限，当语音创意内容、驱动库和服务代码被集中存放时，很容易超出限制。我们实现了条件编译，Wi-Fi 版本会直接移除所有与 BLE 相关的代码，同时将语音压缩为 8000Hz 采样率的 PCM 格式，以节省空间用于用户自定义内容。

3. 上层计算机工具必须配备完善的异常回退机制：用户所处的网络环境多种多样，IP冲突、防火墙拦截以及通过子网扫描无法检测到设备等问题时有发生。该工具必须具备异常提示、手动输入IP地址和日志导出等回退功能，以确保用户在遇到错误信息时不会陷入困境。

5.3 产品形态设计中对细节的精准控制

作为桌面装饰品，其外观与交互细节直接决定了它是否能长期被使用于桌面上，还是最终沦为堆积灰尘的电子废弃物。

1. 恰到好处地平衡了存在感：既不能太笨重，占据桌面空间，也不能太小巧，容易被忽视。它的尺寸大约与手掌相当，低调地放置在显示器旁，既实用又兼具时尚的桌面装饰效果。

2. 照明必须经过适当柔化处理：直射的RGB LED灯珠对眼睛极为刺眼，深夜加班时突然闪烁的光线容易造成眩光。因此必须加装磨砂灯罩并采用漫反射设计，使光线柔和不刺眼，适合长期日常使用。

3. 设备端的交互应尽可能简单：仅需一个电源开关即可，所有配置、配对和参数修改均通过电脑端的工具完成。设备端越人性化，上手门槛就越低，真正实现即插即用的功能。

4. 为DIY爱好者留出充分的改装空间：开源项目必须为用户释放创造力留有余地。该外壳设计为标准3D打印部件，保留了通用的安装孔，所有硬件引脚均被合理布线，便于用户更换颜色、添加传感器或修改外形，从而让社区能够开发出更多多样且富有创意的应用方式。

5.4 可扩展性方向：超越Claude状态提示

该解决方案的底层框架具备强大的通用性，可扩展至多种游戏玩法形式和配置：

1. 多AI工具适配：目前仅支持Claude Code，未来可扩展与具备Hook功能的各类AI编码工具(如Cursor、GPT和通义灵机)集成，以构建通用的AI开发状态指标。

2. 多设备协同网络：可在同一局域网内部署多个设备，分别放置在书房、客厅和卧室。执行长时间任务时，无论身处何地，您都能收到通知，无需一直盯着电脑。

3. 硬件功能扩展：增加一个小屏幕，用于显示特定任务名称和错误摘要;安装温湿度传感器，兼具桌面环境监控功能;集成NFC模块，通过轻触智能手机即可快速配对。

4. 形态风格变体：目前采用卡通人物设计，可完全适配成多种风格，如极简交通灯、像素方块、潮流人物等，以满足不同桌面布局和审美偏好。

5. 团队协作场景的延伸：构建一个轻量级服务器中继，使开发团队每位成员的任务状态都能同步到公共仪表板上，团队可以一目了然地看到谁在编译、谁在等待审批，以及谁遇到了错误。

本文编译自hackster.io