Build your own AWTRIX¶

AWTRIX NG is not tied to the Ulanzi TC001. It drives any 32-128 x 8 WS2812-style panel on a board you wired yourself, and every peripheral around that panel is optional. This page is the hardware side of that: what to buy, what to connect where, and what to configure once it boots.

The firmware itself needs exactly two things from your build: a matrix on a supported data pin, and power. Buttons, light sensor, battery, sound and the environment sensor are all add-ons you can leave off and add later - the pin map is runtime configuration, not a compile-time choice.

1. Pick the chip first¶

Everything else follows from it. Both are supported first-class, with their own firmware image.

Recommendation: an ESP32-S3 DevKitC-1 N16R8 (16 MB flash, 8 MB octal PSRAM). It is the board the S3 image is built against, it has flash for a large icon and script library, and PSRAM is what makes Internet radio available. A classic ESP32 with 4 MB is entirely fine for a clock that never plays a stream.

2. Bill of materials¶

Required¶

Optional - add what you want¶

You do not need all of it, and nothing here is soldered into the firmware: a peripheral you skip gets -1 in the pin map and disappears cleanly - its keys vanish from device state, its Home Assistant entities are not published, and its built-in app drops out of the rotation.

3. The standard pinout¶

These are the firmware defaults. A board wired exactly like this needs no pin configuration at all - flash it and it works.

System diagram¶

Required blocks are the panel and its supply; everything to the left and below is optional.

Connection list¶

Power - run these before anything else, and never through the dev board's regulator.

Signals

The DFPlayer and the I2S DAC are alternatives, not companions: the firmware picks one sound backend. Leave the pins of the one you did not build at -1.

Pins you cannot freely choose¶

Four hard rules, all enforced on every write and re-checked at boot. The full rule set, the exact error messages and the ESP32 equivalents are in GPIO & boards.

Two more the firmware accepts but your hardware may not:

• Strapping pins - 0, 3, 45, 46 on the S3; 0, 2, 5, 12, 15 on the ESP32. They are sampled at reset, so anything holding them high or low can stop the board from booting. Accepted by validation, punished by physics.
• Deep-sleep wake - only a select button on GPIO 0-21 (S3) or 0, 2, 4, 12-15, 25-27, 32-39 (ESP32) can end a /device/sleep early. Any other pin works normally while awake and simply cannot wake the board.

Never hardcode these tables into your own tooling - the running device reports its own rules:

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

4. Power the panel first¶

This is where DIY builds fail, not in the firmware.

AWTRIX NG does not limit LED current. There is no software power cap between a white frame and your supply, so size the supply for the worst case you can actually reach: full white at brightness 255, through moodlight, Art-Net or a script.

Nobody builds for the theoretical maximum. 5 V / 3-4 A for a 32 x 8 panel is the sane compromise: it covers every normal app plus a bright notification, and the way to stay inside it is to cap brightness rather than to oversize the supply.

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

The wiring rules that go with it:

1. Never power the panel through the dev board's 5 V pin. Feed the panel from the supply directly; the board taps the same supply.
2. Common ground. Board GND and panel GND must be joined, or the data line has no reference and the panel shows noise.
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 suppress the inrush edge that kills the first pixel.
4. Inject power at both ends on anything wider than 32 px, and use proper wire - 18 AWG for the 5 V run, not breadboard jumpers.
5. Data level. WS2812B wants 0.7 x VDD on DIN, which is 3.5 V - above the 3.3 V an ESP32 drives. Short runs usually work anyway. If the first pixels flicker or show wrong colours, add a 74AHCT125 level shifter, or drop the panel's supply to ~4.5 V with a series diode so 3.3 V clears the threshold.

5. Wire the options¶

Buttons¶

Three momentary buttons from the GPIO to GND. The firmware configures INPUT_PULLUP, so pressed reads LOW. No external resistors needed; a 100 nF cap across each button quiets a noisy mechanical switch. Debounce and the double-press window are fixed in firmware.

