# Hardware
# Prebuilt
PixelIt provides firmware for the Ulanzi TC001. Select the ESP32_ulanzi build when installing or updating it.
| Quantity | Name | Link | Notice |
|---|---|---|---|
| 1 | Ulanzi TC001 Pixel Clock | Official store (opens new window) | ESP32, 32×8 LED matrix, three buttons, built-in battery and light sensor. PixelIt 3.0.0 does not implement the built-in buzzer. |
# DIY components list
To build a PixelIt, you need basic soldering skills and these components:
- A supported ESP8266 or classic ESP32 board
- A 32×8 WS2812B matrix, or four compatible 8×8 tiles
- A 1000 µF capacitor rated for at least 6.3 V
- A regulated 5 V supply sized for your matrix and brightness
Sensors, a DFPlayer Mini and buttons are optional.
Wiring examples
The diagrams show ESP8266 D1 mini examples. ESP32 connections are listed separately in the tables. Check the exact board pinout and configure the peripheral pins in the WebUI before use. The examples are individual circuits; do not assign the same GPIO to unrelated peripherals when combining them.
# Matrix
The released firmware targets a 32×8 matrix. Other dimensions require a custom build and code changes; changing a WebUI setting does not change the matrix dimensions.
Connect the capacitor across the matrix power input, observing its polarity. It buffers changes in current demand; it does not limit LED current or replace a suitable power supply. Follow the NeoPixel wiring and power recommendations (opens new window), including common ground, a data-line resistor and appropriate logic-level shifting for 3.3 V controllers driving 5 V pixels.
| Quantity | Name | Link | Notice |
|---|---|---|---|
| 1 | WS2812B LED Matrix 8x32 | Amazon (opens new window) AliExpress (opens new window) | |
| 4 | WS2812B LED Matrix CJMCU 8x8 | Amazon (opens new window) AliExpress (opens new window) | alternative |
| 4 | MicroMatrix by foorschtbar 8x8 | GitHub (opens new window) | alternative (really micro) |
| 1 | Capacitor 1000uF/6.3V or higher | Amazon (opens new window) AliExpress (opens new window) |
# Microcontrollers
The stable release includes builds for ESP8266 generic, D1 mini and NodeMCU v2 boards, plus classic ESP32 generic, D1 mini32 and Ulanzi TC001 boards. Choose the matching firmware asset. ESP32-C3, ESP32-S2 and ESP32-S3 are not interchangeable with these classic ESP32 builds.
| Quantity | Name | Link | Notice |
|---|---|---|---|
| 1 | Wemos D1 Mini V3 (ESP8266) | Amazon (opens new window) AliExpress (opens new window) | |
| 1 | Wemos D1 ESP32 (ESP32) | Amazon (opens new window) AliExpress (opens new window) | alternative |
# Extensions
- LDR GL5516 Sensor (Brightness)
- DHT22 Sensor (Temperature & Humidity)
- BME280 Sensor (Temperature, Humidity & Pressure)
- BME680 Sensor (Temperature, Humidity, Pressure & Gas)
- DFPlayer Mini (MP3 player and sound effects)
- Touch Buttons (Touch Sensor)
# Wiring guide
Matrix and analog light-sensor pins are fixed by the selected firmware build:
| Build | Matrix DIN | Analog light sensor |
|---|---|---|
| ESP8266 builds | D2 / GPIO4 | A0 |
| Generic ESP32 and D1 mini32 | GPIO27 | GPIO34 |
| Ulanzi TC001 | GPIO32 | A7 (board-defined) |
The DIY tables below apply to ESP8266 D1 mini and generic classic ESP32 boards, not the internal Ulanzi wiring.
Set digital peripheral pins in the WebUI to match your wiring: sensor and button pins are under Sensors & Buttons, and DFPlayer pins are under Options → Sound. Saving through the WebUI restarts the device to initialize peripherals with the new configuration. Use GPIOs exposed by your board and supported by the firmware's pin selector. On classic ESP32, GPIO20 and GPIO24 are not usable choices for these builds.
Refer to the D1 mini board documentation (opens new window) and Espressif ESP32 GPIO documentation (opens new window). ESP8266 D-labels are board labels, not GPIO numbers: for example, D2 is GPIO4. GPIO signals use 3.3 V logic.
# Basic wiring

