DIY build¶

This page shows you how to build your own AWTRIX clock: what to buy, how to wire it, and what to set after the first start.

AWTRIX NG runs on any WS2812-style LED panel 8 pixels high and 32 to 128 pixels wide, on an ESP32-S3 board you wired yourself.

Your build needs only two things: an LED panel on a supported data pin and power. Buttons, light sensor, battery, sound and the temperature sensor are optional. You can leave them off and add them later. You set the pins in the web UI, not in the firmware.

1. Pick the board¶

We recommend an ESP32-S3 DevKitC-1 N16R8 (16 MB flash, 8 MB octal PSRAM). It has room for many icons and scripts, and its PSRAM (extra memory) is needed for Internet radio.

2. Bill of materials¶

Required¶

Optional: add what you want¶

You do not need all of it. For each part you leave out, set its pin to -1 (not connected). Its values then disappear from device state, its Home Assistant entities are not created, and its built-in app leaves the rotation.

3. The standard pinout¶

These are the default pins. If you wire your board exactly like this, you do not need to set any pins. Install the firmware and it works.

System diagram¶

Only the panel and its power supply are required. Everything else is optional.

Connection list¶

Power. Wire these first. Never feed the panel through the ESP32 board.

Signals

The buzzer, the DFPlayer and the I2S DAC are separate outputs, and you can build any of them together. Set the pins of every part you did not build to -1.

Pins you cannot freely choose¶

AWTRIX checks these rules every time you save pins, and again at every start. All rules and the exact error messages are in GPIO & boards.

Two more points. AWTRIX accepts these pins, but your hardware may not like them:

• Strapping pins: 0, 3, 45, 46. The chip reads them at power-on. Anything that holds them high or low can stop the board from starting.
• Deep-sleep wake: only a select button on GPIO 0–21 can end a /device/sleep early. On any other pin the button works normally while AWTRIX is awake, but it cannot wake it up.

AWTRIX reports the rules for its own chip. Use this instead of copying the tables into your own tools:

curl http://<awtrix-ip>/api/v1/capabilities

4. Power the panel first¶

Most DIY problems come from the power wiring.

AWTRIX NG does not limit LED current. A full-white picture at brightness 255 draws the full current, whether it comes from the mood light, Art-Net or a script. Plan your supply for that.

You do not need a supply for the full maximum. 5 V / 3–4 A for a 32 x 8 panel covers every normal app and a bright notification. To stay inside it, limit the brightness instead of buying a bigger supply:

curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"autoBrightness":false,"brightness":120}'

With auto-brightness on, brightness is ignored. Cap the panel with maxBrightness in the system configuration instead.

Follow these wiring rules:

1. Never power the panel through the ESP32 board's 5 V pin. Connect the panel directly to the supply. The board is fed from the same supply.
2. Common ground. Connect board GND and panel GND. Without it the data signal has no reference and the panel shows random pixels.
3. 1000 uF across 5 V/GND at the panel input, and a 330–470 ohm resistor in series with the data line at the board end. Both protect the first LED from voltage spikes.
4. Feed power at both ends of panels wider than 32 px. Use proper wire: 18 AWG for the 5 V line, not breadboard jumpers.
5. Data level. A WS2812B needs at least 0.7 × its supply voltage on DIN: 3.5 V at 5 V. An ESP32 sends only 3.3 V. Short cables usually work anyway. If the first pixels flicker or show wrong colors, add a 74AHCT125 level shifter. Or lower the panel supply to about 4.5 V with a diode in series, so 3.3 V is high enough.

5. Wire the options¶

Buttons¶

Wire three push buttons, each between its GPIO and GND. AWTRIX turns on the internal pull-up, so a pressed button reads LOW. You need no external resistors. If a button is noisy, add a 100 nF capacitor across it.

If the panel ends up upside down, fix it in the settings instead of resoldering: rotate turns the picture and swaps left and right, swapButtons swaps only the buttons.

Light sensor (auto-brightness)¶

Build a voltage divider from a GL5528-type LDR and a 10 k resistor, and connect the middle to the ADC pin:

Wired this way, more light gives a higher voltage. This matches the default ldrOnGround: false. If you swap the two parts, set {"ldrOnGround": true}.

Then calibrate: ldrFactor sets what counts as full light on your divider, ldrGamma shapes the curve. Both take effect at once. The full steps are in Brightness & sensors.

Battery monitoring¶

Build a 2:1 divider from the cell to an ADC1 pin:

4.2 V at the cell becomes 2.1 V at the pin, safely inside the ADC range. Tell AWTRIX the ratio, then correct it with a fully charged cell:

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"batteryDividerRatio":2.0}'

