Go Keyboard Firmware framework
This is an experimental project that I am using to test out and iterate on the USB HID implementation being developed
for TinyGo. Once things become more stable I will add features and clean up the codebase to be more
general-purpose and maintain it as a library.
Architecture
The architecture of the firmware code is loosely based on concepts from the excellent TMK Keyboard library.
The high-level abstractions in the codebase are the same as defined by TMK, including:
- Device (actually called "Keyboard" in the context of TMK) - often this is a physical keyboard, but also could
could be something like a protocol converter, logger, re-mapper, etc. It is comprised of a specific Host, Matrix,
and Keymap implementation. At runtime the Device maintains state such as the status of LEDs, active Layer, etc.
- Host - represents the hardware and protocol used to communicate with the host to which the device is connected;
typically this may be something like USB HID, Bluetooth, PS/2, Serial, etc.
- Matrix - contains the state of the device's switches/inputs, organized in memory as a matrix of rows and columns.
For a keyboard, this may represent an actual matrix of rows and columns to which physical switches are connected.
For a converter, the rows/columns are virtual and are used to maintain state based on events from the peripheral.
- Keymap - user-configurable, ordered set of one or more Layers for translating the state of the matrix into events
and/or keycodes to be sent to the host. For keymaps with multiple layers, the Device keeps track of the "active"
layer. When translating a matrix location to a keycode, if a layer does not define a mapping for a matrix location,
any layers below the active layer are searched in order (from highest to lowest layer) until a mapping is found.
- Layer - a mapping of matrix locations (row/column) to specific keycodes or framework events. A layer does not need
to define a mapping for every matrix location; some locations can be "transparent" to delegate to a lower-level
layer as defined by the keymap.
Please note that not all protocols and features described above, such as multiple layers, are implemented yet
Design Considerations
-
import
-able as an idiomatic Go module; no Makefiles etc necessary to use core functionality and most use cases.
- Usable from both TinyGo and full-sized Go... all TinyGo-specific packages (machine, etc.) should be
protected with build tags. Conversely ... functionality not available in TinyGo must be protected as well.
- No/few allocations in core library ... user code should initialize memory when necessary.
Building Firmware
In order to build firmware in this repository, please install Go 1.20+ and TinyGo 0.30+.
Note: for Teensy 4.1 targets, please see README.md in the devices/kint41
folder.
License
Copyright © 2019-2023 Benjamin Gould
Licensed GPLv3 or later.