ReadingLampController

Reading Lamp Controller

A fully open-source smart reading lamp with Matter/Google Home integration. Features a cylindrical RGBW LED shade, rotary encoder control, analog color mixing, and multiple dimming modes including an animated fire effect.

Features

• Matter/Google Home — On/off control via WiFi after BLE commissioning
• Rotary encoder — Short press cycles modes, long press turns off, rotation controls brightness
• RGBW color mixing — Four potentiometers for real-time red, green, blue, and white adjustment
• Four dimming modes:
  • Uniform — All LEDs at equal brightness
  • Vertical Fade — Light expands from center row outward
  • Radial Fade — Light wraps around the cylindrical shade
  • Fire Flicker — Animated flame effect with realistic flicker-out
• Smooth transitions — Perceptual gamma correction and interpolated fades

Project Structure

This repository contains everything needed to build the lamp from scratch:

ReadingLampController/
├── Firmware/           # ESP32-S3 firmware (PlatformIO)
├── PCB/                # KiCad schematic and PCB design
├── Mechanical/         # CAD files (Fusion 360, STEP, DXF for CNC/laser)
└── Doc/                # Additional documentation

Firmware

The firmware runs on a Seeed XIAO ESP32-S3 and is built with PlatformIO. It uses the pioarduino platform fork to enable Matter support via Arduino Core 3.x.

📁 Firmware Documentation — Build instructions, flashing, Matter commissioning, usage guide

📁 Architecture Guide — Deep-dive technical documentation for contributors

PCB

The PCB is based on my LCCLightingController project — a general-purpose ESP32-S3 lighting controller with I²C ADC, rotary encoder support, and LED strip output. This lamp runs custom firmware tailored for the cylindrical RGBW shade and Matter integration.

• Schematic: PCB/pcb.kicad_sch
• PCB layout: PCB/pcb.kicad_pcb
• Gerber outputs: PCB/Outputs/

Mechanical

CAD files for the lamp body, shade, and hardware. Designed in Fusion 360 with exports for fabrication:

Hardware Overview

Quick Start

Prerequisites

• Visual Studio Code
• PlatformIO IDE extension

Clone & Build

git clone https://github.com/vsi5004/ReadingLampController.git
cd ReadingLampController/Firmware/ReadingLampController

Open the Firmware/ReadingLampController folder in VS Code. PlatformIO will auto-configure the project.

Windows users: Set this environment variable before building:

$env:SCONSFLAGS = "-j1"
platformio run

Flash

Option A — Pre-built binary (no dev environment needed):

Download the latest *-merged.bin from the Releases page and flash with esptool:

pip install esptool
esptool.py --chip esp32s3 --port COM3 write_flash 0x0 ReadingLampController-*-merged.bin

Option B — Build from source:

platformio run --target upload

Commission

Open a serial monitor at 115200 baud to see the Matter pairing code:

platformio device monitor

On first boot, use the Google Home app to commission the device as a Matter accessory.

Usage

License

This project is licensed under the BSD 2-Clause License. See LICENSE for details.

Contributing

Contributions are welcome! For firmware changes, please review the Architecture Guide first to understand the codebase structure and design decisions.

Acknowledgments

• pioarduino — Arduino Core 3.x platform with Matter support
• NeoPixelBus — RGBW LED strip driver
• Adafruit seesaw — I²C rotary encoder library