A truly modular keyboard
C
app: media keys, BLE pairing and name-only scan
Nathand26d9fdcd776
diff --git a/app/PROTOCOL.md b/app/PROTOCOL.mdindex 882dea4..03b49ef 100644--- a/app/PROTOCOL.md+++ b/app/PROTOCOL.md@@ -5,7 +5,9 @@ How the desktop app talks to the Keyword. The same protocol runs over USB and Bl## Transport- **USB:** CDC ACM (virtual serial port). The baud rate is ignored.-- **Bluetooth LE:** Nordic UART Service, with the advertised name starting with `Keyword`.+- **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)@@ -28,9 +30,10 @@ Only Keybits that touch the Keyword directly are visible. `at` is the Keyword si| `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>` |-| `MAP? uid=<uid>` | `MAP uid=<uid> mods=<2hex> key=<2hex>` (`00`/`00` if unmapped) |+| `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) |+| `CLEAR` | `OK CLEAR` (drop every mapping, both kinds) || `SAVE` | `OK SAVE` (write the table to flash) || anything invalid | `ERR <text>` |@@ -39,7 +42,9 @@ Only Keybits that touch the Keyword directly are visible. `at` is the Keyword si- bits 4 to 7 are the right-hand versions of the same keys- `key` is a HID keyboard usage ID (page 0x07): `04` = A, `3A` = F1, `68` = F13.- `key=00` with only `mods` set is a valid mapping.-- When a mapped Keybit is pressed, the Keyword sends a HID report containing `mods` and `key`.+- `usage` in `MAPC` is a Consumer page (0x0C) usage: `00CD` = play/pause, `00E9` = volume up, `00E2` = mute.+- Each Keybit has one mapping, so `MAPC` replaces a `MAP` for that UID and `MAP` replaces a `MAPC`. `UNMAP` clears either kind.+- When a mapped Keybit is pressed, the Keyword sends a keyboard report with `mods` and `key`, or a consumer report with `usage`.## Keyword → host (unsolicited)@@ -52,7 +57,7 @@ Only Keybits that touch the Keyword directly are visible. `at` is the Keyword si## How the app uses it-- **On connect,** the app sends `HELLO`, `SIDES?` and `KEYS?`, then pushes the active profile: `CLEAR`, one `MAP` per key, then `SAVE`. Firmware can skip the flash write when the table is unchanged.+- **On connect,** the app sends `HELLO`, `SIDES?` and `KEYS?`, then pushes the active profile: `CLEAR`, one `MAP` or `MAPC` per key, then `SAVE`. Firmware can skip the flash write when the table is unchanged.- **While connected,** it polls `SIDES?` every 2 s and `KEYS?` every 10 s, in case an unsolicited line was missed.- **Profiles** live only in the app. The Keyword holds just the current table.diff --git a/app/README.md b/app/README.mdindex 19ab581..a5d6f6b 100644--- a/app/README.md+++ b/app/README.md@@ -28,11 +28,12 @@ They cover the protocol parser, the HID key table and profile import/export.## Using it-- **USB serial / Bluetooth:** pick the Keyword from the list. ST devices (USB VID 0483) and BLE names starting with `Keyword` are highlighted.+- **USB serial / Bluetooth:** pick the Keyword from the list. Bluetooth pairs the first time, which the Keyword requires. ST devices (USB VID 0483) and BLE names starting with `Keyword` are highlighted.- **Keys:** every Keybit the Keyword reports, with its side, its UID and what it's assigned to.- A key lights up while it's held.- Keys from the profile that aren't attached right now show greyed out.- **Assign…:** press the key or shortcut you want, for example `Ctrl+Shift+K`, `Cmd+Space` or `F13`. Modifiers on their own work too.+ - Media keys (play/pause, volume, mute, brightness and so on) are in the key list under **Media**, or you can press them.- For combos the OS grabs first, like Cmd+Tab, tick the modifiers and pick the key from the list instead.- You can also give the key a name.- **Profiles:** edits save automatically to `profiles.json` in the app's user-data folder. Switching profiles sends the new keymap to the Keyword.@@ -47,10 +48,11 @@ They cover the protocol parser, the HID key table and profile import/export.The app is ready, but the Keyword firmware doesn't speak this protocol yet:-- USB CDC, the BLE Nordic UART Service, the I2C3 side scan and the keymap table still need adding on the Keyword.+- The BLE side (HID keyboard, Nordic UART Service and keymap table) is done in the Keyword firmware.+- USB CDC isn't there yet, so for now connect over Bluetooth.- The Keybit side (assigned addresses, and the side register 0x07) lives in `firmware/keybit/`.-Until then, use **Demo**.+**Demo** works without any firmware.## Ways to detect a Keybit's sidediff --git a/app/main.js b/app/main.jsindex c096c3f..2290f05 100644--- a/app/main.js+++ b/app/main.js@@ -43,6 +43,13 @@ function createWindow() {ses.setDevicePermissionHandler((details) =>['serial', 'bluetooth'].includes(details.deviceType));+ // The Keyword's NUS needs an encrypted link. macOS pairs through its own prompt;+ // on Windows and Linux Electron asks us, and the user already picked the device.+ ses.setBluetoothPairingHandler((details, callback) => {+ if (details.pairingKind === 'providePin') callback({ confirmed: false });+ else callback({ confirmed: true });+ });+ses.on('select-serial-port', (event, portList, _wc, callback) => {event.preventDefault();finishPick(''); // cancel any older pickerdiff --git a/app/renderer/app.js b/app/renderer/app.jsindex 466f854..fd60fc6 100644--- a/app/renderer/app.js+++ b/app/renderer/app.js@@ -1,5 +1,5 @@/* global KeywordProtocol, Hid, Profiles */-const { SIDES, NUS, LineBuffer, parseLine, cmd, profileCommands } = KeywordProtocol;+const { SIDES, NUS, LineBuffer, parseLine, cmd, mapCommand, profileCommands } = KeywordProtocol;const POLL_MS = 2000; // ask for SIDES? this often in case a push was missedconst KEYS_POLL_MS = 10000; // full KEYS? resync@@ -67,7 +67,8 @@ class BleTransport {label = 'Bluetooth';async open(onText, onClose) {this.device = await navigator.bluetooth.requestDevice({- filters: [{ namePrefix: 'Keyword' }, { services: [NUS.service] }],+ // NUS's 128-bit UUID isn't advertised, so match on the name.+ filters: [{ namePrefix: 'Keyword' }],optionalServices: [NUS.service],});this.device.addEventListener('gattserverdisconnected', () => { if (!this.closed) onClose(); });@@ -124,6 +125,7 @@ class DemoTransport {for (const s of SIDES) if (this.present[s]) this.emit(`KEY+ uid=${this.uids[s]} at=${s}`);this.emit('KEYS END');} else if (c === 'MAP') { this.maps[f.uid] = f; this.emit(`OK MAP uid=${f.uid}`); }+ else if (c === 'MAPC') { this.maps[f.uid] = f; this.emit(`OK MAPC uid=${f.uid}`); }else if (c === 'UNMAP') { delete this.maps[f.uid]; this.emit(`OK UNMAP uid=${f.uid}`); }else if (c === 'CLEAR') { this.maps = {}; this.emit('OK CLEAR'); }else if (c === 'SAVE') this.emit('OK SAVE');@@ -172,7 +174,8 @@ const shortUid = (uid) => uid.slice(-4);const keyName = (uid) => activeProfile().keys[uid]?.name || `Keybit ${shortUid(uid)}`;const comboFor = (uid) => {const m = activeProfile().keys[uid];- return m && (m.mods || m.key) ? Hid.comboLabel(m.mods, m.key, MAC) : '';+ if (!m) return '';+ return m.consumer ? Hid.consumerLabel(m.consumer) : Hid.comboLabel(m.mods, m.key, MAC);};function addKey(uid, at, quiet) {@@ -400,28 +403,38 @@ chooser.addEventListener('cancel', () => window.devicePicker?.pick(''));const assign = $('#assign');const capture = $('#capture');let assignUid = null;-let draft = { mods: 0, key: 0 };+let draft = { mods: 0, key: 0, consumer: 0 };$('#assign-mods').append(...Hid.MODS.map((m) =>el('label', {}, el('input', { type: 'checkbox', value: m.bit }), Hid.modName(m, MAC))));-$('#assign-key').append(el('option', { value: 0, textContent: '(no key, modifiers only)' }),- ...Hid.KEYS.map((k) => el('option', { value: k.usage, textContent: k.label })));+// Option values are "k:<usage>" for keyboard keys and "c:<usage>" for media keys.+$('#assign-key').append(el('option', { value: 'k:0', textContent: '(no key, modifiers only)' }),+ el('optgroup', { label: 'Keys' }, ...Hid.KEYS.map((k) => el('option', { value: `k:${k.usage}`, textContent: k.label }))),+ el('optgroup', { label: 'Media' }, ...Hid.CONSUMER.map((c) => el('option', { value: `c:${c.usage}`, textContent: c.label }))));++const draftLabel = () => (draft.consumer ? Hid.consumerLabel(draft.consumer) : Hid.comboLabel(draft.mods, draft.key, MAC));+const draftEmpty = () => !draft.consumer && !draft.mods && !draft.key;function showDraft() {$('#assign-mods').querySelectorAll('input').forEach((c) => { c.checked = !!(draft.mods & (1 << c.value)); });- $('#assign-key').value = draft.key;- $('#capture-combo').textContent = Hid.comboLabel(draft.mods, draft.key, MAC) || 'Press a key or shortcut…';+ $('#assign-key').value = draft.consumer ? `c:${draft.consumer}` : `k:${draft.key}`;+ $('#capture-combo').textContent = draftLabel() || 'Press a key or shortcut…';}$('#assign-mods').addEventListener('change', () => {draft.mods = [...$('#assign-mods').querySelectorAll('input')].reduce((m, c) => m | (c.checked ? 1 << c.value : 0), 0);+ draft.consumer = 0; // media keys can't take modifiers+ showDraft();+});+$('#assign-key').addEventListener('change', (e) => {+ const [kind, usage] = e.target.value.split(':');+ draft = kind === 'c' ? { mods: 0, key: 0, consumer: Number(usage) } : { ...draft, key: Number(usage), consumer: 0 };showDraft();});-$('#assign-key').addEventListener('change', (e) => { draft.key = Number(e.target.value); showDraft(); });function captureKey(e) {const r = Hid.fromEvent(e);if (!r) return;- draft = { mods: r.mods, key: r.usage };+ draft = r.consumer ? { mods: 0, key: 0, consumer: r.consumer } : { mods: r.mods, key: r.usage, consumer: 0 };showDraft();}capture.addEventListener('keydown', (e) => { e.preventDefault(); e.stopPropagation(); captureKey(e); });@@ -432,7 +445,7 @@ window.desktop?.onCaptureKey((k) => { if (k.type === 'keyDown') captureKey(k); }function openAssign(uid) {assignUid = uid;const m = activeProfile().keys[uid];- draft = { mods: m?.mods || 0, key: m?.key || 0 };+ draft = { mods: m?.mods || 0, key: m?.key || 0, consumer: m?.consumer || 0 };$('#assign-name').textContent = keyName(uid);$('#assign-label').value = m?.name || '';$('#assign-clear').disabled = !m;@@ -450,11 +463,11 @@ $('#assign-save').onclick = () => {const uid = assignUid;const name = $('#assign-label').value.trim();const p = activeProfile();- if (!draft.mods && !draft.key && !name) delete p.keys[uid];- else p.keys[uid] = { mods: draft.mods, key: draft.key, ...(name ? { name } : {}) };+ if (draftEmpty() && !name) delete p.keys[uid];+ else p.keys[uid] = { ...draft, ...(name ? { name } : {}) };+ if (!draft.consumer) delete p.keys[uid]?.consumer;persist();- if (draft.mods || draft.key) send(cmd.map(uid, draft.mods, draft.key), cmd.save());- else send(cmd.unmap(uid), cmd.save());+ send(mapCommand(uid, draft) || cmd.unmap(uid), cmd.save());activity(`${keyName(uid)} → ${comboFor(uid) || 'nothing'}`);closeAssign();render();diff --git a/app/renderer/hid.js b/app/renderer/hid.jsindex ef054db..0c47466 100644--- a/app/renderer/hid.js+++ b/app/renderer/hid.js@@ -30,10 +30,20 @@['ContextMenu', 0x65, 'Menu'], ['NumpadEqual', 0x67, 'Num ='],].forEach((k) => add(...k));for (let i = 13; i <= 24; i++) add(`F${i}`, 0x5b + i, `F${i}`);- [- ['AudioVolumeMute', 0x7f, 'Mute'], ['AudioVolumeUp', 0x80, 'Volume Up'],- ['AudioVolumeDown', 0x81, 'Volume Down'],- ].forEach((k) => add(...k));++ // Media keys go through the Consumer page (0x0C), sent with MAPC. Keyed by+ // KeyboardEvent.code where the browser reports one.+ const CONSUMER = [+ ['MediaPlayPause', 0xcd, 'Play/Pause'], ['MediaTrackNext', 0xb5, 'Next Track'],+ ['MediaTrackPrevious', 0xb6, 'Previous Track'], ['MediaStop', 0xb7, 'Stop'],+ ['AudioVolumeMute', 0xe2, 'Mute'], ['AudioVolumeUp', 0xe9, 'Volume Up'],+ ['AudioVolumeDown', 0xea, 'Volume Down'], ['', 0x6f, 'Brightness Up'],+ ['', 0x70, 'Brightness Down'], ['LaunchApp2', 0x192, 'Calculator'],+ ['LaunchMail', 0x18a, 'Mail'], ['BrowserSearch', 0x221, 'Search'],+ ['BrowserHome', 0x223, 'Browser Home'],+ ].map(([code, usage, label]) => ({ code, usage, label }));+ const consumerByCode = new Map(CONSUMER.filter((c) => c.code).map((c) => [c.code, c]));+ const consumerByUsage = new Map(CONSUMER.map((c) => [c.usage, c]));const byCode = new Map(KEYS.map((k) => [k.code, k]));const byUsage = new Map(KEYS.map((k) => [k.usage, k]));@@ -56,6 +66,10 @@return m.name.replace('GUI', 'Cmd').replace('Alt', 'Option');}+ function consumerLabel(usage) {+ return consumerByUsage.get(usage)?.label || `Media 0x${usage.toString(16).padStart(4, '0')}`;+ }+// "Ctrl+Shift+A", "Cmd+Space", "Shift" (modifier only), "" when empty.function comboLabel(mods, usage, mac) {const parts = MODS.filter((m) => mods & (1 << m.bit)).map((m) => modName(m, mac));@@ -63,9 +77,12 @@return parts.join('+');}- // Turns a key event ({code, ctrlKey, shiftKey, altKey, metaKey}) into {mods, usage}.- // usage is 0 when only modifiers are held. Returns null for keys HID can't send.+ // Turns a key event ({code, ctrlKey, shiftKey, altKey, metaKey}) into {mods, usage},+ // or {consumer} for a media key. usage is 0 when only modifiers are held.+ // Returns null for keys HID can't send.function fromEvent(e) {+ const media = consumerByCode.get(e.code);+ if (media) return { consumer: media.usage };let mods = (e.ctrlKey ? 1 : 0) | (e.shiftKey ? 2 : 0) | (e.altKey ? 4 : 0) | (e.metaKey ? 8 : 0);const mod = modByCode.get(e.code);if (mod) return { mods: mods | (1 << mod.bit), usage: 0 };@@ -74,7 +91,7 @@return { mods, usage: k.usage };}- const api = { KEYS, MODS, byUsage, comboLabel, fromEvent, modName };+ const api = { KEYS, MODS, CONSUMER, byUsage, comboLabel, consumerLabel, fromEvent, modName };if (typeof module !== 'undefined' && module.exports) module.exports = api;else root.Hid = api;})(typeof window !== 'undefined' ? window : globalThis);diff --git a/app/renderer/profiles.js b/app/renderer/profiles.jsindex c4de116..195ed07 100644--- a/app/renderer/profiles.js+++ b/app/renderer/profiles.js@@ -14,7 +14,8 @@if (!keys || typeof keys !== 'object') return out;for (const [uid, m] of Object.entries(keys)) {if (!/^([0-9a-fA-F]{24}|[0-9a-fA-F]{8})$/.test(uid) || !m || typeof m !== 'object') continue;- const entry = { mods: (Number(m.mods) || 0) & 0xff, key: (Number(m.key) || 0) & 0xff };+ const consumer = (Number(m.consumer) || 0) & 0xffff;+ const entry = consumer ? { mods: 0, key: 0, consumer } : { mods: (Number(m.mods) || 0) & 0xff, key: (Number(m.key) || 0) & 0xff };if (typeof m.name === 'string' && m.name.trim()) entry.name = m.name.trim().slice(0, 40);out[uid.toUpperCase()] = entry;}diff --git a/app/renderer/protocol.js b/app/renderer/protocol.jsindex 719786e..4ba45a7 100644--- a/app/renderer/protocol.js+++ b/app/renderer/protocol.js@@ -40,6 +40,14 @@const isUid = (u) => typeof u === 'string' && /^([0-9a-fA-F]{24}|[0-9a-fA-F]{8})$/.test(u);const hex2 = (n) => (n & 0xff).toString(16).toUpperCase().padStart(2, '0');+ const hex4 = (n) => (n & 0xffff).toString(16).toUpperCase().padStart(4, '0');++ // One profile entry -> the MAP/MAPC command for it, or null if it maps nothing.+ function mapCommand(uid, m) {+ if (m.consumer) return cmd.mapConsumer(uid, m.consumer);+ if (m.mods || m.key) return cmd.map(uid, m.mods || 0, m.key || 0);+ return null;+ }// Host -> Keyword commands.const cmd = {@@ -47,6 +55,7 @@sides: () => 'SIDES?',keys: () => 'KEYS?',map: (uid, mods, key) => `MAP uid=${uid} mods=${hex2(mods)} key=${hex2(key)}`,+ mapConsumer: (uid, usage) => `MAPC uid=${uid} usage=${hex4(usage)}`,mapQuery: (uid) => `MAP? uid=${uid}`,unmap: (uid) => `UNMAP uid=${uid}`,clear: () => 'CLEAR',@@ -57,7 +66,8 @@function profileCommands(keys) {const out = [cmd.clear()];for (const [uid, m] of Object.entries(keys)) {- if (isUid(uid) && (m.mods || m.key)) out.push(cmd.map(uid.toUpperCase(), m.mods || 0, m.key || 0));+ const c = isUid(uid) && mapCommand(uid.toUpperCase(), m);+ if (c) out.push(c);}out.push(cmd.save());return out;@@ -92,6 +102,9 @@case 'MAP':if (!isUid(f.uid)) break;return { type: 'map', uid: f.uid.toUpperCase(), mods: parseInt(f.mods || '0', 16) || 0, key: parseInt(f.key || '0', 16) || 0 };+ case 'MAPC':+ if (!isUid(f.uid)) break;+ return { type: 'mapConsumer', uid: f.uid.toUpperCase(), usage: parseInt(f.usage || '0', 16) || 0 };case 'OK':return { type: 'ok', what: parts[1] || '', ...parseFields(parts.slice(2)) };case 'ERR':@@ -100,7 +113,7 @@return { type: 'unknown', line };}- const api = { SIDES, NUS, LineBuffer, parseLine, cmd, profileCommands, isUid };+ const api = { SIDES, NUS, LineBuffer, parseLine, cmd, mapCommand, profileCommands, isUid };if (typeof module !== 'undefined' && module.exports) module.exports = api;else root.KeywordProtocol = api;})(typeof window !== 'undefined' ? window : globalThis);diff --git a/app/test/hid.test.js b/app/test/hid.test.jsindex 6c2d08e..6212faf 100644--- a/app/test/hid.test.js+++ b/app/test/hid.test.js@@ -25,3 +25,8 @@ test('fromEvent and labels', () => {assert.strictEqual(Hid.comboLabel(0x09, 0x2c, false), 'Ctrl+Win+Space');assert.strictEqual(Hid.comboLabel(0x02, 0, false), 'Shift');});++test('media keys', () => {+ assert.deepStrictEqual(Hid.fromEvent({ code: 'MediaPlayPause' }), { consumer: 0xcd });+ assert.strictEqual(Hid.consumerLabel(0xe9), 'Volume Up');+});diff --git a/app/test/profiles.test.js b/app/test/profiles.test.jsindex b6aa077..5121cf3 100644--- a/app/test/profiles.test.js+++ b/app/test/profiles.test.js@@ -29,3 +29,8 @@ test('normalizeStore fills in a default', () => {const s2 = P.normalizeStore({ active: 'zz', profiles: [{ id: 'a', name: 'A', keys: {} }] });assert.strictEqual(s2.active, 'a');});++test('consumer entries survive a round trip', () => {+ const p = P.importProfile(P.exportProfile(P.newProfile('M', { '5F1821C1': { consumer: 0xcd, mods: 3 } })));+ assert.deepStrictEqual(p.keys, { '5F1821C1': { mods: 0, key: 0, consumer: 0xcd } });+});diff --git a/app/test/protocol.test.js b/app/test/protocol.test.jsindex 0bf30aa..46d3804 100644--- a/app/test/protocol.test.js+++ b/app/test/protocol.test.js@@ -57,3 +57,11 @@ test('formats commands', () => {assert.deepStrictEqual(profileCommands({ '5F1821C1': { mods: 1, key: 6 }, '00000001': { mods: 0, key: 0 }, bad: { key: 4 } }),['CLEAR', 'MAP uid=5F1821C1 mods=01 key=06', 'SAVE']);});++test('media key mappings', () => {+ const { mapCommand } = require('../renderer/protocol.js');+ assert.strictEqual(mapCommand('5F1821C1', { consumer: 0xcd }), 'MAPC uid=5F1821C1 usage=00CD');+ assert.strictEqual(mapCommand('5F1821C1', { mods: 0, key: 0 }), null);+ assert.deepStrictEqual(parseLine('MAPC uid=5F1821C1 usage=00E9'), { type: 'mapConsumer', uid: '5F1821C1', usage: 0xe9 });+ assert.deepStrictEqual(profileCommands({ '5F1821C1': { consumer: 0x192 } }), ['CLEAR', 'MAPC uid=5F1821C1 usage=0192', 'SAVE']);+});