Adafruit Macropad RP2040

Das Adafruit Macropad RP2040 basiert, wie der Name bereits andeutet, auf dem RP2040 der Raspberry Pi Foundation. Es ist ein kleiner Mikrocontroller, der kinderleicht mit Micropython oder Circuitpython programmiert werden kann.

Dieser Post erläutert den Anwendungsfall eines klassischen Macropads, basierend auf diesem Guide von Adafruit mit dem wesentlichen Unterschied, dass statt dem standardmäßigen US-Tastatur-Layout das Deutsche Layout verwendet wird. Somit können mit vordefinierten Macros Tastenkombinationen und Strings mit einem einfachen Klick auf einen der 12 Buttons an den angeschlossenen Computer gesendet werden. Ein Treiber ist nicht notwendig, da sich das Macropad als HID-Device ausweist.

Setup

Auch wenn Adafruit viele gute Tutorials für das Macropad auf ihrer Webseite anbietet, zeichnete sich schnell ab, dass insbesondere die Zuweisung eines Tastatur Layouts fernab des amerikanischen US-Layouts eine Hürde für Beginner darstellt. Um diesen Showstopper zu überwinden sind im Folgenden alle Schritte erläutert, die zu einem funktionalem Macropad mit deutschem Tastaturlayout und den entsprechenden Keycodes führen.

Circuitpython

Der einfachste Weg das Macropad lauffähig zu machen erfolgt mittels Circuitpython. Sämtliche Adafruit Tutorials greifen auf diese Programmierumgebung zurück und können daher hervorragen als Basis für eigene Vorhaben dienen.

Für das Macropad stehen auf der Webseite von Circuitpython eine eigene Firmware zur Verfügung. Diese muss heruntergeladen werden. Anschließend muss das Macropad mit dem heimischen Computer per USB verbunden und in den Bootloader gebootet werden. Dies erfolgt durch ein gedrückt halten des Rotary Encoders und einem Druck auf die seitliche Reset-Taste am Macropad. Es erscheint anschließend ein Laufwerk im Dateiexplorer mit dem Namen RPI-RP2. Die heruntergeladene Firmwaredatei muss nun auf dieses Laufwerk kopiert werden. Das Macropad startet anschließend neu und es erscheint ein weiteres Laufwerk mit dem Namen CIRCUITPYTHON. Für alle folgenden Schritte muss diese Laufwerk sichtbar und das Macropad mit dem Computer verbunden sein.

Circup

Circup ist ein nützliches Kommandozeilentool, das unkompliziert alle benötigten Circuitpython-Bibliotheken installieren kann. Es benötigt ein installiertes Python3 und den Paketmanager Pip. Nach der Installation können die notwendigen Bibliotheken installiert werden.

Libraries installieren

Die benötigten Bibliotheken werden direkt auf dem angeschlossenen Macropad installiert. Die Downloads sind allesamt vorkompilierter Python-Code im .mpy-Format, sprich sie können anschließend nicht als Textdateien bearbeitet werden:

circup install adafruit_bitmap_font adafruit_display_shapes adafruit_display_text adafruit_hid adafruit_debouncer adafruit_pixelbuf adafruit_simple_text_display adafruit_ticks adafruit_neopixel

Zusätzlich wird noch die eigentliche Bibliothek für das Macropad benötigt. Da in dieser Datei das Tastaturlayout definiert wird, muss in diesem Fall eine nicht kompilierte Pythondatei heruntergeladen werden. Die kann über den Parameter --py erreicht werden:

circup install --py adafruit_macropad

Deutsches Tastatur-Layout

Im finalen Schritt fehlen nur noch die Dateien, die das deutsche Tastaturlayout definieren. Diese können als Bundle neben vielen anderen Layouts installiert werden:

circup bundle-add Neradoc/Circuitpython_Keyboard_Layouts

gefolgt von dem Befehl zur eigentlichen Installation des deutschen Layouts:

