Adding advanced HID keyboard example with multiple layers.

README.md

@@ -54,13 +54,13 @@ changes, then it should load up and run the code!
   * [LED sleep](#led-sleep)
   * [Attaching functions to keys with decorators](#attaching-functions-to-keys-with-decorators)
   * [Key combos](#key-combos)
-* [USB MIDI](#usb-midi)
-  * [Setup](#setup)
-  * [Sending MIDI notes](#sending-midi-notes)
 * [USB HID](#usb-hid)
-  * [Setup](#setup-1)
+  * [Setup](#setup)
   * [Sending key presses](#sending-key-presses)
   * [Sending strings of text](#sending-strings-of-text)
+* [USB MIDI](#usb-midi)
+  * [Setup](#setup-1)
+  * [Sending MIDI notes](#sending-midi-notes)
 
 # Library functionality
 
@@ -368,74 +368,6 @@ held and a third to be pressed, and so on...
 The [colour-picker.py example](examples/colour-picker.py) has an example of
 using a modifier key to change the hue of the keys.
 
-# USB MIDI
-
-This covers basic MIDI note messages and how to link them to key presses.
-
-## Setup
-
-USB MIDI requires the `adafruit_midi` CircuitPython library. Download it from
-the link below and then drop the `adafruit_midi` folder into the `lib` folder on
-your `CIRCUITPY` drive.
-
-[Download the Adafruit MIDI CircuitPython library](https://github.com/adafruit/Adafruit_CircuitPython_MIDI)
-
-You'll need to connect your Keybow 2040 with a USB cable to a computer running a
-software synth or DAW like Ableton Live, to a hardware synth that accepts USB
-MIDI, or through a MIDI interface that will convert the USB MIDI messages to
-regular serial MIDI through a DIN connector.
-
-Using USB MIDI, Keybow 2040 shows up as a device with the name 
-`Keybow 2040 (CircuitPython usb midi.ports[1])`
-
-In my testing, Keybow 2040 works with the Teenage Engineering OP-Z quite nicely.
-
-## Sending MIDI notes
-
-Here's a complete, minimal example of how to send a single MIDI note (middle C,
-or MIDI note number 60) when key 0 is pressed, sending a note on message when
-pressed and a note off message when released.
-
-```
-import board
-from keybow2040 import Keybow2040
-
-import usb_midi
-import adafruit_midi
-from adafruit_midi.note_off import NoteOff
-from adafruit_midi.note_on import NoteOn
-
-i2c = board.I2C()
-keybow = Keybow2040(i2c)
-keys = keybow.keys
-
-midi = adafruit_midi.MIDI(midi_out=usb_midi.ports[1], out_channel=0)
-
-key = keys[0]
-note = 60
-velocity = 127
-
-was_pressed = False
-
-while True:
-    keybow.update()
-
-    if key.pressed:
-        midi.send(NoteOn(note, velocity))
-        was_pressed = True
-    elif not key.pressed and was_pressed:
-        midi.send(NoteOff(note, 0))
-        was_pressed = False
-```
-
-There'a more complete example of how to set up all of Keybow's keys with 
-associated MIDI notes using decorators in the 
-[midi-keys.py example](examples/midi-keys.py).
-
-The example above, and the `midi-keys.py` example both send notes on MIDI
-channel 0 (all channels), but you can set this to a specific channel, if you
-like, by changing `out_channel=` when you instantiate your `midi` object.
-
 # USB HID
 
 This covers setting up a USB HID keyboard and linking physical key presses to 
@@ -535,7 +467,7 @@ while True:
 ```
 
 This code is available in the 
-hid-keys-simple.py example](examples/hid-keys-simple.py).
+[hid-keys-simple.py example](examples/hid-keys-simple.py).
 
 As well as sending a single keypress, you can send multiple keypresses at once,
 simply by adding them as additional argumemnts to `keyboard.send()`, e.g. 
@@ -583,3 +515,71 @@ and then check against a `time_elapsed` variable created with
 Also, be aware that the Adafruit HID CircuitPython library only currently 
 supports US Keyboard layouts, so you'll have to work around that and map any
 keycodes that differ from their US counterpart to whatever your is.
+
+# USB MIDI
+
+This covers basic MIDI note messages and how to link them to key presses.
+
+## Setup
+
+USB MIDI requires the `adafruit_midi` CircuitPython library. Download it from
+the link below and then drop the `adafruit_midi` folder into the `lib` folder on
+your `CIRCUITPY` drive.
+
+[Download the Adafruit MIDI CircuitPython library](https://github.com/adafruit/Adafruit_CircuitPython_MIDI)
+
+You'll need to connect your Keybow 2040 with a USB cable to a computer running a
+software synth or DAW like Ableton Live, to a hardware synth that accepts USB
+MIDI, or through a MIDI interface that will convert the USB MIDI messages to
+regular serial MIDI through a DIN connector.
+
+Using USB MIDI, Keybow 2040 shows up as a device with the name 
+`Keybow 2040 (CircuitPython usb midi.ports[1])`
+
+In my testing, Keybow 2040 works with the Teenage Engineering OP-Z quite nicely.
+
+## Sending MIDI notes
+
+Here's a complete, minimal example of how to send a single MIDI note (middle C,
+or MIDI note number 60) when key 0 is pressed, sending a note on message when
+pressed and a note off message when released.
+
+```
+import board
+from keybow2040 import Keybow2040
+
+import usb_midi
+import adafruit_midi
+from adafruit_midi.note_off import NoteOff
+from adafruit_midi.note_on import NoteOn
+
+i2c = board.I2C()
+keybow = Keybow2040(i2c)
+keys = keybow.keys
+
+midi = adafruit_midi.MIDI(midi_out=usb_midi.ports[1], out_channel=0)
+
+key = keys[0]
+note = 60
+velocity = 127
+
+was_pressed = False
+
+while True:
+    keybow.update()
+
+    if key.pressed:
+        midi.send(NoteOn(note, velocity))
+        was_pressed = True
+    elif not key.pressed and was_pressed:
+        midi.send(NoteOff(note, 0))
+        was_pressed = False
+```
+
+There'a more complete example of how to set up all of Keybow's keys with 
+associated MIDI notes using decorators in the 
+[midi-keys.py example](examples/midi-keys.py).
+
+The example above, and the `midi-keys.py` example both send notes on MIDI
+channel 0 (all channels), but you can set this to a specific channel, if you
+like, by changing `out_channel=` when you instantiate your `midi` object.

examples/hid-keys-advanced.py

@@ -0,0 +1,167 @@
+# SPDX-FileCopyrightText: 2021 Sandy Macdonald
+#
+# SPDX-License-Identifier: MIT
+
+# An advanced example of how to set up a HID keyboard.
+
+# There are three layers, selected by pressing and holding key 0 (bottom left), 
+# then tapping one of the coloured layer selector keys above it to switch layer.
+
+# The layer colours are as follows:
+
+#  * layer 1: pink: numpad-style keys, 0-9, delete, and enter.
+#  * layer 2: blue: sends strings on each key press
+#  * layer 3: media controls, rev, play/pause, fwd on row one, vol. down, mute,
+#             vol. up on row two
+
+# You'll need to connect Keybow 2040 to a computer, as you would with a regular
+# USB keyboard.
+
+# Drop the keybow2040.py file into your `lib` folder on your `CIRCUITPY` drive.
+
+# NOTE! Requires the adafruit_hid CircuitPython library also!
+
+import board
+import time
+from keybow2040 import Keybow2040
+
+import usb_hid
+from adafruit_hid.keyboard import Keyboard
+from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
+from adafruit_hid.keycode import Keycode
+
+from adafruit_hid.consumer_control import ConsumerControl
+from adafruit_hid.consumer_control_code import ConsumerControlCode
+
+# Set up Keybow
+i2c = board.I2C()
+keybow = Keybow2040(i2c)
+keys = keybow.keys
+
+# Set up the keyboard and layout
+keyboard = Keyboard(usb_hid.devices)
+layout = KeyboardLayoutUS(keyboard)
+
+# Set up consumer control (used to send media key presses)
+consumer_control = ConsumerControl(usb_hid.devices)
+
+# Our layers. The key of item in the layer dictionary is the key number on
+# Keybow to map to, and the value is the key press to send.
+
+# Note that keys 0-3 are reserved as the modifier and layer selector keys 
+# respectively.
+
+layer_1 =     {4: Keycode.ZERO,
+               5: Keycode.ONE,
+               6: Keycode.FOUR,
+               7: Keycode.SEVEN,
+               8: Keycode.DELETE,
+               9: Keycode.TWO,
+               10: Keycode.FIVE,
+               11: Keycode.EIGHT,
+               12: Keycode.ENTER,
+               13: Keycode.THREE,
+               14: Keycode.SIX,
+               15: Keycode.NINE}
+
+layer_2 =     {7: "pack ",
+               11: "my ",
+               15: "box ",
+               6: "with ",
+               10: "five ",
+               14: "dozen ",
+               5: "liquor ",
+               9: "jugs "}
+
+layer_3 =     {6: ConsumerControlCode.VOLUME_DECREMENT,
+               7: ConsumerControlCode.SCAN_PREVIOUS_TRACK,
+               10: ConsumerControlCode.MUTE,
+               11: ConsumerControlCode.PLAY_PAUSE,
+               14: ConsumerControlCode.VOLUME_INCREMENT,
+               15: ConsumerControlCode.SCAN_NEXT_TRACK}
+
+layers =      {1: layer_1,
+               2: layer_2,
+               3: layer_3}
+
+# Define the modifier key and layer selector keys
+modifier = keys[0]
+
+selectors =   {1: keys[1],
+               2: keys[2],
+               3: keys[3]}
+
+# Start on layer 1
+current_layer = 1
+
+# The colours for each layer
+colours = {1: (255, 0, 255),
+           2: (0, 255, 255),
+           3: (255, 255, 0)}
+
+layer_keys = range(4, 16)
+
+# Set the LEDs for each key in the current layer
+for k in layers[current_layer].keys():
+    keys[k].set_led(*colours[current_layer])
+
+# To prevent the strings (as opposed to single key presses) that are sent from 
+# refiring on a single key press, the debounce time for the strings has to be 
+# longer.
+short_debounce = 0.025
+long_debounce = 0.25
+debounce = 0.025
+fired = False
+
+while True:
+    # Always remember to call keybow.update()!
+    keybow.update()
+
+    # This handles the modifier and layer selector behaviour
+    if modifier.held:
+        # If the modifier key is held, light up the layer selector keys
+        for layer in layers.keys():
+            keys[layer].set_led(*colours[layer])
+
+            # Change layer if layer key is pressed
+            if current_layer != layer:
+                if selectors[layer].pressed:
+                    current_layer = layer
+
+                    # Set the key LEDs first to off, then to their layer colour
+                    for k in layer_keys:
+                        keys[k].set_led(0, 0, 0)
+
+                    for k in layers[layer].keys():
+                        keys[k].set_led(*colours[layer])
+
+    # Turn off the layer selector LEDs if the modifier isn't held
+    else:
+        for layer in layers.keys():
+            keys[layer].led_off()
+
+    # Loop through all of the keys in the layer and if they're pressed, get the
+    # key code from the layer's key map
+    for k in layers[current_layer].keys():
+        if keys[k].pressed:
+            key_press = layers[current_layer][k]
+
+            # If the key hasn't just fired (prevents refiring)
+            if not fired:
+                fired = True
+
+                # Send the right sort of key press and set debounce for each
+                # layer accordingly (layer 2 needs a long debounce)
+                if current_layer == 1:
+                    debounce = short_debounce
+                    keyboard.send(key_press)
+                elif current_layer == 2:
+                    debounce = long_debounce
+                    layout.write(key_press)
+                elif current_layer == 3:
+                    debounce = short_debounce
+                    consumer_control.send(key_press)
+
+    # If enough time has passed, reset the fired variable
+    if fired and time.monotonic() - keybow.time_of_last_press > debounce:
+        fired = False

examples/hid-keys-simple.py

@@ -1,3 +1,16 @@
+# SPDX-FileCopyrightText: 2021 Sandy Macdonald
+#
+# SPDX-License-Identifier: MIT
+
+# A simple example of how to set up a keymap and HID keyboard on Keybow 2040.
+
+# You'll need to connect Keybow 2040 to a computer, as you would with a regular
+# USB keyboard.
+
+# Drop the keybow2040.py file into your `lib` folder on your `CIRCUITPY` drive.
+
+# NOTE! Requires the adafruit_hid CircuitPython library also!
+
 import board
 from keybow2040 import Keybow2040
 
@@ -6,13 +19,16 @@ from adafruit_hid.keyboard import Keyboard
 from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
 from adafruit_hid.keycode import Keycode
 
+# Set up Keybow
 i2c = board.I2C()
 keybow = Keybow2040(i2c)
 keys = keybow.keys
 
+# Set up the keyboard and layout
 keyboard = Keyboard(usb_hid.devices)
 layout = KeyboardLayoutUS(keyboard)
 
+# A map of keycodes that will be mapped sequentially to each of the keys, 0-15
 keymap =    [Keycode.ZERO,
              Keycode.ONE,
              Keycode.TWO,
@@ -30,11 +46,23 @@ keymap =    [Keycode.ZERO,
              Keycode.E,
              Keycode.F]
 
+# The colour to set the keys when pressed, yellow.
+rgb = (255, 255, 0)
+
+# Attach handler functions to all of the keys
 for key in keys:
+    # A press handler that sends the keycode and turns on the LED
     @keybow.on_press(key)
     def press_handler(key):
         keycode = keymap[key.number]
         keyboard.send(keycode)
+        key.set_led(*rgb)
+
+    # A release handler that turns off the LED
+    @keybow.on_release(key)
+    def release_handler(key):
+        key.led_off()
 
 while True:
+    # Always remember to call keybow.update()!
     keybow.update()

examples/midi-arp.py

@@ -11,7 +11,7 @@
 
 # Drop the keybow2040.py file into your `lib` folder on your `CIRCUITPY` drive.
 
-# NOTE! Requires the adafruit_midi CircuitPython library!
+# NOTE! Requires the adafruit_midi CircuitPython library also!
 
 import time
 import board

examples/midi-keys.py

@@ -10,7 +10,7 @@
 
 # Drop the keybow2040.py file into your `lib` folder on your `CIRCUITPY` drive.
 
-# NOTE! Requires the adafruit_midi CircuitPython library!
+# NOTE! Requires the adafruit_midi CircuitPython library also!
 
 import time
 import board