Frequently Asked Questions

Each lamp needs an ESP32 dev board, a TTP223 touch sensor, a 3D-printed enclosure (files provided), and a USB-C cable for power.

For the lights, you choose one of two options:
PCB: A custom 100mm PCB with through-hole RGB LEDs, transistors, and resistors.
NeoPixel: A WS2812B ring (up to 16 LEDs, 66mm) — just 3 wires to the ESP32.

Both options produce nearly identical lamps. The full parts list with download links is in the Setup Guide.

Yes! Any Linked Lamp can connect to any other Linked Lamp, regardless of which lighting method was used. One person can build a PCB version and the other can build a NeoPixel version — they'll work together perfectly.

This usually means the ESP32 doesn't have your config.json settings yet.

Browser flash (Chrome/Edge): The config is sent automatically — check the log output for a "✓ Done" confirmation. If it shows a warning, try re-flashing.

PlatformIO: Make sure you ran "Upload Filesystem Image" in addition to the regular Upload. This pushes your data/config.json into the ESP32's storage. Restart the lamp after uploading.

If you connect your ESP32 via USB but it doesn't appear in the serial port list (in the browser popup, Device Manager, or PlatformIO), try these steps:

1. Make sure you're using a data transfer cable.
Many USB cables (especially short ones bundled with power banks or chargers) are charge-only and do not carry data. If your cable charges the board but doesn't show a serial port, swap it for a known data-capable USB cable. Data cables are usually slightly thicker and are often labeled "data" or "sync."

2. Install the correct USB-to-Serial drivers.
Most ESP32 dev boards use either a CP2102 or CP2104 USB-to-UART bridge chip made by Silicon Labs. Your operating system may not include these drivers by default.

To install the drivers:
• Go to the Silicon Labs CP210x VCP Drivers page.
• Download the driver for your operating system (Windows, macOS, or Linux).
• Run the installer and follow the on-screen prompts.
• Restart your computer after installation.
• Reconnect your ESP32 via USB. It should now appear as a COM port (Windows) or /dev/ttyUSB0 (Linux/macOS).

After completing both steps, the ESP32 should show up in the serial port picker when you click "Connect & Flash" on the setup page.

Updates are delivered over-the-air (OTA). Open your personalized Web App, go to Settings, and tap "Check for Update". The lamp downloads the correct firmware from the public repository and reboots itself — no computer needed.

Not particularly. If you use Google Chrome or Microsoft Edge, the Setup Guide flashes firmware directly from your browser — no coding or command line needed. Each lamp takes less than 30 minutes to build.

For other browsers, you'll need VS Code with PlatformIO, but the guide walks you through every step.

No, you don't have to pay. The Linked Lamp system requires an MQTT broker to pass messages between lamps, but any broker that supports TLS encryption on port 8883 will work.

Recommended Free Options:
• HiveMQ Cloud: The "Serverless Multi-tenant" free tier provides more than enough bandwidth.
• Adafruit IO: Excellent real-time broker but limits free accounts to 10 "feeds". Each lamp takes up 4 feeds, so a pair fits perfectly under the limit.
• Eclipse Mosquitto: Open-source broker for power users. Note: The Web Dashboard requires secure WebSocket (WSS) support. If you self-host Mosquitto, ensure you bind WSS correctly. The dashboard connects to 8884 by default, but you can override this by appending your custom WSS port directly to the Broker URL during setup (e.g., mqtt.mydomain.com:8081). The firmware will still intelligently use the standard TLS port (8883) while providing the custom port to the dashboard.

Please note: Cloud brokers like HiveMQ and Adafruit IO are third-party proprietary software. They are subject to change their pricing or Terms of Service at any time, and we are not affiliated with or responsible for them.

The ESP32 only supports 2.4 GHz Wi-Fi. It won't connect to 5 GHz-only networks. Most modern routers broadcast both bands, so this is rarely an issue.

Having WiFi trouble? Use the WiFi Configuration Tool to scan for nearby networks and update your lamp's WiFi settings directly from your browser over USB.

If your lamp can't connect to WiFi (e.g. you changed your router password, moved to a new location, or it's stuck trying to connect), you can fix it without re-flashing:

Option 1 — 5-tap reset (easiest): With the lamp off (powered but not lit), tap the touch sensor 5+ times quickly. The lamp will flash red, erase its WiFi credentials, and reboot into setup mode. It will create a WiFi hotspot called "Linked Lamp Setup" — connect to it from your phone and pick your network from the captive portal.

Option 2 — WiFi Tool: Open the WiFi Configuration Tool in Chrome or Edge, plug your lamp in via USB, and scan for available networks. Select your network, enter the password, and your lamp will reboot and connect.

Option 3 — Serial monitor (advanced): Open any serial monitor at 115200 baud and type RESET_WIFI to clear credentials, or SET_WIFI:YourNetwork,YourPassword to directly set new ones. These commands work even when the lamp is stuck.

Ambient Mode allows your lamp to keep glowing gently in a color of your choice even when it's not active.

For power efficiency and subtlety, the brightness in Ambient Mode is capped at 10% of your daytime max brightness setting. Ambient Mode automatically turns off during your scheduled Nighttime Mode hours to ensure total darkness while you sleep.

The lamp is designed to recover on its own. If WiFi drops, it immediately tries to reconnect every 15 seconds. If it stays disconnected for 5 minutes, the lamp automatically reboots to get a fresh start.

If WiFi is working but the MQTT broker is unreachable, the lamp retries MQTT every 5 seconds. After 3 consecutive failures, it forces a clean MQTT disconnect and retries. After 6 failures (~30 seconds), it forces a full WiFi reconnect as a fallback.

While offline, touch gestures still work — you can still hold to pick a color or double-tap to turn off the lamp. The signal just won't be sent until connectivity is restored.

Color Cycle presets let you send multi-color animated sequences to a lamp instead of a single static color. Each preset contains up to 10 colors, and each color has its own hold time (how long to display it) and transition time (how long to smoothly fade to the next color).

For example, you could create a preset that slowly fades between red, orange, and yellow to represent a sunset, or cycle through someone's favorite colors. Color Cycle presets can be created and sent from the web app.

The lamp uses brief LED flashes to communicate its status:

• Double green flash — WiFi connected successfully (only on initial power-up/cold boot).
• Double red flash — WiFi credentials are being reset (triggered by 5+ taps when lamp is off).
• 1-second flash of your color — Confirmation that your single tap was sent. The lamp briefly shows the sent color, then reverts to its previous state.
• 3-second flash of picked color — After holding to pick a new default color, the lamp shows your selection for 3 seconds before reverting.
• 20-second breathing pulse — When a signal arrives, the lamp gently pulses (fading between 30% and 100% brightness in ~2-second cycles) for 20 seconds, then holds a steady glow.

Each lamp syncs its clock via NTP (Network Time Protocol) using internet time servers. You can set a POSIX timezone string (e.g., EST5EDT, PST8PDT) for each lamp through the web app.

This means Nighttime Mode is timezone-aware — if you set night mode from 10 PM to 8 AM, the lamp uses your local time, not UTC. Two lamps in different time zones will each respect their own local schedule.

When the lamp receives a firmware update over the air (OTA), it doesn't immediately mark the new firmware as "good." Instead, it waits until the firmware successfully connects to the MQTT broker.

If the new firmware crashes or can't reach the broker, the ESP32's bootloader will automatically roll back to the previous working firmware on the next reboot. This ensures a bad update can never permanently brick your lamp.