WaveLight

WaveLight

A gesture-controlled night light. Wave your hand over it to turn it on or off, hold your hand over it to set the flame size, and double-wave to pick a color. The light is an animated candle flame on WS2812 LEDs. It runs on a Li-ion battery and sleeps when nobody is around.

• MCU: ATtiny416 (4 kB flash, 256 B RAM), internal 16 MHz oscillator
• Sensor: ams TMF8801 time-of-flight distance sensor
• LEDs: 4× WS2812B-2020 (count is configurable)
• Firmware: C, MPLAB XC8 (free license), in FW/
• Hardware: KiCad project in the repository root

---

Using it

Distances: hands are detected up to 60 cm. Size and color are set between about 6 cm (closest) and 32 cm (farthest).

Colors, from close to far in color mode:

So the strip goes once around the color wheel back to red, then into warm white and cools down to 6500 K. The hotter parts of the flame shift a little further along the strip, which gives the flame its lighter tips.

Status signals

The battery signals only appear if the battery check is enabled (see Configuration).

Things that might surprise you

• Static objects are learned. Anything that stays still for 10 s becomes background. A hand only counts if it is at least 8 cm closer than the background, so you can wave between the lamp and e.g. a shelf. After you place or remove something, give it ~10 s to adapt.
• Placed objects never change the settings. A hold only adjusts the flame once the hand has moved 3 cm, and objects don't move.
• Pulling your hand away doesn't change the setting. On release the value from ~200 ms earlier is kept.
• Idle: after 15 s without a hand, whether the light is on or off, the sensor slows down (one shorter measurement every 200 ms) to save power. The first wave still works, but a very quick flick can be missed. Idle measurements are shorter, so a hand near the 60 cm limit may only be noticed once it comes a bit closer.

---

Hardware

Pinout

Board

• Power: Li-ion battery (J6) → power switch (SW1) → TCR2L LDO → VDD for the MCU and sensor. The LED strip runs directly from the battery voltage.
• Charging: USB-C (J7) or the jack tip → charger IC (U3, charge current set by R3). The charger's battery output is on the switched side of SW1, so the battery only charges while the switch is on.
• 3.5 mm jack (J1): tip = charger input, ring = UPDI, sleeve = GND. It is used for programming.
• J4 / J5: sensor signal headers (VDD, GPIO0/1, SDA, SCL, INT, EN, GND).
• JP1: solder jumper EN → GND (holds the sensor off when closed).
• Battery divider: R2 1 MΩ (battery → PA1) and R4 470 kΩ (PA1 → PC3).

Known hardware limitations

• No I²C pull-ups. The internal ones are used and the bus runs at 50 kHz. Add 4.7 kΩ to VDD on SDA/SCL in the next revision.
• The LEDs run straight from the battery. The WS2812B-2020 is specified for 3.3-5.3 V. Below ~3.6 V the green and blue channels may lose current (dimmer, redder light), and below 3.3 V the LEDs are out of spec.
• The sensor dominates standby current (~3 mA), see Power analysis. A 300 mAh battery lasts about 3.5 days in standby.
• Sensor range is ~64 cm with the firmware built into the sensor (see Sensor range).

---

Firmware

Files

Building and flashing

1. Open FW/ in VS Code with the MPLAB extensions (project file FW/.vscode/Wavelight-firmware.mplab.json, XC8 v3.00, ATtiny_DFP 3.4.278).
2. Build. The optimization level in the project doesn't matter: main.c forces -O2 without inlining with a #pragma. At -O0 the firmware doesn't fit. The free XC8 license allows -O2 but not -Os.
3. Flash over UPDI (the project uses an MPLAB Snap).
4. Set the fuse OSCCFG to 16 MHz (FREQSEL_16MHZ) on every new chip. The factory default is 20 MHz, and then all timing (LED data, I²C, gestures) is off by 25%.
5. First boot after flashing: keep nothing within 40 cm of the sensor, ideally in the dark. The sensor calibrates itself and stores the result (1 s magenta flash).

Flashing erases the EEPROM, which holds the sensor calibration and the saved size and color, unless the EESAVE fuse is set.

Flash usage is about 3.65 kB, or 3.9 kB with the battery check, out of 4 kB.

Configuration

All settings are #defines.

main.c

gesture.h

light.h

battery.h

How it works

Sensor. The TMF8801 runs the measurement app built into its ROM. No firmware is uploaded, because the ~11 kB patch doesn't fit in 4 kB. On the first boot the sensor runs its factory calibration (crosstalk). The 14-byte result is stored in EEPROM and sent to the sensor on every start. It measures with 900k iterations; each measurement takes ~27 ms.

Gestures. Every sensor result goes into gesture_reading(), which decides whether a hand is present. gesture_update() runs every 10 ms and turns presence over time into events: wave, double wave, hold, hold end, track, track end. While color mode is active, wave and hold detection are off and the hand position is reported directly ("tracking"). When color mode ends, a hand that is still there is ignored until it leaves, so color mode never turns into a size change.

