DIY Long-Distance Friendship Lamps

Vlad — Fri, 13 Nov 2026 14:35:33 +0000

I have a sister. I remember thinking, when I enrolled at university far away from home, that I had a lot of time while she was a little girl, so I had time to build a life for myself. Unfortunately, as often happens, I'm still working on my life, and she is a teenager now. At some point I felt like I screwed up our relationship. We live 900 km apart, so I cannot see her as often as I would like to. We keep in touch from time to time, but I think about her way more often than I text her. That's why I decided to build something to just quickly say "I'm thinking about you".

Friendship lamps are a thing you can buy. The pairs I looked at cost more than train tickets for a few visits. I work on Uniot, a platform for building solutions for SMEs (small and medium-sized enterprises), and it already does the one hard part: connecting devices without me hosting anything. So this time I used it for something personal, and made the lamps myself. Everything is on GitHub: the firmware, the scripts (also as blocks), the STL files, the OpenSCAD model, the diagrams and the photos.

How it works

It's a lamp first. A tap on the heart switches it on or off, in one of eight soft colors. Tap it off and straight back on, and it comes on in the next one.
Hold the heart for two seconds and both lamps fill with the same two colors, drifting into each other round the shade like ink in water, for ten minutes. Then they fade back to whatever each lamp was doing.
The next hold sends the next color. The old pair melts into a warm white glow and the new one seeps in, so you can see that the hug went out. While a hug is on, a tap does the same.
A button on the back says good night: the hug goes out on both lamps, and yours switches off.
WiFi trouble shows. While the ring is dark, one LED blinks green: slowly when the lamp waits to be set up, fast when it can't find its network.

Both lamps run the same firmware and the same script. The lamps talk through the platform's MQTT broker: there is no server of mine, no port forwarding and no app. The person at the other end needs a power socket and their WiFi password. And everything the lamp does, the animation included, is a short script that I can change from the browser while the lamp is 900 km away.

Supplies

For two lamps, with spares where parts are cheap or fragile.

Part	Qty	Notes
ESP32-C3 SuperMini (USB-C)	3	One spare. Look for at least 1 mm between the crystal can and the chip antenna: some 2024 batches have bad WiFi
WS2812B ring, 16 LEDs, 68 mm	2	Any 66-70 mm ring fits once you enter its size in the model
TTP223 touch module (small, 3 pins)	4	Occasionally dead on arrival
1N4007 diode	3
470 µF electrolytic capacitor, 8 mm diameter, 6.3-25 V	3	A 10 mm one doesn't fit the junction board
470 Ω resistor	2
Double-sided perfboard, 2.54 mm, 5 × 7 cm	1	Gives both junction boards
JST-XH sockets, through-hole	4 × 3-pin, 2 × 2-pin	Often sold as "XH2.54"
JST-XH leads, plug on one end, 19-20 cm	4 × 3-pin, 2 × 2-pin	Ready-made, no crimping
Tact switch 6 × 6 mm, 14 mm tall	3	Other heights work: enter yours in the model
Silicone wire 26 AWG, 6 colors, and bare tinned wire	~1.5 m, ~50 cm
Self-tapping screws 3 × 10 mm, countersunk	6
Self-adhesive bumper feet, Ø 10-12 mm	8
White PETG, 1.75 mm	~340 g	Every printed part, from one spool so the lamps match
USB charger, 5 V ≥ 1.5 A, and a USB-C cable	2

Tools: a 3D printer, soldering iron, flush cutters, wire stripper, multimeter, hot glue gun and a screwdriver.

Software: PlatformIO for the firmware, a slicer, and a browser. OpenSCAD and Python only if you change the model.

The two rolls of tape on the right, double-sided tape and copper tape for the touch module, were on my first parts list. The lamp needs neither, and I didn't use them.

How it goes together

Each lamp is three printed parts. The base carries everything: the LED ring lies in a pocket on its top deck, a groove around the ring holds the shade, the front has a flat panel with an engraved heart, and the back has a notch for the USB-C cable and a hole for the button. The shade is a hollow cup with a 0.8 mm wall, two printed lines, so it glows instead of showing sixteen dots. The bottom plate carries both boards and screws on from below, so the whole controller lifts out in one piece.

The circuit is small. The SuperMini's USB-C socket powers everything. Its 5V pin feeds the ring through a diode, which drops the supply to about 4.1 V so the board's 3.3 V data signal is read reliably, and a 470 µF capacitor steadies it. GPIO4 drives the ring's data line through 470 Ω. The TTP223 touch module reports on GPIO3, and the button pulls GPIO9 to ground, in parallel with the board's own BOOT button. The few extra parts sit on a small piece of perfboard, the junction board, and the ring, the touch module and the button each plug into it with a JST-XH lead.

Step 1: Print the casing

Print base.stl, bottom.stl and one of the three shades for each lamp. They're in the repository's hardware/stl folder, already in print orientation. I used white PETG for everything: the deck under the LEDs gets warm, and PETG keeps its shape where PLA would start to soften.

Part	File	Mass
Base, printed upside down	`base.stl`	≤ 86 g
Bottom plate	`bottom.stl`	≤ 35 g
Shade, printed upside down	`shade_twist.stl`, `shade_smooth.stl` or `shade_ribs.stl`	44-46 g

Base and plate: 0.2 mm layers, 6 walls (the 1.2 mm skin behind the heart has to print solid), 15 % infill, no supports, elephant foot compensation 0.15 mm so the shade's groove stays open, Z seam at the back. Shade: the normal mode, not spiral vase: the file is already hollow, with a wall of exactly two 0.4 mm lines. Use 2 walls, 0 % infill and no supports. The hardware README has the rest, with each slicer's menu names.