| ESP8266 | ESP32 | Matrix | Function | Note |
|---|---|---|---|---|
| 5V | VIN | VCC | Power supply (+) | |
| G | GND | GND | Power supply (-) | |
| D2 | GPIO27 | DIN | Data In |
Size the 5 V supply, cables and connectors for the panel's specified maximum current and your brightness limit. Do not assume that a 5 V / 4 A supply or a computer USB port can power every 256-pixel panel at full white brightness. Connect the matrix supply and controller ground together; use your board's documented power input and avoid backfeeding USB.
# LDR GL5516
Provides the light reading used for automatic brightness control and exposed through the API and MQTT. The LDR reading is an estimate based on the selected photocell model and resistor. Check the ADC input limit of your exact board; bare ESP8266 ADC inputs differ from D1 mini A0 inputs.
# Components
| Quantity | Name | Link |
|---|---|---|
| 1 | LDR GL5516 | Amazon (opens new window) AliExpress (opens new window) |
| 1 | Resistor 10k Ohm | Amazon (opens new window) AliExpress (opens new window) |
# Wiring

| ESP8266 | ESP32 | LDR GL5516 | Resistor 10k Ohm | Function | Note |
|---|---|---|---|---|---|
| 3V3 | 3V3 | Leg 1 | |||
| G | GND | - | Leg 1 | ||
| A0 | GPIO34 | Leg 2 | Leg 2 | Acts as a voltage divider |
The analog driver also supports GL5528, GL5537_1, GL5537_2, GL5539 and GL5549. Select the actual LDR model and physical pulldown resistance, then restart. See automatic brightness calibration for sensor settings and lux-to-brightness mapping.
# DHT22 Sensor
Exposes temperature and humidity through the API and MQTT. Set onewirePin to match DATA; use a pull-up between DATA and 3.3 V if your sensor module does not already include one.
# Components
| Quantity | Name | Link |
|---|---|---|
| 1 | DHT22 | Amazon (opens new window) AliExpress (opens new window) |
| 1 | Resistor 4.7k Ohm | Amazon (opens new window) AliExpress (opens new window) |
# Wiring

| ESP8266 | ESP32 | DHT22 | Function | Note |
|---|---|---|---|---|
| 3V3 | 3V3 | VCC | Power supply (+) | |
| G | GND | GND | Power supply (-) | |
| D1 | GPIO16 | DATA |
# BME280 Sensor
Exposes temperature, humidity and pressure values via API and MQTT.
# Components
| Quantity | Name | Link |
|---|---|---|
| 1 | BME280 3.3V | Amazon (opens new window) AliExpress (opens new window) |
# Wiring

| ESP8266 | ESP32 | BME280 | Function | Note |
|---|---|---|---|---|
| 3V3 | 3V3 | VCC | Power supply (+) | |
| G | GND | GND | Power supply (-) | |
| D1 | GPIO22 | SCL | Clock | |
| D3 | GPIO21 | SDA | Data |
# BME680 Sensor
Exposes temperature, humidity, pressure and gas values via API and MQTT.
# Components
| Quantity | Name | Link |
|---|---|---|
| 1 | BME680 | Amazon (opens new window) AliExpress (opens new window) |
# Wiring