circup install keyboard_layout_win_de keycode_win_de

Die heruntergeladenen Layouts bestehen aus zwei Dateien:

1. Der Layoutdefinition, also der Tastenanordnung auf der Tastatur. In diesem Beispiel ist es die Datei keyboard_layout_win_de.py.
2. Den Keycodes, also welcher Buchstabe ausgegeben werden soll, wenn die Taste auf dem vordefinierten Layout gedrückt wird. In diesem Beispiel ist es die Datei keycode_win_de.py.

Macropad Code

Das deutsche Tastaturlayout funktioniert nur durch die Anpassung der Datei lib/adafruit_macropad.py. Die Originaldatei von Adafruit kann hier bezogen werden und muss wie in diesem Pull Request beschrieben angepasst werden.

Weiterhin benötigt wird die Datei code.py, die den eigentlichen Programmcode enthält. Sie steht bei Github zum Download bereit.

Damit ist das Macropad mit deutschem Tastaturlayout und den zugehörigen Keycodes einsatzbereit. Es fehlen lediglich noch die Makros. Diese müssen in einem Ordner namens macros/ auf dem Macropad abgelegt werden. Sie werden alphabetisch sortiert geladen und können mit dem Drehschalter auf dem Pad gewechselt werden. Zur Festlegung der Reihenfolge empfiehlt es sich also einen numerischen Prefix im Dateinamen zu vergeben.

Die Ordnerstruktur auf dem Macropad sollte anschließend so aussehen:

CIRCUITPYTHON/
  │
  ├── code.py
  ├── lib/
  │   ├── adafruit_bitmap_font/
  │   ├── adafruit_display_shapes/
  │   ├── adafruit_display_text/
  │   ├── adafruit_hid/
  │   ├── adafruit_midi/
  │   ├── adafruit_debouncer.mpy
  │   ├── adafruit_macropad.py
  │   ├── adafruit_pixelbuf.mpy
  │   ├── adafruit_simple_text_display.mpy
  │   ├── adafruit_ticks.mpy
  │   ├── keyboard_layout_win_de.mpy
  │   ├── keycode_win_de.mpy
  │   └── neopixel.mpy
  └── macros/
      ├── 0_windows.py
      └── 1_firefox.py

Beispielmakros:

Im folgenden sind zwei Beispielmakros für Windowsfunktionen und den Firefox Browser erläutert. Die Bezeichnung im Feld 'name': wird oben auf dem Display des Macropads angezeigt. Die Benennung der einzelnen Makrofunktionen ebenfalls. Die Namen der Funktionen sollte nicht länger als 6 Buchstaben sein.

Windows Funktionen

Die Datei 0_windows.pykönnte beispielsweise so aussehen. Sie verwendet sowohl Tastenkombinationen, als auch sogenannte Consumer Control Codes. Letztere sind spezifische Eingabekommandos, wie bspw. das erhöhen oder reduzieren der Lautstärke oder der Bildschirmhelligkeit oder die Musiksteuerung. Alle implementierten Consumer Control Codes sind hier dokumentiert.

# MACRO ..... :  Windows
# DESCRIPTION :  Basic Windows Functions

from keycode_win_de import Keycode
from adafruit_hid.consumer_control_code import ConsumerControlCode

