Jesse Vincent
4 years ago
committed by
GitHub
commit
f074b58d8e
@ -0,0 +1,55 @@
|
||||
#!/usr/bin/env bash
|
||||
# find-filename-conflicts - Finds cpp files with conflicting filenames
|
||||
# Copyright (C) 2020 Keyboard.io, Inc.
|
||||
#
|
||||
# This program is free software: you can redistribute it and/or modify it under
|
||||
# the terms of the GNU General Public License as published by the Free Software
|
||||
# Foundation, version 3.
|
||||
#
|
||||
# This program is distributed in the hope that it will be useful, but WITHOUT
|
||||
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
||||
# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License along with
|
||||
# this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
## When building Kaleidoscope, the compiled object files are linked together
|
||||
## into a static archive. This static archive has a very simple structure, and
|
||||
## only stores filenames, not paths, not even relative ones. As such, we can't
|
||||
## have files with the same name, because they will conflict, and one will
|
||||
## override the other.
|
||||
##
|
||||
## To avoid this situation, this script will find all cpp source files (we don't
|
||||
## need to care about header-only things, those do not result in an object
|
||||
## file), and will comb through them to find conflicting filenames.
|
||||
##
|
||||
## If a conflict is found, it will print all files that share the name, and will
|
||||
## exit with an error at the end. It does not exit at the first duplicate, but
|
||||
## will find and print all of them.
|
||||
##
|
||||
## If no conflict is found, the script just prints its status message and exits
|
||||
## with zero.
|
||||
|
||||
set -e
|
||||
|
||||
FILE_LIST="$(find src -name '*.cpp' | sed -e 's,\(\(.*\)/\([^/]*\)\),\3 \1,')"
|
||||
|
||||
exit_code=0
|
||||
|
||||
echo -n "Looking for conflicting filenames... "
|
||||
|
||||
for f in $(echo "${FILE_LIST}" | cut -f1 -d" "); do
|
||||
count=$(echo "${FILE_LIST}" | grep -c "^${f}")
|
||||
if [ "$count" -gt 1 ]; then
|
||||
echo >&2
|
||||
echo " Conflict found for ${f}: " >&2
|
||||
echo "${FILE_LIST}" | grep "${f}" | cut -d" " -f2 | sed -e 's,^, ,' >&2
|
||||
exit_code=1
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "${exit_code}" -eq 0 ]; then
|
||||
echo "done."
|
||||
fi
|
||||
|
||||
exit ${exit_code}
|
||||
@ -0,0 +1,19 @@
|
||||
#! /bin/sh
|
||||
## -*- mode: sh -*-
|
||||
set -e
|
||||
|
||||
uname_S=$(uname -s 2>/dev/null || echo not)
|
||||
|
||||
ARDUINO_LOCAL_LIB_PATH="${ARDUINO_LOCAL_LIB_PATH:-${HOME}/Arduino}"
|
||||
|
||||
if [ "${uname_S}" = "Darwin" ]; then
|
||||
ARDUINO_LOCAL_LIB_PATH="${ARDUINO_LOCAL_LIB_PATH:-${HOME}/Documents/Arduino}"
|
||||
fi
|
||||
|
||||
BOARD_HARDWARE_PATH="${BOARD_HARDWARE_PATH:-${ARDUINO_LOCAL_LIB_PATH}/hardware}"
|
||||
|
||||
docker build -t kaleidoscope/docker etc
|
||||
docker run --rm -it \
|
||||
-v "${BOARD_HARDWARE_PATH}/keyboardio:/kaleidoscope/hardware/keyboardio" \
|
||||
-v "$(pwd):/kaleidoscope/hardware/keyboardio/avr/libraries/Kaleidoscope" \
|
||||
kaleidoscope/docker -c "$*"
|
||||
@ -0,0 +1,15 @@
|
||||
#!/bin/bash -e
|
||||
|
||||
# This script sets all of the files inside src and example to have mtimes
|
||||
# that match the times of the last git commit that touched each file
|
||||
|
||||
# This can be useful when build tools depend on file timestamps to
|
||||
# make caching decisions
|
||||
|
||||
find src examples -type f -exec sh -c '
|
||||
timestamp=$(git log --pretty=format:%ad --date=format:%Y%m%d%H%M.%S -n 1 HEAD "$1" 2> /dev/null)
|
||||
if [ "x$timestamp" != "x" ]; then
|
||||
touch -t "$timestamp" "$1"
|
||||
fi
|
||||
' sh {} \;
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Binary file not shown.
@ -0,0 +1,64 @@
|
||||
# Build and install the latest firmware for your keyboard
|
||||
|
||||
# Select your keyboard
|
||||
|
||||
1. Open the 'Tools' menu, click on 'Board' and then click on the name of your keyboard. In the screenshot, we picked 'Keyboardio Model 01'. (You may have to scroll through a long list of other boards to get there.)
|
||||
|
||||
|
||||
|
||||
|
||||
2. Open the 'Tools' menu, click on "Port > ". If your keyboard is not already selected, click on it to select it. (If there is only one option such as "COM3" try it, it's almost certainly the correct port.)
|
||||
|
||||
|
||||
|
||||
Next step: [Install the latest firmware on your keyboard](#Install-latest-firmware)
|
||||
|
||||
# <a name="Install-latest-firmware" />Install the latest default firmware on your keyboard
|
||||
|
||||
To load the firmware, open the Arduino IDE's "File" menu, and click on the "Examples" submenu.
|
||||
|
||||
If you're using a Keyboardio Model 01, Scroll down to 'Model01-Firmware':
|
||||
|
||||
|
||||
|
||||
If you're using another keyboard, you should find it under Examples -> Kaleidoscope -> Devices -> (Your keyboard maker) -> (Your keyboard)
|
||||
|
||||
After you pick your example sketch, Arduino wil open a new window showing the sketch's source code above a black message log section and a green status message bar at the bottom. The message log displays detailed information about what Arduino is doing.
|
||||
|
||||
_**Note:** We recommend that you install the default firmware at least once before you start to make changes. This gives you a chance to ensure that the firmware update process works._
|
||||
|
||||
# Build the firmware
|
||||
|
||||
Click the check mark icon below "File" to build your firmware.
|
||||
|
||||
|
||||
|
||||
If the firmware builds successfully, Arduino reports "Done Compiling" in the green status bar.
|
||||
|
||||
|
||||
|
||||
If something goes wrong, the status bar turns orange and displays an error message. Additionally, there may be text in the black message log with more details about the error. At this point, it may be helpful to expand the message log so that you can see a bit more about what's going on.
|
||||
|
||||
|
||||
|
||||
|
||||
If you see errors, refer to [Getting help](Getting-help) for troubleshooting tips and useful resources.
|
||||
|
||||
# Install the firmware
|
||||
|
||||
If your keyboard has a programming interlock key, you'll need to hold it down now. On the Keyboardio Model 01, this is the `Prog` key. On the Keyboardio Atreus, this is the `Esc` key.
|
||||
|
||||
Without releasing that key, click on the "right arrow" button in the sketch window menu bar. This starts the firmware installation process.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
If the process is successful, Arduino will tell you that in the status area. Some keyboards may also use LEDs to report their results. For example, the Model 01's LED's flash red across the board as the firmware is installed, and then the "LED" key glows blue.
|
||||
|
||||
On Windows, you may also see the message "the device Model 01 is undergoing additional configuration."
|
||||
|
||||
If you have any trouble flashing your keyboard's firmware, check to see if the issue is addressed on the [Troubleshooting Firmware Upload Issues](https://github.com/keyboardio/Kaleidoscope/wiki/Troubleshooting-Firmware-Upload-Issues)
|
||||
|
||||
@ -0,0 +1,11 @@
|
||||
# Design philosophy
|
||||
|
||||
Kaleidoscope should, in order:
|
||||
|
||||
1) Work well as a keyboard
|
||||
2) Be compatible with real hardware
|
||||
3) Be compatible with the spec
|
||||
4) Be easy to read and understand
|
||||
5) Be easy to modify and customize
|
||||
|
||||
Our code indentation style is managed with 'make astyle.' For code we 'own', there should be an astyle target in the Makefile. For third party code we use and expect to update (ever), we try not to mess with the upstream house style.
|
||||
@ -0,0 +1,9 @@
|
||||
<!-- -*- mode: markdown; fill-column: 8192 -*- -->
|
||||
|
||||
# Kaleidoscope Maintainers
|
||||
|
||||
We consider pull requests to the Kaleidoscope GitHub repo.
|
||||
|
||||
- [obra](https://github.com/obra)
|
||||
- [noseglasses](https://github.com/noseglasses)
|
||||
- [algernon](https://github.com/algernon)
|
||||
@ -0,0 +1,97 @@
|
||||
# Release testing
|
||||
|
||||
Before a new release of Kaleidoscope, the following test process should be run through on all supported operating systems.
|
||||
|
||||
(As of August 2017, this whole thing really applies to Model01-Firmware, but we hope to generalize it to Kaleidoscope)
|
||||
|
||||
# Tested operating systems
|
||||
|
||||
* The latest stable Ubuntu Linux release running X11. (We _should_ eventually be testing both X11 and Wayland)
|
||||
* The latest stable release of macOS
|
||||
* An older Mac OS X release TBD. (There were major USB stack changes in 10.9 or so)
|
||||
* Windows 10
|
||||
* Windows 7
|
||||
* The current release of ChromeOS
|
||||
* A currentish android tablet that supports USB Host
|
||||
* an iOS device (once we fix the usb connection issue to limit power draw)
|
||||
|
||||
# Test process
|
||||
|
||||
## Basic testing
|
||||
1. Plug the keyboard in
|
||||
1. Make sure the host OS doesn't throw an error
|
||||
1. Make sure the LED in the top left doesn't glow red
|
||||
1. Make sure the LED in the top-right corner of the left side breathes blue for ~10s
|
||||
1. Bring up some sort of notepad app or text editor
|
||||
|
||||
## Basic testing, part 2
|
||||
|
||||
1. Test typing of shifted and unshifted letters and numbers with and without key repeat
|
||||
1. Test typing of fn-shifted characters: []{}|\ with and without key repeat
|
||||
1. Test that 'Any' key generates a random letter or number and that key repeat works
|
||||
1. Test fn-hjkl to move the cursor
|
||||
1. Test Fn-WASD to move the mouse
|
||||
1. Test Fn-RFV for the three mouse buttons
|
||||
1. Test Fn-BGTabEsc for mouse warp
|
||||
1. Test that LeftFn+RightFn + hjkl move the cursor
|
||||
1. Verify that leftfn+rightfn do not light up the numpad
|
||||
|
||||
## NKRO
|
||||
|
||||
1. Open the platform's native key event viewer
|
||||
(If not available, visit https://www.microsoft.com/appliedsciences/KeyboardGhostingDemo.mspx in a browser)
|
||||
1. Press as many keys as your fingers will let you
|
||||
1. Verify that the keymap reports all the keys you're pressing
|
||||
|
||||
|
||||
## Test media keys
|
||||
|
||||
1. Fn-Any: previous track
|
||||
1. Fn-Y: next-track
|
||||
1. Fn-Enter: play/pause
|
||||
1. Fn-Butterfly: Windows 'menu' key
|
||||
1. Fn-n: mute
|
||||
1. Fn-m: volume down
|
||||
1. Fn-,: volume up
|
||||
|
||||
## Test numlock
|
||||
|
||||
1. Tap "Num"
|
||||
1. Verify that the numpad lights up red
|
||||
1. Verify that the num key is breathing blue
|
||||
1. Verify that numpad keys generate numbers
|
||||
1. Tap the Num key
|
||||
1. Verify that the numpad keys stop being lit up
|
||||
1 Verify that 'jkl' don't generate numbers.
|
||||
|
||||
## Test LED Effects
|
||||
|
||||
1. Tap the LED key
|
||||
1. Verify that there is a rainbow effect
|
||||
1. Tap the LED key a few more times and verify that other LED effects show up
|
||||
1. Verify that you can still type.
|
||||
|
||||
## Second connection
|
||||
1. Unplug the keyboard
|
||||
1. Plug the keyboard back in
|
||||
1. Make sure you can still type
|
||||
|
||||
## Programming
|
||||
1. If the OS has a way to show serial port devices, verify that the keyboard's serial port shows up.
|
||||
1. If you can run stty, as you can on linux and macos, make sure you can tickle the serial port at 1200 bps.
|
||||
Linux: stty -F /dev/ttyACM0 1200
|
||||
Mac:
|
||||
1. If you tickle the serial port without holding down the prog key, verify that the Prog key does not light up red
|
||||
1. If you hold down the prog key before tickling the serial port, verify that the Prog key's LED lights up red.
|
||||
1. Unplug the keyboard
|
||||
1. While holding down prog, plug the keyboard in
|
||||
1. Verify that the prog key is glowing red.
|
||||
1. Unplug the keyboard
|
||||
1. Plug the keyboard in
|
||||
1. Verify that the prog key is not glowing red.
|
||||
|
||||
# If the current platform supports the Arduino IDE (Win/Lin/Mac)
|
||||
1. use the Arduino IDE to reflash the current version of the software.
|
||||
1. Verify that you can type a few keys
|
||||
1. Verify that the LED key toggles between LED effects
|
||||
|
||||
@ -0,0 +1,56 @@
|
||||
# Automated Testing
|
||||
|
||||
## Testing with gtest/gmock
|
||||
|
||||
Before feature requests or bug fixes can be merged into master, the folowing
|
||||
steps should be taken:
|
||||
|
||||
- Create a new test suite named after the issue, e.g. `Issue840`.
|
||||
- Add a test case named `Reproduces` that reproduces the bug. It should fail if
|
||||
the bug is present and pass if the bug is fixed.
|
||||
- Merge the proposed fix into a temporary testing branch.
|
||||
- The reproduction test should fail.
|
||||
- Add a test called "HasNotRegresed" that detects a potential regression.
|
||||
It should pass with the fix and fail before the fix.
|
||||
- Comment out and keep the `Reproduces` test case as documentation.
|
||||
|
||||
For an example, see keyboardio:Kaleidoscope/tests/issue_840.
|
||||
|
||||
### Adding a New Test Case
|
||||
|
||||
For general information on writing test with gtest/gmock see [gtest
|
||||
docs](https://github.com/google/googletest/tree/master/googletest/docs) and
|
||||
[gmock docs](https://github.com/google/googletest/tree/master/googlemock/docs).
|
||||
|
||||
1. Create a new test file, if appropriate.
|
||||
1. Choose a new test suite name and create a new test fixture, if appropriate.
|
||||
1. Write your test case.
|
||||
|
||||
The final include in any test file should be `#include
|
||||
"testing/setup-googletest.h"` which should be followed by the macro
|
||||
invocation `SETUP_GOOGLETEST()`. This will take care of including headers
|
||||
commonly used in tests in addtion to gtest and gmock headers.
|
||||
|
||||
Any test fixtures should inherit from `VirtualDeviceTest` which wraps the test
|
||||
sim APIs and provides common setup and teardown functionality. The appropriate
|
||||
header is already imported by `setup-googletest.h`
|
||||
|
||||
### Test Infrastructure
|
||||
|
||||
If you need to modify or extend test infrastructure to support your use case,
|
||||
it can currently be found under `keyboardio:Kaleidoscope/testing`.
|
||||
|
||||
### Style
|
||||
|
||||
TODO(obra): Fill out this section to your liking.
|
||||
|
||||
You can see samples of the desired test style in the [example tests](#examples).
|
||||
|
||||
### Examples
|
||||
|
||||
All existing tests are examples and may be found under
|
||||
`keyboardio:Kaleidoscope/tests`.
|
||||
|
||||
## Testing with Aglais/Papilio
|
||||
|
||||
TODO(obra): Write (or delegate the writing of) this section.
|
||||
@ -0,0 +1,99 @@
|
||||
# Release testing
|
||||
|
||||
Before a new release of Kaleidoscope, the following test process should be run through on all supported operating systems.
|
||||
|
||||
Always run all of the [automated tests](automated-testing.md) to verify there are no regressions.
|
||||
|
||||
(As of August 2017, this whole thing really applies to Model01-Firmware, but we hope to generalize it to Kaleidoscope)
|
||||
|
||||
# Tested operating systems
|
||||
|
||||
* The latest stable Ubuntu Linux release running X11. (We _should_ eventually be testing both X11 and Wayland)
|
||||
* The latest stable release of macOS
|
||||
* An older Mac OS X release TBD. (There were major USB stack changes in 10.9 or so)
|
||||
* Windows 10
|
||||
* Windows 7
|
||||
* The current release of ChromeOS
|
||||
* A currentish android tablet that supports USB Host
|
||||
* an iOS device (once we fix the usb connection issue to limit power draw)
|
||||
|
||||
# Test process
|
||||
|
||||
## Basic testing
|
||||
1. Plug the keyboard in
|
||||
1. Make sure the host OS doesn't throw an error
|
||||
1. Make sure the LED in the top left doesn't glow red
|
||||
1. Make sure the LED in the top-right corner of the left side breathes blue for ~10s
|
||||
1. Bring up some sort of notepad app or text editor
|
||||
|
||||
## Basic testing, part 2
|
||||
|
||||
1. Test typing of shifted and unshifted letters and numbers with and without key repeat
|
||||
1. Test typing of fn-shifted characters: []{}|\ with and without key repeat
|
||||
1. Test that 'Any' key generates a random letter or number and that key repeat works
|
||||
1. Test fn-hjkl to move the cursor
|
||||
1. Test Fn-WASD to move the mouse
|
||||
1. Test Fn-RFV for the three mouse buttons
|
||||
1. Test Fn-BGTabEsc for mouse warp
|
||||
1. Test that LeftFn+RightFn + hjkl move the cursor
|
||||
1. Verify that leftfn+rightfn do not light up the numpad
|
||||
|
||||
## NKRO
|
||||
|
||||
1. Open the platform's native key event viewer
|
||||
(If not available, visit https://www.microsoft.com/appliedsciences/KeyboardGhostingDemo.mspx in a browser)
|
||||
1. Press as many keys as your fingers will let you
|
||||
1. Verify that the keymap reports all the keys you're pressing
|
||||
|
||||
|
||||
## Test media keys
|
||||
|
||||
1. Fn-Any: previous track
|
||||
1. Fn-Y: next-track
|
||||
1. Fn-Enter: play/pause
|
||||
1. Fn-Butterfly: Windows 'menu' key
|
||||
1. Fn-n: mute
|
||||
1. Fn-m: volume down
|
||||
1. Fn-,: volume up
|
||||
|
||||
## Test numlock
|
||||
|
||||
1. Tap "Num"
|
||||
1. Verify that the numpad lights up red
|
||||
1. Verify that the num key is breathing blue
|
||||
1. Verify that numpad keys generate numbers
|
||||
1. Tap the Num key
|
||||
1. Verify that the numpad keys stop being lit up
|
||||
1 Verify that 'jkl' don't generate numbers.
|
||||
|
||||
## Test LED Effects
|
||||
|
||||
1. Tap the LED key
|
||||
1. Verify that there is a rainbow effect
|
||||
1. Tap the LED key a few more times and verify that other LED effects show up
|
||||
1. Verify that you can still type.
|
||||
|
||||
## Second connection
|
||||
1. Unplug the keyboard
|
||||
1. Plug the keyboard back in
|
||||
1. Make sure you can still type
|
||||
|
||||
## Programming
|
||||
1. If the OS has a way to show serial port devices, verify that the keyboard's serial port shows up.
|
||||
1. If you can run stty, as you can on linux and macos, make sure you can tickle the serial port at 1200 bps.
|
||||
Linux: stty -F /dev/ttyACM0 1200
|
||||
Mac:
|
||||
1. If you tickle the serial port without holding down the prog key, verify that the Prog key does not light up red
|
||||
1. If you hold down the prog key before tickling the serial port, verify that the Prog key's LED lights up red.
|
||||
1. Unplug the keyboard
|
||||
1. While holding down prog, plug the keyboard in
|
||||
1. Verify that the prog key is glowing red.
|
||||
1. Unplug the keyboard
|
||||
1. Plug the keyboard in
|
||||
1. Verify that the prog key is not glowing red.
|
||||
|
||||
# If the current platform supports the Arduino IDE (Win/Lin/Mac)
|
||||
1. use the Arduino IDE to reflash the current version of the software.
|
||||
1. Verify that you can type a few keys
|
||||
1. Verify that the LED key toggles between LED effects
|
||||
|
||||
@ -0,0 +1,125 @@
|
||||
# Core plugin overview
|
||||
|
||||
This is an annotated list of some of Kaleidoscope's most important core plugins. You may also want to consult the [automatically generated list of all plugins bundled with Kaleidoscope](../plugin_list).
|
||||
|
||||
|
||||
You can find a list of hird-party plugins not distributed as part of Kaleidoscope at https://community.keyboard.io/c/programming/Discuss-Plugins-one-thread-per-plugin
|
||||
|
||||
## EEPROM-Keymap
|
||||
|
||||
[EEPROM-Keymap Documentation](../plugins/EEPROM-Keymap.md)
|
||||
|
||||
While keyboards usually ship with a keymap programmed in, to be able to change that keymap, without flashing new firmware, we need a way to place the keymap into a place we can update at run-time, and which persists across reboots. Fortunately, we have a bit of EEPROM on the keyboard, and can use it to store either the full keymap (and saving space in the firmware then), or store an overlay there. In the latter case, whenever there is a non-transparent key on the overlay, we will use that instead of the keyboard default.
|
||||
|
||||
In short, this plugin allows us to change our keymaps, without having to compile and flash new firmware. It does so through the use of the Focus plugin.
|
||||
|
||||
## Escape-OneShot
|
||||
|
||||
[Escape-OneShot Documentation](../plugins/Escape-OneShot.md)
|
||||
|
||||
Turn the Esc key into a special key, that can cancel any active OneShot effect - or act as the normal Esc key if none are active. For those times when one accidentally presses a one-shot key, or change their minds.
|
||||
|
||||
## KeyLogger
|
||||
|
||||
[KeyLogger Documentation](../plugins/KeyLogger.md)
|
||||
|
||||
The KeyLogger plugin, as the name suggests, implements a key logger for the Kaleidoscope firmware. It logs the row and column of every key press and release, along with the event, and the layer number, in a format that is reasonably easy to parse, to the Serial interface.
|
||||
|
||||
**A word of warning**: Having a key logger is as dangerous as it sounds. Anyone who can read the serial events from the keyboard, will know exactly what keys you press, and when. Unless you know what you are doing, and can secure your keyboard, do not enable this plugin.
|
||||
|
||||
## Leader
|
||||
|
||||
[Leader Documentation](../plugins/Leader.md)
|
||||
|
||||
Leader keys are a kind of key where when they are tapped, all following keys are swallowed, until the plugin finds a matching sequence in the dictionary, it times out, or fails to find any possibilities. When a sequence is found, the corresponding action is executed, but the processing still continues. If any key is pressed that is not the continuation of the existing sequence, processing aborts, and the key is handled normally.
|
||||
|
||||
This behaviour is best described with an example. Suppose we want a behaviour where ``LEAD u`` starts unicode input mode, and ``LEAD u h e a r t`` should result in a heart symbol being input, and we want ``LEAD u 0 0 e 9 SPC`` to input é, and any other hex code that follows ``LEAD u``, should be handled as-is, and passed to the host. Obviously, we can't have all of this in a dictionary.
|
||||
|
||||
So we put ``LEAD u`` and ``LEAD u h e a r t`` in the dictionary only. The first will start unicode input mode, the second will type in the magic sequence that results in the symbol, and then aborts the leader sequence processing. With this setup, if we type ``LEAD u 0``, then ``LEAD u`` will be handled first, and start unicode input mode. Then, at the 0, the plugin notices it is not part of any sequence, so aborts leader processing, and passes the key on as-is, and it ends up being sent to the host. Thus, we covered all the cases of our scenario!
|
||||
|
||||
## Macros
|
||||
|
||||
[Macros Documentation](../plugins/Macros.md)
|
||||
|
||||
Macros are a standard feature on many keyboards and powered ones are no exceptions. Macros are a way to have a single key-press do a whole lot of things under the hood: conventionally, macros play back a key sequence, but with Kaleidoscope, there is much more we can do. Nevertheless, playing back a sequence of events is still the primary use of macros.
|
||||
|
||||
Playing back a sequence means that when we press a macro key, we can have it play pretty much any sequence. It can type some text for us, or invoke a complicated shortcut - the possibilities are endless!
|
||||
|
||||
## MagicCombo
|
||||
|
||||
[MagicCombo Documentation](../plugins/MagicCombo.md)
|
||||
|
||||
The MagicCombo extension provides a way to perform custom actions when a particular set of keys are held down together. The functionality assigned to these keys are not changed, and the custom action triggers as long as all keys within the set are pressed. The order in which they were pressed do not matter.
|
||||
|
||||
This can be used to tie complex actions to key chords.
|
||||
|
||||
## OneShot
|
||||
|
||||
[OneShot Documentation](../plugins/OneShot.md)
|
||||
|
||||
One-shots are a new kind of behaviour for your standard modifier and momentary layer keys: instead of having to hold them while pressing other keys, they can be tapped and released, and will remain active until any other key is pressed. In short, they turn ``Shift, A`` into ``Shift+A``, and ``Fn, 1`` to ``Fn+1``. The main advantage is that this allows us to place the modifiers and layer keys to positions that would otherwise be awkward when chording. Nevertheless, they still act as normal when held, that behaviour is not lost.
|
||||
|
||||
Furthermore, if a one-shot key is tapped two times in quick succession, it becomes sticky, and remains active until disabled with a third tap. This can be useful when one needs to input a number of keys with the modifier or layer active, and still does not wish to hold the key down. If this feature is undesirable, unset the ``OneShot.double_tap_sticky property`` (see later).
|
||||
|
||||
To make multi-modifier, or multi-layer shortcuts possible, one-shot keys remain active if another one-shot of the same type is tapped, so ``Ctrl, Alt, b`` becomes ``Ctrl+Alt+b``, and ``L1, L2, c`` is turned into ``L1+L2+c``.
|
||||
|
||||
## Qukeys
|
||||
|
||||
[Qukeys Documentation](../plugins/Qukeys.md)
|
||||
|
||||
A Qukey is a key that has two possible values, usually a modifier and a printable character. The name is a play on the term "qubit" (short for "quantum bit") from quantum computing. The value produced depends on how long the key press lasts, and how it is used in combination with other keys (roughly speaking, whether the key is "tapped" or "held").
|
||||
|
||||
The _primary_ value (a printable character) of a Qukey is output if the key is "tapped" (i.e. quickly pressed and released). If it is held long enough, it will instead produce the Qukey's _alternate_ value (usually a modifier). It will also produce that alternate value if a subsequent key is tapped after the initial keypress of the Qukey, even if both keys are released before the time it takes to produce the alternate value on its own. This makes it feasible for most people to use Qukeys on home-row keys, without slowing down typing. In this configuration, it can become very comfortable to use modifier combinations, without needing to move one's hands from the home position at all.
|
||||
|
||||
Qukeys can be defined to produce any two keys, including other plugin keys and keys with modifier flags applied. For example, one could define a Qukey to produce ``Shift + 9`` when tapped, and a OneShot ``Ctrl`` when held.
|
||||
|
||||
It is also possible to use Qukeys like SpaceCadet (see below), by setting the primary value to a modifier, and the alternate value to a printable character (e.g. ``(``). In that case, the behavior is reversed, and the alternate value will only be used if the key is pressed and released without any rollover to a subsequent key press.
|
||||
|
||||
## ShapeShifter
|
||||
|
||||
[ShapeShifter Documentation](../plugins/ShapeShifter.md)
|
||||
|
||||
ShapeShifter is a plugin that makes it considerably easier to change what symbol is input when a key is pressed together with ``Shift``. If one wants to rearrange the symbols on the number row for example, without modifying the layout on the operating system side, this plugin is where one can turn to.
|
||||
|
||||
What it does, is very simple: if any key in its dictionary is found pressed while ``Shift`` is held, it will press another key instead of the one triggering the event. For example, if it sees ``Shift + 1`` pressed together, which normally results in a ``!``, it will press ``4`` instead of ``1``, inputting ``$``.
|
||||
|
||||
## SpaceCadet
|
||||
|
||||
[SpaceCadet Documentation](../plugins/SpaceCadet.md)
|
||||
|
||||
Space Cadet is a way to make it more convenient to input parens - those ``(`` and ``)`` things -, symbols that a lot of programming languages use frequently. If you are working with Lisp, you are using these all the time.
|
||||
|
||||
What it does, is that it turns your left and right ``Shift`` keys into parens if you tap and release them, without pressing any other key while holding them. Therefore, to input, say, ``(print foo)``, you don't need to press ``Shift``, hold it, and press ``9`` to get a ``(``, you simply press and release ``Shift``, and continue writing. You use it as if you had a dedicated key for parens!
|
||||
|
||||
But if you wish to write capital letters, you hold it, as usual, and you will not see any parens when you release it. You can also hold it for a longer time, and it still would act as a ``Shift``, without the parens inserted on release: this is useful when you want to augment some mouse action with ``Shift``, to select text, for example.
|
||||
|
||||
After getting used to the Space Cadet style of typing, you may wish to enable this sort of functionality on other keys, as well. Fortunately, the Space Cadet plugin is configurable and extensible to support adding symbols to other keys. Along with ``(`` on your left ``Shift`` key and ``)`` on your right ``Shift`` key, you may wish to add other such programming mainstays as ``{`` to your left-side ``cmd`` key, ``}`` to your right-side ``alt`` key, [ to your left ``Control`` key, and ``]`` to your right ``Control`` key. You can map the keys in whatever way you may wish to do, so feel free to experiment with different combinations and discover what works best for you!
|
||||
|
||||
## TapDance
|
||||
|
||||
[TapDance Documentation](../plugins/TapDance.md)
|
||||
|
||||
Tap-dance keys are general purpose, multi-use keys, which trigger a different action based on the number of times they were tapped in sequence. As an example to make this clearer, one can have a key that inputs ``A`` when tapped once, inputs ``B`` when tapped twice, and lights up the keyboard in Christmas colors when tapped a third time.
|
||||
|
||||
This behaviour is most useful in cases where we have a number of things we perform rarely, where tapping a single key repeatedly is not counter-productive. Such cases include - for example - multimedia forward / backward keys: forward on single tap, backward on double. Of course, one could use modifiers to achieve a similar effect, but that's two keys to use, this is only one. We can also hide some destructive functionality behind a number of taps: reset the keyboard after 4 taps, and light up LEDs in increasingly frightful colors until then.
|
||||
|
||||
How does it work?
|
||||
|
||||
To not interfere with normal typing, tap-dance keys have two ways to decide when to call an action: they either get interrupted, or they time out. Every time a tap-dance key is pressed, the timer resets, so one does not have to finish the whole tapping sequence within a short time limit. The tap-dance counter continues incrementing until one of these cases happen.
|
||||
|
||||
When a tap-dance key is pressed and released, and nothing is pressed on the keyboard until the timeout is reached, then the key will time out, and trigger an action. Which action, depends on the number of times it has been tapped up until this point.
|
||||
|
||||
When a tap-dance key is pressed and released, and another key is hit before the timer expires, then the tap-dance key will trigger an action first, perform it, and only then will the firmware continue handling the interrupting key press. This is to preserve the order of keys pressed.
|
||||
|
||||
In both of these cases, the ``tapDanceAction`` will be called, with ``tapDanceIndex`` set to the index of the tap-dance action (as set in the keymap), the ``tapCount``, and tapDanceAction set to either ``kaleidoscope::TapDance::Interrupt``, or ``kaleidoscope::TapDance::Timeout``. If we continue holding the key, then as long as it is held, the same function will be called with tapDanceAction set to ``kaleidoscope::TapDance::Hold``. When the key is released, after either an Interrupt or Timeout action was triggered, the function will be called with tapDanceAction set to ``kaleidoscope::TapDance::Release``.
|
||||
|
||||
These actions allow us to create sophisticated tap-dance setups, where one can tap a key twice and hold it, and have it repeat, for example.
|
||||
|
||||
There is one additional value the tapDanceAction parameter can ``take: kaleidoscope::TapDance::Tap``. It is called with this argument for each and every tap, even if no action is to be triggered yet. This is so that we can have a way to do some side-effects, like light up LEDs to show progress, and so on.
|
||||
|
||||
## TopsyTurvy
|
||||
|
||||
[TopsyTurvy Documentation](../plugins/TopsyTurvy.md)
|
||||
|
||||
TopsyTurvy is a plugin that inverts the behaviour of the Shift key for some selected keys. That is, if configured so, it will input ``!`` when pressing the ``1`` key without ``Shift``, but with the modifier pressed, it will input the original ``1`` symbol.
|
||||
|
||||
@ -0,0 +1,29 @@
|
||||
# Using EEPROM
|
||||
|
||||
## Why Use EEPROM?
|
||||
|
||||
While we've done our best to make it easy to change how your keyboard works by changing your firmware & re-flashing it, sometimes it would be convenient to be able to make changes without having to go through that rigamarole.
|
||||
Maybe you'd like to be able to use a GUI like [Chrysalis](https://github.com/keyboardio/Chrysalis) to configure your keyboard layout or LED themes, or maybe your sketch is getting very complicated and you're looking for a way to save program memory.
|
||||
In either case, you'll want to use EEPROM to store your settings.
|
||||
|
||||
## What is EEPROM?
|
||||
|
||||
EEPROM stands for "Electronic Erasable Programmable Read-Only Memory" and is one of the three memory mediums your keyboard has.
|
||||
The other two are RAM, which is used for variables when running your code, and program memory, which is used for storing the program, as well as some other select pieces of data (if you're curious, the bit in your sketch where it says `PROGMEM` indicates that a variable is being stored in program memory instead of RAM).
|
||||
RAM we want to keep as free as we can, since running our code will need some RAM to work.
|
||||
While we can put stuff in PROGMEM, your code itself will take up some room there, so it may be useful to store things elsewhere.
|
||||
EEPROM provides us with another place to store things that can free up RAM and PROGMEM.
|
||||
Additionally, by leveraging a few plugins, we can store configuration in EEPROM and allow a GUI tool on the connected computer to change settings on the keyboard!
|
||||
|
||||
## Move Settings to EEPROM
|
||||
|
||||
There are a few important Kaleidoscope plugins for putting settings in EEPROM:
|
||||
|
||||
<!-- - [Kaleidoscope-EEPROM-Keymap-Programmer][] - is this worth mentioning in this context? -->
|
||||
- Kaleidoscope-Focus] - This plugin is what enables communication between your keyboard and programs running on your computer; all the following plugins require you to be using this if you want to be able to change your settings from the computer without re-flashing.
|
||||
- Kaleidoscope-EEPROM-Settings - This is a plugin that doesn't do much by itself, but most of the other EEPROM plugins will need active to be able to make use of EEPROM storage.
|
||||
- Kaleidoscope-EEPROM-Keymap - This plugin uses Focus and EEPROM-Settings to allow either overriding or fully replacing the programmed-in keymap without reflashing (by means of a program like Chrysalis running on your computer).
|
||||
- Kaleidoscope-Colormap - This plugin allows you to use a computer-side program to set a (static -- i.e. the keys won't change colour over time) LED theme for each layer.
|
||||
|
||||
All these plugins have minimal installation that can be found in their respective READMEs.
|
||||
After following the instructions for each and adding them together, you should be able to download a program that knows how to communicate with the keyboard (i.e. [Chrysalis](https://github.com/keyboardio/Chrysalis) and you can start customizing settings without having to do any more programming!
|
||||
@ -0,0 +1,19 @@
|
||||
# What can go on your keymap
|
||||
|
||||
Eventually there should be a helpful table here with good definitions for the common codes. In the meantime, you can check these files for all the codes the Keyboardio supports:
|
||||
|
||||
- Most of the common keyboard key codes are here:
|
||||
|
||||
[key_defs_keyboard.h](https://github.com/keyboardio/Kaleidoscope/blob/master/src/kaleidoscope/key_defs_keyboard.h)
|
||||
|
||||
- Key codes for system tasks like shutting down, switching windows, and moving through menus are here:
|
||||
|
||||
[key_defs_sysctl.h](https://github.com/keyboardio/Kaleidoscope/blob/master/src/kaleidoscope/key_defs_sysctl.h)
|
||||
|
||||
- A wide range of key codes for controlling consumer electronics, most of which are probably not relevant, are in this file:
|
||||
|
||||
[key_defs_consumerctl.h](https://github.com/keyboardio/Kaleidoscope/blob/master/src/kaleidoscope/key_defs_consumerctl.h)
|
||||
|
||||
## In-keymap chorded keys
|
||||
|
||||
In addition, the keys in `key_defs_keyboard.h` can be augmented with modifier macros: `LCTRL()`, `LSHIFT()`, `LALT()`, `LGUI()` and `RALT()` to add chorded keys to your keymap. For example `LCTRL(LALT(Key_Delete))` can be used to add control-alt-delete as a single key to your keymap, should you wish. The innermost bracket must be of the standard format as taken from the above key definitions, and all other modifiers must be from the aforementioned list, and in that format. This does allow you to create single keys for multiple modifiers, e.g. `LCTRL(LALT(LSHIFT(Key_LeftGui)))`, when held, would have the effect of all left modifiers at once. These modifier macros only work for standard keys! When applied to any key provided by a plugin, they will have no effect.
|
||||
@ -0,0 +1,37 @@
|
||||
# Core LED Effects
|
||||
|
||||
|
||||
This is the list of the stable LED effects in the core libraries.
|
||||
|
||||
<h4>LED-ActiveModColor</h4>
|
||||
|
||||
A very simple plugin, that lights up the LED in white under any active modifier, for the duration of its activity. Also supports one-shots.
|
||||
|
||||
<h4>Kaleidoscope-LEDEffects</h4>
|
||||
|
||||
The LEDEffects plugin provides a selection of LED effects, each of them fairly simple, simple enough to not need a plugin of their own. There are a number of different effects included in the package, all of them are available once including the header, and one's free to choose any number of them.
|
||||
<h4>Kaleidoscope-LEDEffect-BootGreeting</h4>
|
||||
|
||||
If you want to have your keyboard signal when it turns on, but you don't want to use any more complicated LED modes, this plugin is for you. It will make the ``LEDEffectNext`` key on your keymap slowly breathe for about ten seconds after plugging the keyboard in (without blocking the normal functionality of the keyboard, of course).
|
||||
|
||||
<h4>Kaleidoscope-LEDEffect-Breathe</h4>
|
||||
|
||||
Provides a breathing effect for the keyboard. Breathe in, breathe out.
|
||||
|
||||
<h4>Kaleidoscope-LEDEffect-Chase</h4>
|
||||
|
||||
A simple LED effect where one color chases another across the keyboard and back, over and over again. Playful colors they are.
|
||||
|
||||
<h4>Kaleidoscope-LEDEffect-Rainbow</h4>
|
||||
|
||||
Two colorful rainbow effects are implemented by this plugin: one where the rainbow waves through the keys, and another where the LEDs breathe though the colors of a rainbow. The difference is that in the first case, we have all the rainbow colors on display, and it waves through the keyboard. In the second case, we have only one color at a time, for the whole board, and the color cycles through the rainbow's palette.
|
||||
|
||||
<h4>Kaleidoscope-LEDEffect-SolidColor</h4>
|
||||
|
||||
This plugin provides tools to build LED effects that set the entire keyboard to a single color. For show, and for backlighting purposes.
|
||||
|
||||
<h4>LED-Stalker</h4>
|
||||
|
||||
Demoed in the backer update, this adds an effect that stalks your keys: whenever a key is pressed, the LED under it lights up, and the slowly fades away once the key is released. This provides a kind of trailing effect.
|
||||
|
||||
There are two color schemes currently: Haunt, which is a white-ish, ghostly color that follows your fingers, and BlazingTrail, demoed in the video, which lights your keyboard on fire. It looks much better in real life.
|
||||
@ -0,0 +1,35 @@
|
||||
# Developing interdependent plugins
|
||||
|
||||
Say you have two Kaleidoscope plugins or, more general, two Arduino libraries `A` and `B`. Let's assume `B` depends on `A` in a sense that `B` references symbols (functions/variables) defined in `A`. Both libraries define header files `a_header.h` and `b_header.h` that specify their exported symbols.
|
||||
|
||||
The following sketch builds as expected.
|
||||
```cpp
|
||||
// my_sketch.ino
|
||||
#include "b_header.h"
|
||||
#include "a_header.h"
|
||||
...
|
||||
```
|
||||
|
||||
If the header appear in opposite order the linker will throw undefined symbol errors regarding missing symbols from `A`.
|
||||
```cpp
|
||||
// my_sketch.ino
|
||||
#include "a_header.h"
|
||||
#include "b_header.h"
|
||||
...
|
||||
```
|
||||
The reason for this somewhat unexpected behavior is that the order of libraries' occurrence in the linker command line is crucial. The linker must see library `B` first to determine which symbols it needs to extract from `A`. If it encounters `A` first, it completely neglects its symbols as there are no references to it at that point.
|
||||
|
||||
To be on the safe side and only if the sketch does not reference symbols from `A` directly, it is better to include the headers in the following way.
|
||||
```cpp
|
||||
// header_b.h
|
||||
#include "header_a.h"
|
||||
...
|
||||
```
|
||||
|
||||
```cpp
|
||||
// my_sketch.ino
|
||||
// Do not include a_header.h directly. It is already included by b_header.h.
|
||||
#include "b_header.h"
|
||||
...
|
||||
```
|
||||
Note: I did no thorough research on how Arduino internally establishes the linker command line, e.g. with respect to a recursive traversal of the include-tree. This means, I am not sure how the link command line order is generated when header files that are included by the main `.ino` do include other files that provide definitions of library symbols in different orders. There might be additional pitfalls when header includes are more complex given a larger project.
|
||||
@ -0,0 +1,10 @@
|
||||
# Keyboardio Atreus
|
||||
|
||||
This is a plugin for [Kaleidoscope][fw], that provides hardware support for
|
||||
the [Keyboardio Atreus][kbio:atreus].
|
||||
|
||||
The default firmware sketch for the Atreus is [included with Kaleidoscope][sketch]
|
||||
|
||||
[fw]: https://github.com/keyboardio/Kaleidoscope
|
||||
[sketch]: https://github.com/keyboardio/Kaleidoscope/blob/master/examples/Devices/Keyboardio/Atreus/Atreus.ino
|
||||
[kbio:atreus]: https://shop.keyboard.io/
|
||||
@ -1,7 +1,10 @@
|
||||
# Kaleidoscope-Hardware-Model01
|
||||
# Keyboardio Model 01
|
||||
|
||||
This is a plugin for [Kaleidoscope][fw], that adds hardware support for
|
||||
the [Keyboardio Model01][kbdio:model01].
|
||||
the [Keyboardio Model 01][kbio:model01].
|
||||
|
||||
The default firmware sketch for the Model 01 is [available on GitHub][sketch]
|
||||
|
||||
[fw]: https://github.com/keyboardio/Kaleidoscope
|
||||
[kbdio:model01]: https://shop.keyboard.io/
|
||||
[sketch]: https://github.com/keyboardio/Model01-Firmware/blob/master/Model01-Firmware.ino
|
||||
[kbio:model01]: https://shop.keyboard.io/
|
||||
|
||||
|
After Width: | Height: | Size: 1.3 MiB |
|
After Width: | Height: | Size: 64 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 43 KiB |
|
After Width: | Height: | Size: 83 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
After Width: | Height: | Size: 281 KiB |
|
After Width: | Height: | Size: 239 KiB |
|
After Width: | Height: | Size: 96 KiB |
|
After Width: | Height: | Size: 60 KiB |
|
After Width: | Height: | Size: 62 KiB |
|
After Width: | Height: | Size: 39 KiB |
|
After Width: | Height: | Size: 37 KiB |
|
After Width: | Height: | Size: 43 KiB |
|
After Width: | Height: | Size: 42 KiB |
|
After Width: | Height: | Size: 34 KiB |
|
After Width: | Height: | Size: 41 KiB |
|
After Width: | Height: | Size: 96 KiB |
|
After Width: | Height: | Size: 103 KiB |
|
After Width: | Height: | Size: 1.3 KiB |
|
After Width: | Height: | Size: 18 KiB |
|
After Width: | Height: | Size: 1.2 MiB |
|
After Width: | Height: | Size: 38 KiB |
|
After Width: | Height: | Size: 160 KiB |
|
After Width: | Height: | Size: 158 KiB |
|
After Width: | Height: | Size: 160 KiB |
|
After Width: | Height: | Size: 152 KiB |
|
After Width: | Height: | Size: 150 KiB |
|
After Width: | Height: | Size: 53 KiB |
|
After Width: | Height: | Size: 140 KiB |
|
After Width: | Height: | Size: 167 KiB |
|
After Width: | Height: | Size: 46 KiB |
|
After Width: | Height: | Size: 34 KiB |
|
After Width: | Height: | Size: 90 KiB |
|
After Width: | Height: | Size: 78 KiB |
|
After Width: | Height: | Size: 98 KiB |
|
After Width: | Height: | Size: 239 KiB |
|
After Width: | Height: | Size: 108 KiB |
|
After Width: | Height: | Size: 34 KiB |
|
After Width: | Height: | Size: 38 KiB |
|
After Width: | Height: | Size: 626 KiB |
|
After Width: | Height: | Size: 2.4 KiB |
|
After Width: | Height: | Size: 33 KiB |
|
After Width: | Height: | Size: 624 KiB |
|
After Width: | Height: | Size: 107 KiB |
|
After Width: | Height: | Size: 111 KiB |
|
After Width: | Height: | Size: 73 KiB |
|
After Width: | Height: | Size: 73 KiB |
|
After Width: | Height: | Size: 86 KiB |
|
After Width: | Height: | Size: 54 KiB |
|
After Width: | Height: | Size: 2.3 KiB |
|
After Width: | Height: | Size: 33 KiB |
|
After Width: | Height: | Size: 5.0 KiB |
|
After Width: | Height: | Size: 5.3 KiB |
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 5.0 KiB |
@ -0,0 +1,10 @@
|
||||
Bundled plugins
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:caption: Bundled plugins
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
plugins/*
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue