Clicky — Keyboard Controller

Built on the AVR128DB64 — the same controller as Sticky — Clicky scans the keyboard, decodes each press to UTF-8 on-chip, and reports it to DeMon over UART, available long before USB is up. It also drives the per-key NeoPixels, handles the 8 status NeoPixels and the buzzer on DeMon's behalf, and (on Ant64) reads a jog dial. The same Clicky firmware binary runs on Ant64 and eZX Spectrum; a board-strap pin selects the matrix-scan mode at boot. Fully reprogrammable by DeMon over UPDI at any time.

Overview

Clicky replaces the earlier RP2350A / QMK controller. With that change there is no RP2350 anywhere in the Ant64.

Same Firmware, Two Products

Clicky ships one firmware binary that runs identically on the Ant64 and the eZX Spectrum. This mirrors how Sticky already works — the 4 joypad ports are wired the same on both products, so one Sticky firmware covers both. Clicky now has the same property.

The selector is a single GPIO — KPRODUCT — read once at boot:

• Tied to 5 V on one product and GND on the other (polarity is firmware-defined; an internal weak pull-up means a floating pin during development falls back to a default mode)
• Read once during setup() to choose the matrix-scan code path
• Never read again — products don't change identity at runtime

What branches on the strap:

• Matrix-scan loop — Ant64 scans the 75% mechanical layout and reads the jog-dial rotary encoder; eZX scans the 8×7 matrix via the Sinclair column + row ribbons and the Spectrum Next keyboard extender, with no encoder
• Default keymap and lighting profile — different physical layouts need different startup defaults

What does not branch — identical bytes executing on both products:

• UTF-8 decode and event composition
• All QMK-equivalent keymap logic — layers, Mod-Tap, Tap Dance, Combos, Leader, Macros, Caps Word, Key Overrides, Repeat / Alt-Repeat, Autocorrect, Grave Escape, Space Cadet, Swap Hands, Key Lock, Bootmagic / Command, configurable debounce
• UART protocol to DeMon (event message format, intent message format)
• Configuration save/load model (Clicky as engine, DeMon as authority and store — see below)
• WS2812 chain driver (status LEDs + per-key NeoPixels)
• Buzzer PWM
• UPDI update path — update clicky ships one image; the strap reading on the target board decides which mode it runs in

One codebase, one CI pipeline, one test matrix, one set of features to track.

What Clicky Does

• Scans the keyboard matrix with Schottky-diode row/column sampling for fast, ghost-free reads. Matrix layout depends on the host product — see Keyboards below
• Decodes row/column → UTF-8 on-chip. Each key event sent to DeMon carries the event type, the raw row/column, and the decoded UTF-8 codepoint — so DeMon receives ready-to-use characters without a host-side keymap
• Reads a jog dial with push button (Ant64 only — the eZX has no rotary encoder)
• Drives the per-key NeoPixels — one WS2812 under each key — and the 8 status NeoPixels on DeMon's status panel, all on the same WS2812 chain. See NeoPixel Chain below
• Drives the buzzer on DeMon's behalf. DeMon sends tone-and-duration intent over UART2 and Clicky handles the PWM timing, so DeMon never has to. See Buzzer below
• Comes alive well before USB enumerates, so DeMon can read the built-in keyboard during early boot, recovery, and configuration — long before a USB HID stack is up. External USB keyboards remain supported through DeMon's USB host port

Keyboards

Ant64 — 75% Custom Mechanical

