FrederikBaerentsen
/
multibow
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

updates readme

This commit is contained in:
Harald Albrecht 2019-01-07 14:12:18 +01:00
parent 0810e11a40
commit 2dbc820086
1 changed files with 63 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
README.md
View File

@ -1,21 +1,36 @@
# Multibow # Multibow
GitHub: [github.com/thediveo/multibow](https://github.com/thediveo/multibow) Find it on GitHub:
[thediveo/multibow](https://github.com/thediveo/multibow).
Multibow turns a [Pimoroni Keybow](https://shop.pimoroni.com/products/keybow)
into a macro keyboard with multiple layouts, switchable at any time. (Keybow is
a solderless DIY 4x3 mechanical USB keyboard, powered by a Raspberry Pi. And
yes, these days even keyboards run Linux...)
![Multibow on Keybow](multibow.jpg) ![Multibow on Keybow](multibow.jpg)
Multibow adds ease-of use support for **multiple layouts** to [Pimoroni
Keybow](https://shop.pimoroni.com/products/keybow) macro keyboards. Simply
switch between the installed layouts by pressing a special key combination
(defaults to press-hold key #11, then tap key #5). And you can even control the key LEDs brightness (press-hold key #11, then tap key #8 to change brightness).
> "_Keybows_" are solderless DIY 4x3 mechanical USB keyboards, powered by a
> Raspberry Pi. And yes, these days even _keyboards_ now run Linux and script
> interpreters...
And yes, this is probably a New Year's project slightly gone overboard ...
what sane reason is there to end up with a Lua-scripted multi-layout keyboard
"operating" system and a bunch of automated unit test cases?
## Layouts ## Layouts
The default setup activates the following macro keyboard layouts shown below.
> You can switch (cycle) between them by pressing and holding key #11
> (top-left key in landscape), then tapping key #5 (immediately right to #11),
> and finally releasing both keys.
### Debug Go in VisualStudio Code ### Debug Go in VisualStudio Code
Debug Go programs and packages in VisualStudio Code with its Go extension. Debug Go programs and packages in VisualStudio Code with its Go extension.
``` ```text
┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐
┊ 11 ┊ ┊ 8 ┊ ┊ 5 ┊ ┊ 2 ┊ ┊ 11 ┊ ┊ 8 ┊ ┊ 5 ┊ ┊ 2 ┊
└╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘
@ -23,14 +38,19 @@ Debug Go programs and packages in VisualStudio Code with its Go extension.
╔════╗ ╔════╗ ┌╌╌╌╌┐ ╔════╗ ╔════╗ ╔════╗ ┌╌╌╌╌┐ ╔════╗
║ 10 ║ ║ 7 ║ ┊ 4 ┊ ║ 1 ║ ║ 10 ║ ║ 7 ║ ┊ 4 ┊ ║ 1 ║
╚════╝ ╚════╝ └╌╌╌╌┘ ╚════╝ ╚════╝ ╚════╝ └╌╌╌╌┘ ╚════╝
⏹STOP ↺RELOAD TSTPKG ⏹STOP ↺RELOAD ☑TSTPKG
╔════╗ ╔════╗ ╔════╗ ╔════╗ ╔════╗ ╔════╗ ╔════╗ ╔════╗
║ 9 ║ ║ 6 ║ ║ 3 ║ ║ 0 ║ ║ 9 ║ ║ 6 ║ ║ 3 ║ ║ 0 ║
╚════╝ ╚════╝ ╚════╝ ╚════╝ ╚════╝ ╚════╝ ╚════╝ ╚════╝
▮▶ ⭢STEP ⮧INTO ⮥OUT ▮▶ ⭢STEP ⮧INTO ⮥OUT
``` ```
* TSTPKG activates the command "go: test package". * ▮▶ starts, continues, or pauses the program to be debugged.
* ⮧INTO steps _into_ a function call.
* ⭢STEP steps _over_ a line/function call.
* ⏹STOP stops debugging
* ↺RELOAD reloads the program being debugged.
* ☑TSTPKG activates the command "go: test package".
### Kdenlive Video Editor ### Kdenlive Video Editor
@ -44,11 +64,11 @@ A SHIFT key, with Keybow LED brightness and keyboard layout cycle control.
> is always active, regardless of keyboard layout. The other keys in this layout > is always active, regardless of keyboard layout. The other keys in this layout
> only become active _while_ holding SHIFT. > only become active _while_ holding SHIFT.
``` ```text
╔════╗ ╔╌╌╌╌╗ ╔╌╌╌╌╗ ┌╌╌╌╌┐ ╔════╗ ╔╌╌╌╌╗ ╔╌╌╌╌╗ ┌╌╌╌╌┐
║ 11 ║ ┊ 8 ┊ ┊ 5 ┊ ┊ 2 ┊ ║ 11 ║ ┊ 8 ┊ ┊ 5 ┊ ┊ 2 ┊
╚════╝ ╚╌╌╌╌╝ ╚╌╌╌╌╝ └╌╌╌╌┘ ╚════╝ ╚╌╌╌╌╝ ╚╌╌╌╌╝ └╌╌╌╌┘
SHIFT →LAYOUT 🔆BRIGHT ⇑SHIFT →LAYOUT 🔆BRIGHT
┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐
┊ 10 ┊ ┊ 7 ┊ ┊ 4 ┊ ┊ 1 ┊ ┊ 10 ┊ ┊ 7 ┊ ┊ 4 ┊ ┊ 1 ┊
└╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘
@ -58,12 +78,20 @@ SHIFT →LAYOUT 🔆BRIGHT
└╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘
``` ```
* press ⇑SHIFT, release ⇑SHIFT: if a keyboard layout has a SHIFT layer, then
this activates and deactivates this ⇑SHIFT layer.
* press ⇑SHIFT, tap →LAYOUT, release ⇑SHIFT: switches to next keyboard layout.
* press ⇑SHIFT, tap 🔆BRIGHT, release 🔆BRIGHT: changes the keyboard LED
brightness in three different brightness steps (70% → 100% → 40% → 70% →
...).
### Empty ### Empty
Just as its name says: an empty keyboard layout -- useful if you want to have Just as its name says: an empty keyboard layout – useful if you want to have
also "no" layout active when working with multiple keyboard layouts. also a "no" layout with no functionality whatsoever to switch to. (_This
layout by courtesy of Margaret Thatcher._)
``` ```text
┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐
┊ 11 ┊ ┊ 8 ┊ ┊ 7 ┊ ┊ 6 ┊ ┊ 11 ┊ ┊ 8 ┊ ┊ 7 ┊ ┊ 6 ┊
└╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘
@ -88,14 +116,14 @@ keybow-firmware GitHub repository.
## Installation ## Installation
1. Download the [Pibow 1. Download the [Pibow
firmware](https://github.com/pimoroni/keybow-firmware/releases) and copy all firmware](https://github.com/pimoroni/keybow-firmware/releases) and copy
files inside its `sdcard/` subdirectory onto an empty, FAT32 formatted microSD all files inside its `sdcard/` subdirectory onto an empty, FAT32 formatted
card. Copy only the files **inside** `sdcard/`, but do **not** place them into a microSD card. Copy only the files **inside** `sdcard/`, but do **not**
~~`sdcard`~~ directory on your microSD card. place them into a ~~`sdcard`~~ directory on your microSD card.
2. Download all files from the `sdcard/` subdirectory of this repository and 2. Download all files from the `sdcard/` subdirectory of this repository and
then copy them onto the microSD card. This will overwrite but one file then copy them onto the microSD card. This will overwrite but one file
`key.lua`, all other files are new. `key.lua`, all other files are new.
## Multiple Keyboard Layouts ## Multiple Keyboard Layouts
@ -105,16 +133,24 @@ accordingly to require them. The default configuration is as follows:
```lua ```lua
require "layouts/shift" -- for cycling between layouts. require "layouts/shift" -- for cycling between layouts.
require "layouts/vsc-golang" -- debugging Go programs in VisualStudio Code. require "layouts/vsc-golang" -- debugging Go programs in VisualStudio Code.
require "layouts/kdenlive" -- editing video using Kdenlive.
require "layouts/empty" -- empty, do-nothing layout. require "layouts/empty" -- empty, do-nothing layout.
``` ```
## Developing ## Developing
For some basic testing, run `lua test.lua` from the base directory of this Whether you want to dry-run your own keyboard layout or to hack Multibow: use
repository. It pulls in `keybow`, then mocks some functionality of it, and the unit tests which you can find in the `spec/` subdirectory. These tests
finally starts `sdcard/keys.lua` as usual. help you in detecting syntax and logic errors early, avoiding the
This helps in detecting syntax and logic erros early, avoiding the
rinse-and-repeat cycle with copying to microSD card, starting the Keybow rinse-and-repeat cycle with copying to microSD card, starting the Keybow
hardware, and then wondering what went wrong, without any real clue. hardware, and then wondering what went wrong, without any real clue as to what
is the cause of failure.
Before your first testing, you'll need to run `./setup-tests.sh` once in order
to install (on Ubuntu-based distributions) the required system distribution and
LuaRocks packages.
Afterwards, simply run `busted` while in the `multibow` repository root
directory to run all tests. For instance, run `busted
spec/layout/kdenlive_spec.lua` to unit test a specific keyboard layout (or set
of layouts).