Dos GatOS turns the Ulanzi TC001 (the ESP32 smart pixel clock AWTRIX runs on) into a tiny computer for your desk. The clock fetches data from the internet on its own, takes updates from your Mac or browser, and shows apps from a marketplace — weather, crypto, CI status, merge requests, Home Assistant sensors, your next meeting and more.
Screens rendered by the clock emulator on dosgatos.app.
Flash it from your browser: dosgatos.app/flash — Chrome or Edge on a computer and a USB cable, nothing to install.
- Apps from any JSON API. An app is a small JSON manifest: which URL to poll, which value to take, how to show it. Install ready-made ones from the marketplace or write your own in the Studio with a live preview.
- Rules, colors and frames. Change the text, color or icon by the data (red when a pipeline fails, blue below zero), tint values on a color scale, show several screens in turn — say, every coin of a crypto ticker. See docs/manifest-v2.md.
- Works on its own. With Wi‑Fi set up, the clock polls its apps itself and keeps time over NTP. When the Dos GatOS app is around (USB or the same Wi‑Fi network), requests go through it instead.
- Up to 16 apps, each with its own icon from the LaMetric gallery, color, font and time on screen. The clock keeps its apps and settings, so they follow it from computer to computer.
- Built in: a Pomodoro timer and plain timers (5 minutes to 2 hours), today's date and day countdowns, an ON CALL screen while your Mac's microphone or camera is busy, notifications, and "do not disturb until morning".
- Three pixel fonts (3×5, 4×6, 5×7), adjustable brightness and scroll speed; Cyrillic and accented text is transliterated.
- A technical screen on all three buttons: the IP address and firmware version, or why Wi‑Fi doesn't connect.
- Ulanzi TC001 smart pixel clock: ESP32 (ESP32-D0WD, 4 MB flash), 32×8 WS2812 LED matrix, three buttons, buzzer, DS1307 real-time clock, CH340 USB serial.
- A computer with Chrome or Edge to flash it from the browser, or
esptool/ PlatformIO.
Other ESP32 matrix clocks aren't supported out of the box: the pins and matrix layout are the TC001's.
Before your first flash, keep a backup of the firmware that's on the clock now (the web flasher offers one). Flashing is at your own risk.
Open dosgatos.app/flash in Chrome or Edge, plug the clock in and follow the steps. It can back up the current firmware first, and keeps the buzzer quiet while it writes.
Download tc001-usb-vX.Y.Z-merged.bin (first install) or tc001-usb-vX.Y.Z-app.bin (update) from
Releases.
pip install esptool
PORT=$(ls /dev/cu.usbserial-* | head -1) # macOS; /dev/ttyUSB0 on Linux, COM3 on Windows
# 1. Back up what's on the clock now (4 MB)
esptool --chip esp32 --port $PORT read-flash 0 0x400000 tc001-backup.bin
# 2a. First install: the whole image from 0x0 (erases the clock's settings)
esptool --chip esp32 --port $PORT --baud 115200 write-flash 0x0 tc001-usb-vX.Y.Z-merged.bin
# 2b. Update a clock already on Dos GatOS: only the app, Wi-Fi and settings stay
esptool --chip esp32 --port $PORT --baud 115200 write-flash 0x10000 tc001-usb-vX.Y.Z-app.bin
# Back to the backup
esptool --chip esp32 --port $PORT write-flash 0x0 tc001-backup.binThe TC001's USB chip (CH340) isn't reliable at higher speeds, so these commands use 115200 baud; a full image takes about two minutes. The buzzer beeps for as long as esptool holds the chip in its bootloader — that's expected; the web flasher silences it.
pip install platformio
pio run # build
pio run -t upload # build and flashThe release images are made by .github/workflows/build.yml.
Wi‑Fi, apps, fonts and the clock face are set from the Dos GatOS app:
- Web app — in Chrome or Edge, over USB (Web Serial). Set up Wi‑Fi here and the clock carries on without the computer.
- Mac app — also answers sources from your Mac (now playing, calendar, battery, Claude usage), finds the clock on your Wi‑Fi network, and puts the clock in your menu bar: next screen (⌥⌘→ from any app), do not disturb, timers.
The clock only joins 2.4 GHz networks.
| Left / right | previous / next screen |
| Middle, short | refresh the screen now (with the Pomodoro running: pause) |
| Middle, hold | start or stop the Pomodoro timer |
| All three | technical screen: IP address, firmware, Wi‑Fi problems |
A dot in the bottom-right corner tells you how the clock gets its data: none — through the app; blue — on its own over Wi‑Fi; red — neither. Grey text means the data is stale.
- docs/sources.md — the fields of an app (source): URL, JSON path, format, icons, headers
- docs/manifest-v2.md — values, templates, rules, color scales and frames
- docs/protocol.md — how the clock talks to the app over USB and Wi‑Fi
How is it different from AWTRIX 3? Both run on the same clock. AWTRIX 3 is a mature firmware built around MQTT and Home Assistant: other systems push apps and notifications to the clock. Dos GatOS works the other way round — the clock pulls its apps from any JSON API itself, described by a small manifest with rules, color scales and frames, installed from a marketplace or written in the Studio, with a Mac app and a web app for setup. No MQTT broker or server needed.
Can I go back to the stock firmware or AWTRIX? Yes. Keep the backup from your first flash and write it back with esptool (see above), or flash AWTRIX 3 from its own web installer.
Does it need my computer to keep running? No. Set up Wi‑Fi once from the app; after that the clock polls its apps on its own. The Mac app adds sources from your Mac (now playing, calendar, battery).
Can I make my own app? Yes — in the Studio: paste a manifest or start from a template, fetch the API, watch the result live, then put it on your clock.
- On its own over Wi‑Fi the clock doesn't verify HTTPS certificates (there's no root store in the firmware). Fine for public data; keep secrets out of apps the clock fetches itself.
- The Wi‑Fi link to the app has no authentication yet. Anyone on your network could drive the clock; the clock refuses Wi‑Fi settings over the network for that reason.
- Icons reach the clock through the app; a clock that never met the app shows apps without icons.
- Fonts are ASCII only; other scripts are transliterated where possible, the rest shows as
?.
Dos GatOS firmware is source-available for noncommercial use under the PolyForm Noncommercial License 1.0.0: you may use, copy, change and share it for personal, hobby, research, education and other noncommercial purposes, and charities, schools and public bodies may use it too. Selling it, shipping it on devices you sell, or using it in a commercial product needs a separate license — open an issue to ask.
Third-party libraries built into the firmware keep their own licenses — see THIRD_PARTY_NOTICES.md.
Not affiliated with Ulanzi. Ulanzi and TC001 are trademarks of their respective owners.