app = {
    'name' : 'WINDOWS',
    'macros' : [
        # COLOR    LABEL    KEY SEQUENCE
        # 1st row ----------
        (0x000020, 'Vol-', [[ConsumerControlCode.VOLUME_DECREMENT]]),
        (0x000020, 'Mute', [[ConsumerControlCode.MUTE]]),
        (0x000020, 'Vol+', [[ConsumerControlCode.VOLUME_INCREMENT]]),
        # 2nd row ----------
        (0x663300, 'TSKMGR', [Keycode.CONTROL, Keycode.SHIFT, Keycode.ESCAPE]),
        (0x663300, 'DSKTP', [Keycode.WINDOWS, 'd']),
        (0x663300, 'EXPL', [Keycode.WINDOWS, 'e']),
        # 3rd row ----------
        (0x380e0e, 'SelAll', [Keycode.CONTROL, 'a']),
        (0x02180B, 'CBHist', [Keycode.WINDOWS, 'v']),
        (0x663300, 'SNIPPT', [Keycode.WINDOWS, 'r', 0.5, '%windir%\system32\SnippingTool.exe', Keycode.RETURN]),
        # 4th row ----------
        (0x380e0e, 'Cut', [Keycode.CONTROL, 'x']),
        (0x380e0e, 'Copy', [Keycode.CONTROL, 'c']),
        (0x380e0e, 'Paste', [Keycode.CONTROL, 'v']),
        # Encoder button ---
        (0x000000, 'NoSkype', [Keycode.WINDOWS, Keycode.ESCAPE])
    ]
}

Erläuterung der einzelnen Funktionen:

Firefox Browser

Die Datei 1_firefox.pykönnte beispielsweise so aussehen:

# MACRO ..... : Firefox
# DESCRIPTION : Firefox Hotkeys incl. Bitwarden Add-On

from keycode_win_de import Keycode

app = {
    'name' : 'FIREFOX',
    'macros' : [
        # COLOR    LABEL    KEY SEQUENCE
        # 1st row ----------
        (0x02180B, '+ TAB', [Keycode.CONTROL, 't']),
        (0x380e0e, '+ WDW', [Keycode.CONTROL, 'n']),
        (0x000020, 'BW PW', [Keycode.CONTROL, Keycode.SHIFT, 'l']),
        # 2nd row ----------
        (0x02180B, '- TAB', [Keycode.CONTROL, 'w']),
        (0x380e0e, '- WDW', [Keycode.CONTROL, Keycode.SHIFT, 'w']),
        (0x000020, 'BW 2F', [Keycode.CONTROL, Keycode.SHIFT, 'l', 1.0, -Keycode.SHIFT, 'v', Keycode.ENTER]),
        # 3rd row ----------
        (0x404000, '< Back', [Keycode.ALT, Keycode.LEFT_ARROW]),
        (0x404000, 'Reload', [Keycode.F5]),
        (0x404000, 'Forw >', [Keycode.ALT, Keycode.RIGHT_ARROW]),
        # 4th row ----------
        (0x121212, '< Tab', [Keycode.CONTROL, Keycode.PAGE_UP]),
        (0x121212, 'Tab >', [Keycode.CONTROL, Keycode.PAGE_DOWN]),
        (0x002000, 'DL', [Keycode.CONTROL, 'j']),
        # Encoder button ---
        (0x000000, 'Quit', [Keycode.ALT, Keycode.F4])
    ]
}

Erläuterung der einzelnen Funktionen:

Beispielcode als Download

Der oben dargestellte Beispielcode mit deutschem Tastaturlayout und samt der zwei beschriebenen Makros kann auf Github als Zip-Archiv heruntergeladen werden. Der Inhalt des Archivs kann direkt auf das Makropad kopiert werden und wird automatisch ausgeführt.

RGB Hex Farbcodes

Als kleines Helferlein gibt es noch eine Tabelle mit einer kleinen Auswahl an Farbcodes für die Zuweisung der RGB-LEDs unterhalb der einzelnen Switches. Diese Farbcodes wurden von mir verwendet:

Es gibt als eine weitere gute Referenz diesen Blogpost für zusätzliche Farben.

Gehäuse drucken

Ich habe in Autodesk Inventor ein eigenes Gehäuse entworfen. Dieses enthält Ausschnitte für sämtliche Anschlüsse und die seitliche Reset-Taste. Es empfiehlt sich jedoch einen Raft um die Grundfläche zu drucken, da sonst Warping-Effekte auftraten. Die Oberseite ist aus Gründen der Ergonomie um 9° geneigt.

Die Druckoptionen:

Viel Spaß mit dem Macropad!