Labs / MicroPython tutorials

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

Author: Li Zisheng · Source: FreakStudio open documentation · License: CC BY 4.0

Contents

0. Background

Recently I've come across quite a few AI status indicator products of the same type, some designed in the shape of traffic lights, others as minimalist discs. Essentially, they all help free up developers' line of sight, so they don' t have to stare fixed at the terminal waiting for the AI to finish running tasks. As for myself, I started working on products in this very category long ago — a desktop status ornament specifically tailored for Claude Code, which has gone through iterations all the way from the earliest Bluetooth version to the current WiFi version.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

After finishing it, I synced the complete project to the LCKFB Open Source Hardware Platform and OSChina, open-sourced all the software and hardware files without holding anything back. Unexpectedly, it received quite a positive response: many DIY enthusiasts followed the tutorial to make their own versions, and plenty of people put forward optimization suggestions, which actually helped me polish the solution into a more complete one.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

To be honest, this was originally just a tool I built for my own use, so I’m quite surprised that it has been recognized by so many people.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]
A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

When we brought it to the Pudong Software Park Hackathon site, it attracted quite a lot of attention. Many people who tried it said that they finally didn't have to switch back to the terminal to take a look every dozen seconds.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]
A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]
A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

In this article, we will break down and discuss all the complete implementation details from 0 to 1, including why we chose the WizFi360-EVB-Pico as the core, what pitfalls we encountered with the WiFi TCP solution, and how the firmware and host computer are used in coordination. All the code, schematics, and 3D files are fully open source, so anyone who wants to replicate this can just follow along to build it.

I. Project Introduction

Simply put, it is a desktop status indicator that connects to the daemon running on your computer via WiFi. Every time Claude performs an action — whether reading a file, executing a command, or searching for code — the status will be pushed to this small device in real time.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

Different statuses correspond to different lights: blue means idle and on standby, cyan running light indicates in execution, slow flashing yellow light signals pending approval, fast flashing green light means the task is completed, and alternating flashing red light indicates an error has occurred. Each status is also equipped with TTS voice broadcast, and both the timbre and speaking speed are adjustable.

Where is its most practical feature? When running batch tasks, you can safely go get coffee, slack off and browse the web, and just come back when you hear "task completed"; when you switch to another window to look up information, once the yellow light turns on with a prompt "please check the terminal", you'll know you need to go back and click to confirm. If you're coding late at night and don't want to turn on the lights, you can also figure out the progress just by listening to the voice prompts.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

Put simply, it extends the working state of AI from your mouse clicks to your peripheral vision and ears.

All the software and hardware of this project are fully open-source. The repository, demo videos, and introduction page are all available here for anyone who wants to replicate it directly:

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

II. Core hardware teardown

The core carrier of this entire project is the WizFi360-EVB-Pico all-in-one development board launched by WIZnet, which integrates both the RP2040 dual-core main controller and the WizFi360 industrial-grade WiFi module on a single board. It eliminates the hassle of separately matching a WiFi module and performing wiring and radio frequency debugging, making it extremely suitable for building IoT desktop gadgets.

Development Board Resources: https://docs.wiznet.io/Product/Chip/Chip_Related_modules/wizfi360-evb-pico

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

On-board hardware core parameters:

This is the officially supported and complete MicroPython development repository, which comes with built-in AT command encapsulation, TCP communication, and a full set of sample codes for WiFi network configuration. The WiFi connection and frame parsing logic in our project are all secondary developments based on this official library, with compatibility and stability guaranteed by the original manufacturer.

Repository Address: https://github.com/Wiznet/WizFi360-EVB-Pico-MicroPython

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

The WizFi360 equipped on this board is a low-cost industrial serial port WiFi module that supports 2.4G 802.11 b/g/n, is compatible with Station/SoftAP/Blend Mode, supports up to 5 TCP/UDP persistent connections, and features a maximum serial port baud rate of 2Mbps. Its biggest advantage lies in being fully driven by AT commands: there is no need for the main controller to run a complex protocol stack, and all processes including network handshake, data forwarding, keep-alive, and DHCP IP acquisition are handled entirely by the module itself.It simultaneously supports OTA remote upgrade, Keep-Alive heartbeat, and PING network detection, and can stay stably online in the local area network for a long time, which perfectly meets our requirement of monitoring TCP port 57321 7×24 hours a day.

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

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

