While not complete yet, this is a stab at documenting the new device APIs. There are parts still missing, but pointers are there to the headers which show the API. `UPGRADING.md` and `NEWS.md` have also been updated to mention these. Signed-off-by: Gergely Nagy <algernon@keyboard.io>pull/695/head
Gergely Nagy
5 years ago
parent
3601272478
commit
7557c6d395
@ -0,0 +1,208 @@
|
|||||||
|
# Kaleidoscope Device API internals
|
||||||
|
|
||||||
|
This document is aimed at people interested in working on adding new devices -
|
||||||
|
or improving support for existing ones - to Kaleidoscope. The APIs detailed here
|
||||||
|
are a little bit more complex than most of the APIs our plugins provide.
|
||||||
|
Nevertheless, we hope they're still reasonably easy to use, and this document is
|
||||||
|
an attempt to explain some of the more intricate parts of it.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The core idea of the APIs is that to build up a device, we compose various
|
||||||
|
components together, by describing their _properties_, and using fairly generic,
|
||||||
|
templated helper classes with the properties as template parameters.
|
||||||
|
|
||||||
|
This way, we can assemble together a device with a given _MCU_, which uses a
|
||||||
|
particular _Bootloader_, some kind of _Storage_, perhaps some _LEDs_, and it
|
||||||
|
will more than likely have a _key scanner_ component too.
|
||||||
|
|
||||||
|
The base and helper classes provide a lot of the functionality themselves, so
|
||||||
|
for a device built up from components already supported by Kaleidoscope, the
|
||||||
|
amount of custom code one has to write will be minimal.
|
||||||
|
|
||||||
|
## Component details
|
||||||
|
|
||||||
|
### Device
|
||||||
|
|
||||||
|
A `Device` is the topmost level component, it is the interface the rest of
|
||||||
|
Kaleidoscope will work with. The [`kaleidoscope::device::Base`][k:d:Base] class
|
||||||
|
is the ancestor of _all_ devices, everything derives from this. Devices that use
|
||||||
|
an `ATMega32U4` MCU we also have the
|
||||||
|
[`kaleidoscope::device::ATMega32U4Keyboard`][k:d:a32u4] class, which sets up
|
||||||
|
some of the components that is common to all `ATMega32U4`-based devices (such as
|
||||||
|
the _MCU_ and the _Storage_).
|
||||||
|
|
||||||
|
[k:d:Base]:../src/kaleidoscope/device/Base.h
|
||||||
|
[k:d:a32u4]: ../src/kaleidoscope/device/ATMega32U4.h
|
||||||
|
|
||||||
|
As hinted at above, a device - or rather, it's `Props` - describe the components
|
||||||
|
used for the device, such as the MCU, the Bootloader, the Storage driver, LEDs,
|
||||||
|
and the key scanner. If any of that is unneeded, there's no need to specify them
|
||||||
|
in `Props` - the defaults are all no-ops.
|
||||||
|
|
||||||
|
All devices must also come with a `Props` struct, deriving from [`kaleidoscope::device::BaseProps`][k:d:BaseProps].
|
||||||
|
|
||||||
|
[k:d:BaseProps]: ../src/kaleidoscope/device/Base.h
|
||||||
|
|
||||||
|
As an example, the most basic device we can have, that does nothing, would look
|
||||||
|
like this:
|
||||||
|
|
||||||
|
```c++
|
||||||
|
class ExampleDevice : public kaleidoscope::device::Base<kaleidoscope::device::BaseProps> {};
|
||||||
|
```
|
||||||
|
|
||||||
|
That's not very useful, though. More often than not, we want to override at
|
||||||
|
least some of the properties. In some cases, even override some of the
|
||||||
|
pre-defined methods of the device. See the [base class][k:d:Base] for an
|
||||||
|
up-to-date list of methods and interfaces it provides. The most often changed
|
||||||
|
methods are likely to be `setup()` and the constructor, and
|
||||||
|
`enableHardwareTestMode()` if the device implements a hardware test mode. The
|
||||||
|
rest are wrappers around the various components described by the `Props`.
|
||||||
|
|
||||||
|
In other words, the majority of customisation is in the `Props`, and in what
|
||||||
|
components the device ends up using.
|
||||||
|
|
||||||
|
### MCU
|
||||||
|
|
||||||
|
The heart of any device will be the main controller unit, or _MCU_ for short.
|
||||||
|
The [`kaleidoscope::driver::mcu::Base`][k:d:m:Base] class is the ancestor of our
|
||||||
|
MCU drivers, including [`mcu::ATMega32U4`][k:d:m:a32u4].
|
||||||
|
|
||||||
|
[k:d:m:Base]: ../src/kaleidoscope/driver/mcu/Base.h
|
||||||
|
[k:d:m:a32u4]: ../src/kaleidoscope/driver/mcu/ATMega32U4.h
|
||||||
|
|
||||||
|
The core firmware will use the `detachFromHost()` and `attachToHost()` methods
|
||||||
|
of the MCU driver, along with `setup()`, but the driver - like any other
|
||||||
|
driver - is free to have other methods, to be used by individual devices.
|
||||||
|
|
||||||
|
For example, the [`ATMega32U4`][k:d:m:a32u4] driver implements a `disableJTAG()`
|
||||||
|
and a `disableClockDivision()` method, which some of our devices use in their
|
||||||
|
constructors.
|
||||||
|
|
||||||
|
Unlike some other components, the `MCU` component has no properties.
|
||||||
|
|
||||||
|
### Bootloader
|
||||||
|
|
||||||
|
Another important component of a device is a bootloader. The bootloader is the
|
||||||
|
thing that allows us to re-program the keyboard without additional hardware
|
||||||
|
(aptly called a programmer). As such, the [`base class`][k:d:b:Base] has a
|
||||||
|
single method, `rebootBootloader()`, which our bootloader components implement.
|
||||||
|
|
||||||
|
[k:d:b:Base]: ../src/kaleidoscope/bootloader/Base.h
|
||||||
|
|
||||||
|
Kaleidoscope currently supports [`Catalina`][k:d:b:Catalina],
|
||||||
|
[`HalfKay`][k:d:b:HalfKay], and [`FLIP`][k:d:b:FLIP] bootloaders. Please consult
|
||||||
|
them for more information. In many cases, setting up the bootloader in the
|
||||||
|
device props is all one needs to do.
|
||||||
|
|
||||||
|
[k:d:b:Catalina]: ../src/kaleidoscope/driver/bootloader/avr/Catalina.h
|
||||||
|
[k:d:b:HalfKay]: ../src/kaleidoscope/driver/bootloader/avr/HalfKay.h
|
||||||
|
[k:d:b:FLIP]: ../src/kaleidoscope/driver/bootloader/avr/FLIP.h
|
||||||
|
|
||||||
|
Like the _MCU_ component, the _bootloader_ does not use Props, either.
|
||||||
|
|
||||||
|
### Storage
|
||||||
|
|
||||||
|
Not nearly as essential for a device is the [`Storage`][k:d:s:Base] component.
|
||||||
|
Storage is for persistent storage of configuration data, such as key maps,
|
||||||
|
colormaps, feature toggles, and so on. It's not a required component, but a
|
||||||
|
recommended one nevertheless. This storage component is what allows apps like
|
||||||
|
[Chrysalis][chrysalis] to configure some aspects of the keyboard without having
|
||||||
|
to flash new firmware.
|
||||||
|
|
||||||
|
The Storage API resembles the Arduino EEPROM API very closely. In fact, our
|
||||||
|
[`AVREEPROM`][k:d:s:AVREEPROM] class is but a thin wrapper around that!
|
||||||
|
|
||||||
|
[k:d:s:Base]: ../src/kaleidoscope/driver/storage/Base.h
|
||||||
|
[chrysalis]: https://github.com/keyboardio/Chrysalis
|
||||||
|
[k:d:s:AVREEPROM]: ../src/kaleidoscope/driver/storage/AVREEPROM.h
|
||||||
|
|
||||||
|
The `Storage` component does use Props, one that describes the length - or
|
||||||
|
size - of it. We provide an [`ATMega32U4EEPROMProps`][k:d:s:a32u4props] helper,
|
||||||
|
which is preconfigured for the 1k EEPROM size of the ATMega32U4.
|
||||||
|
|
||||||
|
[k:d:s:a32u4props]: ../src/kaleidoscope/driver/storage/ATMega32U4EEPROMProps.h
|
||||||
|
|
||||||
|
### LEDs
|
||||||
|
|
||||||
|
[`kaleidoscope::driver::led::Base`][k:d:l:Base]
|
||||||
|
|
||||||
|
[k:d:l:Base]: ../src/kaleidoscope/driver/led/Base.h
|
||||||
|
|
||||||
|
### Keyscanner
|
||||||
|
|
||||||
|
[`kaleidoscope::driver::keyscanner::Base`][k:d:ks:Base]
|
||||||
|
|
||||||
|
[k:d:ks:Base]: ../src/kaleidoscope/driver/keyscanner/Base.h
|
||||||
|
|
||||||
|
## Helpers
|
||||||
|
|
||||||
|
[`kaleidoscope::device::ATMega32U4Keyboard`][k:d:a32u4k]
|
||||||
|
[`kaleidoscope::driver::keyscanner::AVR`][k:d:ks:avr]
|
||||||
|
|
||||||
|
[k:d:a32u4k]: ../src/kaleidoscope/device/ATMega32U4Keyboard.h
|
||||||
|
[k:d:ks:avr]: ../src/kaleidoscope/driver/keyscanner/AVR.h
|
||||||
|
|
||||||
|
## Putting it all together
|
||||||
|
|
||||||
|
To put things into perspective, and show a simple example, we'll build an
|
||||||
|
imaginary mini keypad: `ATMega32U4` with `Caterina` as bootloader, no LEDs, and
|
||||||
|
four keys only.
|
||||||
|
|
||||||
|
### `ImaginaryKeypad.h`
|
||||||
|
|
||||||
|
```c++
|
||||||
|
#pragma once
|
||||||
|
|
||||||
|
#ifdef ARDUINO_AVR_IMAGINARY_KEYPAD
|
||||||
|
|
||||||
|
#include <Arduino.h>
|
||||||
|
#include "kaleidoscope/driver/keyscanner/AVR.h"
|
||||||
|
#include "kaleidoscope/driver/bootloader/avr/Caterina.h"
|
||||||
|
#include "kaleidoscope/device/ATMega32U4Keyboard.h"
|
||||||
|
|
||||||
|
namespace kaleidoscope {
|
||||||
|
namespace device {
|
||||||
|
namespace imaginary {
|
||||||
|
|
||||||
|
ATMEGA32U4_KEYBOARD(
|
||||||
|
Keypad, Caterina,
|
||||||
|
ROW_PIN_LIST({ PIN_D0, PIN_D1 }),
|
||||||
|
COL_PIN_LIST({ PIN_C0, PIN_C1 })
|
||||||
|
);
|
||||||
|
|
||||||
|
#define PER_KEY_DATA(dflt, \
|
||||||
|
R0C0, R0C1, \
|
||||||
|
R1C0, R1C1 \
|
||||||
|
) \
|
||||||
|
R0C0, R0C1, R1C0, R1C1
|
||||||
|
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
typedef kaleidoscope::device::imaginary::Keypad Device;
|
||||||
|
|
||||||
|
}
|
||||||
|
#endif
|
||||||
|
```
|
||||||
|
|
||||||
|
### `ImaginaryKeypad.cpp`
|
||||||
|
|
||||||
|
```c++
|
||||||
|
#ifdef ARDUINO_AVR_IMAGINARY_KEYPAD
|
||||||
|
|
||||||
|
#include <Kaleidoscope.h>
|
||||||
|
|
||||||
|
namespace kaleidoscope {
|
||||||
|
namespace device {
|
||||||
|
namespace imaginary {
|
||||||
|
|
||||||
|
AVR_KEYSCANNER_BOILERPLATE
|
||||||
|
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
#endif
|
||||||
|
```
|
||||||
|
|
||||||
|
That's it.
|
||||||
Loading…
Reference in new issue