手把手教你搭建一个AI运行状态指示装置【全开源拆解】

零、背景

最近刷到不少同类型的 AI 状态指示产品,有交通灯造型的,也有简约圆盘款的,本质都是帮开发者解放视线,不用死盯着终端等 AI 跑任务。其实我自己很早就开始做同款方向的东西了,专门适配 Claude Code 的桌面状态摆件,从最早的蓝牙版一路迭代到现在的 WiFi 版。

做好之后我把完整项目同步到了立创开源硬件平台和开源中国,软硬件文件全部开源,没留一手。没想到反响还挺不错,不少 DIY 爱好者跟着教程做出来了,也有很多人提了优化建议,反而帮我把方案补得更完善了。

说实话最开始只是做给自己用的工具,能被这么多人认可,还挺意外的。

带去浦软黑客松现场的时候也挺受关注,好多人试用之后说终于不用每隔十几秒切回终端看一眼了。

这篇就把从 0 到 1 的完整实现细节全拆开来聊,包括为什么选 WizFi360-EVB-Pico 当核心、WiFi TCP 方案踩了哪些坑、固件和上位机怎么配套使用。所有代码、原理图、3D 文件全部开源,想复刻的朋友照着就能做。

一、项目介绍

简单说,它就是个桌面状态指示器,通过 WiFi 跟你电脑上的守护进程连着。Claude 每执行一个操作 ------ 读文件、跑命令、搜代码,状态都会实时推到这个小设备上。

不同状态对应不同的灯光:蓝色是闲着待命,青色流水灯是正在执行,黄灯慢闪是有待审批,绿灯快闪是任务跑完了,红灯交替闪就是出了错。每种状态还配了 TTS 语音播报,音色语速都能调。

最实用的地方在哪呢?跑批量任务的时候你大可放心去倒咖啡、摸鱼刷网页,听见 "任务完成" 再回来就行;切出去查资料的时候,黄灯一亮加一句 "请查看终端",就知道得回去点确认了。深夜写代码不想亮灯,光听语音也能摸清楚进度。

说白了,就是把 AI 的工作状态,从你的鼠标点击里,延伸到了余光和耳朵里。

项目所有软硬件全部开源,仓库、演示视频、介绍页都放在这了,想复刻的朋友可以直接拿:

二、核心硬件拆解

整个项目的核心载体是 WIZnet 原厂推出的 WizFi360-EVB-Pico 一体化开发板,一块板同时集成 RP2040 双核主控与 WizFi360 工业级 WiFi 模组,省去单独搭配 WiFi 模块、接线调试射频的麻烦,非常适合做物联网桌面小设备。

开发板资料:https://docs.wiznet.io/Product/Chip/Chip_Related_modules/wizfi360-evb-pico

板上硬件核心参数:

  • RP2040 主控单元:双核 Cortex-M0+,主频最高 133MHz,自带 2MB Flash、264KB 高速 SRAM,原生支持 MicroPython,烧录门槛极低;按住 BOOTSEL 按键插入 USB,直接把 .uf2 固件拖入弹出的虚拟 U 盘即可完成刷写,无需额外安装 esptool 等工具。
  • 内置 WizFi360 WiFi 单元:走 UART AT 指令通信,波特率 115200,RP2040 仅需通过串口下发指令就能完成配网、TCP 服务端 / 客户端创建、数据收发,相当于把 WiFi 功能外包给模组,主控只专注业务逻辑。
  • 硬件拓展资源:40pin 标准 DIP 引脚、完整 SPI/I2S/UART 外设、工业宽温 - 40℃~85℃,支持 TCP Server/Client/UDP 多链路,自带唯一出厂 MAC,适配局域网静态 IP 固定方案。

官方配套完整 MicroPython 开发仓库,内置 AT 指令封装、TCP 通信、WiFi 配网全套示例代码,我们项目里的 WiFi 连接、帧解析逻辑都基于这套官方 lib 二次开发,兼容性、稳定性有原厂保障。

