# tertiary

A three-piece keyboard: two mirrored halves plus a numpad/nav/media board that
also carries the USB hub. One cable reaches the computer.

Status: **design**. No boards ordered, no firmware written.

---

## The three boards

| Board | Qty | Keys | Carries |
|---|---|---|---|
| `hardware/half` | 2 (mirrored) | TBD — layout not designed | MCU, matrix, USB-C, SBU split link |
| `hardware/numpad` | 1 | 26 (17 numpad + 9 nav) | MCU, matrix, 2 encoders, **CH334R hub**, 3 downstream ports |

Cabling:

```
PC ──USB-C── numpad ──USB-C── left half
                     └─USB-C── right half
```

Both halves plug into the numpad. The numpad's hub gives each half a USB port,
and a **passive trace across the numpad shorts SBU between the two half ports**,
which is how QMK's split protocol gets from one half to the other. See below.

---

## Decisions, and why

### MCU: CH32L103C8T6, with an STM32F103C8T6 escape hatch

`C22398291`, LQFP-48, 62–64 K flash / 20 K SRAM, QingKe RISC-V4C.

**QMK does not support CH32.** Verified: zero issues or PRs mentioning CH32 in
`qmk/qmk_firmware` ever, and no `os/hal/ports/CH32` in ChibiOS-Contrib. Adding it
means a ChibiOS HAL port — PAL, ST, and critically a `usb_lld` for WCH's own USBFS
peripheral. Estimated 3–6 weeks of evenings; the USB driver is ~75% of it.

So the board is laid out to the **STM32F103C8T6 (`C8734`) footprint**, which the
L103 is pin-compatible with (same LQFP-48, `PC13`/`PC14`/`PC15`, `PD0`/`PD1` as
`OSC_IN`/`OSC_OUT`, `PA11`/`PA12` as USB DM/DP, `PA13`/`PA14` as SWDIO/SWCLK).
Populate the F103 and it works with stock QMK today; populate the L103 when the
port lands. Same board either way.

> ⚠️ **Unverified assumption the whole board rests on:** pin *names and functions*
> were confirmed identical from both datasheets, but the pin *numbering* was not —
> the PDFs interleave four packages and extract badly. **Overlay the two pinout
> drawings before routing.**

**Only one component differs between the two MCUs:** `R5`, a 1.5 kΩ pull-up on
D+. The F103 has no internal one. The L103 does (~1.5 kΩ, enabled via
`RB_UC_DEV_PU_EN` in `R8_USB_CTRL`) — so populate `R5` for F103, DNF for L103.

Buy three loose F103s and keep them in a drawer. When the first board doesn't
enumerate, hot-air one over and flash stock QMK: that tells you instantly whether
the fault is the PCB or your USB driver. Debugging both at once is where this
project would die.

### Why not RP2040

No internal flash, so it needs an external QSPI chip, a crystal, and fussy
decoupling — ~24 line items versus ~16. Modules (RP2040-Zero, $3.99) were the
first plan and are still viable, but bare silicon gives USB-C placement freedom
and no single-supplier risk.

### Why not crystal-less

Nothing in WCH's catalogue does spec-compliant crystal-less USB. Checked V203,
X035 and L103: all use factory-calibrated RC with manual `HSITRIM` and **no
SOF-based clock recovery anywhere in the family**. Accuracies run −1.0/+1.6 %
(V203), −1.7/+1.6 % (X035), ±1.6 % rising to ±2.2 % over full range (L103).
USB full-speed wants ±0.25 %.

WCH's own datasheet admits it: crystal-free "may deviate from the USB
specification, and are only applicable to non-precision occasions", and it's a
factory ordering option not enabled by default on stock parts.

The only genuinely crystal-less option found was **STM32F0x2** (HSI48 + CRS,
actively trimmed against host SOF packets) — rejected on stock: 773 units.

An 8 MHz crystal plus two caps is $0.12 and satisfies both MCUs' USB PLL.

### Hub in the numpad, not the right half

Keeps both halves the same design. The numpad is a one-off anyway and it's the
roomiest board. Cost: the numpad must be plugged in for the halves to reach the
computer — but each half has a complete USB stack, so any half can be plugged
directly into a machine when travelling.

**CH334R** (`C4154405`, QSOP-16, $0.50), 4 ports mapping exactly:

| Port | Destination |
|---|---|
| Upstream | PC |
| 1 | numpad's own MCU — internal trace, no connector |
| 2 | left half |
| 3 | right half |
| 4 | spare external |

CH334R has no port power switching (dropped in the 16-pin package), so each
downstream port gets a **CH213K** ideal diode for overcurrent — WCH's own
recommendation in the CH334 reference design.

Downstream ports are host-side: **56 kΩ Rp pull-*ups* on CC, not 5.1 kΩ Rd
pull-downs.** Getting this backwards means nothing enumerates.

### Split link over USB-C SBU

The 16-pin USB-C connector breaks out **SBU1 (A8) and SBU2 (B8)** and nothing
uses them. Each half ties SBU1+SBU2 together — **SBU is crossed inside the
cable**, so tying them makes the link orientation-proof and doubles the
conductor — and runs it through 100 Ω + ESD to a USART pin. The numpad shorts
the two half-ports' SBU nets with a passive trace.

