Pico Display Keypad

Pico Display Keypad

This is my current setup for using a Rasberry Pi Pico / Pico W with a Pimoroni RGB Keypad Base and their Pico Display Pack 2.0. This code includes a few modifications to the following libraries so that it is able to communicate with both devices at once:

• the PMK.platform.rgbkeypadbase module

  • The GPIO pins have been changed but the defaults are still in the code if needed, just uncomment the lines and comment the ones not used.
  • There is now an original arrangement for the LED that is an alternative to the Reversed arrangement. It can be changed from there as well to suit your needs.

The Display Pack 2.0 is the main pack connected to the Pico as it requires more pins than the RGB Keypad Base so it's easier to wire up.

Installation

Hardware Connections

To facilitate the use of a Pimoroni Base and a Pack at the same time, I used a headerless Pico and soldered stackable pins with the pins facing down. This allows for connecting the pins to the Display Pack 2.0 directly and the RGB Keypad Base using jumper wires.

GPIO Pin assignment

• The Display Pack 2.0 uses the default pin layout, so just plug the Pico into the Display Pack 2.0
• The RGB Keypad Base changes the following pins, going from Keypad Base to Pico:
  • KB_MOSI - Pin 25 (GPIO19) -> Pin 34 (GPIO28)
  • KB_SCLK - Pin 24 (GPIO18) -> Pin 32 (GPIO27)
  • KB_CS - Pin 22 (GPIO17) -> Pin 31 (GPIO26)
• All other pins are the same on the Keypad Base

PCB Design

A simple PCB design mapping all pins to a board is also present in the Pico-Display-Keypad folder. It can be used as an easier reference for the wiring.

Software

• Clone this repo
• Copy the contents of the "pico" folder into your Raspberry Pi Pico / W with CircuitPython 9.2.7 installed

Features

• Ability to display descriptors for assigned buttons on the screen
• Able to send key combos when pressing a button
• Switchable layouts using a modifier key
• Ability to set colours for each layer
• Support for Keyboard, Mouse and ConsumerControl Keycodes
• Turbo Key mode for repetitive key pressing

Details

Currently, each layer definition is stored in a series of mapped dictionary objects. These can be translated into a serialised JSON format and deserialised at runtime. This allows the layouts to be stored in a separate file and the possibility of being edited on a separate device (app in progress) .

Layers

Each layer is made from a dictionary of all the populated layers with each key containing the following:

• A layer title (layer_title)
• A default colour for each key that is assigned (layer_colour)
• A nested dictionary containing information on assigned keys (layer_data)

The anatomy of a layer's data is as follows:

layer_titles = {
        1: {                 # The key in the layer to be used. Cannot be 0 as it is the modifier key to switch layers.
        "codes": ConsumerControlCode.VOLUME_DECREMENT, # The keycodes to send. 
                                                       # Refer to adafruit_hid's KeyboardLayoutUS or ConsumerControlCodes for codes
        "title": "Vol -",                              # The key description to be displayed on the screen when layer is active
        "device": "consumer_control",                  # The USB_HID device used to send the input.
        "colours": (255, 255, 0),                      # Optional: Custom colour for the key if you want to differentiate.
    }, ...                                             # Repeat for other keys.
}

The same applies to keyboard inputs, however mouse inputs are a bit different.

mouse_layer = {
    1: {
    "buttons": Mouse.LEFT_BUTTON,           # Use buttons for mouse buttons
                                            # Use adafruit_hid's Mouse for codes.
    "wheel" : 3                             # Wheel refers to the mouse wheel, +ive num = up, -ive = down
    "x" : 50                                # X is the direction to move the cursor, + = right, - = left
    "y" : -50                               # Y is the same as X, - = up, + = down.
    "title": "Left Mouse",                  # Title and device are the same
    "device": "mouse"
    },
}

Keyboard Outputs

For single keys, codes: Keycode.KEY_NAME works.

For key combos, you need to use a set so that the code knows to send all keys at the same time.

7: {
    "codes": {Keycode.CONTROL, Keycode.SHIFT, Keycode.Z},
    "title": "Stop Sharing",
    "device": "keyboard",
}

Macros can be a combination of integers and sets so that you can send a string of keys in quick succession. A current limitation of this setup is that delays are not supported yet, which means that you won't be able to make macros that require delayed presses. They use the tuple class to differentiate between combos and single keys.

Below is an example of a macro used to make selected text red in Excel. Uncommenting the commented parts also makes it bold.

    10: {
        "codes": (
            # {Keycode.CONTROL, Keycode.B},
            Keycode.ALT,
            Keycode.H,
            Keycode.F,
            Keycode.C,
            Keycode.DOWN_ARROW,
            Keycode.DOWN_ARROW,
            Keycode.DOWN_ARROW,
            Keycode.DOWN_ARROW,
            Keycode.DOWN_ARROW,
            Keycode.DOWN_ARROW,
            Keycode.DOWN_ARROW,
            Keycode.RIGHT_ARROW,
            Keycode.ENTER,
        ),
        "title": "Change to red",  # and bold",
        "device": "keyboard",
    },

A list of macros are there already in lib/layers.py. This is also where all of the layers and their keys are stored.

Consumer Control Codes

NOTE: ConsumerControl HID Devices do not support combos or macros, as the module only supports single keystroke.

Consumer control codes only support one button at this time due to the circuitpython library only supporting single buttons. Their layout is largely unchanged from the keyboard

media_keys = {
1:{
"codes": ConsumerControlCode.VOLUME_DECREMENT,

"title": "Vol -",

"device": "consumer_control",

"colours": (255, 255, 0),

},
...
}

MIDI

Currently, it only supports single button presses, with a note value being assigned. This was used for pressing buttons to trigger sound effects on a soundboard application, which supported using MIDI in place of keyboard shortcuts.

soundboard = {
...
4: {"note": 4, 
	"title": "Fake Discord Ping", 
	"device": "midi"},
...
}

Serialising JSON

The JSON format is used as it has a built-in circuitpython module. This format also closely matches the dictionary format used in python as well, allowing for a quick translation between both formats.

A limitation present in the JSON format is that it does not maintain a distinction between a set and a tuple. Both are converted to a list format when serialising, deleting information about whether a nested list of keys are pressed at the same time or not. To counteract this, the serialiser adds a string at the end of each list to differentiate between a combo or a macro.

Below is an example case

"9": {
	"codes": [
		[
			224,
			30,
			"combo"
		],
		[
			226,
			5,
			"combo"
		],
		40,
		"macro"
	],
	"device": "keyboard",
	"title": "Change Format"
},

Is derived from the following code

9: {
	"codes": (
		{Keycode.CONTROL, Keycode.ONE},
		{Keycode.ALT, Keycode.B},
		Keycode.ENTER,
	),
	"title": "Change Format",
	"device": "keyboard",
},

The encoded values are integers representing the keycodes programmed. If one is aware of the HID spec for Keyboards, you can also edit these values to change it. The adafruit_hid library has a handy set of constants one can use to easily encode the keys instead.