Text Editor

Adafruit recommends using the Mu editor for using your CircuitPython code with the Feather. You can get more info in this guide.

Alternatively, you can use any text editor that saves files.

CircuitPython Code

Copy the code below and paste it into Mu. Then, save it to your Feather RP2040's CIRCUITPY drive as code.py.

You'll need to download the .zip file in the GitHub link below and decompress the file to get all of the touch_deck_icons directory that's full of sample icons, as well as the touch_deck_layers.py file. Copy both of these to your Feather's CIRCUITPY drive.

Project Files

Download the project files and copy them onto your CIRCUITPY drive.

# SPDX-FileCopyrightText: 2020 Tim C, written for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense
"""
This version runs on Feather RP2040 with a 3.5" FeatherWing
"""

import time
import displayio
import terminalio
from adafruit_display_text import bitmap_label
from adafruit_displayio_layout.layouts.grid_layout import GridLayout
from adafruit_displayio_layout.widgets.icon_widget import IconWidget
from adafruit_featherwing import tft_featherwing_35
import usb_hid
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
from adafruit_hid.consumer_control import ConsumerControl
from touch_deck_layers import (
    touch_deck_config,
    KEY,
    STRING,
    MEDIA,
    KEY_PRESS,
    KEY_RELEASE,
    CHANGE_LAYER,
)

# seems to help the touchscreen not get stuck with chip not found
time.sleep(3)

# display and touchscreen initialization
displayio.release_displays()
tft_featherwing = tft_featherwing_35.TFTFeatherWing35()
display = tft_featherwing.display
touchscreen = tft_featherwing.touchscreen

# HID setup
kbd = Keyboard(usb_hid.devices)
cc = ConsumerControl(usb_hid.devices)
kbd_layout = KeyboardLayoutUS(kbd)

# variables to enforce timout between icon presses
COOLDOWN_TIME = 0.5
LAST_PRESS_TIME = -1

# 'mock' icon indexes for the layer buttons
# used for debouncing
PREV_LAYER_INDEX = -1
NEXT_LAYER_INDEX = -2
HOME_LAYER_INDEX = -3

# start on first layer
current_layer = 0

# Make the main_group to hold everything
main_group = displayio.Group()
display.show(main_group)

# loading screen
loading_group = displayio.Group()

# black background, screen size minus side buttons
loading_background = displayio.Bitmap(
    (display.width - 40) // 20, display.height // 20, 1
)
loading_palette = displayio.Palette(1)
loading_palette[0] = 0x0

# scaled group to match screen size minus side buttons
loading_background_scale_group = displayio.Group(scale=20)
loading_background_tilegrid = displayio.TileGrid(
    loading_background, pixel_shader=loading_palette
)
loading_background_scale_group.append(loading_background_tilegrid)

