零、背景
最近刷到不少同类型的 AI 状态指示产品,有交通灯造型的,也有简约圆盘款的,本质都是帮开发者解放视线,不用死盯着终端等 AI 跑任务。其实我自己很早就开始做同款方向的东西了,专门适配 Claude Code 的桌面状态摆件,从最早的蓝牙版一路迭代到现在的 WiFi 版。
做好之后我把完整项目同步到了立创开源硬件平台和开源中国,软硬件文件全部开源,没留一手。没想到反响还挺不错,不少 DIY 爱好者跟着教程做出来了,也有很多人提了优化建议,反而帮我把方案补得更完善了。
说实话最开始只是做给自己用的工具,能被这么多人认可,还挺意外的。
带去浦软黑客松现场的时候也挺受关注,好多人试用之后说终于不用每隔十几秒切回终端看一眼了。
这篇就把从 0 到 1 的完整实现细节全拆开来聊,包括为什么选 WizFi360-EVB-Pico 当核心、WiFi TCP 方案踩了哪些坑、固件和上位机怎么配套使用。所有代码、原理图、3D 文件全部开源,想复刻的朋友照着就能做。
一、项目介绍
简单说,它就是个桌面状态指示器,通过 WiFi 跟你电脑上的守护进程连着。Claude 每执行一个操作 ------ 读文件、跑命令、搜代码,状态都会实时推到这个小设备上。
不同状态对应不同的灯光:蓝色是闲着待命,青色流水灯是正在执行,黄灯慢闪是有待审批,绿灯快闪是任务跑完了,红灯交替闪就是出了错。每种状态还配了 TTS 语音播报,音色语速都能调。
最实用的地方在哪呢?跑批量任务的时候你大可放心去倒咖啡、摸鱼刷网页,听见 "任务完成" 再回来就行;切出去查资料的时候,黄灯一亮加一句 "请查看终端",就知道得回去点确认了。深夜写代码不想亮灯,光听语音也能摸清楚进度。
说白了,就是把 AI 的工作状态,从你的鼠标点击里,延伸到了余光和耳朵里。
项目所有软硬件全部开源,仓库、演示视频、介绍页都放在这了,想复刻的朋友可以直接拿:
- 项目链接:https://github.com/FreakStudioCN/MicroPython_Claude_Assistant_Public
- 介绍页面:https://claude.freakstudio.cn/
- Github Pages:https://freakstudiocn.github.io/MicroPython_Claude_Assistant_Public/presentation.html
- 相关演示视频可看:https://www.bilibili.com/video/BV1SNEc6YEdV/?spm_id_from=333.1387.homepage.video_card.click
二、核心硬件拆解
整个项目的核心载体是 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 客户端主动发起连接,只要二者处于同一局域网,全屋任意位置都能稳定接收状态信号。 整套链路分工清晰:
- Claude Code 触发各类工具 Hook 事件,输出标准 JSON 数据流;
- PC 端
ble_daemon.py守护进程聚合、节流状态,通过 TCP 转发; - WizFi360 WiFi 模组接收网络数据,通过 UART AT 指令转发给 RP2040 主控;
- RP2040 解析数据,驱动 WS2812 灯光、TTS 语音、振动马达完成状态反馈。
举设备联网核心逻辑示例,transport.py 内 connect() 函数封装了整套 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状态枚举 → 灯光/语音动效
- 事件产生:Claude 内置 Hook 捕获 PreToolUse、PostToolUse、Stop 等 8 类事件,输出 JSON 通过标准 stdin 推送;
- 标准化封装:
hook_bridge统一封装为 v2 信封数据包,屏蔽不同工具事件格式差异; - 状态聚合节流:守护进程 5Hz 刷新全局会话状态,设置优先级(报错 > 待审批 > 运行 > 空闲),防止短时间大量事件刷屏;
- 序列化推送:每 200ms 打包一次状态为 v6 wire 轻量协议,TCP 单向推送到硬件;
- WiFi 硬件落地解析:WizFi360 接收 TCP 数据包,通过
+IPD串口帧转发给 RP2040,代码从杂乱 AT 串口回显中剥离有效载荷,解析链路号与状态数据; - 多感官呈现:状态送入渲染器,同步输出 RGB 灯光动画、TTS 语音、振动反馈。
项目定义 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 配置文件:
- 在线安装:直接在 Claude 插件市场拉取插件仓库,一键完成部署;
- 离线安装:无网络环境可克隆项目源码,在 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 资源文件夹,无需手动转换音频格式。
设备重启联网后,点击左下角【配对设备】:
- 工具自动扫描整个局域网 57321 端口,检索在线 WizFi360 硬件;
- 自动筛选未占用的静态 IP,写入设备配置,设备永久固定该 IP,无需每次重启重新查找;
- TCP 连通校验通过后,将 IP、端口配置保存至本地电脑 JSON 文件,下次打开工具自动读取,无需重复配对。
配对完成后点击【启动桥接】,GUI 内嵌守护进程在后台常驻运行:
- WiFi 版通过 TCP 57321 端口持续接收 Claude Code 推送的 Hook 状态;
- 5Hz 频率实时转发状态数据到硬件,同步驱动灯光、语音、振动;
- 界面实时展示桥接连接状态、当前活跃 AI 会话数量;
- 支持随时停止桥接、读取设备运行日志,用于故障排查; 关闭软件窗口时,后台守护进程自动终止,不会后台残留占用端口。
五、总结扩展
从最开始只是想解决自己 "每隔十几秒切一次终端" 的小痛点,到迭代出 WiFi 版完整方案,前后踩了不少硬件和软件的坑,也摸出了做这类桌面 AI 状态硬件的一些通用思路。这里把设计思路、避坑点和可扩展方向统一整理出来,不管是想复刻改款,还是自己做同类产品,都能少走点弯路。
5.1 核心设计思路:本质是「注意力减负工具」
做这类产品最容易走的歪路,是堆砌功能、堆叠参数,最后做成个四不像。其实它的核心定位非常明确:把屏幕里的数字状态,物理化到桌面上,用最低的注意力成本传递信息。 围绕这个核心,有几个必须守住的设计原则:
- 状态极简,一眼可识别:不要搞十几种状态、复杂的灯效图案。人用余光扫一下就要能分辨出 "在运行 / 等审批 / 已完成 / 报错了",颜色是最高效的区分方式,所以我们只保留 5 种核心状态,用纯色 + 简单动效区分。
- 多感官冗余,适配不同场景:灯光、语音、振动三个反馈通道,不是炫技,是场景补位。专注写代码时看灯光,切出去查资料时听语音,深夜加班开振动不扰民,总有一种方式能不打断你的工作节奏。
- 连接逻辑统一,降低学习成本:从最早的蓝牙版到现在的 WiFi 版,我们一直坚持「PC 主动连设备」的逻辑,用户不用换个版本就更换操作心智。哪怕底层通信协议从 BLE 换成了 TCP,用户端的操作流程几乎没有变化。
- 隐私底线不能破:所有状态数据只在局域网内流转,不上云、没有后台服务器、不收集任何用户数据。对开发者群体来说,这点比多十个功能都重要。
5.2 开发落地的注意事项 & 踩坑经验
真正从 0 到 1 落地的时候,细节坑远比想象得多,挑几个最关键的维度来说:
硬件开发避坑:
- 串口 WiFi 模组的解析一定要做容错:WizFi360 这类 AT 指令 WiFi 模组,串口输出的数据不是干净的数据包,会混杂 AT 回显、冗余字节、粘包,多 TCP 链路还会出现链路号竞态。我们最开始就踩了丢包、解析错乱的坑,最后把串口接收缓冲拉到 8192 字节,写了完整的帧头帧尾校验、异常丢弃逻辑,才跑稳了长时间连接。
- 静态 IP 是 WiFi 版的体验底线:如果默认用 DHCP,设备每次重启 IP 都可能变动,用户每次使用都要重新找设备配对,体验直接崩塌。一定要在烧录阶段就自动扫描子网、分配空闲 IP、写入设备固件,钉死地址,做到配对一次、长期有效。
- 二合一开发板比自己搭电路更省心:别为了省几块钱成本,自己买主控 + WiFi 模块画板。射频走线、天线匹配这些隐性坑,没有相关经验的话调半个月都调不好。WizFi360-EVB-Pico 这类原厂一体板,稳定性是经过验证的,小项目、开源项目优先选成熟方案,把精力放在核心功能上。
软件开发注意:
- 状态一定要做节流防抖:Claude 的 Hook 事件触发非常频繁,不做节流的话灯光一秒钟跳好几次,人眼会非常疲劳。我们做了 5Hz 的状态聚合,再加优先级排序(报错 > 待审批 > 运行 > 空闲),高优先级事件直接插队,既保证重要提醒不延迟,又不会出现灯光乱闪的问题。
- 固件体积要精打细算:RP2040 的 Flash 空间不大,语音素材、驱动库、业务代码挤在一起很容易超限。我们做了条件编译,WiFi 版直接砍掉所有 BLE 相关代码,语音也压缩成 8000 采样率的 PCM 格式,把空间留给用户自定义内容。
- 上位机工具要做好异常兜底:用户的网络环境千奇百怪,IP 冲突、防火墙拦截、子网扫不到设备都是常事。工具里一定要做异常提示、手动输入 IP、日志导出这些兜底功能,别让用户对着报错无从下手。
5.3 产品形态设计的细节拿捏
作为桌面摆件,外观和交互的细节,直接决定了它是长期放在桌上用,还是吃灰的电子垃圾。
- 存在感要刚刚好:体积不能太大挤占桌面空间,也不能太小看不见。巴掌大小的尺寸,放在显示器旁边不突兀,既是实用工具也能当桌搭摆件。
- 灯光一定要做柔化处理:直射的 RGB 灯珠非常刺眼,深夜写代码亮一下能晃得人眼晕。一定要加磨砂灯罩、做漫反射,灯光柔和不刺眼,才能长时间日常使用。
- 设备端交互越简单越好:就留一个电源开关就足够,所有配置、配对、参数修改全在电脑端工具里完成。设备端越傻瓜,上手门槛越低,真正做到插电就能用。
- 给 DIY 玩家留足改造空间:开源项目一定要给玩家留发挥余地。外壳做成标准 3D 打印件,预留通用孔位,硬件引脚全部引出,用户想改色、加传感器、换造型都方便,社区才能玩出更多花样。
5.4 可扩展方向:不止是 Claude 状态提示
这个方案的底层框架通用性很强,能延伸出很多玩法和形态:
- 多 AI 工具适配:目前只做了 Claude Code,后续可以扩展对接 Cursor、GPT、通义灵码等所有带 Hook 能力的 AI 编码工具,做成通用的 AI 开发状态指示器。
- 多设备联动组网:同一个局域网里可以布置多个设备,书房、客厅、卧室各放一个,跑长任务的时候走到哪都能收到提醒,不用死守在电脑前。
- 硬件功能拓展:加一块小屏幕,可以显示具体任务名称、报错摘要;加温湿度传感器,顺便兼任桌面环境监测;加 NFC 模块,手机碰一下就能快速配对。
- 形态风格变种:现在是卡通小人造型,完全可以做成极简交通灯、像素方块、潮玩手办等不同风格,适配不同的桌面装修和审美偏好。
- 团队协作场景延伸:做一个轻量服务端中转,开发团队每个人的任务状态都能同步到公共看板,谁在跑编译、谁在等审批、谁遇到了报错,团队一眼就能看清。
最后想说,这类桌面小硬件从来不是什么高精尖技术,核心就是抓住了开发者日常里一个很小的痛点,用硬件的方式把它落地解决。把屏幕里抽象的代码状态,变成桌面上看得见、听得见、摸得到的反馈,这件事本身就挺有意思的。所有软硬件资料全部开源,欢迎大家拿去修改,玩出更多有意思的版本。