From c4e0c297913ac55d7e812bc4b7345b917ca4b685 Mon Sep 17 00:00:00 2001 From: MangaValk Date: Sun, 25 Oct 2026 22:50:11 +0100 Subject: [PATCH] Add a README Co-Authored-By: Claude Opus 5.5 --- README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3c0637d --- /dev/null +++ b/README.md @@ -0,0 +1,91 @@ +# IN-12 nixie clock: open firmware + +Replacement firmware for a RetroModding **NixieIN12v2** WiFi nixie clock (the 5 V, USB-C version +sold on AliExpress): 4x IN-12 tubes, 2x IN-3 neon dots, 4 WS2812 LEDs, an ESP8266 (ESP-12) and a +light sensor. The closed stock firmware (SV1.3) is replaced by +[ESP_UniClock](https://github.com/gpeter62/ESP_UniClock) with a new display driver for this board, +WiFi updates and Home Assistant control. + +## Features + +- Time from NTP with time zone and EU summer time, 12/24 h, day/night brightness, auto dimming + from the light sensor, digit animations, cathode-poisoning protection, blinking colon +- WS2812 backlight: fixed colour or one of nine animated effects +- UniClock's web page for all settings +- Firmware updates over WiFi (ArduinoOTA) +- Home Assistant over MQTT discovery: tubes on/off, day/night brightness, auto dim, backlight + (on/off, brightness, colour), LED effect, cathode protect, light and WiFi-signal sensors + +## The hardware + +The pinout was taken from the stock firmware by disassembly and checked on the clock; +details and evidence are in [docs/stock-firmware-pins.md](docs/stock-firmware-pins.md). + +| Function | GPIO | +|---|---| +| 2x 74HC595 (cathodes, anodes, dots) DATA / CLOCK | 13 / 14 (hardware SPI) | +| 74HC595 latch | 15 | +| WS2812 data | 12 | +| Light sensor (LDR) | A0 | + +The two shift registers hold one 16-bit word: bits 0-9 are the cathodes for digits 0-9, bits +11-14 the tube anodes (bit 11 = left tube), bit 10 the neon dots and bit 15 the decimal points. +The tubes are multiplexed, one at a time. This board has no RTC chip and no buttons. + +> **Warning:** the board makes about 170 V for the tubes whenever USB-C is connected. + +## Repository layout + +| Path | Contents | +|---|---| +| [firmware/uniclock/](firmware/uniclock/) | ESP_UniClock with the board support (PlatformIO project, see its [README](firmware/uniclock/README.md)) | +| `firmware/uniclock/ESP32_UniClock2/nixie595.ino` | Display driver for this board | +| `firmware/uniclock/ESP32_UniClock2/clocks.h` | Board configuration, `CLOCK_90` | +| [docs/](docs/) | Pinout analysis of the stock firmware, schematic of the related 12 V board | +| [tools/](tools/) | Python helpers used to disassemble the stock firmware | + +The stock firmware dump is not included: it contains the WiFi password. + +## Building and flashing + +Install [PlatformIO](https://platformio.org/), then in `firmware/uniclock/`: + +```sh +pio run # build +pio run -t upload # first flash, over serial +pio run -t uploadfs # web page files, over serial +pio run -e nixie_in12_ota -t upload # later updates, over WiFi +``` + +The first flash needs a USB-serial adapter (3.3 V logic) on the programming header (GND, GPIO0, +RST, RXD, TXD, 3.3V). The clock stays powered from its own USB-C, so leave the adapter's 3.3V +unconnected. There is no auto-reset: before each serial upload, hold GPIO0 to GND, tap RST to +GND and release GPIO0. Set the serial port and the clock's IP address in `platformio.ini`. Back up the stock +firmware first (`esptool read-flash 0 0x400000 stock.bin`); it is the only way back. + +On first boot the clock opens a WiFi access point called **UNICLOCK**. Connect to it and set +your WiFi on http://192.168.4.1. For Home Assistant, enter the MQTT broker on the clock's web page +and restart the clock; it then shows up under Settings > Devices > MQTT. + +Optional passwords for the web page and OTA updates go in +`firmware/uniclock/ESP32_UniClock2/secrets.h` (see `secrets.h.example`; the file is gitignored). + +## Changes to ESP_UniClock + +Besides the new driver and configuration: + +- NeoPixels on any ESP8266 pin, sent only when they change and between tube slots (the + bit-banged update blocks interrupts and made the tubes flicker) +- ArduinoOTA; Home Assistant integration rewritten for ArduinoHA 2.1 +- EU summer-time rules (upstream ended summer time on the US date); switching DST on no longer + shifts the clock by an hour in winter +- Saving the firmware URL no longer starts an HTTP update; optional web password +- Small fixes: PlatformIO build, MQTT message buffer overflow, cathode-protect random start, + LED gamma + +## Credits and license + +ESP_UniClock is © Peter Gautier and licensed GPL-3.0-or-later; the modified firmware in +`firmware/uniclock/` is under the same license. The libraries in `firmware/uniclock/lib/` keep +their own licenses. The board support, analysis and changes were made with +[Claude Code](https://claude.com/claude-code).