If the panel ends up mounted upside down, fix it in configuration rather than by resoldering - rotate flips the picture and swaps left/right, swapButtons swaps them on their own.

Light sensor (auto-brightness)¶

A GL5528-class LDR and a 10 k resistor as a divider into the ADC pin:

Wired this way, brighter means a higher voltage, which is what the firmware expects (ldrOnGround: false). Swap the two parts and set {"ldrOnGround": true} instead - the reading is simply inverted.

Then calibrate: ldrFactor decides what counts as full light on your divider, ldrGamma shapes the response curve. Both apply live. Full procedure in Brightness & sensors.

Battery monitoring¶

A plain 2:1 divider from the cell into an ADC1 pin:

4.2 V at the cell becomes 2.1 V at the pin - inside the ADC's range with margin. Tell the firmware the ratio, then correct it against a known-full 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. Charge fully, read batteryPinMillivolts from GET /api/v1/device, and write 4.2 / (batteryPinMillivolts / 1000). The percentage comes off a Li-Ion discharge curve, not a fuel gauge - see Power & battery.

Environment sensor¶

Any one of BME280 (0x76/0x77), BMP280 (same addresses), HTU21DF or SHT31 (0x44) on the I2C bus. Detection is automatic at boot in that order - the first chip that answers wins, so put only one on the bus. Most breakouts carry their own pull-ups; add 4.7 k to 3V3 on both lines if yours does not.

Temperature comes from all four; humidity from BME280, HTU21DF and SHT31; pressure from BME280 and BMP280. Trim self-heating with tempOffset and humOffset.

Sound - three mutually useful options¶

Buzzer: a passive piezo (not a self-driving active buzzer) straight on the GPIO. It is quiet by design; a small NPN transistor with a 100 ohm base resistor makes it usable.

DFPlayer Mini: 5 V supply, a 1 k resistor in the line into the module's RX, and the speaker on SPK1/SPK2. It replaces the buzzer entirely - it plays files, not notes, so RTTTL melodies make no sound on such a board. Set dfplayer: true.

MAX98357A: BCLK, LRC and DIN to the three I2S pins, plus 3V3/GND and a 4-8 ohm speaker. The board needs no separate amplifier. The three I2S pins are validated as a set - all three assigned, or all three -1; a partial set is rejected with a 422. A UDA1334A or PCM5102A works identically.

6. Describe the panel¶

The pixel height is fixed at 8. Everything else about your matrix is configuration:

panelStart, panelWiring and panelSerpentine describe one panel; the two chain keys describe how the panels are joined to each other. On a single-panel build the chain keys cannot change anything.

Common builds:

If the picture comes out scrambled, try panelSerpentine first, then panelStart, then panelWiring. If each panel then looks right but the panels are in the wrong order, or every second one is upside down, that is panelChainReverse and panelChainSerpentine. All of them re-apply on the next frame, so you can watch the panel while you change them. Only a change to the total width needs a reboot.

7. Flash and configure¶

1. Flash the image for your chip - Flashing, browser flasher or esptool. Tick erase the whole flash on a fresh board.
2. Join Wi-Fi through the setup access point - First boot.
3. Write the pin map. Send it complete, in one request: cross-field rules (duplicates, the I2S trio) are checked against the merged map, so a partial write can be rejected for a conflict you are in the middle of resolving.

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,
        "dfplayer": false,
        "panelWidth": 32,
        "panels": 1
      }'

1. Reboot - the pin map is read at startup and nothing in it applies before that:

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 the Ulanzi TC001's and will be wrong for your parts.
2. Tune the colours if the panel runs cold or warm: colorCorrection and colorTint in Settings.

The same map is editable under System -> GPIO in the web UI, where each field is a dropdown already filtered to what your chip can do with that peripheral.

8. Verify the build¶

Work down this list; each step isolates one part of the hardware.

Troubleshooting a fresh build¶

Where to go next¶

• GPIO & boards - every validation 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, the S3 requirements
• App scripting - make the panel do something only your build can
• Building from source - if you want to change the firmware itself