

Ws2812b Breakout v11
Synchronized mood lamp between two devices
- Size
- 17.8 × 12.7 mm
- Copper layers
- 2
- Thickness
- 1.6 mm
- Parts
- 11
- Nets
- 4
- Pads
- 16
- Tracks, vias
- 22, 1
- Pours
- 2
- Routed
- Yes
- KiCad
- KiCad 10.0 (file 20260206)
- Created
- 1 Jul 2026
- Updated
- 6 Oct 2026
Overview
Ws2812b Breakout v11 is an open-source printed circuit board by Ryan-Jing, from the Ryan-Jing/Mood-Lamp repository on GitHub. It is a 2-layer board of 17.8 × 12.7 mm with 11 parts on 4 nets, routed with 22 tracks and 1 via.
It is built around the WS2812B. Its parts include 1 capacitor and 1 IC. It belongs with the lEDs and displays and interfaces and adapters boards of this library.
Main components
1README
README.mdMood-Lamp
Synchronized mood lamp between two paired devices. Each lamp is a Seeed XIAO ESP32-C3 with a single WS2812B RGB LED and a dual-stage button. A lamp shows its peer's mood by default; you set your own mood with the button, it's pushed to a small server, and the peer lamp polls and renders it.
- Firmware (
Firmware/) — PlatformIO + Arduino, two FreeRTOS tasks (UI + networking). SeeFirmware/README.md. - Server (
Server/) — FastAPI + SQLite on a Raspberry Pi, exposed publicly via Tailscale Funnel. - Utils (
Utils/) —moods.yaml(mood source of truth), the mood-header generator, and the BLE Wi-Fi provisioning script. SeeUtils/README.md. - Docs (
Docs/) — architecture and CI/CD notes. - Electrical / Mechanical — KiCad project and the printable enclosure STLs.
Setup guide
1. Flash the firmware (first time only)
Skip to step 2 if the lamp is already flashed. Requires PlatformIO Core
(pio) on your computer.
cd Firmwarecp include/secrets.example.h include/secrets.hOpen include/secrets.h and fill in SERVER_URL, DEVICE_TOKEN (one per lamp, from
Server/database_init.py), and ROOT_CA. Then connect the lamp by USB-C and flash it:
pio run -e seeed_xiao_esp32c3 -t uploadDo not press the lamp's button while flashing.
2. Power the lamp over USB-C
Plug the XIAO's USB-C port into any 5 V USB source (charger, laptop, power bank). The lamp boots in about two seconds and the LED tells you where it is:
| LED | Meaning | What to do |
|---|---|---|
| Cyan blink | BLE provisioning — no Wi-Fi credentials saved | Go to step 3 |
| Warm-white breath | Connected, peer hasn't set a mood yet | Nothing, it's ready |
| Animated mood colour | Connected, showing the peer's mood | Nothing, it's ready |
| Orange blink | Wi-Fi problem | Re-provision (step 3) or check the network |
If the lamp already has credentials but you want to re-provision, hold the button fully pressed for 5 seconds to force BLE provisioning on.
3. Send Wi-Fi credentials with Utils/provision.py
Do this on a computer with Bluetooth, within a few metres of the lamp, while the LED is blinking cyan. Provisioning stays open for 2 minutes per session.
cd /path/to/Mood-Lamppython3 -m venv .venvsource .venv/bin/activatepip install bleakpython3 Utils/provision.pyThe script prompts for the network name and password, finds the lamp advertising as MoodLamp,
and writes the credentials over BLE:
Wi-Fi SSID: MyNetwork
Wi-Fi password: ********
Scanning for 'MoodLamp' (the lamp LED should be blinking cyan)...
Connected. Sending credentials...
Credentials sent. Waiting for the lamp to connect to Wi-Fi...
Lamp status: connectingThe lamp saves the credentials to flash (they survive reboots and power loss), leaves BLE, and joins the network. The LED stops blinking cyan within a few seconds. Notes:
- 2.4 GHz networks only — the ESP32-C3 has no 5 GHz radio.
- If the lamp isn't found, it's not in provisioning mode; hold the button fully pressed for 5 seconds and run the script again.
python3 Utils/ble_check.pylists nearby BLE devices if you want to confirm the lamp is advertising at all.
4. Using the button
The button is a dual-action pushbutton: pressing part-way is a half press (first detent), and pressing all the way down is a full press. Every gesture fires when you release.
| Gesture | What it does |
|---|---|
| Half tap | Only in mood-select mode: step to the next mood |
| Full tap | Enter mood-select mode → then confirm the mood and send it to your peer |
| Full press, hold 5 s | Turn BLE provisioning on (or off if it's already on) |
| Full press, hold 10 s | Erase the saved Wi-Fi credentials and reopen BLE provisioning |
To set your mood:
- Full tap — the LED switches from your peer's mood to your own. (This only works while the lamp is connected; if it isn't, nothing happens.)
- Half tap repeatedly until the LED shows the mood you want. It wraps around from Working back to Excited.
- Full tap — the mood is posted to the server and the LED goes back to showing your peer's mood. Their lamp picks it up within 10 seconds.
Half taps do nothing outside mood-select mode, so brushing the button won't change anything. Hold times are measured from the moment the full stage engages, so resting at the half press first doesn't count toward the 5 s and 10 s timers.
Moods
Colours and patterns are defined in Utils/moods.yaml and generated into
Firmware/include/moods.h. The ID below is the mood_id the firmware and server exchange.
Three status moods are shown by the lamp but are never user-selectable (mood-select skips them):
| ID | Mood | Colour | Pattern | Period |
|---|---|---|---|---|
| 0 | Idle / default | soft warm white | breath | 6000 ms |
| 1 | BLE provisioning | cyan | blink | 1000 ms |
| 2 | No Wi-Fi | reddish orange | blink | 500 ms |
The user-selectable moods:
| ID | Mood | Colour(s) | Pattern | Period |
|---|---|---|---|---|
| 3 | Excited | bright yellow | breath | 1000 ms |
| 4 | Happy | rainbow (7 colours) | fade | 1000 ms |
| 5 | Sad | dark blue | breath | 3000 ms |
| 6 | Upset | dark red | breath | 1000 ms |
| 7 | Anxious | dark purple → purple → violet → red | breath alternate | 800 ms |
| 8 | Deep Breaths | dark green | breath | 8000 ms |
| 9 | Love | dark pink → pink → bright pink → light purple | fade | 1000 ms |
| 10 | Heepy | bright pink | blink | 800 ms |
| 11 | Hungry | dark brownish yellow | breath | 1000 ms |
| 12 | Tired | dark red ↔ dark orange | fade | 10000 ms |
| 13 | Working | warm orange | solid | — |
Patterns: solid, blink (on for the first half of the period), breath (dim → bright → dim),
alternate (hard switch between colours), fade (smooth cross-fade), and breath_alternate
(one breath per colour, advancing to the next each cycle).
To change moods, edit Utils/moods.yaml, then regenerate the firmware header
and re-flash:
cd /path/to/Mood-Lamppython3 Utils/generate_moods.pyBoth lamps must run the same mood table — IDs are what travel over the wire, so a lamp with an older table will render the wrong mood.
Parts
11| Qty | Value | Footprint | References |
|---|---|---|---|
| 2 | FIDUCIAL1X2 | FIDUCIAL-1X2 | FID1, FID2 |
| 2 | STAND-OFF | STAND-OFF | JP4, JP15 |
| 1 | CREATIVE_COMMONS | FRAME1 | |
| 1 | 0.1uF | 0603-CAP | C1 |
| 1 | INPUT | 1X03 | JP1 |
| 1 | OSHW-LOGOS | OSHW-LOGO-S | LOGO1 |
| 1 | OUTPUT | 1X03 | JP2 |
| 1 | SFE_LOGO_FLAME.1_INCH | SFE_LOGO_FLAME_.1 | LOGO2 |
| 1 | WS2812B | WS2812B | U1 |
More from Ryan-Jing/Mood-Lamp
1- 2 layers