仓库地址:https://github.com/Wiznet/WizFi360-EVB-Pico-MicroPython

板子搭载的 WizFi360 是一款低成本工业串口 WiFi 模组,支持 2.4G 802.11 b/g/n,兼容 Station/SoftAP/ 混合模式,最大支持 5 路 TCP/UDP 长连接,串口最高波特率 2Mbps。 它最大优势是全 AT 指令驱动,不用主控跑复杂 TCP 协议栈,所有网络握手、数据转发、保活、DHCP 获取 IP 全部由模组自身处理;同时支持 OTA 远程升级、Keep-Alive 心跳、PING 网络检测,局域网长时间稳定在线,刚好适配我们 7×24 小时监听 TCP 57321 端口的需求。

https://docs.wiznet.io/Product/Modules/Wi-Fi-Module/WizFi360

整机完整硬件工程(原理图、PCB、BOM、3D 外壳模型)全部开源上传至 OSHWHub 立创开源平台,MIT 开源协议,任何人可免费下载、复刻、二次修改。

项目开源地址:https://oshwhub.com/baizekun/project_svwkrlfc

整机电路围绕 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 眼镜灯实时同步 Claude Code 运行状态,搭配语音、震动多维度提醒,无需频繁切换电脑窗口查看终端。

三、软件工作原理

市面上同类 AI 状态摆件大多采用 BLE 蓝牙方案,存在传输距离短、隔墙断连、必须电脑主动广播扫描的短板,本次 WiFi 版完全换用 TCP 长连接架构,逻辑做了反向设计: 设备端 WizFi360 开机后作为 TCP 服务端,固定监听 57321 端口;电脑端守护进程作为 TCP 客户端主动发起连接,只要二者处于同一局域网,全屋任意位置都能稳定接收状态信号。 整套链路分工清晰:

  1. Claude Code 触发各类工具 Hook 事件,输出标准 JSON 数据流;
  2. PC 端 ble_daemon.py 守护进程聚合、节流状态,通过 TCP 转发;
  3. WizFi360 WiFi 模组接收网络数据,通过 UART AT 指令转发给 RP2040 主控;
  4. RP2040 解析数据,驱动 WS2812 灯光、TTS 语音、振动马达完成状态反馈。

举设备联网核心逻辑示例,transport.pyconnect() 函数封装了整套 WizFi360 配网 + 开启 TCP 服务端 AT 指令流程:

JavaScript 复制代码
async def connect(self):
    await self._wizfi.set_mode(WizFi_ATcontrol_Async.MODE_STATION)   # ​AT+CWMODE_CUR=1await self._wizfi.connect({"ssid": self._ssid, "password": self._password})  # ​AT+CWJAP
    ip = await self._wizfi.get_local_ip()                          # ​AT+CIFSR​ (DHCP)await self._wizfi.at_response("AT+CIPMUX=1")                    # 多连接模式await self._wizfi.at_response(f"AT+CIPSERVER=1,{TCP_PORT}")      # 起 ​TCP​ ​Server​ :57321await self._wizfi.at_response("AT+CIPSTO=60")                   # 60s 超时
    self._connected = True

设备开机自动执行 AT 指令配网、读取本地静态 IP、开启多连接 TCP 服务,全程由 MicroPython 异步调度,不阻塞灯光、语音任务。

关键设计亮点:RP2040 本身不处理任何网络协议栈,所有 WiFi 配网、TCP 连接、数据收发全部交给 WizFi360 模组代理,主控仅下发 AT 指令即可完成全部网络操作,大幅降低固件开发复杂度。 硬件串口接线:RP2040 UART1(GP4/GP5)对接 WizFi360,波特率固定 115200。外设输出依靠 GP16 双路 WS2812 灯、I2S 音频功放、振动马达实现多感官提醒。

