7 Minuten
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:
- Der Layoutdefinition, also der Tastenanordnung auf der Tastatur. In diesem Beispiel ist es die Datei
keyboard_layout_win_de.py
. - 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.py
kö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:
Name | Funktion |
---|---|
Vol- | Verringert die Lautstärke |
Mute | Toggle für das Stummschalten der Lautstärke |
Vol+ | Erhöht die Lautstärke |
TSKMGR | Startet den Taskmanager |
DSKTP | Toggle um alle Fenster auszublenden und den Desktop anzuzeigen |
EXPL | Öffnet den Windows Explorer |
SelAll | Markiert den gesamten Text |
CBHist | Zeigt den Verlauf der Einträge in der Zwischenablage |
SNIPPT | Startet das Snipping Tool |
Cut | Markierten Text ausschneiden |
Copy | Kopiert den markierten Text in die Zwischenablage |
Paste | Fügt den Text aus der Zwischenablage ein |
Quit | Schließt das aktive Programm |
Firefox Browser
Die Datei 1_firefox.py
kö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:
Name | Funktion |
---|---|
+ TAB | Öffnet einen neuen Tab |
+ WDW | Öffnet ein neues Fenster |
BW PW | Setzt Passwörter aus dem Bitwarden Add-On ein |
- TAB | Schließt den aktiven Tab |
- WDW | Schließt das aktive Browser-Fenster |
BW 2F | Setzt Passwörter aus dem Bitwarden Add-On inkl. 2Fa ein |
< Back | Navigiert zurück in der Browserhistory |
Forw > | Navigiert vor in der Browserhistory |
Reload | Lädt den aktiven Tab neu |
< Tab | Wechselt zum vorherigen geöffneten Tab |
Tab > | Wechselt zum nächsten geöffneten Tab |
DL | Wechselt zu den Downloads |
Quit | Schließt den Firefox Browser |
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:
Farbe | Dunkel | Hell |
---|---|---|
Blau | 0x000020 | - |
Grün | 0x002000 | - |
Rot | 0x200000 | - |
Gelb | 0x404000 | - |
Orange | 0x663300 | - |
Cyan | 0x02180B | 0x0de05e |
Rosa | 0x380e0e | - |
Lila | 0x1d0320 | 0x770de0 |
Grau | 0x121212 | - |
Dunkel | 0x202000 | - |
Schwarz | 0x000000 | - |
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 empfielt 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:
Setting | Wert |
---|---|
Infill | 10% |
Resolution | 0.2mm |
Support | Nein |
Raft | Ja |
Druckdauer | 4h |


Viel Spaß mit dem Macropad!