nixie-clock/CLAUDE.md

Nixie clock: notes for Claude

An AliExpress WiFi nixie clock (4x IN-12 + 2x IN-3 neon dots, 8x WS2812) that is being moved from its closed stock firmware to ESP_UniClock (https://github.com/gpeter62/ESP_UniClock) with ArduinoOTA and Home Assistant (MQTT) support.

The device

• On the network at 10.1.1.97 (WiFi dlink-iot). Stock web UI on port 80, nothing else open: no OTA, no API, no MQTT.
• Board: RetroModding (Konstantin Repnikov) "NixieIN12v2 HV2.0", stock firmware SV1.3 (©2020). ESP-12 (ESP8266, MAC 30:83:98:99:BF:DE, Espressif).
• Powered by USB-C 5 V only (no DC jack). Most likely the maker's "v2.0L lightweight 5 volt version". The user says the PCB looks different from the 12 V v2 board.
• No buttons fitted, only the light sensor.
• Stock settings (2026-10-25): time zone +01:00, EU DST on, NTP time.euro.apple.com, brightness auto, 24 h. Stock DST might not work: check in late March.

Stock firmware (from the flash dump)

• firmware/stock/nixie_stock_SV1.3_full_4MB.bin (gitignored), SHA-256 b069f4eb93cf1e9063a30374db4d70508211f07b0a17049bcf9ebdeda65f2985, verified against the chip with verify-flash. Flash: 4 MB, DIO, 40 MHz.
• Arduino ESP8266 core 2.x (NONOS SDK 2.2.2-dev), built for board ESP8266_NODEMCU. App at 0x1000 (~1 MB slot), SPIFFS at 0x200000. Settings live in SPIFFS as JSON (/config.json, /wifi.json, /light.json, /leds.json, /alerts.json, /hardware.json).
• Hidden pages: /d = "Hardware setting" (hidden from the menu by default). It has checkboxes to hide/show menu items and a Debug mode (dev) checkbox. With Debug mode on, /u serves the standard ESP8266HTTPUpdateServer upload form, which is web OTA for .bin/.bin.gz. /r reboots on a plain GET; don't GET unknown paths blindly.
• No pin numbers are visible as strings; confirming the pinout needs disassembly or the bit-stepping test sketch.

Pinout (from the 12 V v2 schematic, docs/schematic_v2_12V.jpg)

Not yet verified on this 5 V board. The stock firmware image is the same for both, which suggests the GPIOs match.

Function	GPIO
74HC595 DATA / CLOCK / LATCH (OE tied to GND)	13 / 14 / 15 (15 has 1k pull-down)
DS3231M RTC SDA / SCL	4 / 5
WS2812 data	12
Photoresistor (LDR, 10k to GND)	ADC (A0)
BTN1 / BTN2 (not fitted)	0 / 2

Two chained 74HC595s make one 16-bit word, all bits active-high:

• U1 QA..QH = cathodes 0..7, U2 QA = cathode 8, QB = cathode 9 (via 2x ULN2003, shared by all tubes)
• U2 QC = P1 (neon dot 1), QD..QG = anodes A1..A4 (MMBTA42/92), QH = P2 (neon dot 2, and the decimal point if jumper JP2 is closed)
• The display is multiplexed: one anode on at a time. Which physical tube is A1 is unknown.

Programming header

Header on the PCB: GND, GPIO0, RST, RXD, TXD, 3.3V. The USB-C port only supplies power. Flashing is done with a CH340C board on COM7 (COM3 is another device; leave it alone). Wiring: GND-GND, adapter TXD -> clock RXD, adapter RXD -> clock TXD, adapter 3.3V not connected (the clock is powered from its own USB-C). No auto-reset: to enter flash mode, hold GPIO0 to GND, tap RST to GND, then release GPIO0.

• esptool is installed for the user (python -m esptool, v5.6.0).
• firmware/stock/ holds the stock flash dump. Never overwrite or delete it; it is the only way back to SV1.3 (write-flash 0 <dump>). Dumps are gitignored because the flash holds the WiFi password; never commit them.

Constraints

• The 170 V tube supply is live whenever USB-C is connected.
• Hardware is only reachable via the user: anything that needs RST/GPIO0 or looking at the tubes must be asked of them. Builds can be checked here, but runtime behaviour can't.
• Show the exact plan before making changes to the device (flashing, saving settings).

Plan

1. Dump and inspect the stock firmware (version strings, pins if possible).
2. Write a test sketch that steps through the 16 shift-register bits, to verify the pinout and the tube order.
3. Add a 74HC595-multiplex driver + CLOCK config to ESP_UniClock, plus ArduinoOTA and Home Assistant controls (display on/off, brightness, LEDs); its stock MQTT only publishes sensors.
4. Work continues in VS Code (PlatformIO).