159 lines
5.5 KiB
Markdown
159 lines
5.5 KiB
Markdown
# zmk-steno-engine
|
|
|
|
Clean-room stenography engine for [ZMK Firmware](https://zmk.dev).
|
|
Carries the **full Plover main dictionary AND the full Lapwing base
|
|
dictionary — 262,309 entries, zero trimming — on a pair of nRF52840
|
|
keyboard halves** using the v4 "union split-section" format
|
|
|
|
**Status:** working end to end on real hardware (corne, 2x nice!nano v2).
|
|
Translations, multi-stroke longest-match with retrace, number strokes,
|
|
runtime dictionary switching (Plover/Lapwing). Known issues tracked in
|
|
the issue tracker; latency optimization in progress.
|
|
|
|
## How it works
|
|
|
|
One logical dictionary structure, its sections split across the two MCUs:
|
|
|
|
| Half | Holds | Role |
|
|
|------|-------|------|
|
|
| Left (central) | MPHF displacements, membership, fingerprints, conflicts, part of the value index | Every stroke *decision* is local — found / not found / which dictionary |
|
|
| Right (peripheral) | Compressed string table, rest of the value index | Serves translation *text* over a custom BLE GATT protocol |
|
|
|
|
Key measured facts:
|
|
|
|
- One union CHD MPHF over 227,091 stroke keys — two separate dictionaries
|
|
would cost 1.8x more flash
|
|
- Lapwing's translations are 93% a subset of Plover's → the shared,
|
|
front-coded, deflate-compressed string table stores both for 193 KB
|
|
- Stroke decisions never wait on BLE; only text retrieval does
|
|
(LRU-cached on the left half)
|
|
|
|
## Requirements
|
|
|
|
- **A split keyboard with two nRF52840 controllers** (e.g. corne with
|
|
2x nice!nano v2). The dictionary spans both halves — **single-MCU
|
|
keyboards are not supported yet.**
|
|
- ZMK v0.3.x build environment (GitHub Actions user-config works)
|
|
- **Adafruit nRF52 bootloader 0.9.0 or newer on BOTH halves —
|
|
0.11.0 recommended.** See [Bootloader](#bootloader) below; old
|
|
bootloaders silently corrupt large firmware images.
|
|
|
|
## Usage
|
|
|
|
`west.yml`:
|
|
|
|
```yaml
|
|
manifest:
|
|
remotes:
|
|
- name: afiqzudinhadi
|
|
url-base: https://github.com/afiqzudinhadi
|
|
projects:
|
|
- name: zmk-steno-engine
|
|
remote: afiqzudinhadi
|
|
revision: main
|
|
```
|
|
|
|
`.conf`:
|
|
|
|
```
|
|
CONFIG_STENO_ENGINE=y
|
|
CONFIG_STENO_DICT_BOTH=y # or STENO_DICT_PLOVER / STENO_DICT_LAPWING
|
|
CONFIG_STENO_SPLIT_DICT=y
|
|
CONFIG_STENO_DICT_LEFT_MAX_SIZE=440320
|
|
CONFIG_STENO_DICT_RIGHT_MAX_SIZE=519168
|
|
CONFIG_STENO_SPLIT_TIMEOUT_MS=250
|
|
```
|
|
|
|
The build FAILS if either half's blob exceeds its budget — entries are
|
|
never trimmed.
|
|
|
|
Keymap: include the behavior and bind the 23 steno keys
|
|
(see `include/dt-bindings/zmk/steno_keys.h` for all key names):
|
|
|
|
```dts
|
|
#include <behaviors/steno_engine.dtsi>
|
|
#include <dt-bindings/zmk/steno_keys.h>
|
|
|
|
// example row: &steno STENO_NUM &steno STENO_SL &steno STENO_TL ...
|
|
```
|
|
|
|
Digits in dictionary strokes (e.g. `12K` → `12:00`) map to the number
|
|
bar plus their positional key, exactly like Plover.
|
|
|
|
## Flash budget
|
|
|
|
The app image on each half must stay below the bootloader's app-region
|
|
ceiling (`0xEA000`, i.e. **802,816 bytes** with Adafruit 0.11.0).
|
|
Firmware blocks above the ceiling are silently dropped and the half
|
|
will not boot. The default budgets above keep both halves under it —
|
|
check the `FLASH` line in your build log if you change them.
|
|
|
|
## Bootloader
|
|
|
|
The nice!nano ships with various versions of the
|
|
[Adafruit nRF52 bootloader](https://github.com/adafruit/Adafruit_nRF52_Bootloader).
|
|
**Versions from ~2021 (e.g. 0.6.0) corrupt large UF2 flashes** — blocks
|
|
go missing mid-image and the firmware crash-loops with no display, no
|
|
typing, no USB. This module's images are large (~1.5 MB UF2 per half),
|
|
so a current bootloader is mandatory.
|
|
|
|
### Check your version
|
|
|
|
Double-tap the reset button. The half mounts as a `NICENANO` USB drive;
|
|
open `INFO_UF2.TXT` on it:
|
|
|
|
```
|
|
UF2 Bootloader 0.6.0 ... ← too old
|
|
UF2 Bootloader 0.11.0 ... ← good
|
|
```
|
|
|
|
(On newer macOS the volume may not auto-mount — run `diskutil list`
|
|
and `diskutil mount diskN`.)
|
|
|
|
### Update
|
|
|
|
1. Download the updater for your board from the
|
|
[official releases](https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases)
|
|
— for nice!nano: `update-nice_nano_bootloader-<version>_nosd.uf2`
|
|
(the `nosd` variant keeps the installed SoftDevice, which ZMK needs).
|
|
2. Enter the bootloader (double-tap reset) and copy the updater UF2 to
|
|
the `NICENANO` drive. The device installs it and reboots.
|
|
3. Re-enter the bootloader and confirm the version in `INFO_UF2.TXT`.
|
|
4. Repeat for the other half.
|
|
|
|
To revert, flash any older `update-nice_nano_bootloader-*.uf2` from the
|
|
same releases page the same way — the process is not one-way.
|
|
|
|
### macOS flashing note
|
|
|
|
Recent macOS versions (FSKit FAT driver) break Finder/`cp` copies to
|
|
UF2 bootloader drives — writes are silently dropped or fail with error
|
|
-50. Flash from the terminal against the raw disk instead:
|
|
|
|
```sh
|
|
diskutil list # find the NICENANO disk number
|
|
diskutil unmountDisk disk4 # keep the device attached
|
|
sudo dd if=firmware.uf2 of=/dev/rdisk4 bs=512
|
|
```
|
|
|
|
The bootloader flashes any 512-byte sector carrying UF2 magic, so the
|
|
filesystem layer is not needed.
|
|
|
|
## Repository layout
|
|
|
|
```
|
|
src/ engine, v4 decoder, BLE split protocol, inflate
|
|
tools/compile_v4.py dictionary compiler (both JSONs → two half blobs)
|
|
tools/fetch_dict.py dictionary downloader (Plover main, Lapwing base)
|
|
tests/test_dict_v4.c host round-trip test (42,000 vectors)
|
|
```
|
|
|
|
### Development
|
|
|
|
The dictionary compiler (`tools/compile_v4.py`) requires Python 3 with
|
|
`numpy`. GitHub Actions runners have this preinstalled; for local builds
|
|
install via `pip install numpy`.
|
|
|
|
## License
|
|
|
|
PolyForm Noncommercial 1.0.0 — see [LICENSE](LICENSE).
|