Skip to the content
2 layers144 × 71 mmHue simple switch mains panel, the printed circuit board in 3D

Hue simple switch mains panel

tineira/hue-simple-switch

Wi-Fi wall switch for Philips Hue on a Seeed XIAO ESP32-C6, wired to a toggle switch or push buttons. Controls the Hue Bridge over its local API (not Zigbee).

Size
144 × 71 mm
Copper layers
2
Thickness
1.6 mm
Parts
163
Nets
72
Pads
298
Tracks, vias
294, 81
Pours
9
Routed
Yes
KiCad
KiCad 10.0 (file 20260206)
Created
19 Sep 2026
Updated
1 Nov 2026

Overview

Hue simple switch mains panel is an open-source printed circuit board by tineira, from the tineira/hue-simple-switch repository on GitHub, published under the MIT licence. It is a 2-layer board of 144 × 71 mm with 163 parts on 72 nets, routed with 294 tracks and 81 vias.

It is built around the HLK-PM01, 0603B103K500NT and CL21A226MAQNNNE, with the SS34 among its other parts. Its parts include 36 resistors, 24 capacitors, 9 connectors, 3 ICs and 3 diodes. It belongs with the home automation and IoT and radio and wireless boards and the ESP32 and RISC-V boards of this library.

Main components

4

README

README.md

hue-simple-switch

Wi‑Fi wall switch for the Seeed XIAO ESP32-C6. Calls the Hue Bridge's local Clip v2 API (HTTPS). Not Zigbee.

GPIO channels (closed = pin to GND, INPUT_PULLUP):

idGPIOdefault kindlabel
boot9momentaryBOOT
d00maintainedD0
d11maintainedD1
d22maintainedD2
d321noneD3
d422noneD4
d523noneD5

