Adafruit Macropad RP2040 Created by Kattni Rembor
Total Page:16
File Type:pdf, Size:1020Kb
Adafruit MacroPad RP2040 Created by Kattni Rembor Last updated on 2021-09-24 01:58:25 PM EDT Guide Contents Guide Contents 2 Overview 5 Pinouts 9 Key Switch Sockets 10 Rotary Encoder / BOOT Button 10 OLED Display 11 NeoPixel LEDs 12 RP2040 Microcontroller 13 QSPI Flash 13 Speaker 14 STEMMA QT Connector 14 USB C Connector 15 Red LED 16 Reset Button 17 Mounting Bosses 18 Macropad Assembly 20 Switches into Plate 20 Connect to Board 21 Add Switches 22 Backplate 23 Keycaps 24 CircuitPython 26 CircuitPython Quickstart 26 Safe Mode 28 Entering Safe Mode in CircuitPython 6.x 28 Entering Safe Mode in CircuitPython 7.x 29 In Safe Mode 29 Flash Resetting UF2 30 Installing Mu Editor 31 Download and Install Mu 31 Using Mu 31 Creating and Editing Code 33 Creating Code 33 Editing Code 35 Your code changes are run as soon as the file is done saving. 36 1. Use an editor that writes out the file completely when you save it. 36 2. Eject or Sync the Drive After Writing 37 Oh No I Did Something Wrong and Now The CIRCUITPY Drive Doesn't Show Up!!! 37 Back to Editing Code... 38 Exploring Your First CircuitPython Program 39 Imports & Libraries 39 Setting Up The LED 39 Loop-de-loops 40 What Happens When My Code Finishes Running? 40 What if I don't have the loop? 41 More Changes 42 Naming Your Program File 42 Connecting to the Serial Console 43 Are you using Mu? 43 Setting Permissions on Linux 44 Using Something Else? 45 © Adafruit Industries https://learn.adafruit.com/adafruit-macropad-rp2040 Page 2 of 135 Interacting with the Serial Console 46 The REPL 50 Returning to the serial console 53 CircuitPython Libraries 54 Installing the CircuitPython Library Bundle 55 Example Files 56 Copying Libraries to Your Board 57 Example: ImportError Due to Missing Library 57 Library Install on Non-Express Boards 59 Updating CircuitPython Libraries/Examples 59 Frequently Asked Questions 60 I have to continue using an older version of CircuitPython; where can I find compatible libraries? 60 Is ESP8266 or ESP32 supported in CircuitPython? Why not? 60 How do I connect to the Internet with CircuitPython? 61 Is there asyncio support in CircuitPython? 62 My RGB NeoPixel/DotStar LED is blinking funny colors - what does it mean? 63 What is a MemoryError? 64 What do I do when I encounter a MemoryError? 64 Can the order of my import statements affect memory? 65 How can I create my own .mpy files? 65 How do I check how much memory I have free? 65 Does CircuitPython support interrupts? 65 Does Feather M0 support WINC1500? 66 Can AVRs such as ATmega328 or ATmega2560 run CircuitPython? 66 Commonly Used Acronyms 66 Troubleshooting 67 Always Run the Latest Version of CircuitPython and Libraries 67 I have to continue using CircuitPython 5.x, 4.x, 3.x or 2.x, where can I find compatible libraries? 67 CPLAYBOOT, TRINKETBOOT, FEATHERBOOT, or GEMMABOOT Drive Not Present 67 You may have a different board. 68 MakeCode 68 MacOS 68 Windows 10 68 Windows 7 or 8.1 68 Windows Explorer Locks Up When Accessing boardnameBOOT Drive 69 Copying UF2 to boardnameBOOT Drive Hangs at 0% Copied 70 CIRCUITPY Drive Does Not Appear 70 Device Errors or Problems on Windows 70 Serial Console in Mu Not Displaying Anything 71 CircuitPython RGB Status Light 72 ValueError: Incompatible .mpy file. 72 CIRCUITPY Drive Issues 73 Easiest Way: Use storage.erase_filesystem() 73 Old Way: For the Circuit Playground Express, Feather M0 Express, and Metro M0 Express: 73 Old Way: For Non-Express Boards with a UF2 bootloader (Gemma M0, Trinket M0): 75 Old Way: For non-Express Boards without a UF2 bootloader (Feather M0 Basic Proto, Feather Adalogger, Arduino Zero): 76 Running Out of File Space on Non-Express Boards 76 Delete something! 76 Use tabs 76 © Adafruit Industries https://learn.adafruit.com/adafruit-macropad-rp2040 Page 3 of 135 MacOS loves to add extra files. 76 Prevent & Remove MacOS Hidden Files 77 Copy Files on MacOS Without Creating Hidden Files 77 Other MacOS Space-Saving Tips 78 Device locked up or boot looping 79 Uninstalling CircuitPython 81 Backup Your Code 81 Moving Circuit Playground Express to MakeCode 81 Moving to Arduino 82 Welcome to the Community! 85 Adafruit Discord 85 Adafruit Forums 86 Adafruit Github 87 ReadTheDocs 88 CircuitPython Essentials 90 Blink 91 LED Location 91 Blinking an LED 91 Digital Input 93 LED and Button 93 Controlling the LED with a Button 93 Keypad 95 MacroPad CircuitPython Library 97 MacroPad Library Installation 97 MacroPad Basics 99 MacroPad Display Text 101 MacroPad Display Image 104 MacroPad Rotation 106 Rotation Example 107 Other Rotations 109 MacroPad Tone 111 MacroPad Keyboard and Mouse 114 Macropad MIDI 118 Modes 120 MacroPad Library Docs 121 Arduino 122 Required Libraries 122 Example Code 123 Installing the Earle Philhower core 127 Connecting your RP2040 129 Downloads 131 Files 131 Original MacroPad Demo 131 Schematic 131 Fab Print 132 3D Model 133 © Adafruit Industries https://learn.adafruit.com/adafruit-macropad-rp2040 Page 4 of 135 Overview Strap yourself in, we're launching in T-minus 10 seconds...Destination? A new Class M planet called MACROPAD! M here, stands for Microcontroller because this 3x4 keyboard controller features the newest technology from the Raspberry Pi sector: say hello to the RP2040. It's speedy little microcontroller with lots of GPIO pins and a 64 times more RAM than the Apollo Guidance Computer. We added 8 MB of flash memory for plenty of storage. © Adafruit Industries https://learn.adafruit.com/adafruit-macropad-rp2040 Page 5 of 135 Get ready to upgrade your desk's mission control station with a CircuitPython or Arduino powered Macropad - complete with 12 buttons, OLED display, speaker and rotary encoder. Customize it for your spacecraft to help guide you through the great reaches of the unknown. (Or just have it type out your favorite emojis.) Each of the 12 sockets can accept a Cherry MX-compatible key switch. No soldering required, just snap it in! Use any key switch you like - but we recommend ones with slots that will allow the matching twelve NeoPixels underneath to shine through. This space-ship is also fitted with a 128x64 monochome OLED for a crisp heads-up display that can be used in Arduino or CircuitPython to display keymaps, stats, computer performance, etc. There's also a rotary encoder with push-button soldered in. Twist and turn it or push to change volume or monitor brightness or scroll: whatever you like! A tiny speaker can give audio feedback or play fun bleepy tunes. Want to add more hardware? No worries - a STEMMA QT port on the side lets you connect any I2C add- on peripherals from the massive STEMMA QT / Qwiic family of plug in boards (https://adafru.it/Qgf). © Adafruit Industries https://learn.adafruit.com/adafruit-macropad-rp2040 Page 6 of 135 Please note, the RP2040 chip does not currently have QMK support - this macropad is designed to be programmed in Arduino or CircuitPython! If QMK eventually does add RP2040 as a supported chipset (no ETA and no plans that we know of), we'll update this page. TL;DR? Raspberry Pi RP2040 Chip + 8MB Flash memory - Dual core Cortex M0+ at ~130MHz with 264KB of RAM. Runs CircuitPython, Arduino or MicroPython with ease and lots of space for development code © Adafruit Industries https://learn.adafruit.com/adafruit-macropad-rp2040 Page 7 of 135 and files USB C Connector for Power/Data - of course this can act as an HID device but also can be MIDI, UART, etc. 3x4 Mechanical key switch sockets - accepts any Cherry MX-compatible switches. Individually tied to GPIO pins (not matrix wired) One NeoPixel RGB LED per switch, on north side Rotary encoder, 20 detents per rotation, with push-switch on GPIO pin. Push switch is also used for entering bootloader mode when held down on power-up or reset. 128x64 SH1106 Monochrome OLED display - On high speed hardware SPI port for quick updates 8mm Speaker/Buzzer - With Class D amplifier and RC filter, can be used to make simple beeps and sounds effects. STEMMA QT Connector - Allows adding any I2C sensors/displays/devices with plug-and-play cables. Reset button - On the side, for quick restarting of code Four M3 mounting bosses - Make custom enclosures easily © Adafruit Industries https://learn.adafruit.com/adafruit-macropad-rp2040 Page 8 of 135 Pinouts The MacroPad RP2040 is full of macropad deliciousness. It has some great features beyond the keys. Time for tour! PDF of the pinouts image above is available here (https://adafru.it/TBk). © Adafruit Industries https://learn.adafruit.com/adafruit-macropad-rp2040 Page 9 of 135 Key Switch Sockets On the MacroPad, laid out in a 3x4 grid, are the Cherry- MX compatible key switch sockets. They are mounted on the back of the board so the socket points through to the front. The key switch sockets are individually tied to GPIO pins (i.e. not matrix-wired). Simply press any compatible key switch into the socket from the top of the board. You can add a dab of glue to keep the switch in place; hot glue or a dot of epoxy will work. Rotary Encoder / BOOT Button We snuck the BOOT button in as the button switch in the rotary encoder. Press the rotary encoder to engage the BOOT button! © Adafruit Industries https://learn.adafruit.com/adafruit-macropad-rp2040 Page 10 of 135 On the top right corner of the board (when viewed from the top), is the rotary encoder / BOOT button.