The production Ant64 keyboard is a 75% custom mechanical design with per-key RGB (NeoPixel) lighting, a rotary jog dial with button, and — where a numeric keypad would normally sit — a vertical TFT touch screen (its panel on/off and I²C touch-controller reset are on DeMon's MCP23017, PB7 / PB6). Matrix scanning uses Schottky diodes for fast row-to-column sampling.

The prototype uses an off-the-shelf AJAZZ AK820 — wired, 75% layout, 82 keys (83 including the rotary-knob button), per-key RGB, and a rotary control — connected to DeMon over USB; the production board moves the controller to Clicky.

Custom prototype key caps: https://yuzukeycaps.com/c/e47a4a66-6aed-4409-a54a-dcedb0a7a3aa

eZX Spectrum — Sinclair Ribbon + Spectrum Next Extender

The eZX Spectrum's keyboard interface follows the established Spectrum-community standards rather than ad-hoc pin headers, so existing Sinclair and Spectrum Next keyboards plug in directly with no adapter hardware:

Two keyboard generations are supported natively:

• An original Sinclair Spectrum membrane keyboard (the 48K rubber-key membrane or any aftermarket clone) plugs into the Sinclair column + row ribbon connectors. The Next extender stays empty; rows 5–6 are never driven. Get the original 40-key 5×8 Speccy layout
• A modern Spectrum Next-compatible 56-key keyboard uses all three connectors via the Next extender for the additional 2 rows. Get the extended 56-key 7×8 layout

Clicky autodetects which keyboard is connected by reading the row-drive lines at boot: if rows 5–6 produce no electrical response (extender unpopulated), Clicky assumes a 5-row Speccy keyboard and applies the 40-key default keymap. If rows 5–6 respond, the full 56-key matrix is scanned with the modern default keymap. Mid-session swap is unsupported — users plug their keyboard in before powering up.

The eZX keyboard has no rotary encoder — Spectrum-lineage keyboards have no integrated rotary control, and there's no separate jog-dial input device on the eZX (the Ant64's dedicated jog-dial controller, Crank, is not present on the eZX). The keyboard handles all menu navigation.

NeoPixel Chain

Clicky drives a single WS2812 data line that carries two logical groups of NeoPixels in one daisy-chained chain:

Because WS2812 is a single-data-line daisy-chain protocol, one Clicky GPIO carries the data for the whole chain. Each LED reads the first 24 bits (or 32 bits for RGBW), then forwards the remainder downstream — so the 8 status LEDs read their values first, the keyboard LEDs read theirs after. Clicky composes both groups into a single contiguous frame per refresh.

Logical addressing. Clicky's firmware exposes the chain to DeMon as two logical address spaces — status[0..7] for the 8 status LEDs and key[row][col] (or key[index]) for the keyboard. DeMon doesn't care about the physical wire order; it addresses each LED by its logical name and Clicky maps that onto the right slot in the contiguous WS2812 frame.

Two refresh strategies share the same chain:

• DeMon-owned status LEDs update on subsystem state changes — power-on, SD insertion, network activity, MIDI traffic. DeMon sends "set status LED N to colour C" intent over the UART; Clicky updates that slot in the frame and triggers a chain redraw. Event-driven, not animated
• Keyboard NeoPixels can be either DeMon-driven (per-keystroke feedback flashes, keymap-layer indicators) or autonomously animated by Clicky (idle breathing patterns, modifier-shift indication, AntOS busy spinner, Velocikey). Clicky's 60 Hz frame loop composes any in-progress animation with the latest DeMon status-LED state into one outgoing frame

DeMon's "still controlling but not driving" model means the status LEDs behave exactly as if they were on DeMon's own GPIO, but the WS2812 timing and bus contention are entirely Clicky's problem. DeMon never bit-bangs a WS2812 frame; Clicky never decides what a status LED should mean.

Buzzer

A passive piezoelectric buzzer is wired directly to a Clicky GPIO. Clicky generates the square-wave PWM that drives it, varying the frequency to produce different tones and the duration to produce different note lengths.

DeMon sends short UART messages describing the tone intent:

Clicky maintains a small queue so DeMon can pre-load a short sequence ("boot chime" = 3 tones over 500 ms) with one UART message and let it play out without further intervention. This keeps DeMon's UART traffic low even during multi-note feedback sequences.

The buzzer is the system-level user-feedback channel — the audio path that works before the main audio stack is up (power-on chime), after AntOS has parked the audio stack (shutdown beep), and orthogonally to whatever the main audio system is doing (low-battery warning during music playback). After AntOS boot and the main audio stack spinning up, most audio output goes through the Tempest mixer to the WM8958/WM8960 codec; the buzzer is reserved for feedback that should be hearable even with headphones unplugged.

Clicky's firmware also uses the buzzer for keyboard-behaviour feedback: a key click on press (optional, off by default), a beep on layer or Caps-Word changes, a locked/error tone, alongside the tone-and-duration intents DeMon sends.