Light. The output level fades linearly in perceptual brightness and is gamma-corrected, so fades look even. Each LED has a "heat" value that drifts towards random targets. Neighboring LEDs are coupled, so the flicker travels along the strip, and occasionally the whole flame dips (a gust). Heat sets both the brightness and a small color shift. The size setting moves the base heat up and down.

Power. While a hand is around, the sensor measures every 33 ms with 900k iterations. After IDLE_AFTER_MS with no hand, no gesture pending and no color mode, whether the light is on or off, the sensor switches to SENSOR_IDLE_MS / SENSOR_IDLE_KITER (200 ms, 600k) and goes to standby between measurements. A hand switches it back.

What the MCU does then depends on the light:

• Light on (or fading): the MCU stays awake and runs the flame every 10 ms.
• Light off: the MCU goes to power-down and is woken by the sensor's INT pin, which goes low on every result (the TMF8801 has no distance-threshold interrupt). After each wake, the firmware catches up the missed 10 ms ticks so all timing stays correct, then sleeps again unless a hand was seen.

Unused pins have their digital inputs disabled, and the battery divider only draws current during a measurement. A watchdog (~8 s, also running in sleep) resets the device if the sensor ever stops waking it.

For the resulting currents and battery life, see Power analysis.

Settings. The flame size and color are saved to EEPROM when a hold or color mode ends, and only if they changed. EEPROM layout: page 0 = calibration + marker, page 1 = size, color + marker.

Debug mode

Set DEBUG_DISTANCE 1 to show what the sensor sees, at 10 cm resolution:

• Color = 40 cm band: green 0-40, yellow 40-80, red 80-120, magenta 120-160, white over 160 cm
• Number of lit LEDs = 10 cm steps within the band (1-4). For example, 3 yellow = 60-70 cm.
• First LED blue: the sensor reports no object
• All cyan: no new reading for 0.5 s

The display assumes 4 LEDs.

Sensor range

With the ROM firmware, the TMF8801 here reports "no object" beyond ~64 cm, even for a white wall in the dark with calibration. The datasheet only promises its 2.5 m range with the latest ams RAM patch (~11 kB, uploaded on every boot) and a tuned oscillator. An ATtiny1616 (16 kB) in the same package fits the patch. The steps are in FW/PATCHING.md.

---

Power analysis

Estimates for 4× WS2812B-2020 and a 300 mAh Li-ion battery. They are calculated from datasheet values and a simulation of the flame code. Nothing has been measured yet.

Assumptions

• Usable capacity 270 mAh: about 90% of 300 mAh, from 4.2 V down to the 3.3 V cut-off.
• Battery current = load current. The LDO is linear, and the LEDs are constant-current drivers. This holds while the battery is high enough for the green/blue LED channels (~3.6 V); below that the LEDs draw less and get dimmer.
• Room temperature, typical (not maximum) values.
• Default firmware settings: sensor every 33 ms with 900k iterations while a hand is around, every 200 ms with 600k iterations while idle; MCU at 16 MHz.
• The iteration count really changes the measurement time. The datasheet contradicts itself on the byte order, and the firmware follows the register description. Verify by measuring the standby current with SENSOR_IDLE_KITER 600 vs 900. It should drop by about a third; if it doesn't, the byte order is wrong.

Per component

LED current of the flame

These figures come from simulating the actual light.h algorithm (random generator, heat model, colors, white balance) for 10 minutes. Each LED channel draws 12 mA × PWM / 255.

• Peak: about 108 mA for the LEDs (cool white, size 255, during flicker peaks), so ~140 mA in total. This is under 0.5 C for a 300 mAh cell.
• Theoretical maximum: 4 × 36 mA = 144 mA; the flame never gets there.

Total current and run time (270 mAh usable)

After the first 15 s without a hand, the light runs with the sensor idle. The "on" rows assume that; the active state only applies briefly after each interaction.

Example day: the light is on for 30 min (red, size 160) and the rest is standby. That's 11 mAh + 73 mAh = ~84 mAh per day, so a charge lasts about 3 days.

Before the sensor idled while on and used fewer iterations (100 ms / 900k idle, 33 ms whenever on), standby was 9.3 mA (~29 h) and red at size 160 ran 5.9 h.

Findings

1. Standby is still mostly the sensor (3.0 of 3.1 mA). Each measurement costs a fixed charge (~0.59 mC at 600k), so the average current scales with measurement interval and iteration count.
2. While the light is on, the MCU is now a big share. At small sizes the busy 16 MHz loop (3 mA) costs as much as the sensor or the LEDs.
3. The LEDs cost nothing when dark (WS2812B-2020 V6: ≤ 1 µA). Older WS2812B revisions and clones draw ~0.5-1 mA each, so check the part revision if standby measures higher than expected.

Ways to extend run time further (not implemented)

---

References

• TMF8801 datasheet DS000648 v7-00 (ams OSRAM): register map, commands, bootloader protocol, calibration
• WS2812B-2020 V6 datasheet (WorldSemi): quiescent current, channel current, supply range, reset time
• ATtiny416/417/814/816/817 datasheet: active and power-down supply current (figures 36-1, 36-9)
• SparkFun TMF8801 Arduino library and DFRobot TMF8x01 library: measurement command bytes, calibration flow, RAM patch data