You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
108 lines
5.5 KiB
108 lines
5.5 KiB
3 years ago
|
# Chrysalis-enabled firmware
|
||
|
|
|
||
|
|
In this document, we'll go over what is required - at a minimum - to let a
|
||
|
|
sketch work with Chrysalis, assuming the hardware itself is supported by it.
|
||
|
|
|
||
|
|
## Basic requirements
|
||
|
|
|
||
|
|
Any sketch that wants to work with Chrysalis has to have at a mininum, the
|
||
|
|
[FocusSerial][plugin:focus-serial] and [EEPROM-Settings][plugin:eeprom-settings]
|
||
|
|
libraries included, and the `Focus`, `FocusEEPROMCommand`,
|
||
|
|
`FocusSettingsCommand` (provided by `FocusSerial`), and `EEPROMSettings`
|
||
|
|
(provided by `EEPROM-Settings`) plugins enabled, by listing them in
|
||
|
|
`KALEIDOSCOPE_INIT_PLUGINS()`.
|
||
|
|
|
||
|
|
To edit the keymap, the sketch will also need
|
||
|
|
[EEPROM-Keymap][plugin:eeprom-keymap] included, enabled, and configured. To have
|
||
|
|
colormap editing support, [Colormap][plugin:colormap] is also required. If
|
||
|
|
`Colormap` is enabled, its dependencies,
|
||
|
|
[LEDPaletteTheme][plugin:led-palette-theme] and [LEDControl][plugin:led-control]
|
||
|
|
must also be enabled.
|
||
|
|
|
||
|
|
These are the absolute essentials to have basic functionality in Chrysalis.
|
||
|
|
There are a lot of other plugins included in most Chrysalis-enabled firmware
|
||
|
|
that further enhance the configurability. For guidelines about what to include
|
||
|
|
in sketches that are intended to be shipped with Chrysalis, see the next
|
||
|
|
section.
|
||
|
|
|
||
|
|
## Firmware shipped with Chrysalis
|
||
|
|
|
||
|
|
Firmware we ship with Chrysalis should come with reasonable defaults, nothing
|
||
|
|
surprising, strange, or uncommon should be enabled by default, unless users of
|
||
|
|
the device can be reasonably expected to know about these features. One such
|
||
|
|
case is when Kaleidoscope is not the default on a particular device, and the
|
||
|
|
firmware we ship with Chrysalis mimics the original default firmware. Whatever
|
||
|
|
features the original firmware had, are safe to include in the
|
||
|
|
Kaleidoscope-based one too, if Kaleidoscope supports a given feature.
|
||
|
|
|
||
|
|
With that said, the recommended list of features in a Chrysalis-enabled firmware are:
|
||
|
|
|
||
|
|
### The Basics
|
||
|
|
|
||
|
|
At a minimum, we need to support the keyboard's basic features. As such, we'll
|
||
|
|
need the required plugins first: `Focus`, `FocusEEPROMCommand`, and
|
||
|
|
`FocusSettingsCommand` (provided by [FocusSerial][plugin:focus-serial]), and
|
||
|
|
`EEPROMSettings` (provided by [EEPROM-Settings][plugin:eeprom-settings]).
|
||
|
|
|
||
|
|
Because we're talking keyboards, we will also need `EEPROMKeymap`, as provided
|
||
|
|
by the [EEPROM-Keymap][plugin:eeprom-keymap] plugin.
|
||
|
|
|
||
|
|
If the device has per-key LEDs, the sketch should also include the `LEDOff` and
|
||
|
|
`LEDControl` (provided by `LEDControl`), `LEDPaletteTheme`
|
||
|
|
(provided by [LED-Palette-Theme][plugin:led-palette-theme]), `ColormapEffect`
|
||
|
|
and `DefaultColormap` plugins, provided by the [Colormap][plugin:colormap]
|
||
|
|
plugin. The latter is optional, depending on whether there's enough space on the
|
||
|
|
device to include a default palette and colormap.
|
||
|
|
|
||
|
|
The number of layers configured for `ColormapEffect` and `EEPROMKeymap` **must**
|
||
|
|
be identical, and the number of default layers should leave ample opportunity
|
||
|
|
for the end-user to customize them. They should not be restricted to the number
|
||
|
|
of layers the keyboard ships with out of the box, unless storage space
|
||
|
|
restrictions prevent us from having more. A sensible default is eight layers for
|
||
|
|
both, as that is the limit the Chrysalis-configurable secondary actions and
|
||
|
|
one-shot keys support.
|
||
|
|
|
||
|
|
If the hardware supports it, including the `HardwareTestMode` plugin is highly
|
||
|
|
recommended, likewise for [HostPowerManagement][plugin:host-power-management].
|
||
|
|
|
||
|
|
When `HostPowerManagement` is included, and the hardware has LEDs, then the
|
||
|
|
sketch should be set up so that upon suspending, the LEDs are turned off, and
|
||
|
|
they're turned back on when the host is resumed.
|
||
|
|
|
||
|
|
### Additional Features
|
||
|
|
|
||
|
|
Space permitting, the following features are recommended to be included in any
|
||
|
|
firmware we expect to ship with Chrysalis, roughly in order of importance:
|
||
|
|
|
||
|
|
- Mouse keys via the [MouseKeys][plugin:mousekeys] plugin.
|
||
|
|
- Secondary actions via [Qukeys][plugin:qukeys].
|
||
|
|
- OneShot functionality via [OneShot][plugin:oneshot] and `EscapeOneShot`, and `EscapeOneShotConfig` (provided by [EscapeOneShot][plugin:escape-oneshot]).
|
||
|
|
- Default LED mode configurability via
|
||
|
|
[DefaultLEDModeConfig][plugin:default-led-mode-config], if the device supports
|
||
|
|
LEDs.
|
||
|
|
- Automatically turning LEDs off after some time, via `IdleLEDs` and
|
||
|
|
`PersistentIdleLEDs`, provided by th [IdleLEDs][plugin:idle-leds] plugin.
|
||
|
|
- Chrysalis-editable macros via [DynamicMacros][plugins:dynamic-macros],
|
||
|
|
configured to leave a fair amount of storage space available for macros, space
|
||
|
|
permitting. Around 512 bytes is a reasonable minimum, with 4096 bytes being a
|
||
|
|
very generous amount. At this time, more than 4k storage space reserved for
|
||
|
|
macros is likely unnecessary.
|
||
|
|
|
||
|
|
All of these should be configured for sensible, not surprising behaviour.
|
||
|
|
Additional plugins on top of these may be enabled if they make sense, but the
|
||
|
|
principle of least surprise should always be kept in mind.
|
||
|
|
|
||
|
|
[plugin:focus-serial]: ../plugins/FocusSerial.md
|
||
|
|
[plugin:eeprom-settings]: ../plugins/EEPROM-Settings.md
|
||
|
|
[plugin:eeprom-keymap]: ../plugins/EEPROM-Keymap.md
|
||
|
|
[plugin:colormap]: ../plugins/Colormap.md
|
||
|
|
[plugin:led-palette-theme]: ../plugins/LED-Palette-Theme.md
|
||
|
|
[plugin:host-power-management]: ../plugins/HostPowerManagement.md
|
||
|
|
[plugin:mousekeys]: ../plugins/MouseKeys.md
|
||
|
|
[plugin:qukeys]: ../plugins/Qukeys.md
|
||
|
|
[plugin:oneshot]: ../plugins/OneShot.md
|
||
|
|
[plugin:escape-oneshot]: ../plugins/Escape-OneShot.md
|
||
|
|
[plugin:default-led-mode-config]: ../plugins/DefaultLEDModeConfig.md
|
||
|
|
[plugin:idle-leds]: ../plugins/IdleLEDs.md
|
||
|
|
[plugin:dynamic-macros]: ../plugins/DynamicMacros.md
|