How to Use Your Lamp

You've built and flashed both lamps — here's how to get them running and how to use them day-to-day.

play_circle First-Time Setup

After flashing the firmware, follow these steps to get each lamp online:

  1. Plug in the lamp using a USB-C cable connected to any USB power adapter (5V). The lamp will power on automatically.
  2. Connect to Wi-Fi. On first boot, the lamp creates a Wi-Fi hotspot called "Linked Lamp Setup". Connect to it from your phone.
  3. Choose your network. A configuration page will open automatically. Select your home Wi-Fi network, enter the password, and tap Save. The lamp will restart and connect to your network. A light will blink twice to indicate it is connected to WiFI.
    If the configuration page doesn't open automatically, open your browser and go to http://192.168.4.1
    Tip: The ESP32 only supports 2.4 GHz Wi-Fi. Make sure you're selecting the 2.4 GHz band if your router has separate network names.
  4. Connect to the Web App. Open the Dashboard and paste in your Unique ID (UID) when prompted. You were given these UIDs at the end of the software setup. If you received this lamp from someone, ask them for your UID.
    NFC Tip: If there is an NFC tag sticker on the bottom of your lamp, tap your phone on the base to open the app directly.
  5. Tap the lamp! Once both lamps are connected and both web apps are open, try a tap — the other lamp should light up.

touch_app Touch Gestures

All gestures use the TTP223 touch sensor on the base of the lamp:

Action What happens
Single Tap Sends your default color to the other lamp. Your lamp briefly flashes the sent color for 1 second as confirmation, then reverts to its previous state.
Double Tap Turns off your lamp (if it's currently on)
Hold (1.5s+) Cycles through all colors (~6 seconds per full hue rotation). Lift your finger to select a color — the lamp flashes your pick for 3 seconds, then saves it as your new default.
5+ Taps Resets Wi-Fi settings (only works when the light on the lamp is off). Flashes red twice before restarting with the "Linked Lamp Setup" hotspot.

phone_iphone The Web App

The Web App dashboard is your remote control. Open it in any browser or download the Progressive Web App (PWA) to your device. Once you enter your Unique ID (UID), your lamp is linked!

From the web app you can:

Your credentials are saved locally after the first visit, so you can bookmark the URL and open it directly next time without re-entering your UID.

system_update Firmware Updates

You can check for updates manually by opening the web app, going to Settings, and tapping "Check for Update". The lamp does not perform any automatic updates or periodic update checks on its own.

Updates are downloaded over Wi-Fi and applied automatically. The lamp reboots after installing. If a new firmware version crashes or can't connect to the MQTT broker, the lamp automatically rolls back to the previous working version.

lightbulb LED Indicators

The lamp uses brief LED flashes to communicate status and confirm actions:

Indicator Meaning
Double green flash WiFi connected successfully. Only shown on initial power-up (cold boot), not after software restarts.
Double red flash WiFi credentials are being reset (triggered by 5+ taps). The lamp restarts with the setup hotspot.
1-second color flash Send confirmation. After a single tap, the lamp briefly shows the color you sent, then reverts to its previous state.
3-second color flash Color pick confirmation. After holding to select a new default color, the lamp shows your selection for 3 seconds.
20-second breathing pulse Signal received. The lamp gently pulses (30–100% brightness, ~2-second cycles) for 20 seconds, then holds a steady glow until the timer expires.

wifi Connectivity & Recovery

The lamp is designed to recover from network issues automatically:

Tip: Touch gestures continue to work even when the lamp is offline. You can still pick colors and turn the lamp off — signals just won't send until connectivity is restored.
WiFi not working? If your lamp can't connect, you changed your password, or moved to a new location, there are several easy ways to fix it without re-flashing. See WiFi troubleshooting steps →

help_outline Quick Troubleshooting

Problem Solution
Lamp won't connect to Wi-Fi Tap 5+ times (while powered but lights are off) to reset Wi-Fi, then reconnect via the "Linked Lamp Setup" hotspot. Make sure you're using a 2.4 GHz network. See all WiFi recovery options →
Other lamp doesn't light up Make sure both lamps are on and connected to Wi-Fi. Open both web apps to verify connectivity.
Web app isn't loading Check that you've entered the correct Unique ID (UID). Try opening in Chrome or Safari for best compatibility. If possible, tap your phone on the NFC tag sticker on the bottom of your lamp to open the app directly.
Lamp keeps restarting This usually means the lamp can't connect to WiFi or the MQTT broker. Check that your WiFi network is online and the MQTT broker credentials are correct. The lamp reboots every 5 minutes if WiFi stays disconnected.
Lamp shows config portal unexpectedly This happens after a power cycle (unplugging and replugging), a WiFi reset (5+ taps), or if the lamp was unable to connect. Connect to the "Linked Lamp Setup" hotspot and re-enter your WiFi credentials.

For more help, check the FAQ or open an issue on GitHub.