Hue switch console
Sign in

How-to

Build a switch, set it up, change what it does, and read what it's telling you. Pick your switch to start.

Build a Simple switch

Build one with no wiring at all or as a button box: what to buy, how to wire it, and whether you need resistors. The in-wall board is withdrawn until a revised board is ready.

Built by the maintainerBuilt and in use by the maintainer, one installation.

Low voltage only. Never connect any pin to anything that is or was on mains.

What to buy

  • 1Seeed XIAO ESP32-C6seeedstudio.com ↗

    With or without pre-soldered headers. Headers let you use jumper wires instead of soldering.

  • 2Switches or push buttons, up to six

    Any plain contact: sold as dry contact or "no light". Wall switches, arcade buttons, tact switches.

  • 3Hook-up wireYou may have it

    Any thin insulated wire. Never wire that is, or was, part of your home's mains wiring.

  • A soldering iron, or jumper wiresYou may have it

    To attach wires to the board's pads. On a XIAO with headers, female jumper wires push on instead.

  • 410 kΩ, 1 kΩ, 10 nF per inputOptional

    Only for long wires. Two resistors (1/4 W through-hole, any tolerance) and one ceramic capacitor for each input. See Do I need resistors?

  • A box and a USB-C phone chargerYou may have it

    Any project box that fits the board and the wires.

Never

  • Connect a pin to anything that is, or ever was, connected to mains (220 V or 120 V). That includes the wires of an existing wall switch until an electrician has taken them off mains at both ends.
  • Connect a pin to 5 V or any other supply. The pins take 3.3 V at most.
  • Run the 3V3 pin out to the switches. It only feeds the pull-up resistors, on the board side.
  • Use illuminated switches (neon or LED pilot light) or smart switches. They have electronics across the contacts, so the board sees them as always pressed or never pressed.

How an input works

Each of D0 to D5 reads one contact. One side of the switch goes to its pin, the other side to GND. Closed means pressed, or on. The board doesn't know what's on a pin until you tell it on Switches: Wall switch (stays on or off) or Push button (press and release).

Two switches for one lamp (a staircase or hallway pair, also called two-way or 3-way): put one board in each switch housing. On Switches, set each input to Wall switch with Flip on Each flip toggles the lights, and pick the same room or zone on both. Either switch then turns the lights on or off, whichever way its lever sits. An old 3-way switch is wired as a plain contact: its common terminal plus one of the other two.

Wire it, one input at a time

Finish and test each input before you start the next, so a mistake shows up on the first wire, not the sixth.

  1. 1

    Set up the board on its own

    Follow Set up a Simple switch below with nothing wired. A board that works bare rules out the board if something goes wrong later.

  2. 2

    Test with BOOT

    Give BOOT a room on Switches and press it: the small button next to the USB-C port. The lights react: the board, Wi-Fi, the Bridge and the console all work.

  3. 3

    Attach the first two wires

    Unplug USB. Solder one wire to D0 and one to GND, or, if your board has headers, use female jumper wires. With the USB-C port at the top and the chip facing you, D0 is the top pad on the left and GND is the second pad on the right.

  4. 4

    Connect the first switch

    One wire to each of its two terminals. Which wire goes on which terminal doesn't matter. A four-leg tact switch has its legs joined in pairs inside: use two diagonally opposite legs.

  5. 5

    Set up the input

    Plug USB back in. On Switches, click Add a switch, or the D0 pad on the board picture, and answer its three questions: what you wired (Wall switch or Push button), the pin (D0), and the room. Click Save changes, then unplug and replug the board so it picks the change up now.

  6. 6

    Test it

    Press or flip it: the lights react. If they don't: check the wire is on D0 and not D1, that the input is saved as D0, and that it isn't an illuminated switch.

  7. 7

    Repeat for each input, one at a time

    D1 to D5, testing each before the next. Every switch's second terminal goes to the same GND: run one wire from switch to switch, soldered at each, and on to GND on the board. A lever connector or a terminal strip works too.

  8. 8

    Long wires? Add the resistors

    Per input, at the board: 10 kΩ from the pin to 3V3, 1 kΩ in series between the pin and the wire, and 10 nF from the wire side of the 1 kΩ to GND. Skip this for wires under about 30 cm. The 10 kΩ can go on the back of the board too. With several inputs, join the 10 kΩ ends first and bring one lead to the 3V3 pad.

  9. 9

    Close it up

    The XIAO into a project box, the buttons in its lid, the USB-C cable out through a slot in the side to a phone charger. Press every switch once more.

Do I need resistors?

Short wires (on a desk, in a small box, under about 30 cm): no. The firmware turns on the chip's own pull-up resistor and ignores contact bounce shorter than 50 ms. A switch straight between a pin and GND works.

Long wires (metres, or next to mains cables in a wall): yes. Per input: a 10 kΩ pull-up from the pin to 3V3, a 1 kΩ resistor in series between the pin and the wire, and a 10 nF capacitor from the wire side of the 1 kΩ to GND. These are the values on our in-wall board.

What goes wrong without them on long wires. The chip's own pull-up is weak (tens of kΩ). A long wire picks up noise from the mains cables next to it, and the lights switch by themselves: ghost presses. A static spark from touching a switch can reach the pin and damage the chip. The 10 kΩ makes the input stiffer, the 1 kΩ limits the current of a spike, and the 10 nF sends fast noise to GND.