The complete hardware engineering of the whole device (schematic diagram, PCB, BOM, 3D enclosure model) has been fully open-sourced and uploaded to the OSHWHub LCKFB Open Source Platform under the MIT open source license, which allows anyone to download, replicate and make secondary modifications for free.

Project Open Source Address: https://oshwhub.com/baizekun/project_svwkrlfc

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

The entire device circuit performs peripheral expansion based on the WizFi360-EVB-Pico, with the complete circuit modules divided as follows:

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]
A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

The complete device comes with a full set of 3D-printed housing models, which features an iconic cartoon figurine shape. The housing consists of an upper cover and a lower cover, with pre-reserved speaker sound outlets, light transmission windows, a power switch, a vibration motor mounting position, and screw holes that are precisely aligned with the PCB. No secondary mold modification is required after printing for assembly.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

The assembly process is extremely simple: first solder the speaker and vibration motor to the reserved terminals on the PCB, fix the WizFi360-EVB-Pico in the positioning slot of the motherboard, connect the rechargeable battery, finally fit the 3D-printed casing, tighten the M3 fixing screws to complete the assembly of the whole device, even beginners can finish the assembly quickly.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]
A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

Once assembled, it takes the form of a desktop ornament that can be placed on your work desk. After being powered on and connected to the network, the WS2812 goggle lights will synchronize the running status of Claude Code in real time. Combined with multi-dimensional reminders via voice and vibration, you don't need to frequently switch computer windows to check the terminal.

III. Working Principle of the Software

Most similar AI status ornaments on the market adopt the BLE Bluetooth solution, which has the shortcomings of short transmission distance, disconnection when blocked by walls, and requiring the computer to actively broadcast and scan. This WiFi version completely switches to a TCP long connection architecture, with the logic designed in reverse: after the device-side WizFi360 powers on, it acts as a TCP server and fixedly listens on port 57321; the computer-side daemon acts as a TCP Client to actively initiate a connection. As long as the two are on the same local area network, status signals can be stably received from any position in the entire house. The entire link has a clear division of labor:

  1. Claude Code triggers various tool Hook events and outputs standard JSON data streams;
  2. PC client ble_daemon.py aggregates and throttles daemon states, and forwards them via TCP;
  3. The WizFi360 WiFi module receives network data and forwards it to the RP2040 main controller via UART AT commands;
  4. The RP2040 parses data and drives the WS2812 lights, TTS voice module and vibration motor to complete status feedback.
A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

Take the core logic of device networking as an example: transport.py connect () function encapsulates the entire process of WizFi360 network configuration + enabling TCP server AT commands:

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")                    # Multi-connection mode await self._wizfi.at_response(f"AT+CIPSERVER=1,{TCP_PORT}")      # Start TCP Server :57321await self._wizfi.at_response("AT+CIPSTO=60")                   # 60s timeout
    self._connected = True

Upon device power-on, AT command-based network configuration, local static IP reading, and multi-connection TCP service startup are automatically executed, all scheduled asynchronously by MicroPython without blocking the lighting and voice tasks.

Key design highlights: The RP2040 itself does not process any protocol stack; all WiFi network configuration, TCP connections, and data transmission/reception are entirely delegated to the WizFi360 module as an agent. The main controller only needs to send AT commands to complete all network operations, significantly reducing the complexity of firmware development. Hardware serial port wiring: RP2040 UART1 (GP4/GP5) is connected to WizFi360, with a fixed baud rate of 115200.Peripheral output relies on dual-channel WS2812 LEDs of GP16, I2S audio power amplifier and vibration motor to achieve multi-sensory reminders.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

The project code is naturally divided into two major modules: the PC-side daemon and the device-side RP2040 MicroPython firmware, which are isolated by compile conditions VARIANT=="wizfi360" to separate different forms; the WiFi version will automatically skip BLE-related code to reduce the firmware size.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