Similar boards
- 4 layers99 × 53.3 mm

PSLab
fossasia/pslab-hardware
PSLab Hardware Design and Schematics https://pslab.io
199 parts1.7kApache-2.0 - 2 layers26 × 30 mm

Microcontroller
FrameworkComputer/ExpansionCards
Reference designs and documentation to create Expansion Cards for the Framework Laptop
34 parts1.1kCC-BY-4.0 - 4 layers82.6 × 82.5 mm

- 2 layers95.3 × 161.9 mm

- 2 layers42.8 × 28.8 mm

MM Skirt
PrintersForAnts/Micron
If you want to purchase full kits there are 3 available (Kits are slowly updating to R1 hardware just make sure to double check the included hardware in your kit and if you have any questions reach out in the discord)
11 parts741GPL-3.0 - 2 layers149.6 × 127.1 mm

- 2 layers285.5 × 95 mm

- 2 layers177.7 × 144.5 mm

Questions
How big is the Ws2812b Breakout v11 PCB?
It measures 17.8 × 12.7 mm and has 2 copper layers, 1.6 mm thick.
What parts does the Ws2812b Breakout v11 use?
11 parts, built around the WS2812B. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.
Where can I download the Ws2812b Breakout v11 KiCad files?
From the Ryan-Jing/Mood-Lamp repository on GitHub, at the commit this page was made from: the board is Mechanical/Components/13282/ws2812b_Breakout_v11/ws2812b_Breakout_v11.kicad_pcb and its schematic Electrical/Mood-Lamp-Electrical/Mood-Lamp-Electrical.kicad_sch. PCBKit opens the board in the browser, with nothing to install.
Can I use the Ws2812b Breakout v11 design in my own project?
Its repository states no licence, so its author keeps all rights: ask Ryan-Jing before reusing the design.