Skip to content

A truly modular keyboard

C

app: media keys, BLE pairing and name-only scan

Nathand26d9fdcd776
diff --git a/app/PROTOCOL.md b/app/PROTOCOL.md
index 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.md
index 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 side
diff --git a/app/main.js b/app/main.js
index 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 picker
diff --git a/app/renderer/app.js b/app/renderer/app.js
index 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 missed
const 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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']);
+});