From the moment a tool is executed by Claude to the moment the desktop ornament's lights turn on, the complete data goes through 6 layers of conversion, with data formats encapsulated and parsed step by step: Native Hook JSON → v2 standardized envelope → v6 wire binary frame → WizFi360 AT + IPD data frame → RP2040 state enumeration → light/voice dynamic effect

  1. Event generation: Claude's built-in hooks capture 8 types of events including PreToolUse, PostToolUse, and Stop, and output JSON via standard stdin push;
  2. Standardized encapsulation: hook_bridge is uniformly encapsulated into v2 envelope data packets to mask the differences in event formats of different tools;
  3. State aggregation throttling: The daemon refreshes the global session state at 5Hz and sets priorities (error > pending approval > running > idle) to prevent a flood of events from cluttering the screen in a short period of time;
  4. Serialized push: The status is packaged once every 200ms based on the v6 wire lightweight protocol, and then pushed unidirectionally to the hardware via TCP;
  5. WiFi hardware implementation analysis: The WizFi360 receives TCP data packets and forwards them to the RP2040 via + IPD serial port frames. The code strips the payload from the messy AT serial port echo and parses the link number and status data;
  6. Multi-sensory presentation: The state is sent to the renderer to synchronously output RGB light animations, TTS speech, and vibration feedback.
A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

The project defines 5 sets of standard business statuses, each corresponding to a dedicated light color, dynamic effect, and voice prompt:

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

The device is equipped with a complete finite-state machine that strictly defines state transition logic and priorities: ERROR > PENDING > WORKING > IDLE > CELEBRATE

Source Code Link: https://github.com/FreakStudioCN/MicroPython_Claude_Assistant_Public

The entire solution relies on the open-source claude-buddy-plugin to implement automatic Hook registration, eliminating the need to manually modify Claude's configuration files:

  1. Online installation: Directly pull the plugin repository from the Claude Extension Marketplace and complete the deployment with one click;
  2. Offline installation: You can clone the project source code in a network-free environment, and run the local installation command in the Claude terminal; after the plugin is installed, the event forwarding logic will be automatically mounted, and all AI operations will be pushed to the local daemon in real time without additional configuration throughout the process.

Claude plugin link: https://github.com/ChrisWu132/claude-buddy-plugin

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]
A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

IV. Supporting Tools

Why develop a separate one-click GUI configuration tool specifically?

The overall design logic of the tool is as follows:

Hierarchical Modularization design with linearly progressive process: project directory selection → hardware form factor selection → resource creatives generation/import → flashing parameter configuration → one-click flashing → device pairing → bridging operation and debugging. Branching and shunting for different hardware forms: selecting WizFi360 automatically switches to WiFi TCP link and shields BLE-related logic; selecting ESP32 series automatically switches to serial port flashing and Bluetooth pairing processes, and the interface automatically hides irrelevant configuration items to reduce information interference.

Document Link: https://github.com/FreakStudioCN/MicroPython_Claude_Assistant_Public/blob/main/setup_tool_guide.md

EXE file link: https://github.com/FreakStudioCN/MicroPython_Claude_Assistant_Public/releases

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

Extract the open-source repository of the project, and double-click Claude_Assistant_Setup.exe to launch the graphical tool. In the first step, you must select the device firmware folder in the repository. The program will automatically read the built-in firmware and voice resource directories, and verify the integrity of the project. A green checkmark will appear once the directory is confirmed valid.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

Select "WizFi360 (RP2040+ WiFi TCP)" in the hardware radio button, the interface will automatically switch to the WiFi configuration panel, enter your home router's WiFi name and password, and the tool will automatically write the WiFi credentials into the device firmware during the flashing phase. The communication mode is automatically locked to Ethernet WiFi, and the Bluetooth-related configuration items are disabled to distinguish the operation logic of the ESP32 Bluetooth version.

The project's light and voice prompt relies on PCM audio files with a fixed sampling rate. The tool has a built-in Doubao speech synthesis plugin: after entering the Open Platform key, you can freely switch between male and female timbres, adjust the speech rate and intonation, generate broadcast audio with one click, and automatically save it to the firmware assets resource folder, no manual audio format conversion is required.