Result: QMK `split_common` runs between the halves with no extra cable and no
TRRS.

> ⚠️ **Requires a full-featured USB-C cable.** Cheap USB 2.0 charge cables omit
> SBU entirely. Failure mode is nasty: power and USB work, only the split dies.
> **Put "USE A FULL-FEATURED CABLE" on the silkscreen.**

A 3-pin JST footprint is carried on both halves as **DNF insurance** if SBU
proves unreliable.

### Hotswap sockets, everything bottom-side

Kailh MX `CPG151101S11` (`C41430893`, $0.037, 93 k in stock — they *are* in JLC's
library). Sockets mount on the back, so put **all** SMD on the bottom: MCU,
passives, diodes, sockets. Single-sided assembly, one JLC setup instead of two.

**A plate is mandatory.** Without one, switch insertion flexes the PCB and tears
socket pads off. FR4 plate is just another JLC board.

Use [perigoso/keyswitch-kicad-library](https://github.com/perigoso/keyswitch-kicad-library)
for footprints — don't draw them.

### Mirrored board files, not a reversible PCB

The socket footprint isn't mirror-symmetric, so a reversible board needs two
socket footprints per key with one populated. Two mirrored layouts sharing one
schematic and one BOM is simpler and keeps everything that mattered.

### RGB: numpad underglow only

Per-key RGB is arithmetically impossible on a bus-powered hub. Each half sits on
a downstream port capped at 100 mA; 42 SK6812MINI-E at full white is 1.5 A, and
even 10 % brightness overruns the port. Real per-key RGB needs a self-powered hub
with an external supply — and probably a bigger CH334 variant, since the small
packages don't expose `PSELF`.

Numpad has ~355 mA to itself: about 9 LEDs at full white or ~30 at 30 %.

If any SK6812 is fitted: **3.3 V data into a 5 V part is out of spec** (Vih ≈
3.5 V). SK6812MINI-E is rated 3.7–5.5 V, so run the LED rail at ~4.3 V through a
series diode — Vih drops to ~3.0 V and you stay in spec.

---

## Firmware notes

Nothing written yet. Things already known:

**Do not use `SPLIT_USB_DETECT`.** Both halves are plugged into the hub, so both
would see VBUS and both would decide they're master. Set `MASTER_LEFT` (or
`MASTER_RIGHT`) at compile time. The peripheral still enumerates as an idle HID
device — expected, not a fault.

**Split pin:** `PA9` (USART1_TX) exists on both MCUs. QMK's half-duplex
`serial_usart` uses TX only, open-drain with pull-up.

**Numpad Num Lock handling.** Num Lock is global host state on Windows and Linux;
with it off, `KP_7` sends Home and the pad silently becomes a duplicate of the
nav cluster three inches away. macOS has no functional Num Lock (Apple keyboards
use Clear) and the pad always types digits there.

Plan is belt-and-braces:

1. One attempt per power-up to turn Num Lock on, fired from
   `housekeeping_task_user` (**never** from inside `led_update_user` — an
   unbounded loop there has been reported to brick a Moonlander), after a 500 ms
   settle so a transient enumeration report doesn't trigger a false correction.
2. Regardless of whether that took, resolve each keypad key at press time against
   `host_keyboard_led_state().num_lock` and emit the number-row keycode when Num
   Lock is off. Latch what was registered so the release matches if state flips
   mid-hold.

Only eleven keys need this (1–9, 0, `.`). `KP_SLASH`/`ASTERISK`/`MINUS`/`PLUS`/
`ENTER` mean the same thing either way.

**Encoders:** volume wants a **detented** EC11; scroll wants a **detentless** one,
because hi-res scrolling (`POINTING_DEVICE_HIRES_SCROLL_ENABLE`, resolution
multiplier, 1/120 tick) fights physical detents. Confirm the detentless SKU from
the datasheet — vendor descriptions are unreliable.

---

## Open questions

- **The layout.** Undesigned, and it's the only input the PCB can't defer. If a
  thumb layer on one half reaches keys on the other, the halves must be a QMK
  split. If each half is self-sufficient, they can be three independent
  keyboards. The hardware supports both — see `docs/104-key-split.svg` for how a
  104-key layout maps onto three boards, and note a straight chop gives 36 vs 39
  keys, so a symmetric core plus layers is needed for mirrored boards.
- Pin-number overlay of L103 vs F103 (above).
- CH334 internal crystal load-cap value vs the 20 pF-CL crystal — fit DNF cap pads.
- Whether AT32F415 is a better fallback than F103 (128 K/32 K vs 64 K/20 K, same price).

---

## TODO before this repo is made public

Per house convention. This one is unusually clean:

- [ ] Nothing here touches LAN topology, credentials, or personal data — no
      scrubbing needed, unlike most repos here.
- [ ] Confirm no JLC/LCSC account identifiers end up in fab exports.
- [ ] Decide on a licence before publishing hardware files (CERN-OHL-S or
      TAPR OHL for hardware; GPL2 for anything derived from QMK).