D3–D5 (GPIO 21–23) are channels since 0.5.0, so one board takes up to six wall switches or buttons on D0–D5, plus BOOT. None of D3–D5 is a strapping pin, and this firmware has no I2C on D4/D5. D6–D10 stay unused (D6 is the chip's serial TX at boot).

Since 0.3.0 the console picks each channel's kind (maintained = toggle switch, momentary = push button) and sends it in the config's channels[]; a pin it does not list does nothing. BOOT is always a push button. The default kinds above apply only to the old config payload (no channels[]), from a console that predates channel types; there D3–D5 do nothing, so an unwired pin never acts.

Each channel has recipes per event, derived by the console:

  • Toggle switch, flip set (the lever sets on or off; no flip in channels[]): on (lever closes), off (lever opens, after the ~400 ms double-click window), double_click (opens and closes inside the window; runs on when there is no double_click recipe).
  • Toggle switch, flip toggle ("flip": "toggle", since 0.8.0; each flip toggles, the console sends toggle for both on and off): each flip posts on (lever closes) or off (lever opens) at once when there is no double_click recipe. With one, a flip either way waits ~400 ms: a second flip inside it is double_click, otherwise the first flip runs. No on fallback. A toggle that turned the lights off restarts the scene list. Boot, a config change or a change of the flip setting never toggles.
  • Push button: short on release, at once when the channel has no double_click recipe; with one, a second press inside ~400 ms is double_click and an expired window is short. hold fires once at ~800 ms while pressed, only when the channel has a hold recipe.
  • BOOT without a hold recipe: a 3 s press re-pairs with the Bridge. With one, the button never re-pairs (USB install only).
  • A scene list (recall_scene with targets[]) cycles from the last scene the channel set (kept in NVS), wraps, skips scenes that answer 404, and starts over at the first scene after an off on the channel (in flip toggle mode, after a toggle that turned the target off).

The GPIO runs NVS → Bridge; it doesn't wait for Vercel. Since 0.5.0 the config is stored as one NVS blob per channel, so saving the largest config (seven channels with scene lists) needs only one channel's worth of free space; the first boot after the update converts the older single blob.

Wiring for up to six wall switches or buttons on D0–D5: docs/wiring-switches.svg. Wire only the inputs you use. The step-by-step build guide (what to buy, wiring one input at a time, what never to connect, and when you need the resistors) is at hue.tineira.com/how-to.

To power the switch from the mains inside a wall box, behind the existing switch, there is a carrier board design (KiCad) and a printable enclosure in hardware/. It keeps the same pins and firmware. Do not build it: the current board has a known isolation defect, its order files are withdrawn and a revised board is pending. It is an uncertified, experimental mains design: read its safety notes.

[!WARNING] Safety. Mains voltage can kill. The designs in this repository are uncertified and some are unproven, and the maintainer is not an electrical engineer. Rules and wire colors differ by country. Read the Safety notice before you build anything, and never connect any pin of a USB-powered build to anything that is or was on mains. Everything here is provided as is, without warranty, as the licenses say.

BOOT (GPIO9) and RST (CHIP_PU) are buttons, not LEDs. The board has two lights:

The orange LED's alphabet (firmware 0.2.7 and later) is below. Design history: docs/archive/specs/led-status.md.

LightWhereDriven by
Orange (user, GPIO15 LED_BUILTIN)Right side, next to RSTThis firmware
Red (charging)Next to the USB-CThe charger hardware; the sketch doesn't touch it

Orange LED (firmware)

One pattern at a time, top to bottom. When the step changes, the burst starts from zero. LOW on GPIO15 turns the orange on (active low).

What you seeMeaning
Solid onSystem error: the console task wasn't created, or the console answered 401. The 401 stays solid until a response with a code other than 401, or a new HUESET token. Wins even without Wi‑Fi.
Continuous blink ~2 Hz (250 ms on / 250 ms off)No Wi‑Fi STA, or Improv scan. Even with a saved SSID.
2 flashes and a pauseWi‑Fi ok, no console (URL or token empty, or a your-… placeholder).
3 flashes and a pauseWi‑Fi and console, Hue not paired, or pairing in progress / timed out. Holding BOOT 3 s (re-pair) uses this pattern.
4 flashes and a pauseWi‑Fi, console and Hue, no recipes.
One short flash every ~3 sArmed: one or more recipes.

Burst (#2–#4): 100 ms on, 200 ms between flashes, 1400 ms pause. The armed flash lasts 80 ms and repeats every 3 s.

Red LED (charging, not the sketch)

What you seeMeaning
On for ~30 s when USB is plugged in without a batteryUSB present; then it turns off.
BlinkingLiPo battery connected and charging over USB.
Off with USB and batteryCharge complete (or no charge cycle).

Contract: hue-switch-console/docs/definitions.md, docs/device-api.md and docs/usb-protocol.md.

Setup

  1. Flash and provision from Chrome on hue.tineira.com → Devices (USB). Improv saves the 2.4 GHz network and HUESET stores the token (hsw_…) and url in NVS console. None of that is compiled in. For development, copy config.example.h to config.h (only SERIAL_DEBUG); arduino-cli upload doesn't erase NVS, so the network and token survive every flash.
  2. The XIAO discovers the Bridge (mDNS _hue._tcp, NVS, discovery.meethue.com) and pairs the Hue key (three orange flashes → Bridge button). IP and key stay in NVS, not in config.h.
  3. Register: POST /api/device/register with product: "simple", MAC, channels[] and snapshot (lights/rooms/scenes). Poll: GET /api/device/config?mac=&rev=&firmware= at boot, then every X-Poll-Sec seconds from the console (clamped 30 s to 1 h; 204 = unchanged, keep NVS), once more right after a new rev is saved, and 1 h after a 401. Without the header (older console): ~1 min without recipes, 1 h with some. With recipes, register (topology) at most hourly.
  4. Arduino IDE 2.3.10: open hue-simple-switch.ino, board XIAO_ESP32C6.
  5. Or arduino-cli: arduino-cli compile --profile xiao-c6 .

List lamps (diagnostics):

text
curl -k -H "hue-application-key: KEY" https://BRIDGE_IP/clip/v2/resource/light

config.h is not committed. Product onboarding = the USB installer on hue.tineira.com.

Release

A push to main is a release. .github/workflows/firmware.yml builds the product image and uploads it to the console (hue.tineira.com) with this version's CHANGELOG.md entry as release notes. The console's USB installer then offers that build to every Simple plugged in over USB, and since 0.6.0 the owner can send it over Wi-Fi from the Switches page (below). The workflow also keeps the usb-installer GitHub Release as a download link. Pushes that change only docs or the board design (*.md, docs/, hardware/) do not run it, except CHANGELOG.md, which re-sends the notes. To skip any other push, put [skip ci] in its commit message.

  • FIRMWARE_VERSION in console.h is the version the console shows. Bump it for any change a board should pick up, and add its entry to CHANGELOG.md in the same commit. A push without a bump re-sends the notes only (409 version_exists warning).
  • THIRD_PARTY.json lists the open-source components linked into the image (the core, ESP-IDF, and every library pinned in sketch.yaml), with version, SPDX license and a link to the license at that version. CI sends it as the release credits for the console's Credits page, and fails if any platform: or libraries: entry in sketch.yaml is missing from it or has a different version (scripts/check-credits.py, run on every pull request too). Update it in the same commit as any core or library bump.
  • Update over Wi-Fi (0.6.0+; wire: console docs/device-api.md, design history: console docs/archive/specs/ota.md): when the owner presses Update, the next poll's 200 carries ota (version, path, sha256, size). After the poll's connection is closed, the console task downloads firmware.bin from the console URL in NVS, writes it to the inactive app slot while hashing it, checks length and sha256, and restarts into it. It waits for the next poll while an input is pressed or a Hue call is queued or running. The new image confirms itself after its first 200/204 poll; a restart before that makes the bootloader go back to the old one, which reports ota_error=boot. A failure is reported once as ota_error and retried at most hourly (a download cut off by a power cut or restart counts, reported as size at the next boot, since 0.6.1) (size/sha from a bad image: not until reboot). NVS is never erased. Boards before 0.6.0 need one USB update first.
  • Image layout and offsets: docs/firmware-artifacts.md.
  • The pipeline needs the FIRMWARE_UPLOAD_TOKEN secret in this repo. Setup and troubleshooting: the console repo's README.md, "Firmware release pipeline".

Build and upload from a fork

A fork builds the same image on every push to its main, and can upload it to your own console instead of hue.tineira.com (self-hosting: the console repo's docs/self-hosting.md).

  • Build only (default). With no FIRMWARE_UPLOAD_TOKEN secret, the workflow builds, skips the upload with a notice and stays green. The four installer parts are in the run's usb-installer-simple artifact and in the fork's usb-installer GitHub Release.
  • Upload to your console. In the fork's Settings → Secrets and variables → Actions:
    1. Add the repository variable CONSOLE_UPLOAD_URL with your console's origin, for example https://hue.example.com (no path, no trailing slash). Without it, the upload goes to https://hue.tineira.com, which rejects a fork's token.
    2. Add the repository secret FIRMWARE_UPLOAD_TOKEN with the value of FIRMWARE_UPLOAD_TOKEN on your console.
    3. Push to main (or run the workflow by hand). The release waits in your console's /admin until you make it current; Setup then flashes it.
  • Bump FIRMWARE_VERSION in console.h and add its CHANGELOG.md entry for each build you want boards to get, as above: your console keeps the first bins it received for a version.

Contributing

See CONTRIBUTING.md. Bugs and ideas go in GitHub issues.

Sponsor

The console and the switch firmwares are free and stay that way. If they are useful to you, you can sponsor the project on GitHub. Sponsorship helps pay for development and does not unlock anything.

License

Copyright (c) 2026 Tomas Neira and contributors. MIT, except the carrier board and enclosure designs in hardware/, which are CERN-OHL-P-2.0 (see hardware/README.md).

The image also links open-source components under their own licenses, listed in THIRD_PARTY.json. The Arduino-ESP32 core is LGPL-2.1-or-later: because this firmware's source is public, you can rebuild it against a modified core.

The console this firmware talks to, hue-switch-console, is AGPL-3.0; it also holds the device contract (docs/device-api.md).

Not affiliated with or endorsed by Signify. Philips Hue is a trademark of Signify.

Parts

163
QtyValueFootprintReferences
76MB1, MB2, MB10, MB11, MB12, MB13, MB14, MB15, MB16, MB17, MB18, MB19, MB20, MB21, MB22, MB23 +60
1810kResistor_SMD:R_0603_1608MetricR1, R1, R1, R2, R2, R2, R3, R3, R3, R4, R4, R4, R5, R5, R5, R6 +2
1810nFCapacitor_SMD:C_0603_1608MetricC11, C11, C11, C12, C12, C12, C13, C13, C13, C14, C14, C14, C15, C15, C15, C16 +2
181kResistor_SMD:R_0603_1608MetricR11, R11, R11, R12, R12, R12, R13, R13, R13, R14, R14, R14, R15, R15, R15, R16 +2
622uF 25VCapacitor_SMD:C_0805_2012MetricC1, C1, C1, C2, C2, C2
3275VAChue:RV_TDK_SIOV_CU3225RV1, RV1, RV1
3D0 D1 D2 D3hue:TerminalBlock_Xinlaiya_XY350V-3.5_1x04J2, J2, J2
3D4 D5 GNDhue:TerminalBlock_Kefa_KF350-3.5_1x03J3, J3, J3
3Fiducial_1mm_Mask2mmFiducial_1mm_Mask2mmFID1, FID2, FID3
3HLK-PM01hue:HiLink_HLK-PM01PS1, PS1, PS1
3MAINS L/Nhue:TerminalBlock_Kefa_KF128-5.08_1x02J1, J1, J1
3SS34Diode_SMD:D_SMAD1, D1, D1
3T500mA 250VFuse:Fuse_Littelfuse_372_D8.50mmF1, F1, F1
3XIAO ESP32-C6XIAO:XIAO-ESP32-C6-SMD-EdgePadsU1, U1, U1

More from tineira/hue-simple-switch

3
  • 2 layers70 × 88.9 mmV2-fit panel, the printed circuit board in 3D

    V2-fit panel

    tineira/hue-simple-switch

    Wi-Fi wall switch for Philips Hue on a Seeed XIAO ESP32-C6, wired to a toggle switch or push buttons. Controls the Hue Bridge over its local API (not Zigbee).

    145 partsMIT
  • 2 layers42 × 52 mmHue simple switch mains, the printed circuit board in 3D

    Hue simple switch mains

    tineira/hue-simple-switch

    Wi-Fi wall switch for Philips Hue on a Seeed XIAO ESP32-C6, wired to a toggle switch or push buttons. Controls the Hue Bridge over its local API (not Zigbee).

    28 partsMIT
  • 2 layers37.9 × 23.6 mmV2-fit, the printed circuit board in 3D

    V2-fit

    tineira/hue-simple-switch

    Wi-Fi wall switch for Philips Hue on a Seeed XIAO ESP32-C6, wired to a toggle switch or push buttons. Controls the Hue Bridge over its local API (not Zigbee).

    24 partsMIT

Similar boards

  • 2 layers100 × 100 mmHour meter board microfit can handroute, the printed circuit board in 3D

    Hour meter board microfit can handroute

    ilomon10/embedded-totalizer-hour-meter

    ESP32 engine hour meter & totalizer: firmware, SensorFrame protocol, Node host tools, KiCad PCB and a Deno device simulator

    152 parts
  • 6 layers72.4 × 115 mmFujiNet-7800-Rev0, the printed circuit board in 3D

    FujiNet-7800-Rev0

    FujiNetWIFI/fujinet-hardware

    Schematics and design files for FujiNet hardware

    135 parts142
  • 4 layers65 × 45 mmLora gps tracker rev a, the printed circuit board in 3D

    Lora gps tracker rev a

    bogdan-kovalchuk/esp32-lora-gps-tracker

    Encrypted point-to-point GPS telemetry over 433 MHz LoRa between two ESP32 boards.

    69 partsMIT
  • 4 layers90 × 66 mmIron node, the printed circuit board in 3D

    Iron node

    enkhbold470/iron-node

    ESP32-S3 industrial gateway: W5500 Ethernet, isolated RS-485 (ADM2587E), CAN, 9-36 V input. 4-layer KiCad 10 board.

    83 partsCERN-OHL-S-2.0
  • 4 layers100 × 80 mmPd brick, the printed circuit board in 3D

    Pd brick

    enkhbold470/pd-brick

    USB-C Power Delivery bench supply: STUSB4500 sink, LM5176 buck-boost, INA228 monitor, 1.2-22 V set over I2C by an ESP32-S3. 4-layer KiCad 10 board.

    120 partsCERN-OHL-S-2.0
  • 4 layers100 × 90 mmOpentouch s3, the printed circuit board in 3D

    Opentouch s3

    JoeMighty/opentouch-s3

    A modern remake of the Bare Conductive Touch Board: 12 capacitive touch electrodes, MP3/WAV/MIDI audio, and now WiFi, Bluetooth LE, USB-C, a proper LiPo power path, a fuel gauge, line-in, MIDI out, Qwiic and an RGB LED.

    185 parts
  • 2 layers100 × 92 mmBase station, the printed circuit board in 3D

    Base station

    yeyintlwin/kicad-board-design

    Design a two-layer KiCad PCB entirely from Python scripts - no GUI step, no commercial autorouter

    69 partsMIT
  • 4 layers30 × 48 mmEsp32 mpu6000, the printed circuit board in 3D

    Esp32 mpu6000

    HeyPCB/esp32-sensors-2

    ESP32-S3 boards, one sensor each: KiCad 10, JLCPCB-ready, CERN-OHL-S-2.0

    26 partsCERN-OHL-S-2.0

Questions

How big is the Hue simple switch mains panel PCB?

It measures 144 × 71 mm and has 2 copper layers, 1.6 mm thick.

What parts does the Hue simple switch mains panel use?

163 parts, built around the HLK-PM01, 0603B103K500NT, CL21A226MAQNNNE and SS34. 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 Hue simple switch mains panel KiCad files?

From the tineira/hue-simple-switch repository on GitHub, at the commit this page was made from: the board is hardware/kicad/hue-simple-switch-mains-panel.kicad_pcb and its schematic hardware/kicad/hue-simple-switch-mains.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the Hue simple switch mains panel design in my own project?

Its repository publishes it under the MIT licence: you may reuse it on that licence's terms (keep the author's notice, and for a copyleft licence share your changes alike).