A truly modular keyboard
Keyword host protocol (v1)
How the desktop app talks to the Keyword. The same protocol runs over USB and Bluetooth.
Transport
- USB: CDC ACM (virtual serial port), USB ID
0483:5740with the product stringKeyword.- The baud rate is ignored.
- Events are pushed once DTR is set or the host has sent a line.
- Bluetooth LE: Nordic UART Service.
- The 128-bit UUID isn't in the advertising packet, so scan for names starting with
Keyword. - Writes to RX need an encrypted, bonded link, so the host pairs first. The app pairs when it connects.
- Service
6e400001-b5a3-f393-e0a9-e50e24dcca9e - RX
6e400002-…(the host writes here, in chunks of 20 bytes or less) - TX
6e400003-…(the Keyword notifies here)
- The 128-bit UUID isn't in the advertising packet, so scan for names starting with
- Framing: ASCII lines ending in
\n.\r\nand a bare\rare also accepted, so terminal programs work. Over BLE a line can be split across several notifications, so the host buffers until it sees\n. - Fields are
name=valuepairs separated by spaces. Hex values are uppercase, and either case is accepted.
Keys
Each Keybit is identified by its full 96-bit CH32V003 UID. The Keybit holds it at registers 0x10..0x1B, little-endian, and the protocol prints it as 24 uppercase hex digits, MSB first (for example 3B0A4F1C88D2E61F5F1821C1). The app also accepts an 8-digit UID.
Profiles are keyed by UID and never by I2C address, because the Keyword can reassign an address.
at is the Keyword side the Keybit is on: L (left), R (right) or T (top edge).
Keybits relayed through other Keybits are reported as KEY+ uid=<uid> at=X via=<uid> depth=<n>:
viais the next Keybit toward the Keyword, anddepthis the number of hops.- The relay only carries the low 32 bits of the UID. So
uidis 8 hex digits unless the Keyword has seen that Keybit directly or holds a mapping for it. MAPwith an 8-digit UID stores a low-32 mapping. A stored 24-digit mapping also matches a relayed Keybit with the same low 32 bits.- The app maps an 8-digit UID onto a full UID it already knows. When it first sees a Keybit's full UID, it carries over any setup saved under the short one.
Host → Keyword
| Command | Reply |
|---|---|
HELLO |
KEYWORD v=<fw> proto=1 |
SIDES? |
SIDES L=<0|1> R=<0|1> T=<0|1> |
KEYS? |
one KEY+ uid=<uid> at=<L|R|T> per present Keybit, then KEYS END |
MAP uid=<uid> mods=<2hex> key=<2hex> |
OK MAP uid=<uid> |
MAPC uid=<uid> usage=<4hex> |
OK MAPC uid=<uid> (media key) |
MAP? uid=<uid> |
MAP uid=<uid> mods=<2hex> key=<2hex> (00/00 if unmapped), or MAPC uid=<uid> usage=<4hex> for a media key |
UNMAP uid=<uid> |
OK UNMAP uid=<uid> |
CLEAR |
OK CLEAR (drop every mapping, both kinds) |
SAVE |
OK SAVE (write the table to flash) |
| anything invalid | ERR <text> |
modsis the HID boot keyboard modifier byte:- bit 0 = LCtrl, 1 = LShift, 2 = LAlt, 3 = LGUI (Cmd/Win)
- bits 4 to 7 are the right-hand versions of the same keys
keyis a HID keyboard usage ID (page 0x07):04= A,3A= F1,68= F13.key=00with onlymodsset is a valid mapping.usageinMAPCis a Consumer page (0x0C) usage:00CD= play/pause,00E9= volume up,00E2= mute.- Each Keybit has one mapping, so
MAPCreplaces aMAPfor that UID andMAPreplaces aMAPC.UNMAPclears either kind. - When a mapped Keybit is pressed, the Keyword sends a keyboard report with
modsandkey, or a consumer report withusage.
Keyword → host (unsolicited)
| Line | When |
|---|---|
SIDES L=.. R=.. T=.. |
any side changes (after debounce) |
KEY+ uid=<uid> at=<L|R|T> |
a Keybit is attached |
KEY- uid=<uid> |
a Keybit is removed |
PRESS uid=<uid> down=<0|1> |
a Keybit is pressed or released |
BACKWARDS uid=<uid> sides=<letters|?|-> |
a Keybit sees another Keybit turned the wrong way round on those of its own sides (N, E, S, W). ? when it is further out and only known to have one, - once it's fixed. Needs Keybit firmware v6 |
ERR bus SDA held low, ... |
SDA has been held low for 100 ms: usually a Keybit on the Keyword turned the wrong way round. The Keyword stops polling until it clears (one retry a second) and blinks red |
OK BUS clear |
the bus is free again after that |
Optional features (v1 extensions)
The Keyword lists the features it supports in HELLO's caps. The app only sends a command when its capability is listed, and hides or greys out the matching UI when it isn't.
KEYWORD v=<fw> proto=1 caps=<comma list> kb=<n> macro=<n>
capscan includebatt,hold,macro,flashandota.otais listed only while the BLE stack runs on CPU2.kbis the version of the Keybit image the Keyword carries. A Keybit reporting a lowervis shown as outdated.macrois the most steps aMACROtakes (64 now). Firmware without it takes 16, and the app cuts macros to that.KEY+may carryv=<n>, the Keybit firmware version (Keybit register 0x01).
| Cap | Host → Keyword | Reply / unsolicited |
|---|---|---|
batt |
BATT? |
BATT pct=<0-100> chg=<0|1> usb=<0|1>, also pushed when pct moves by 5 or chg/usb changes |
hold |
HOLD uid=<uid> mods=<2hex> key=<2hex> ms=<dec> |
OK HOLD uid=<uid> |
macro |
MACRO uid=<uid> seq=<MMKK,MMKK,…> |
OK MACRO uid=<uid> |
flash |
FLASH uid=<uid> |
FLASH uid=<uid> pct=<n> progress, then OK FLASH uid=<uid> or ERR flash <reason> |
| ota | OTA | OK OTA, then the Keyword restarts into the OTA bootloader after about 500 ms. ERR no BLE stack on CPU2, use DFU if it can't |
| (any) | DFU | OK DFU, then the Keyword restarts into the ROM USB DFU bootloader |
| (any) | STACK? | STACK ble v=1.24.0 fus=2.2.0, STACK none fus=<x.y.z> or STACK unknown |
| (any) | BOOTCFG? | BOOTCFG nBOOT0=<0\|1> nSWBOOT0=<0\|1> nBOOT1=<0\|1> RDP=0x<2hex> |
| (USB serial only) | BOOTLOCK yes | OK BOOTLOCK, reloading option bytes, then a reset that boots from flash only (BOOT0 ignored). OK BOOTLOCK already, or ERR <reason> before the app has run 10 s, without the BLE stack, or when RDP isn't level 0 |
How each one behaves:
- Hold (tap/hold).
- If the key is released within
ms, the normalMAP/MAPC/MACROaction fires on release. - Held longer than that, the hold action stays pressed until release.
mods=00 key=00clears the hold action, and so doUNMAPandCLEAR.
- If the key is released within
- Macro.
- Each
MMKKis one tap: modifier byte, then key usage. There are up tomacrosteps fromHELLO(16 on older firmware). - A step takes 10 ms to type, so 64 steps is about 0.65 s.
- Long macros count against the 4 KB flash page the keymap is saved in. If it would outgrow it, the reply is
ERR keymap full. That's at about 26 macros of 64 steps. - A macro replaces
MAP/MAPCfor that UID, andUNMAPclears it.
- Each
MAP?can answer with several lines for one key: aMAP,MAPCorMACROline, followed by aHOLDline if a hold action is set.- Programming a single key, the app sends
UNMAP, then the key's commands, thenSAVE. That way a stale macro or hold never survives an edit.
Keyword firmware update (BLE OTA)
After OK OTA the Keyword erases its app (4-5 s) and restarts into ST's BLE_Ota bootloader. That works whichever link sent OTA, but the image itself always goes over Bluetooth.
- Finding it: it advertises as
Keyword OTA, at the Keyword's BD address + 1, with ST manufacturer data (device ID 0x86). No pairing is needed. - GATT: service
0000fe20-cc7a-482a-984a-7f2ed5b3e58f- Base address
0000fe22-8e22-4541-9d4c-21edae82ed19: write without response, 4 bytes[cmd, offset>>16, offset>>8, offset], offset from 0x08000000. Start =02 00 70 00, finish =07 00 00 00, cancel =08 00 00 00. - Raw data
0000fe24-8e22-4541-9d4c-21edae82ed19: write without response, up to MTU-3 bytes per write, appended in order. - Confirm
0000fe23-8e22-4541-9d4c-21edae82ed19: indicate, 1 byte,01when the image is accepted.
- Base address
- Sequence: connect, enable indications on fe23, write start, stream
firmware/release/keyword_app.binto fe24, write finish, wait for01. The Keyword then restarts into the new app. A bad image brings it back asKeyword OTA. - Pacing: there's no flow control, so the host waits about 3 ms per 248 bytes, the bootloader's flash time.
How the app does it (Settings → Update Keyword firmware…, or File → Update Keyword Firmware…):
- It checks the file first: a Cortex-M vector table whose reset handler is inside 0x08007000 plus the image size. That rejects
keyword_full.bin, which is for USB DFU. - It sends writes of 240 bytes (176 on macOS, whose usual MTU is 185), stepping down to 176 and then 16 if the first write is refused. Every write is a multiple of 8, and the last one is padded with
FF, because the bootloader programs flash 8 bytes at a time. - On macOS it waits 20 ms after each write. macOS drops write-without-response packets that come faster (a run of 131 × 176 B went missing at 4 ms).
- If the Keyword reports no BLE stack, the app offers Restart into USB DFU instead. After DFU, flash with STM32CubeProgrammer and replug. Never use
-g,:leave,-startfusor-fwupgradeover USB DFU: they rewrite nSWBOOT0 and can lock the Keyword out of DFU. - With no Keyword connected, it goes straight to finding
Keyword OTA, so it can recover a Keyword stuck in the bootloader.
Computer actions (no protocol)
Some actions run on the computer rather than on the Keyword: open a URL, open an app, run a command, or switch profile.
- The app stores them only in its profile and never sends them to the Keyword.
- It reacts to
PRESS … down=1for that UID, so these keys work only while Keyword Monitor is running.
How the app uses it
- On connect, the app sends
HELLO,SIDES?andKEYS?, waits for theKEYWORDreply (so it knowscaps), then pushes the active profile:CLEAR, the commands for each key, thenSAVE. Firmware can skip the flash write when the table is unchanged. - While connected, it polls
SIDES?every 2 s,KEYS?every 10 s andBATT?every 30 s (withbatt), in case an unsolicited line was missed. - Profiles live only in the app. The Keyword holds just the current table.
Side detection (Keyword ↔ Keybit, I2C)
The full Keybit side is in firmware/keybit/README.md. In short:
- One shared bus on the Keyword. All three Keyword side joints sit on the same I2C bus (I2C3: left U5/U6, right U4/U7, top edge U13/U15).
- Four separate buses on the Keybit. Each Keybit has its own bit-banged bus per side.
- Addressing. A new Keybit answers on 0x30. The Keyword reads its UID, then assigns it an address from 0x08..0x77, which the Keybit keeps in flash. If several new Keybits answer at once, they arbitrate by UID.
- Which side. Register 0x07 returns the Keybit side the request arrived on, as
N,E,SorW. The Keyword maps that to its own side:
| Keybit side (reg 0x07) | Keyword side |
|---|---|
E |
L: the Keybit is on the Keyword's left |
W |
R: right |
S |
T: top edge |
A Keybit can only mate upright, since rotating it would land its SDA on the Keyword's SCL. So the side it reports always maps to exactly one Keyword side.