This document is intended to name and describe the concepts, functions and data structures inside Kaleidoscope.
It is, as yet, incredibly incomplete.
Entries should be included in dictionary order. When describing an identifier of any kind from the codebase, it should be
written using identical capitalization to its use in the code and surrounded by backticks:
These terms commonly arise when discussing the firmware.
loop method in one’s sketch file is the heart of the firmware. It runs -
as the name suggests - in a loop. We call these runs cycles. A lot of things
happen within a cycle: from key scanning, through key event handling, LED
animations, and so on and so forth.
At the time of this writing, the following event handlers are run by hooks:
onSetup: Run once, when the plugin is initialised during
beforeEachCycle: Run as the first thing at the start of each cycle.
onKeyswitchEvent: Run for every non-idle key, in each cycle the key isn’t idle in. If a key gets pressed, released, or is held, it is not considered idle, and this event handler will run for it too.
beforeReportingState: Runs each cycle right before sending the various reports (keys pressed, mouse events, etc) to the host.
afterEachCycle: Runs at the very end of each cycle.
These terms arise when discussing the testing framworks and related tests.
An abstraction used in testing to inject events into or invoke actions on the simulated firmware. This abstraction comprises half of the interface to the test simulator.
An abstraction used in testing to encapsulate, snapshot, and examine firmware state. This abstraction comprises half of the interface to the test simulator.
TEST* macro invocation. Its body consists of one or tests
and optionally other code, e.g. to invoke the test harness.
Note that gtest uses the non-standard term Test for what we call a Test
A class comprising setup, teardown, and other code and common state to make writing test cases easieer. A fresh object of the fixture class associated with a test suite is constructed for each run of each teset case in the test suite.
An abstraction wrapping a virtual firmware build that allows performing actions against the virtual firmware and reading state out of the virtual firmware. The interface to the test simular is comprised of the sim harness and the sim state.