DeMon ↔ Clicky Interface

DeMon-side pins are in demon.

Default baud rate is 115200 with optional hardware flow control (RTS/CTS). For high-throughput keymap or NeoPixel buffer uploads the link can negotiate up to ~1 Mbps on the AVR128DB64's UART; the default rate is sufficient for all routine traffic.

Event message format

Each key event from Clicky to DeMon is a single message containing four fields:

The exact byte-level framing (binary with length prefix vs ASCII-escaped JSON vs SLIP-style framing) is an implementation detail of the firmware; the four fields above are the architectural contract.

Intent message forms (DeMon → Clicky)

Firmware Features

Clicky's firmware reproduces the keyboard-behaviour surface of QMK — everything about how a keyboard interprets presses — done entirely on-chip and reported to DeMon over UART2 rather than presented as USB-HID. It drops only the parts that were never Clicky's job (screens, wireless, multi-speaker audio).

Keymap & layer logic — handled on-chip, independent of the transport:

• Layers — the keymap is built from stacked overlays, like a generalised Fn key. Switching layer makes every physical key do something different, so a compact board reaches far more than its key count. Layers can be momentary (active only while a key is held), toggled on and off, one-shot (active for just the next keypress), entered by a tap-or-hold key, set as the default base, or combined so that holding two layers activates a third (tri-layer).
• Mod-Tap and tap-hold tuning — a dual-function key that types a normal character when tapped but acts as a modifier (Shift, Ctrl…) or layer when held, so a home-row key can double as Shift. The "tuning" is the set of timing rules that decide tap-versus-hold cleanly: the tapping term (how long a hold must last), permissive hold and hold-on-other-key-press (treat another keypress as the hold signal), quick tap, and retro tap — adjustable globally or per key.
• One-Shot keys and modifiers — "sticky" keys: tap Shift once and it applies to just the next key, then releases itself, so you never have to hold a modifier down.
• Tap Dance — one key that does different things depending on how many times you tap it (or tap then hold): e.g. one tap (, two taps [, hold {.
• Combos — pressing two or more keys at the same instant produces a separate action from any of them alone — chording, for symbols or shortcuts without a dedicated key.
• Leader key — press a dedicated leader key, then type a short sequence, and Clicky runs the action bound to it (the keyboard version of Vim's leader): leader, then c, a could launch the calculator.
• Macros and dynamic macros — a single key sends a whole string of keystrokes. Fixed macros are defined ahead of time; dynamic macros are recorded live on the keyboard itself and replayed on demand.
• Auto Shift — hold a key a fraction longer to get its shifted form instead of reaching for Shift: a quick tap of a gives a, a slightly longer hold gives A.
• Caps Word — a smart one-word caps lock that capitalises until you type a space or punctuation, then switches itself off — made for CONSTANT_NAMES without leaving caps lock on.
• Key Overrides — redefine what a modifier-plus-key combination emits (say Shift + 1 producing something other than !) without disturbing the base key.
• Repeat / Alternate-Repeat — a key that re-sends your last keypress, plus an "alternate" variant that sends its logical opposite (after → it sends ←).
• Autocorrect — fixes common typos as you type, from a small on-board dictionary (e.g. "teh" → "the").
• Grave Escape — lets one key serve as both Esc and the grave/tilde key, choosing between them by modifier state — handy on compact boards with no room for both.
• Space Cadet — the Shift keys gain a second job: a quick tap of left Shift types ( and right Shift ), while holding them still shifts normally.
• Swap Hands — temporarily mirrors the layout left-to-right so the board can be typed one-handed while a key is held.
• Key Lock — press once to hold a key or modifier "down" until it's pressed again — useful for holding a game key or for one-finger operation.
• Bootmagic / Command — change settings without reflashing: hold chosen keys at power-on (Bootmagic), or a key combo at runtime (Command), to swap modifiers, toggle options, or drop into the bootloader.
• Configurable debounce — a mechanical switch "bounces" (makes and breaks several times in a millisecond); the debounce algorithm filters that so one physical press is one clean event, with the method and timing tunable.

Cleaner on UART than on USB — being a UART peer of DeMon rather than a USB-HID device improves three things outright:

• Full N-key rollover — every key registers independently no matter how many are already held, with no ghosting or blocking. USB's boot protocol caps this at six keys; the UART event stream has no such limit, so fast typing and gaming chords all come through. (On the eZX this matters especially for Spectrum games that read multi-key chords via IN $FEFE half-rows in tight game loops.)
• Native Unicode — Clicky already ships a real UTF-8 codepoint with each event, so accented and non-Latin characters just work, without the OS-specific input-method tricks QMK needs over USB.
• Live remap (VIA-style) — DeMon can change the keymap, build macros and combos, set the encoder map and tap-hold timings, and adjust lighting on the fly, with Clicky applying it immediately and no reflash — then saving it (below).

Lighting — on the WS2812 chain Clicky drives:

• Per-key RGB matrix — individually addressable lighting under every key, with animations and typing-reactive effects (keys can light as they're pressed); the same LEDs can also act as indicators for caps, active layer, and so on.
• Status pixels — the eight status LEDs at the head of the chain double as indicator lights, driven by Clicky on DeMon's behalf — DeMon sends colour intent for system states (power / SD activity / network / Wi-Fi / Bluetooth / MIDI / etc.) and Clicky composes them into the same outgoing frame as the keyboard lighting.
• Velocikey — the lighting animation speeds up or slows down with how fast you're actually typing.

Audio — buzzer only. No twin speakers, no MIDI, no music mode — just feedback tones on the single buzzer: a key click, a beep on layer or Caps-Word changes, a locked/error tone, a startup chime — alongside the tone-and-duration intents DeMon already sends.

Encoder — the jog dial. (Ant64 only.) The rotary dial is mapped per layer, so turning it clockwise or anticlockwise can do different things on each layer (volume, scroll, brightness, zoom…), and the knob's push button is a fully configurable key, layer switch, or macro. The eZX has no integrated rotary control and no Crank chip, so this feature is absent there — encoder-mapped layer behaviour on the eZX uses keyboard chords or modifier combinations instead.

Speccy compatibility mode. (eZX only.) The eZX-specific decoder mode for running Spectrum software that expects the original keyboard semantics:

• Standard key events are emitted as UTF-8 codepoints exactly like the modern mode
• Spectrum BASIC keyword chords — the CAPS SHIFT and SYMBOL SHIFT combinations that the original Spectrum uses to enter BASIC keywords (PRINT, LET, GOTO, etc.) are resolved on Clicky and the keyword's Unicode equivalent is emitted as a single event. Applications that want the raw chord (modifier + base key) rather than the resolved keyword can switch to a "raw chord" sub-mode
• Raw matrix dumps on request — Spectrum applications that read the keyboard via IN $FEFE (and the floating-bus quirks around it) need bit-exact half-row matrix state, not UTF-8 events. Clicky exposes a polling endpoint that returns the current 5×8 matrix bitmap on demand; the running Classic-image core's IN $FEFE emulation reads this directly. For 56-key modern keyboards in Speccy mode, only the lower 5 rows participate in the IN $FEFE dump — the extra 2 rows return idle, preserving bit-exact Speccy compatibility

Not included: screen drivers (OLED / LCD — Clicky drives no screen; the vertical touch TFT on Ant64 is DeMon's), Bluetooth (DeMon / C5's job), split-keyboard, PS/2 mouse, thermal printer, the pointing-device driver framework, mouse keys (moving the cursor from the keyboard), haptic feedback (a buzzing solenoid or motor in the case), and music-mode / MIDI audio. Stenography — a Plover-style chord mode for machine shorthand — is left as an optional future mode.

Configuration — Save / Load via DeMon

Clicky holds its active configuration — keymap and layers, macros, combos, tap-dance, leader sequences, encoder map (Ant64), tap-hold timings, lighting, Speccy-compat-mode flag (eZX) — in working memory, and DeMon owns the persistent copy. A small protocol over UART2 keeps the two in sync:

• Boot — Clicky comes up immediately on a built-in default held in its own EEPROM, so the keyboard works before DeMon is ready. The default is product-aware: 75% mechanical default on Ant64, Spectrum-style default on eZX (40-key or 56-key per autodetect). Once the UART link is up, DeMon loads the saved configuration down to Clicky, which applies it in place
• Save — when a config changes (a live remap, a recorded macro, a lighting tweak), Clicky sends the updated configuration up to DeMon, which writes it to persistent storage (DBFS). A user key combo can also force a save
• Load on demand — DeMon can push a different stored profile at any time — per-user or per-application keymaps, say — and Clicky swaps to it without a reset. Useful examples: a speccy profile for retro-compat work on the eZX, a code profile for AntOS shell sessions, a game profile with tighter debounce and gaming-favourable layer assignments

DeMon is the authority and the store; Clicky is the engine. The same link that carries key events and lighting intents carries these config transfers, so no extra wiring is needed.

Programming

Clicky is UPDI-programmed directly from DeMon. The UPDI line runs from DeMon's io45 to Clicky's UPDI pin; DeMon bit-bangs the single-wire UPDI protocol to upload firmware, fuse settings, and read back verification data.

The flow is simpler than Sticky's UPDI path (which goes through Pulse — the SPI peer link to Pulse is used because Sticky sits next to Pulse, not DeMon):

• DeMon holds the firmware file in DBFS, parses it (Intel HEX / ELF), extracts the program bytes and fuse settings
• DeMon bit-bangs UPDI directly to Clicky — no Pulse intermediary, no SPI-to-UPDI translation
• The user-facing entry point is the AntOS update clicky command
• During UPDI the keyboard, NeoPixel chain, and buzzer are all unavailable; AntOS warns the user before initiating the update if there are no other input methods configured (e.g., a USB keyboard on DeMon's hub)

UPDI is used for firmware update and possible debug only. Normal keyboard, NeoPixel, and buzzer traffic flows over the UART2 link.

OCD-level debug (single-step, breakpoint, register inspection on the AVR core via pyupdi-style tooling) is the natural extension if it's ever needed; the bit-bang transport supports it. Initial implementation is programming only.

Pin Naming

Curiosity Nano Pinout (eZX prototype layout)

Pin assignments are provisional and will be finalised during board layout. The shape and signal count are firm; specific pin-to-signal mappings may change as the PCB routing settles. The Ant64 production board uses the same chip with a different pin-to-signal mapping reflecting the 75% mechanical matrix and the rotary encoder; the dev-kit pinout below shows the eZX configuration.

The 8 column lines sit on port A and the lower bytes of port F, matching the layout Sticky uses for its DB9 column lines — both AVRs have the same physical port footprint on the prototype kit, simplifying parallel development. The 7 row lines plus the LED data line sit on port D, which has internal drive capability and clean timing for the WS2812 protocol's 800 kbit/s serial output. UART signals sit on port E. The buzzer output sits on port C using a TCA-timer-capable pin so Clicky can drive the buzzer with hardware-PWM precision. The product-strap pin sits on a spare port C pin with a weak internal pull-up. The UPDI line shares the AVR's dedicated UPDI pin, wired directly to a DeMon GPIO for in-circuit programming.

Future considerations

• Stenography mode — Plover-style chord input for machine shorthand. Clicky's UTF-8 output already passes raw codepoints to DeMon, and the chord-resolution machinery for Speccy BASIC keywords is the same shape needed for steno output. Listed in the "not included" set above as an optional future mode
• LED brightness limiting — total NeoPixel current draw scales with brightness × LED count; for 8 status + 56 keyboard LEDs at full white the draw approaches 3.8 A. Production firmware caps total current via per-LED brightness scaling; the cap is configurable from DeMon so users can trade visibility for power consumption
• Higher UART baud rates for fast keymap reloads or live-debug matrix streaming — the AVR128DB64's UART supports rates up to ~1 Mbps with care taken on clock accuracy; the default 115200 baud is sufficient for routine use
• Per-key haptic feedback — a small actuator under each key could give tactile confirmation of keypresses on a membrane-style keyboard. Not currently planned; pin budget allows it
• Programmable key remapping in EEPROM — Clicky's on-chip EEPROM (512 bytes) holds a small per-user keymap override applied at the scanner level before reporting to DeMon. Useful for keeping user remaps persistent across power cycles without DeMon involvement at every boot; the AntOS clicky CLI exposes the editor