Build Guide

Put the hardware together, start to finish: no soldering experience required.

This page walks through building your own Agent Andon Light, from installing the software you'll need to seeing the light turn on for the first time. If you've never soldered anything before, don't worry: the fabricated board only needs one part attached, and it's a lot more forgiving than it sounds.

Looking for the parts list instead? See the BOM.

1. Install the software

Before touching any hardware, install the tools that let your computer talk to the board:

1. Install the Arduino IDE (version 2.x). This is the program you'll use to send the firmware (the small program that runs directly on the board) onto the device.
2. Add support for this board's chip family:
   • In the Arduino IDE, go to Preferences and add the arduino-pico board package URL under "Additional Board Manager URLs."
   • Open the Boards Manager and install "Raspberry Pi Pico/RP2040."
   • When it's time to flash the firmware, select "Waveshare RP2040-Zero" as the board: that's the specific chip this device uses.
3. Install the Adafruit NeoPixel library (Tools → Manage Libraries → search "Adafruit NeoPixel" → Install). This is the library that knows how to talk to the LEDs: they need very precisely timed signals that a simple on/off command can't produce.

2. Build the hardware

If you don't have a board yet, start with fabricating one below, then come back and continue to If you have the fabricated board. If you already have one, or you're only testing without committing to a board yet, skip straight to whichever of the next two sections matches you: you only need one of those two.

If you want to fabricate your own board

Skip this if you already have the fabricated board, or you're only prototyping on a breadboard (see below).

Everything needed to have a real board made is in the hardware folder on GitHub:

• The KiCad project: the actual design files, in the same free tool (KiCad) used to design this board. Open it if you want to view or change the design yourself; skip it if you don't.
• The gerber files: a set of manufacturing files that tell a board fabrication service exactly what to build. You don't need to open or understand these: upload the whole folder to a fabrication service (this project used JLCPCB) and they send back a board with everything soldered on except the microcontroller, same as the parts list describes.
• The chassis files: ready-to-print files for the 3D-printed case, for a 3D-printing service or your own printer.

Once your board arrives, come back and continue below.

If you have the fabricated board

This is the easy path, and it's what most people will do. The fabricated board already has the LEDs and small components placed by the manufacturer: the only thing you need to attach yourself is the small microcontroller board (the RP2040-Zero, the chip that runs everything).

1. Solder the RP2040-Zero onto the board. It has small half-circle notches along its edge (called "castellated pads") that line up with matching pads on the board. Solder each one. Some of these connections carry power and data, and some are just there to hold the chip in place mechanically, but it's simplest to just solder all of them.

A couple of tips if you're new to soldering: let each joint cool for a few seconds before you touch it, and try not to let solder bridge across two neighboring pads into one blob. If that happens, you can usually fix it by reheating and adding a touch more solder to separate them, or using solder wick to pull the extra away.

That's the entire build: there's no cable to connect or wire to run. The connection between the chip and the LEDs is already built into the board itself. Once you're done soldering, skip ahead to Flash and verify.

If you're prototyping on a breadboard

Skip this section if you already did the fabricated-board build above. This path is for testing the firmware against a bare RP2040-Zero wired by hand to a separate LED strip, useful if you're experimenting before committing to the custom board, or don't have one yet.

1. Solder header pins onto the RP2040-Zero. It ships without any pins attached: just the bare half-circle notches. Solder on at least three: 5V, GND, and one GPIO pin (the firmware expects GPIO1 by default). Using a row of male header pins is the easiest way to go, since it lets the board plug into a breadboard like any other component. Soldering wires on directly works too, but it permanently commits you to those specific wires.

2. Wire it to the LED strip:

    [RP2040-Zero]                    [LED strip, 3-pin connector]
      GND o---------------------------o G  (ground)
      5V  o---------------------------o V  (power, not 3V3, see below)
      GP1 o---------------------------o S  (signal / data)
   
      USB-C port -----> cable -----> your computer

   A few things worth knowing:

   • Connect the ground wire (G) first.
   • Connect V to the 5V pin, not 3V3.
   • Connect S (signal) to whichever GPIO pin you soldered, matching the kDataPin setting in the firmware file (or just edit that file to match however you wired it).
   • Plug in the USB-C cable only after all three wires are connected. Powering up a half-finished connection risks a short.
   • Optional: a small resistor and capacitor can help with signal stability. See items #8–9 in the BOM if you run into flicker.

Once wired up, continue to Flash and verify.

3. Flash and verify

1. Open andon_light_firmware.ino (found under device/firmware/andon_light_firmware/ in the project source) in the Arduino IDE.
2. Select "Waveshare RP2040-Zero" as the board, then click Upload to flash the firmware onto it.
3. Open the Serial Monitor, set it to 115200 baud with the line ending set to "Newline."
4. You should see the very first LED light up dim white, with the rest dark. That's the "I'm alive" indicator: it's always on, no matter what state the device is in.
5. Type G, then Y, then R into the Serial Monitor and press enter after each. Each one should light up its own group of three LEDs (positions 2-4, 5-7, and 8-10), not the whole strip.

If that all worked, congratulations. You have a working device. Next, install the host software so it can start following what your coding agent is doing: see the Quick Start on the project's GitHub page.

Reference

A few terms, explained

How the LEDs are laid out

LED 1 stays dim white through all of this, right from the moment the device powers on. If you ever see all 10 LEDs light up the same color at once, that means older firmware is flashed: re-flash from the current source.

Common pitfalls

The watchdog and heartbeat aren't just a nice-to-have: they're what makes it safe to actually walk away and trust the light while you're gone.

Notes for your operating system

Wire protocol reference

This is the exact set of single-character commands the computer sends to the device over USB:

If the device doesn't hear from your computer for 30 minutes, it assumes something went wrong and switches to the slow pulsing red pattern rather than freezing on whatever color it last showed.