# loading screen label
loading_label = bitmap_label.Label(terminalio.FONT, text="Loading...", scale=3)
loading_label.anchor_point = (0.5, 0.5)
loading_label.anchored_position = (display.width // 2, display.height // 2)

# append background and label to the group
loading_group.append(loading_background_scale_group)
loading_group.append(loading_label)

# GridLayout to hold the icons
# size and location can be adjusted to fit
# different sized screens.
layout = GridLayout(
    x=20,
    y=20,
    width=420,
    height=290,
    grid_size=(4, 3),
    cell_padding=6,
)

# list that holds the IconWidget objects for each icon.
_icons = []

# list that holds indexes of currently pressed icons and layer buttons
# used for debouncing
_pressed_icons = []

# layer label at the top of the screen
layer_label = bitmap_label.Label(terminalio.FONT)
layer_label.anchor_point = (0.5, 0.0)
layer_label.anchored_position = (display.width // 2, 4)
main_group.append(layer_label)

# right side layer buttons
next_layer_btn = IconWidget("", "touch_deck_icons/layer_next.bmp", on_disk=True)
next_layer_btn.x = display.width - 40
next_layer_btn.y = display.height - 100
next_layer_btn.resize = (40, 100)
main_group.append(next_layer_btn)

prev_layer_btn = IconWidget("", "touch_deck_icons/layer_prev.bmp", on_disk=True)
prev_layer_btn.x = display.width - 40
prev_layer_btn.y = 110
prev_layer_btn.resize = (40, 100)
main_group.append(prev_layer_btn)

home_layer_btn = IconWidget("", "touch_deck_icons/layer_home.bmp", on_disk=True)
home_layer_btn.x = display.width - 40
home_layer_btn.y = 0
home_layer_btn.resize = (40, 100)
main_group.append(home_layer_btn)


# helper method to laod icons for an index by its index in the
# list of layers
def load_layer(layer_index):
    # show the loading screen
    main_group.append(loading_group)
    time.sleep(0.05)

    # resets icon lists to empty
    global _icons
    _icons = []
    layout._cell_content_list = []

    # remove previous layer icons from the layout
    while len(layout) > 0:
        layout.pop()

    # set the layer labed at the top of the screen
    layer_label.text = touch_deck_config["layers"][layer_index]["name"]

    # loop over each shortcut and it's index
    for i, shortcut in enumerate(touch_deck_config["layers"][layer_index]["shortcuts"]):
        # create an icon for the current shortcut
        _new_icon = IconWidget(shortcut["label"], shortcut["icon"], on_disk=True)

        # add it to the list of icons
        _icons.append(_new_icon)

        # add it to the grid layout
        # calculate it's position from the index
        layout.add_content(_new_icon, grid_position=(i % 4, i // 4), cell_size=(1, 1))

    # hide the loading screen
    time.sleep(0.05)
    main_group.pop()


# append the grid layout to the main_group
# so it gets shown on the display
main_group.append(layout)

# load the first layer to start
load_layer(current_layer)

#  main loop
while True:
    if touchscreen.touched:
        # loop over all data in touchscreen buffer
        while not touchscreen.buffer_empty:
            touches = touchscreen.touches
            # loop over all points touched
            for point in touches:
                if point:
                    # current time, used for timeout between icon presses
                    _now = time.monotonic()

                    # if the timeout has passed
                    if _now - LAST_PRESS_TIME > COOLDOWN_TIME:
                        # print(point)

                        # map the observed minimum and maximum touch values
                        # to the screen size
                        y = point["y"] - 250
                        x = 4096 - point["x"] - 250
                        y = y * display.width // (3820 - 250)
                        x = x * display.height // (3820 - 250)

                        # touch data is 90 degrees rotated
                        # flip x, and y here to account for that
                        p = (y, x)
                        # print(p)

                        # Next layer button pressed
                        if (
                            next_layer_btn.contains(p)
                            and NEXT_LAYER_INDEX not in _pressed_icons
                        ):

                            # increment layer
                            current_layer += 1
                            # wrap back to beginning from end
                            if current_layer >= len(touch_deck_config["layers"]):
                                current_layer = 0
                            # load the new layer
                            load_layer(current_layer)

                            # save current time to check for timeout
                            LAST_PRESS_TIME = _now

                            # append this index to pressed icons for debouncing
                            _pressed_icons.append(NEXT_LAYER_INDEX)

                        # home layer button pressed
                        if (
                            home_layer_btn.contains(p)
                            and HOME_LAYER_INDEX not in _pressed_icons
                        ):
                            # 0 index is home layer
                            current_layer = 0
                            # load the home layer
                            load_layer(current_layer)

                            # save current time to check for timeout
                            LAST_PRESS_TIME = _now

                            # append this index to pressed icons for debouncing
                            _pressed_icons.append(HOME_LAYER_INDEX)

                        # Previous layer button pressed
                        if (
                            prev_layer_btn.contains(p)
                            and PREV_LAYER_INDEX not in _pressed_icons
                        ):

                            # decrement layer
                            current_layer -= 1
                            # wrap back to end from beginning
                            if current_layer < 0:
                                current_layer = len(touch_deck_config["layers"]) - 1

                            # load the new layer
                            load_layer(current_layer)

                            # save current time to check for timeout
                            LAST_PRESS_TIME = _now

                            # append this index to pressed icons for debouncing
                            _pressed_icons.append(PREV_LAYER_INDEX)

                        # loop over current layer icons and their indexes
                        for index, icon_shortcut in enumerate(_icons):
                            # if this icon was pressed
                            if icon_shortcut.contains(p):
                                # debounce logic, check that it wasn't already pressed
                                if index not in _pressed_icons:
                                    # print("pressed {}".format(index))

                                    # get actions for this icon from config object
                                    _cur_actions = touch_deck_config["layers"][
                                        current_layer
                                    ]["shortcuts"][index]["actions"]

                                    # tuple means it's a single action
                                    if isinstance(_cur_actions, tuple):
                                        # put it in a list by itself
                                        _cur_actions = [_cur_actions]

                                    # loop over the actions
                                    for _action in _cur_actions:
                                        # HID keyboard keys
                                        if _action[0] == KEY:
                                            kbd.press(*_action[1])
                                            kbd.release(*_action[1])

                                        # String to write from layout
                                        elif _action[0] == STRING:
                                            kbd_layout.write(_action[1])

                                        # Consumer control code
                                        elif _action[0] == MEDIA:
                                            cc.send(_action[1])

                                        # Key press
                                        elif _action[0] == KEY_PRESS:
                                            kbd.press(*_action[1])

                                        # Key release
                                        elif _action[0] == KEY_RELEASE:
                                            kbd.release(*_action[1])

                                        # Change Layer
                                        elif _action[0] == CHANGE_LAYER:
                                            if isinstance(
                                                _action[1], int
                                            ) and 0 <= _action[1] < len(
                                                touch_deck_config["layers"]
                                            ):

                                                current_layer = _action[1]
                                                load_layer(_action[1])

                                        # if there are multiple actions
                                        if len(_cur_actions) > 1:
                                            # small sleep to make sure
                                            # OS can respond to previous action
                                            time.sleep(0.2)

                                    # save current time to check for timeout
                                    LAST_PRESS_TIME = _now
                                    # append this index to pressed icons for debouncing
                                    _pressed_icons.append(index)
    else:  # screen not touched

        # empty the pressed icons list
        _pressed_icons.clear()

Testing

Once you've pasted the project files onto your device, it will automatically reboot and begin running the touch deck app using the build-in example layers. Open up a text editor and click into it to give it focus. Press the "Play" icon at the top left of the screen. If everything working properly you should see "k" get typed into the text editor. If the touch deck app does not launch for you try opening the Mu Serial Console and check to see if there are any errors printed in there. 

How it Works

Hardware Driver

This project is made to work with the adafruit_featherwing library contains a helper class that we use to initialize the touch overlay and display. Once we've done that, we're ready to start drawing things on the screen and reacting to user touches.

Graphical Interface

There are two main components used in the interface: GridLayout and IconWidget. Both of them are in the adafruit_displayio_layout library. The IconWidget component contains an image, and optionally some text beneath it. All of the shortcut icons in the touch deck are IconWidget objects. The layer buttons on the right side are also IconWidgets, with a differently shaped image and no text. GridLayout is the widget we use to distribute our IconWidgets into a 4x3 grid. It does all the mathematical heavy lifting to size and position all of the widgets that we add to it.

Shortcut Sending

Whenever you press one of the touch deck icons, the code uses the adafruit_hid library to send the keys, consumer codes, or strings specified by your layers configuration file.

Configuration

The code reads a configuration dictionary object from the file touch_deck_layers.py. Within this file, you can define the layers of icons that you'd like to use, and set the keys and other shortcuts they'll send when you touch them.

Customizing the Layers File

Your layers file is where you define what icons you want to use and what actions they should do when you press them. These are grouped into lists known as layers. Each layer can hold up to 12 icons. Each layer contains a name that will get shown at the top of the screen.

Each item in the layer has three properties: label, icon, and actions. The icon is a string filepath pointing to the bmp image that should be shown. All of the icons in this project are in the touch_deck_icons/ directory. The label property is the text that will be shown under the icon image. Lastly, the actions are the things to do when you press on the icon -- keys to press, or strings to write.

There are five types of actions that can be used on an icon. Each icon can have a single action, or a list of actions that will get run in sequence.

KEY

This will press and release a single key. It can also contain modifier keys that will be held down while the selected key is pressed. 

{
    "label": "Play",
    "icon": "touch_deck_icons/pr_play.bmp",
    "actions": (KEY, [Keycode.K]),
 },
 {
    "label": "Fast",
    "icon": "touch_deck_icons/pr_fast.bmp",
    "actions": (KEY, [Keycode.RIGHT_SHIFT, Keycode.PERIOD]),
}

In the example above, there is a "Play" shortcut that presses the "k" key, and a "Fast" shortcut that holds shift while pressing the period key, which would make ">" -- which is the fast forward shortcut for YouTube.

MEDIA

This action type will send the specified consumer control codes. 

{
    "label": "Vol +",
    "icon": "touch_deck_icons/pr_volup.bmp",
    "actions": (MEDIA, ConsumerControlCode.VOLUME_INCREMENT),
},

This shortcut will press the volume up key.

STRING

The STRING action type will write a string using the US Keyboard Layout. You can use this to type words.

{
    "label": "Blinka",
    "icon": "touch_deck_icons/af_blinka.bmp",
    "actions": (STRING, ":blinka:"),
}

This shortcut will type the string ":blinka:" which gets interpreted by Discord as an emoji and gets replaced by a Blinka icon on the Adafruit Discord server.

KEY_PRESS and KEY_RELEASE

The final 2 action types are meant to be used together. These allow you to hold a key down while pressing several other keys. These are helpful for PC shortcuts like "hold alt and type 1234". KEY_PRESS will press and hold a key down. Then you can do some other actions. And finally KEY_RELEASE will release the pressed key. KEY_RELEASE will release the pressed key.

 

{
    "label": "Test (L)",
    "icon": "touch_deck_icons/test48_icon.bmp",
    "actions": [
        (KEY_PRESS, [Keycode.SHIFT]),
        (KEY, [Keycode.B]),
        (KEY, [Keycode.L]),
        (KEY, [Keycode.I]),
        (KEY, [Keycode.N]),
        (KEY, [Keycode.K]),
        (KEY, [Keycode.A]),
        (KEY_RELEASE, [Keycode.SHIFT])
    ]
},

This example holds the shift key down, and then presses the B, L, I, N, K, A keys in succession.

Full Layers File

 

from adafruit_hid.keycode import Keycode
from adafruit_hid.consumer_control_code import ConsumerControlCode

MEDIA = 1
KEY = 2
STRING = 3
KEY_PRESS = 4
KEY_RELEASE = 5
CHANGE_LAYER = 6

touch_deck_config = {
    "layers": [
        {
            "name": "Youtube Controls",
            "shortcuts": [
                {
                    "label": "Play",
                    "icon": "touch_deck_icons/pr_play.bmp",
                    "actions": (KEY, [Keycode.K]),
                },
                {
                    "label": "Pause",
                    "icon": "touch_deck_icons/pr_pause.bmp",
                    "actions": (KEY, [Keycode.K]),
                },
                {
                    "label": "Rewind",
                    "icon": "touch_deck_icons/pr_rewind.bmp",
                    "actions": (KEY, [Keycode.LEFT_ARROW]),
                },
                {
                    "label": "FastForward",
                    "icon": "touch_deck_icons/pr_ffwd.bmp",
                    "actions": (KEY, [Keycode.RIGHT_ARROW]),
                },
                {
                    "label": "Previous",
                    "icon": "touch_deck_icons/pr_previous.bmp",
                    "actions": (KEY, [Keycode.RIGHT_SHIFT, Keycode.P]),
                },
                {
                    "label": "Next",
                    "icon": "touch_deck_icons/pr_next.bmp",
                    "actions": (KEY, [Keycode.RIGHT_SHIFT, Keycode.N]),
                },
                {
                    "label": "Vol -",
                    "icon": "touch_deck_icons/pr_voldown.bmp",
                    "actions": (MEDIA, ConsumerControlCode.VOLUME_DECREMENT),
                },
                {
                    "label": "Vol +",
                    "icon": "touch_deck_icons/pr_volup.bmp",
                    "actions": (MEDIA, ConsumerControlCode.VOLUME_INCREMENT),
                },
                {
                    "label": "Fullscreen",
                    "icon": "touch_deck_icons/pr_fullscreen.bmp",
                    "actions": (KEY, [Keycode.F]),
                },
                {
                    "label": "Slow",
                    "icon": "touch_deck_icons/pr_slow.bmp",
                    "actions": (KEY, [Keycode.RIGHT_SHIFT, Keycode.COMMA]),
                },
                {
                    "label": "Fast",
                    "icon": "touch_deck_icons/pr_fast.bmp",
                    "actions": (KEY, [Keycode.RIGHT_SHIFT, Keycode.PERIOD]),
                },
                {
                    "label": "Mute",
                    "icon": "touch_deck_icons/pr_mute.bmp",
                    "actions": (KEY, [Keycode.M]),
                },
            ],
        },
        {
            "name": "Discord",
            "shortcuts": [
                {
                    "label": "Blinka",
                    "icon": "touch_deck_icons/af_blinka.bmp",
                    "actions": (STRING, ":blinka:"),
                },
                {
                    "label": "Adabot",
                    "icon": "touch_deck_icons/af_adabot.bmp",
                    "actions": (STRING, ":adabot:"),
                },
                {
                    "label": "Billie",
                    "icon": "touch_deck_icons/af_billie.bmp",
                    "actions": (STRING, ":billie:"),
                },
                {
                    "label": "Cappy",
                    "icon": "touch_deck_icons/af_cappy.bmp",
                    "actions": (STRING, ":cappy:"),
                },
                {
                    "label": "Connie",
                    "icon": "touch_deck_icons/af_connie.bmp",
                    "actions": (STRING, ":connie:"),
                },
                {
                    "label": "Gus",
                    "icon": "touch_deck_icons/af_gus.bmp",
                    "actions": (STRING, ":gus:"),
                },
                {
                    "label": "Hans",
                    "icon": "touch_deck_icons/af_hans.bmp",
                    "actions": (STRING, ":hans:"),
                },
                {
                    "label": "Mho",
                    "icon": "touch_deck_icons/af_mho.bmp",
                    "actions": (STRING, ":mho:"),
                },
                {
                    "label": "Minerva",
                    "icon": "touch_deck_icons/af_minerva.bmp",
                    "actions": (STRING, ":minerva:"),
                },
                {
                    "label": "NeoTrellis",
                    "icon": "touch_deck_icons/af_neotrellis.bmp",
                    "actions": (STRING, ":neotrellis:"),
                },
                {
                    "label": "Ruby",
                    "icon": "touch_deck_icons/af_ruby.bmp",
                    "actions": (STRING, ":ruby:"),
                },
                {
                    "label": "Sparky",
                    "icon": "touch_deck_icons/af_sparky.bmp",
                    "actions": (STRING, ":sparky:"),
                },
            ],
        },
        {
            "name": "Symbols",
            "shortcuts": [
                {
                    "label": "Infinity",  # ∞
                    "icon": "touch_deck_icons/sy_infinity.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.FIVE]),
                },
                {
                    "label": "Degree",  # º
                    "icon": "touch_deck_icons/sy_degree.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.ZERO]),
                },
                {
                    "label": "Pi",  # π
                    "icon": "touch_deck_icons/sy_pi.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.P]),
                },
                {
                    "label": "Sigma",  # ∑
                    "icon": "touch_deck_icons/sy_sigma.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.W]),
                },
                {
                    "label": "Partial diff",  #
                    "icon": "touch_deck_icons/sy_pdiff.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.D]),
                },
                {
                    "label": "Increment",  # ∆
                    "icon": "touch_deck_icons/sy_increment.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.J]),
                },
                {
                    "label": "Omega",  # Ω
                    "icon": "touch_deck_icons/sy_omega.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.Z]),
                },
                {
                    "label": "Mu",  # µ
                    "icon": "touch_deck_icons/sy_micro.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.M]),
                },
                {
                    "label": "Rad O",  # Ø
                    "icon": "touch_deck_icons/sy_rado.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.SHIFT, Keycode.O]),
                },
                {
                    "label": "Square root",  # √
                    "icon": "touch_deck_icons/sy_sqrrt.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.V]),
                },
                {
                    "label": "Approx",  # ≈
                    "icon": "touch_deck_icons/sy_approx.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.X]),
                },
                {
                    "label": "Plus minus",  # ±
                    "icon": "touch_deck_icons/sy_plusminus.bmp",
                    "actions": (KEY, [Keycode.ALT, Keycode.SHIFT, Keycode.EQUALS]),
                },
            ],
        },
    ]
}

This guide was first published on Mar 24, 2021. It was last updated on 2021-06-08 12:05:38 -0400.

This page (Code the Touch Deck) was last updated on Oct 23, 2021.

Text editor powered by tinymce.