| ESP8266 | ESP32 | BME680 | Function | Note |
|---|---|---|---|---|
| 3V3 | 3V3 | VCC | Power supply (+) | |
| G | GND | GND | Power supply (-) | |
| D1 | GPIO22 | SCL | Clock | |
| D3 | GPIO21 | SDA | Data |
# Other supported sensors
Firmware 3.0.0 also contains support for BMP280 (temperature and pressure), SHT31 (temperature and humidity), BH1750 and MAX44009 (light). It selects one environmental sensor and one light-sensor source during startup, rather than reporting every connected sensor independently.
The light-sensor probe tries BH1750 at 0x23, then MAX44009, then the analog LDR. The environmental probe tries SHT31 at 0x44, then BME280 at 0x76, BMP280 at 0x76, BME680, then DHT22. Use sensor modules compatible with the board's 3.3 V signals and check their address configuration. Restart after wiring or configuration changes.
The SHT31 driver uses its default Wire bus rather than the explicitly configured I²C bus in 3.0.0. Verify the default bus pins on your board and avoid conflicts with the matrix; changing SDAPin and SCLPin alone does not reconfigure that driver.
# DFPlayer Mini
The DFPlayer Mini plays audio stored on its microSD card. PixelIt can control it at startup, with configured button actions, or through the sound API. Use the module's speaker outputs as described in the DFRobot documentation (opens new window).
# Components
| Quantity | Name | Link |
|---|---|---|
| 1 | DFPlayer Mini MP3 Player | Amazon (opens new window) AliExpress (opens new window) |
# Wiring

The diagram uses D5 for PixelIt TX and D7 for PixelIt RX. For this ESP8266 wiring, set dfpTXpin to Pin_D5 and dfpRXpin to Pin_D7; the firmware default TX is D8 instead. Generic ESP32 defaults are TX GPIO16 and RX GPIO17. The DFPlayer RX connects to the controller TX, and vice versa. A GPIO cannot be shared with the DHT data line.
The table shows a 3.3 V supply as in the diagram. The DFPlayer's specified supply range is 3.2–5 V; ensure your supply supports the module and speaker load.
| ESP8266 | ESP32 | DFPlayer Mini | Function | Note |
|---|---|---|---|---|
| 3V3 | 3V3 | VCC | Power supply (+) | |
| G | GND | GND | Power supply (-) | |
| D5 | GPIO16 | RX | PixelIt TX -> DFPlayer RX | |
| D7 | GPIO17 | TX | PixelIt RX <- DFPlayer TX |
# Touch Buttons
TTP223 touch modules provide digital button inputs. Configure each button's pin, enabled state, pressed level and action in Sensors & Buttons. Firmware actions include showing the clock, toggling sleep and controlling the DFPlayer. Button states are also published through MQTT.
# Components
| Quantity | Name | Link |
|---|---|---|
| 1 | TTP223 Touch Sensor | Amazon (opens new window) AliExpress (opens new window) |
# Wiring

| ESP8266 | ESP32 | Button left | Button middle | Button right | Function | Note |
|---|---|---|---|---|---|---|
| 3V3 | 3V3 | VCC | VCC | VCC | Power supply (+) | |
| G | GND | GND | GND | GND | Power supply (-) | |
| D0 | GPIO25 | I/O | - | - | Touch signal | See disclaimer |
| D4 | GPIO26 | - | I/O | - | Touch signal | See disclaimer |
| D8 | GPIO23 | - | - | I/O | Touch signal | See disclaimer |
ESP8266 boot pins
D4 / GPIO2 must be HIGH during boot, so its touch module must idle HIGH and become LOW when touched. Configure that button's pressed level as LOW. D8 / GPIO15 must be LOW during boot, so its module must idle LOW and become HIGH when touched; configure its pressed level as HIGH. Use the module manufacturer's active-level configuration, and verify the idle voltage before connecting it to a boot pin.
These are example assignments, not firmware defaults. ESP8266 button defaults are D0, D4 and D5, with buttons initially disabled. The diagram instead uses D8 for the right button; select D8 explicitly to use it. Use the ESP32 pins from the table only when they are free on your board.
TTP223 Image for Fritzing by rbricheno (opens new window).
# 3D Printing Files
by PlastikJunkies
# Downloads
# Makes
Find examples from other builders in the discussion below.
# Troubleshooting
See Troubleshooting.
← Introduction Firmware →