diff --git a/README.md b/README.md index aa9dfa6..c476327 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,36 @@ # Multibow -GitHub: [github.com/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...) +Find it on GitHub: +[thediveo/multibow](https://github.com/thediveo/multibow). ![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 +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 programs and packages in VisualStudio Code with its Go extension. -``` +```text ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┊ 11 ┊ ┊ 8 ┊ ┊ 5 ┊ ┊ 2 ┊ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ @@ -23,14 +38,19 @@ Debug Go programs and packages in VisualStudio Code with its Go extension. ╔════╗ ╔════╗ ┌╌╌╌╌┐ ╔════╗ ║ 10 ║ ║ 7 ║ ┊ 4 ┊ ║ 1 ║ ╚════╝ ╚════╝ └╌╌╌╌┘ ╚════╝ -⏹STOP ↺RELOAD TSTPKG +⏹STOP ↺RELOAD ☑TSTPKG ╔════╗ ╔════╗ ╔════╗ ╔════╗ ║ 9 ║ ║ 6 ║ ║ 3 ║ ║ 0 ║ ╚════╝ ╚════╝ ╚════╝ ╚════╝ ▮▶ ⭢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 @@ -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 > only become active _while_ holding SHIFT. -``` +```text ╔════╗ ╔╌╌╌╌╗ ╔╌╌╌╌╗ ┌╌╌╌╌┐ ║ 11 ║ ┊ 8 ┊ ┊ 5 ┊ ┊ 2 ┊ ╚════╝ ╚╌╌╌╌╝ ╚╌╌╌╌╝ └╌╌╌╌┘ -SHIFT →LAYOUT 🔆BRIGHT +⇑SHIFT →LAYOUT 🔆BRIGHT ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┊ 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 -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. +Just as its name says: an empty keyboard layout – useful if you want to have +also a "no" layout with no functionality whatsoever to switch to. (_This +layout by courtesy of Margaret Thatcher._) -``` +```text ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┌╌╌╌╌┐ ┊ 11 ┊ ┊ 8 ┊ ┊ 7 ┊ ┊ 6 ┊ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ └╌╌╌╌┘ @@ -88,14 +116,14 @@ keybow-firmware GitHub repository. ## Installation 1. Download the [Pibow -firmware](https://github.com/pimoroni/keybow-firmware/releases) and copy all -files inside its `sdcard/` subdirectory onto an empty, FAT32 formatted microSD -card. Copy only the files **inside** `sdcard/`, but do **not** place them into a -~~`sdcard`~~ directory on your microSD card. + firmware](https://github.com/pimoroni/keybow-firmware/releases) and copy + all files inside its `sdcard/` subdirectory onto an empty, FAT32 formatted + microSD card. Copy only the files **inside** `sdcard/`, but do **not** + place them into a ~~`sdcard`~~ directory on your microSD card. 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 -`key.lua`, all other files are new. + then copy them onto the microSD card. This will overwrite but one file + `key.lua`, all other files are new. ## Multiple Keyboard Layouts @@ -105,16 +133,24 @@ accordingly to require them. The default configuration is as follows: ```lua require "layouts/shift" -- for cycling between layouts. require "layouts/vsc-golang" -- debugging Go programs in VisualStudio Code. +require "layouts/kdenlive" -- editing video using Kdenlive. require "layouts/empty" -- empty, do-nothing layout. ``` - ## Developing -For some basic testing, run `lua test.lua` from the base directory of this -repository. It pulls in `keybow`, then mocks some functionality of it, and -finally starts `sdcard/keys.lua` as usual. - -This helps in detecting syntax and logic erros early, avoiding the +Whether you want to dry-run your own keyboard layout or to hack Multibow: use +the unit tests which you can find in the `spec/` subdirectory. These tests +help you in detecting syntax and logic errors early, avoiding the 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).