项目代码天然分为两大模块:PC 端守护进程、设备端 RP2040 MicroPython 固件,通过编译条件 VARIANT=="wizfi360" 做形态隔离,WiFi 版本会自动跳过 BLE 相关代码,精简固件体积。

  • ① PC 端 daemon 守护进程
    • ble_daemon.py:主状态机,5Hz 频率聚合所有 Claude 会话状态,做优先级节流避免频繁刷屏;
    • hook_bridge.py:接收 Claude 原生 Hook JSON,标准化封装为 v2 通信信封;
    • WifiTransport:TCP 客户端通信层,主动连接硬件设备 57321 端口;
    • pair_device.py:局域网设备扫描、IP 配对工具;
    • smoke.py:设备联机自检、冒烟测试脚本。
  • ② 设备端 RP2040 固件
    • main.py:程序入口,完成硬件初始化、传输器、渲染器调度;
    • transport.py:WizFi360 AT 指令封装,TCP 服务端创建、网络帧解析核心;
    • protocol.py:v6 wire 通信协议解析、ACK 应答逻辑;
    • state.py:设备端有限状态机,定义空闲 / 运行 / 待审批 / 完成 / 报错 5 种模式;
    • light_renderer.py:灯光动效渲染,同步刷新 20FPS 状态灯;
    • voice_task.py:TTS 语音播报任务,调用 PCM 音频驱动扬声器;
    • vibration.py:振动马达控制,状态变更触觉提醒;
    • lib/wizfiatcontrol/:WizFi360 全套 AT 指令驱动库。

从 Claude 执行工具,到桌面摆件灯光亮起,完整数据要经过 6 层转换,数据格式逐级封装解析:Hook原生JSON → v2标准化信封 → v6 wire二进制帧 → WizFi360 AT +IPD数据帧 → RP2040状态枚举 → 灯光/语音动效

  1. 事件产生:Claude 内置 Hook 捕获 PreToolUse、PostToolUse、Stop 等 8 类事件,输出 JSON 通过标准 stdin 推送;
  2. 标准化封装:hook_bridge 统一封装为 v2 信封数据包,屏蔽不同工具事件格式差异;
  3. 状态聚合节流:守护进程 5Hz 刷新全局会话状态,设置优先级(报错 > 待审批 > 运行 > 空闲),防止短时间大量事件刷屏;
  4. 序列化推送:每 200ms 打包一次状态为 v6 wire 轻量协议,TCP 单向推送到硬件;
  5. WiFi 硬件落地解析:WizFi360 接收 TCP 数据包,通过 +IPD 串口帧转发给 RP2040,代码从杂乱 AT 串口回显中剥离有效载荷,解析链路号与状态数据;
  6. 多感官呈现:状态送入渲染器,同步输出 RGB 灯光动画、TTS 语音、振动反馈。