A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

After the device restarts and connects to the network, tap the [Pair Device] button in the bottom left corner:

  1. The tool automatically scans port 57321 of the entire LAN to search for online WizFi360 hardware;
  2. Automatically filter unoccupied static IPs, write them into the device configuration, so that the device will permanently fix this IP without re-searching it every time it restarts;
  3. After the TCP connectivity check passes, the IP and port configurations will be saved to a JSON file on the local computer, which will be read automatically the next time the tool is launched, eliminating the need for repeated pairing.
A Step-by-Step Guide to Building an AI Operation Status Indicator [Fully Open-Source Breakdown]

After pairing is complete, click [Start Bridging], and the GUI-embedded daemon will run resident in the background:

V. Summary and Extension

Starting from just wanting to solve my own small pain point of "switching terminals every dozen seconds" to iterating out a complete WiFi version solution, I stepped on quite a few pitfalls in both hardware and software along the way, and also figured out some general ideas for making this kind of desktop AI status hardware. Here I have sorted out the design concepts, pitfalls to avoid, and scalable directions all in one place, so whether you want to replicate and modify it, or make a similar product yourself, you can take fewer detours.

5.1 Core Design Concept: Essentially an "Attention Burden Reduction Tool"

The most common pitfall when developing products of this kind is cramming in features and piling up specs, only to end up with a jack-of-all-trades but master of none. In fact, its core positioning is crystal clear: to translate the digital states on the screen into a physical form on your desk, conveying information with the minimum possible attentional cost. Centering on this core, there are several design principles that must be upheld:

  1. Minimalist status design for instant recognition: avoid a dozen different statuses or complex lighting patterns. Users should be able to tell at a glance out of the corner of their eye whether a task is "running / pending approval / completed / error", and color is the most efficient way to distinguish them. That's why we only retain 5 core statuses, differentiated by solid colors plus simple animations.
  2. Multi-sensory redundancy for different scenarios: The three feedback channels of light, voice and vibration are not gimmicks, but scenario-specific complements. You can check the light feedback when focusing on coding, listen to the voice prompt when switching to look up information, and turn on vibration mode for late-night overtime to avoid disturbing others — there is always a way that won't interrupt your work rhythm.
  3. Unified connection logic to reduce learning cost: From the earliest Bluetooth version to the current WiFi version, we have always adhered to the logic of "PC actively connects to devices", so users do not need to adjust their operation mindset when switching versions. Even if the underlying Communication Protocol is changed from BLE to TCP, the operation process on the user side remains almost unchanged.
  4. There is a non-negotiable privacy bottom line: all status data only circulates within the local area network, never goes to the cloud, involves no backend servers, and does not collect any user data. For the developer community, this matters far more than adding ten extra features.

5.2 Notes for Development Implementation & Lessons Learned from Pitfalls

When it comes to the actual implementation from 0 to 1, there are far more pitfalls in the details than imagined. Let me highlight a few of the most critical dimensions:

hardware development pitfalls to avoid:

  1. Fault tolerance is a must for the parsing of serial port WiFi modules: for AT-command based WiFi modules like the WizFi360, the data output via the serial port is not a clean data packet, but mixed with AT echo, redundant bytes and packet concatenation, and link number race conditions will also occur with multiple TCP links. We initially ran into the pitfalls of packet loss and parsing disorder, and finally stabilized the long-term connection only after expanding the serial port receive buffer to 8192 bytes and implementing complete header and footer checksum as well as exception discarding logic.
  2. A static IP address is the bare minimum for a good WiFi version experience: if DHCP is used by default, the device's IP may change every time it restarts, forcing users to re-pair with the device on every use, which completely ruins the user experience. It is necessary to automatically scan the subnet, assign an available IP, and write it to the device firmware during the flashing stage to fix the address, so that pairing only needs to be done once and remains valid permanently.
  3. A 2-in-1 development board saves you the hassle of building circuits from scratch: don’t skimp on a few dollars by buying a separate main controller and WiFi module to design your own PCB. Hidden pitfalls like RF trace routing and antenna matching can take half a month to debug without relevant experience. Official all-in-one boards such as the WizFi360-EVB-Pico have proven stability. For small and open-source projects, it’s better to opt for a mature solution so you can focus your energy on core functions.

