Skip to the content
2 layers17.8 × 12.7 mmWs2812b Breakout v11, the printed circuit board in 3D

Ws2812b Breakout v11

Ryan-Jing/Mood-Lamp

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

1

README

README.md

Mood-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). See Firmware/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. See Utils/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.

bash
cd Firmware
bash
cp include/secrets.example.h include/secrets.h

Open 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:

bash
pio run -e seeed_xiao_esp32c3 -t upload

Do 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:

LEDMeaningWhat to do
Cyan blinkBLE provisioning — no Wi-Fi credentials savedGo to step 3
Warm-white breathConnected, peer hasn't set a mood yetNothing, it's ready
Animated mood colourConnected, showing the peer's moodNothing, it's ready
Orange blinkWi-Fi problemRe-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.

bash
cd /path/to/Mood-Lamp
bash
python3 -m venv .venv
bash
source .venv/bin/activate
bash
pip install bleak
bash
python3 Utils/provision.py

The script prompts for the network name and password, finds the lamp advertising as MoodLamp, and writes the credentials over BLE:

text
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: connecting

The 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.py lists 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.

GestureWhat it does
Half tapOnly in mood-select mode: step to the next mood
Full tapEnter mood-select mode → then confirm the mood and send it to your peer
Full press, hold 5 sTurn BLE provisioning on (or off if it's already on)
Full press, hold 10 sErase the saved Wi-Fi credentials and reopen BLE provisioning

To set your mood:

  1. 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.)
  2. Half tap repeatedly until the LED shows the mood you want. It wraps around from Working back to Excited.
  3. 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):

IDMoodColourPatternPeriod
0Idle / defaultsoft warm whitebreath6000 ms
1BLE provisioningcyanblink1000 ms
2No Wi-Fireddish orangeblink500 ms

The user-selectable moods:

IDMoodColour(s)PatternPeriod
3Excitedbright yellowbreath1000 ms
4Happyrainbow (7 colours)fade1000 ms
5Saddark bluebreath3000 ms
6Upsetdark redbreath1000 ms
7Anxiousdark purple → purple → violet → redbreath alternate800 ms
8Deep Breathsdark greenbreath8000 ms
9Lovedark pink → pink → bright pink → light purplefade1000 ms
10Heepybright pinkblink800 ms
11Hungrydark brownish yellowbreath1000 ms
12Tireddark red ↔ dark orangefade10000 ms
13Workingwarm orangesolid—

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:

bash
cd /path/to/Mood-Lamp
bash
python3 Utils/generate_moods.py

Both 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
QtyValueFootprintReferences
2FIDUCIAL1X2FIDUCIAL-1X2FID1, FID2
2STAND-OFFSTAND-OFFJP4, JP15
1CREATIVE_COMMONSFRAME1
10.1uF0603-CAPC1
1INPUT1X03JP1
1OSHW-LOGOSOSHW-LOGO-SLOGO1
1OUTPUT1X03JP2
1SFE_LOGO_FLAME.1_INCHSFE_LOGO_FLAME_.1LOGO2
1WS2812BWS2812BU1

More from Ryan-Jing/Mood-Lamp

1

Similar boards

  • 4 layers99 × 53.3 mmPSLab, the printed circuit board in 3D

    PSLab

    fossasia/pslab-hardware

    PSLab Hardware Design and Schematics https://pslab.io

    199 parts1.7kApache-2.0
  • 2 layers26 × 30 mmMicrocontroller, the printed circuit board in 3D

    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 mmJumperless2, the printed circuit board in 3D

    Jumperless2

    Architeuthis-Flux/Jumperless

    A jumperless breadboard

    208 parts914
  • 2 layers95.3 × 161.9 mmDfh badge, the printed circuit board in 3D

    Dfh badge

    tanaes/whopping_Voron_mods

    135 parts787GPL-3.0
  • 2 layers42.8 × 28.8 mmMM Skirt, the printed circuit board in 3D

    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 mmErgodash, the printed circuit board in 3D

    Ergodash

    omkbd/ErgoDash

    keyboard

    187 parts732MIT
  • 2 layers285.5 × 95 mmReviung46 ver1 1, the printed circuit board in 3D

    Reviung46 ver1 1

    gtips/reviung

    The REVIUNG41 is 41-key column staggered keyboard.

    119 parts517MIT
  • 2 layers177.7 × 144.5 mmCOMM PANEL, the printed circuit board in 3D

    COMM PANEL

    jrsteensen/OpenHornet

    OpenHornet 1:1 F/A-18C Simulator Repository

    275 parts431

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.