alpha
/
Kaleidoscope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
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.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '6aef9b99bb'
${ noResults }
Kaleidoscope/docs/codebase/chrysalis-firmware.md

5.5 KiB
Raw Blame History

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 and 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 included, enabled, and configured. To have colormap editing support, Colormap is also required. If Colormap is enabled, its dependencies, LEDPaletteTheme 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), and EEPROMSettings (provided by EEPROM-Settings).

Because we're talking keyboards, we will also need EEPROMKeymap, as provided by the 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), ColormapEffect and DefaultColormap plugins, provided by the 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.

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.
  • Secondary actions via Qukeys.
  • OneShot functionality via OneShot and EscapeOneShot, and EscapeOneShotConfig (provided by EscapeOneShot).
  • Default LED mode configurability via DefaultLEDModeConfig, if the device supports LEDs.
  • Automatically turning LEDs off after some time, via IdleLEDs and PersistentIdleLEDs, provided by th IdleLEDs 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.