Note for Software Development:

  1. Throttling and debouncing must be implemented for status updates: Claude's Hook events are triggered extremely frequently, and without throttling, the indicator light would flicker several times per second, causing severe eye fatigue. We have implemented 5Hz status aggregation, supplemented by a priority ranking (error > pending approval > running > idle), where high-priority events can directly jump the queue. This ensures that important alerts are not delayed while preventing erratic flickering of the indicator light.
  2. We need to carefully control the firmware size: the RP2040 has limited Flash space, and it is easy to exceed the limit when voice creatives, driver libraries and service code are crowded together. We have implemented conditional compile: the WiFi version directly removes all BLE-related code, and the voice is also compressed into PCM format with an 8000 sampling rate to reserve space for user-defined content.
  3. The host computer tool must have proper exception fallback: users have all kinds of network environments, and IP conflicts, firewall blocks, and failure to detect devices via subnet scans are common occurrences. The tool must include fallback features such as exception prompts, manual IP entry, and log export, so that users do not feel lost when encountering error messages.

5.3 Handling Details in Product Form Design

As a desktop ornament, the details of its appearance and interaction directly determine whether it will be a device you keep using on your desk for a long time, or just electronic waste that ends up gathering dust.

  1. Strike just the right balance of presence: it shouldn't be so bulky that it clutters up your desk, nor so tiny that it's barely noticeable. With a palm-sized form factor, it sits unobtrusively next to your monitor, functioning both as a practical tool and a stylish desk decor piece.
  2. Be sure to soften the lighting: direct RGB LED beads are extremely harsh to the eyes, and a sudden flash while coding late at night can be dazzling enough to make you feel dizzy. It is essential to add a frosted lampshade and adopt diffuse reflection, so that the light is soft and non-glaring for long-term daily use.
  3. The interaction on the device side should be as simple as possible: just a power switch is enough, and all configuration, pairing, and parameter modification are completed via the computer-side tool. The more user-friendly the device side is, the lower the barrier to entry, making it truly plug-and-play.
  4. Leave ample modification room for DIY enthusiasts: Open-source projects must leave room for users to bring their creativity into play. The enclosure is designed as a standard 3D-printed part with reserved universal mounting holes, and all hardware pins are routed out, making it easy for users to change the color, add sensors, or alter the shape, so that the community can create more diverse and interesting variations.

5.4 Scalability Directions: Beyond Just Claude State Prompts

The underlying framework of this solution boasts high versatility and can be extended into a wide variety of gameplay modes and forms.

  1. Multi-AI Tool Adaptation: Currently, only Claude Code is supported. Subsequent extensions will integrate with all AI coding tools with Hook capabilities, including Cursor, GPT, and Tongyi Lingma, to build a universal AI development status indicator.
  2. Multi-device linkage networking: Multiple devices can be deployed within the same local area network, with one placed in the study, one in the living room, and one in the bedroom. When running long tasks, you can receive notifications no matter where you go, without having to wait fixed in front of the computer.
  3. Hardware feature expansion: add a small screen to display specific task names and error summaries; add a temperature and humidity sensor that also serves as desktop environment monitoring by the way; add an NFC module to enable quick pairing with a single tap from a mobile phone.
  4. Variations in form and style: Currently designed as a cartoon figurine, it can be fully adapted into different styles such as minimalist traffic lights, pixel blocks, trendy collectible figures, etc. , to suit various desktop setups and aesthetic preferences.
  5. Extended team collaboration scenario: Build a lightweight server-side relay so that the task status of every member in the development team can be synced to a public dashboard, and the team can see at a glance who is running a compile, who is waiting for approval, and who has encountered an error.

Finally, I want to say that this kind of small desktop hardware is never some cutting-edge technology. Its core lies in capturing a tiny pain point in developers' daily work and solving it in a hardware-based way. Turning the abstract code status on the screen into visible, audible and tangible feedback right on your desktop is quite interesting in itself. All software and hardware materials are fully open source, and everyone is welcome to modify them to create more interesting versions.