Your parts measure differently? The model is parametric OpenSCAD. If your ring, board, switch or cable plug differ from mine, measure them and export again with your numbers, for example ./build.sh -D ring_od=67.6 -D usb_over=1.6. It refuses to export if a part would collide or a design rule breaks. The key dimensions list what each number is.

Step 2: Wire the circuit

Step 3: Assemble the lamp

Ring. Push the ring's plug down through the slot in the deck, lay the ring in its pocket with the LEDs up, and fix it with a thin bead of hot glue along its inner edge.

Touch. Hot-glue the TTP223 flat against the inside of the heart, pad side (the side without components) to the plastic, with no air gap. I first tried a copper-tape electrode behind the heart, and it made the pad so sensitive that the lamp reacted to a hand a few centimetres away. The bare module through 1.2 mm of PETG is just right.

Button. Push the tact switch into its pocket from inside until the plunger stands out of the back wall. Check that it clicks, then glue it.

Plate. Press the junction board into its holder, sockets towards the plate's flat front edge, and the SuperMini into its cradle, USB-C towards the tongue. Fix each with a dot of hot glue, never at the SuperMini's antenna end.

Close. Plug the three leads in, lay the link wires along the right wall and the button lead along the left one, with nothing over the antenna end, and screw the plate on: its three holes line up one way only. Stick on four feet.

Shade. Set it into the groove without glue for now. It gets glued once the lamp works, in Step 7.

Step 4: Create an account

Both lamps live on one account. Open app.uniot.io, choose Create Account, enter an email and a password, and confirm the email. The free plan takes three devices, so a pair fits.

Then log in, open the Devices page and click Add new device. The window shows your Account ID with a Copy button; the My Account page has it too. The firmware needs it in the next step: it is how a new board finds its way into your account.

Step 5: Upload the firmware

The firmware is the PlatformIO project in firmware/lamp. Open it in VS Code with the PlatformIO extension, or use the command line, and change three things.

In platformio.ini, replace my VLDBLKHN with a short name of yours. The web app shows it as the device's Creator on its General tab:

-D UNIOT_CREATOR_ID=\"VLDBLKHN\"

In src/main.cpp, your WiFi network (2.4 GHz) and the Account ID from Step 4:

Uniot.configWiFiCredentials("YourSSID", "YourPassword");
Uniot.configUser("your_account_id");

For lamp B, the one that travels, comment out the configWiFiCredentials line. Without WiFi settings, the lamp opens its own setup hotspot, so it can join whatever network it ends up near. Then upload, with the lamp connected by its USB-C cable:

cd firmware/lamp
pio run -e esp32c3_supermini --target upload

If no serial port appears, hold the back button while you plug the lamp in: it is wired to the board's BOOT button. Upload, then unplug the lamp and plug it in again. Until the lamp is online, one ring LED blinks green, which also tells you the ring is wired right.

The firmware knows nothing about hugs or colors. It adds three words to the board's script language: glow_led paints one LED, glow paints the whole ring, and bheld says a button was held rather than tapped. The heart is button 1 and the back button is button 0.

Step 6: Authorize the lamps

Once lamp A is online, it shows up on the Devices page under Unauthorized. Click Authorize, give it a name (I called mine Lamp (Me)) and Confirm. Open it and look at the Primitives tab: glow, glow_led and bheld are listed. The lamp reported them when it connected, and the Sandbox builds its blocks from that list.

Lamp B has no WiFi yet, so it opens a hotspot named UNIOT- and a few characters, and one LED blinks green, slowly. Join it from your phone, pick your own network for now, type its password, leave New Account ID empty and save. Then authorize it too: mine is Lamp (Sister).

Step 7: Deploy the script

On Uniot, what a device does is a script, not firmware. Scripts are written in UniotLisp, a small Lisp that runs on the board, either as text or as blocks in the web app's Sandbox, which turn into the same Lisp. Deploying sends the script to the device over MQTT. The device stores it and runs it from then on, and you can replace it from the browser at any time, even after the lamp has shipped.

The lamp script is scripts/lamp.lisp. Twenty times a second it:

reads the heart and the button. A tap switches the lamp. A hold publishes the event hug with the next color number, 1 to 8. The back button publishes hug 0.
listens for hug from either lamp; its own comes back too, which does no harm. A number shows that color pair for ten minutes, and 0 puts the hug out.
ends its own hugs. The broker keeps the last value of every event for devices that connect later, which is how a lamp that reboots mid-hug lights up again. So when the countdown runs out, the lamp publishes hug 0 itself. Otherwise a lamp that reboots tomorrow would replay yesterday's hug.
paints every LED itself. Two waves run round the ring in opposite directions and mix the hug's color with its partner, three colors further round the palette. The firmware only puts on the ring what the script paints.

The colors, the flow speed and the hug length are plain numbers at the top of the script. The repository's README explains each one.

I built the script as blocks:

If you'd rather read blocks than Lisp, the repository has the whole script as blocks, drawn as the Sandbox draws them.

There's no way to import blocks yet, so paste the text instead. In the Sandbox, click New Script, flip the editor switch from Blockly to Advanced, paste lamp.lisp, and press Compile (Ctrl+B). Then press the Deploy button and pick Lamp (Me). Deploy it again and pick Lamp (Sister).

Now hold one heart for two seconds. Amber and purple seep into the ring under your finger, and a moment later into the other lamp too. Hold it again for coral and blue, and press the back button to say good night.

Once both lamps work, glue the shades: six pea-sized dots of hot glue in the groove, then push the shade all the way in with a slight twist. Work quickly, because the glue sets in seconds.

This article was drafted with AI assistance, and so were the enclosure model, the circuit layout and the firmware. The build, the tests and the photos are mine.

DEV Community: Vlad