batteryDividerRatio is V_cell / V_pin. To correct it:

1. Charge the cell fully.
2. Read batteryPinMillivolts from GET /api/v1/device.
3. Write 4.2 / (batteryPinMillivolts / 1000) as batteryDividerRatio.

The percentage is estimated from the voltage of a typical Li-Ion cell, so it is not exact. See Power & battery.

Environment sensor¶

Connect one of BME280 (0x76/0x77), BMP280 (same addresses), HTU21DF or SHT31 (0x44) to the I2C pins. AWTRIX finds it at startup, looking in that order, and uses the first one that answers. So connect only one sensor. Most breakout boards have pull-up resistors. If yours does not, add 4.7 k from each line to 3V3.

All four measure temperature. BME280, HTU21DF and SHT31 also measure humidity. BME280 and BMP280 also measure air pressure. If the sensor reads too warm because of heat from the clock, correct it with tempOffset and humOffset.

Sound options¶

Buzzer: a passive piezo (not an active buzzer with its own oscillator), connected directly to the GPIO. It is quiet. A small NPN transistor with a 100 ohm base resistor makes it louder.

DFPlayer Mini: 5 V supply, a 1 k resistor in the line to the module's RX, and the speaker on SPK1/SPK2. It plays numbered tracks from its microSD card. The buzzer keeps playing melodies and RTTTL tunes. Set dfplayer: true.

MAX98357A: BCLK, LRC and DIN to the three I2S pins, plus 3V3/GND and a 4–8 ohm speaker. You need no extra amplifier. Set all three I2S pins, or all three to -1. If you set only some, AWTRIX rejects the change with 422. A UDA1334A or PCM5102A works the same way.

Two optional pins go with it. A DAC with an MCLK input uses pinI2sMclk. An amplifier with an enable input, for example CTRL on an NS4168 or SD on a MAX98357A, uses pinAmpEnable. AWTRIX sets that pin high at startup, so the amplifier plays.

6. Describe the panel¶

Tell AWTRIX how your panel is built. Every panel is 8 pixels high. The total width can be 32–128.

panelStart, panelWiring, panelColorOrder and panelSerpentine describe one panel. The two chain keys describe how the panels are joined. With a single panel the chain keys change nothing.

Common builds:

If the picture is scrambled, try panelSerpentine first, then panelStart, then panelWiring. If each panel looks right but the panels are in the wrong order, or every second one is upside down, try panelChainReverse and panelChainSerpentine. These keys take effect at once, so you can watch the panel while you change them. Only a new total width needs a restart.

7. Flash and configure¶

1. Install the firmware for your chip. See Install AWTRIX NG, with the browser installer or esptool. In the browser installer, choose Fresh install for a new board.
2. Connect to Wi-Fi through the setup hotspot. See Connect to Wi-Fi.
3. Write the pin map. Send all pins in one request. Some rules compare pins with each other (no duplicates, all three I2S pins). If you send only part of the map, a pin you have not yet moved can cause a rejection.

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{
        "pinMatrix": 21,
        "pinBtnLeft": 11,
        "pinBtnSelect": 12,
        "pinBtnRight": 13,
        "pinBattery": -1,
        "pinLdr": 2,
        "pinBuzzer": 7,
        "pinI2cSda": 8,
        "pinI2cScl": 9,
        "pinDfRx": -1,
        "pinDfTx": -1,
        "pinI2sBclk": 5,
        "pinI2sLrclk": 6,
        "pinI2sDout": 4,
        "pinI2sMclk": -1,
        "pinAmpEnable": -1,
        "dfplayer": false,
        "panelWidth": 32,
        "panels": 1
      }'

1. Restart. A new pin map takes effect only after a restart:

curl -X POST http://<awtrix-ip>/api/v1/device/reboot

1. Calibrate what you wired: batteryDividerRatio for the divider, ldrFactor / ldrGamma / ldrOnGround for the light sensor, tempOffset / humOffset for the sensor. The defaults are general values and may be wrong for your parts.
2. Adjust the colors if the panel looks too cold or too warm: colorCorrection and colorTint in Settings.

You can also edit the pins under System → GPIO in the web UI. Each field is a dropdown that offers only the pins your chip can use for that part.

8. Verify the build¶

Work down this list. Each step tests one part of the hardware.

Troubleshooting a fresh build¶

Related¶

• GPIO & boards – every pin rule, the web UI dropdowns, recovery
• System configuration – all fields you wrote above, plus Wi-Fi, MQTT, NTP
• Brightness & sensors and Power & battery – calibration
• Internet radio – stations, volume, what the board needs
• Scripting guide – write your own apps
• Building from source – if you want to change the firmware itself