!\[\](https://f1829ryac0m.feishu.cn/space/api/box/stream/download/asynccode/?code=MDkwYjI2NWZhZWJjMDAwNDgyNDk3ZjlhMWYwMTliM2ZfSVdHNm93U1JadDBLcnVEM0lQaGJ5QVlreFJVZ1NMdFZfVG9rZW46WXNqd2JnOW5Nb0pwYlp4OFVJWWNkaHJ

项目定义 5 套标准业务状态,每套对应专属灯光颜色、动态效果、语音提示:

  • IDLE 空闲:蓝色缓慢呼吸灯,设备待机;
  • WORKING 运行中:青色流水渐变,提示 AI 正在执行代码 / 读取文件;
  • PENDING 待审批:黄色慢闪烁,语音播报「请查看终端」;
  • COMPLETE 任务完成:绿色连续快闪 3 次,语音播报「任务完成啦」;
  • ERROR 执行报错:红蓝色交替频闪,马达同步震动提醒。

设备端搭载完整有限状态机,严格定义状态切换逻辑与优先级:ERROR > PENDING > WORKING > IDLE > CELEBRATE

  • 运行中收到审批事件,直接切至 PENDING;
  • 任意阶段捕获报错,强制切入 ERROR 高优先级告警;
  • 工具执行完毕自动进入 COMPLETE 庆祝动效,结束后回归 IDLE 待机;
  • 长时间无事件推送自动休眠,降低功耗。

源码链接:https://github.com/FreakStudioCN/MicroPython_Claude_Assistant_Public

整套方案依赖开源 claude-buddy-plugin 插件实现 Hook 自动注册,无需手动修改 Claude 配置文件:

  1. 在线安装:直接在 Claude 插件市场拉取插件仓库,一键完成部署;
  2. 离线安装:无网络环境可克隆项目源码,在 Claude 终端执行本地安装命令; 插件安装完成后自动挂载事件转发逻辑,所有 AI 操作实时推送至本地守护进程,全程无需额外配置。

claude 插件链接:https://github.com/ChrisWu132/claude-buddy-plugin

四、配套工具

为什么要单独做一套 GUI 一键配置工具?

  • 降低复刻门槛,屏蔽多平台差异 本项目同时支持 4 套硬件方案(WizFi360 WiFi 版、ESP32-C3 时钟版、ESP32-S3 屏幕 Panel/D-Shell 版),主控、通信协议、烧录方式完全不同:RP2040 靠拖拽 uf2、ESP32 依赖 esptool、WiFi 需要配网写静态 IP、BLE 需要蓝牙扫描配对,新手手动敲命令极易出错。 统一 GUI 工具把多套硬件的差异化操作封装,不用区分命令行、不用查烧录指令,全程可视化点选。
  • 自动处理繁琐前置工作,减少踩坑
    • 项目依赖 TTS 语音 PCM 素材、像素角色动画资源、WiFi 静态 IP 分配、串口扫描、TCP 配对校验等大量重复操作。如果纯手动操作:
    • 语音需要自行调用豆包 API、转换采样率、放到指定 assets 目录;
    • WiFi 版需要手动查局域网空闲 IP、写进设备配置;
    • 每次升级固件要区分首次烧录 / 增量升级、勾选对应擦除选项; 工具全部自动化完成,规避文件放错、IP 冲突、语音采样率不兼容等高频 bug。
  • 一体化链路闭环,一站式完成「烧录 + 配对 + 桥接调试」
    • 完整使用流程:硬件选型 → 语音 / 角色素材生成 → 固件烧录 → 局域网 TCP 配对 → 后台桥接启动 → 日志调试,全部功能集成在单一 exe 程序,不用同时打开多个终端、串口工具、语音合成网页。
    • 同时内置设备日志读取功能,遇到灯光 / 语音不生效可直接抓取运行日志排查问题,省去串口调试工具。
  • 兼顾小白与开发者,两种使用模式
    • 纯新手:全程鼠标点击,无需任何 Python 环境、命令行基础;
    • 进阶玩家:底层保留 python 脚本入口,可通过 python -m setup_tool 命令行启动,自定义二次开发自动化烧录脚本。

工具整体设计逻辑为:

分层模块化设计,流程线性递进:工程目录选择 → 硬件形态选型 → 资源素材生成 / 导入 → 烧录参数配置 → 一键烧录 → 设备配对 → 桥接运行调试 不同硬件形态做分支分流:选择 WizFi360 自动切换 WiFi TCP 链路、屏蔽 BLE 相关逻辑;选择 ESP32 系列自动切换串口烧录、蓝牙配对流程,界面自动隐藏无关配置项,减少信息干扰。

文档链接:https://github.com/FreakStudioCN/MicroPython_Claude_Assistant_Public/blob/main/setup_tool_guide.md

exe 文件链接:https://github.com/FreakStudioCN/MicroPython_Claude_Assistant_Public/releases

解压项目开源仓库,双击 Claude_Assistant_Setup.exe 打开图形化工具,第一步必须选中仓库内 device 固件文件夹,程序会自动读取内置固件、语音资源目录,校验工程完整性,目录有效会出现绿色 √ 标记。

在硬件单选框选中「WizFi360 (RP2040+WiFi TCP)」,界面自动切换 WiFi 配置面板,填入自家路由器 WiFi 名称与密码,烧录阶段工具会自动将 WiFi 凭证写入设备固件。 通信模式自动锁定为以太网 WiFi,关闭蓝牙相关配置项,区分开 ESP32 蓝牙版本的操作逻辑。

项目灯光语音提示依赖固定采样率 PCM 音频文件,工具内置豆包语音合成插件:填入开放平台密钥后,可自由切换男女音色、调节语速语调,一键生成播报音频,自动保存到固件 assets 资源文件夹,无需手动转换音频格式。

设备重启联网后,点击左下角【配对设备】:

  1. 工具自动扫描整个局域网 57321 端口,检索在线 WizFi360 硬件;
  2. 自动筛选未占用的静态 IP,写入设备配置,设备永久固定该 IP,无需每次重启重新查找;
  3. TCP 连通校验通过后,将 IP、端口配置保存至本地电脑 JSON 文件,下次打开工具自动读取,无需重复配对。

配对完成后点击【启动桥接】,GUI 内嵌守护进程在后台常驻运行:

  • WiFi 版通过 TCP 57321 端口持续接收 Claude Code 推送的 Hook 状态;
  • 5Hz 频率实时转发状态数据到硬件,同步驱动灯光、语音、振动;
  • 界面实时展示桥接连接状态、当前活跃 AI 会话数量;
  • 支持随时停止桥接、读取设备运行日志,用于故障排查; 关闭软件窗口时,后台守护进程自动终止,不会后台残留占用端口。

五、总结扩展

从最开始只是想解决自己 "每隔十几秒切一次终端" 的小痛点,到迭代出 WiFi 版完整方案,前后踩了不少硬件和软件的坑,也摸出了做这类桌面 AI 状态硬件的一些通用思路。这里把设计思路、避坑点和可扩展方向统一整理出来,不管是想复刻改款,还是自己做同类产品,都能少走点弯路。

5.1 核心设计思路:本质是「注意力减负工具」

做这类产品最容易走的歪路,是堆砌功能、堆叠参数,最后做成个四不像。其实它的核心定位非常明确:把屏幕里的数字状态,物理化到桌面上,用最低的注意力成本传递信息。 围绕这个核心,有几个必须守住的设计原则:

  1. 状态极简,一眼可识别:不要搞十几种状态、复杂的灯效图案。人用余光扫一下就要能分辨出 "在运行 / 等审批 / 已完成 / 报错了",颜色是最高效的区分方式,所以我们只保留 5 种核心状态,用纯色 + 简单动效区分。
  2. 多感官冗余,适配不同场景:灯光、语音、振动三个反馈通道,不是炫技,是场景补位。专注写代码时看灯光,切出去查资料时听语音,深夜加班开振动不扰民,总有一种方式能不打断你的工作节奏。
  3. 连接逻辑统一,降低学习成本:从最早的蓝牙版到现在的 WiFi 版,我们一直坚持「PC 主动连设备」的逻辑,用户不用换个版本就更换操作心智。哪怕底层通信协议从 BLE 换成了 TCP,用户端的操作流程几乎没有变化。
  4. 隐私底线不能破:所有状态数据只在局域网内流转,不上云、没有后台服务器、不收集任何用户数据。对开发者群体来说,这点比多十个功能都重要。

5.2 开发落地的注意事项 & 踩坑经验

真正从 0 到 1 落地的时候,细节坑远比想象得多,挑几个最关键的维度来说:

硬件开发避坑:

  1. 串口 WiFi 模组的解析一定要做容错:WizFi360 这类 AT 指令 WiFi 模组,串口输出的数据不是干净的数据包,会混杂 AT 回显、冗余字节、粘包,多 TCP 链路还会出现链路号竞态。我们最开始就踩了丢包、解析错乱的坑,最后把串口接收缓冲拉到 8192 字节,写了完整的帧头帧尾校验、异常丢弃逻辑,才跑稳了长时间连接。
  2. 静态 IP 是 WiFi 版的体验底线:如果默认用 DHCP,设备每次重启 IP 都可能变动,用户每次使用都要重新找设备配对,体验直接崩塌。一定要在烧录阶段就自动扫描子网、分配空闲 IP、写入设备固件,钉死地址,做到配对一次、长期有效。
  3. 二合一开发板比自己搭电路更省心:别为了省几块钱成本,自己买主控 + WiFi 模块画板。射频走线、天线匹配这些隐性坑,没有相关经验的话调半个月都调不好。WizFi360-EVB-Pico 这类原厂一体板,稳定性是经过验证的,小项目、开源项目优先选成熟方案,把精力放在核心功能上。

软件开发注意:

  1. 状态一定要做节流防抖:Claude 的 Hook 事件触发非常频繁,不做节流的话灯光一秒钟跳好几次,人眼会非常疲劳。我们做了 5Hz 的状态聚合,再加优先级排序(报错 > 待审批 > 运行 > 空闲),高优先级事件直接插队,既保证重要提醒不延迟,又不会出现灯光乱闪的问题。
  2. 固件体积要精打细算:RP2040 的 Flash 空间不大,语音素材、驱动库、业务代码挤在一起很容易超限。我们做了条件编译,WiFi 版直接砍掉所有 BLE 相关代码,语音也压缩成 8000 采样率的 PCM 格式,把空间留给用户自定义内容。
  3. 上位机工具要做好异常兜底:用户的网络环境千奇百怪,IP 冲突、防火墙拦截、子网扫不到设备都是常事。工具里一定要做异常提示、手动输入 IP、日志导出这些兜底功能,别让用户对着报错无从下手。

5.3 产品形态设计的细节拿捏

作为桌面摆件,外观和交互的细节,直接决定了它是长期放在桌上用,还是吃灰的电子垃圾。

  1. 存在感要刚刚好:体积不能太大挤占桌面空间,也不能太小看不见。巴掌大小的尺寸,放在显示器旁边不突兀,既是实用工具也能当桌搭摆件。
  2. 灯光一定要做柔化处理:直射的 RGB 灯珠非常刺眼,深夜写代码亮一下能晃得人眼晕。一定要加磨砂灯罩、做漫反射,灯光柔和不刺眼,才能长时间日常使用。
  3. 设备端交互越简单越好:就留一个电源开关就足够,所有配置、配对、参数修改全在电脑端工具里完成。设备端越傻瓜,上手门槛越低,真正做到插电就能用。
  4. 给 DIY 玩家留足改造空间:开源项目一定要给玩家留发挥余地。外壳做成标准 3D 打印件,预留通用孔位,硬件引脚全部引出,用户想改色、加传感器、换造型都方便,社区才能玩出更多花样。

5.4 可扩展方向:不止是 Claude 状态提示

这个方案的底层框架通用性很强,能延伸出很多玩法和形态:

  1. 多 AI 工具适配:目前只做了 Claude Code,后续可以扩展对接 Cursor、GPT、通义灵码等所有带 Hook 能力的 AI 编码工具,做成通用的 AI 开发状态指示器。
  2. 多设备联动组网:同一个局域网里可以布置多个设备,书房、客厅、卧室各放一个,跑长任务的时候走到哪都能收到提醒,不用死守在电脑前。
  3. 硬件功能拓展:加一块小屏幕,可以显示具体任务名称、报错摘要;加温湿度传感器,顺便兼任桌面环境监测;加 NFC 模块,手机碰一下就能快速配对。
  4. 形态风格变种:现在是卡通小人造型,完全可以做成极简交通灯、像素方块、潮玩手办等不同风格,适配不同的桌面装修和审美偏好。
  5. 团队协作场景延伸:做一个轻量服务端中转,开发团队每个人的任务状态都能同步到公共看板,谁在跑编译、谁在等审批、谁遇到了报错,团队一眼就能看清。

最后想说,这类桌面小硬件从来不是什么高精尖技术,核心就是抓住了开发者日常里一个很小的痛点,用硬件的方式把它落地解决。把屏幕里抽象的代码状态,变成桌面上看得见、听得见、摸得到的反馈,这件事本身就挺有意思的。所有软硬件资料全部开源,欢迎大家拿去修改,玩出更多有意思的版本。