# Ableton Live MacroPad Launcher
## Overview
https://youtu.be/lm_ZTL-pGts
Launch [Ableton Live](https://www.ableton.com/en/live/) clips with the MacroPad RP2040! Mechanical keyswitch clip launching is now a reality. Sync NeoPixel LEDs with your Live session via USB MIDI.
All coded in CircuitPython and customizable to suit your needs. It's the tiny little Launchpad or Push you've always dreamed of!
The basic code concept can be adapted to [Pure Data](https://puredata.info/) with [r\_cycle](https://novationmusic.com/en/news/create-your-own-rcycle-instrument) or [Max/MSP](https://cycling74.com/).
## Sync with MIDI
One of the coolest things about this project is how you can keep the MacroPad and Ableton in sync so that any clip launched in the software UI will light up the related keyswitch LED. This is accomplished with bi-directional MIDI messages.
For example, when Ableton launches a clip, it sends a MIDI message to the MacroPad to say "hey, turn the LED green, this clip is running!" It doesn't matter if the clip was launched with the hardware or software, Ableton takes care of all the LED MIDI message logic. In fact, it even encodes the LED color in the MIDI message. Clever!
## Parts
### Adafruit MacroPad RP2040 Starter Kit - 3x4 Keys + Encoder + OLED
[Adafruit MacroPad RP2040 Starter Kit - 3x4 Keys + Encoder + OLED](https://www.adafruit.com/product/5128)
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 a speedy...
Out of Stock
[Buy Now](https://www.adafruit.com/product/5128)
[Related Guides to the Product](https://learn.adafruit.com/products/5128/guides)
-or-
### Adafruit MACROPAD RP2040 Bare Bones - 3x4 Keys + Encoder + OLED
[Adafruit MACROPAD RP2040 Bare Bones - 3x4 Keys + Encoder + OLED](https://www.adafruit.com/product/5100)
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 a speedy...
In Stock
[Buy Now](https://www.adafruit.com/product/5100)
[Related Guides to the Product](https://learn.adafruit.com/products/5100/guides)
### Adafruit MacroPad RP2040 Enclosure + Hardware Add-on Pack
[Adafruit MacroPad RP2040 Enclosure + Hardware Add-on Pack](https://www.adafruit.com/product/5103)
Dress up your Adafruit Macropad with PaintYourDragon's fabulous decorative silkscreen enclosure and hardware kit. You get the two custom PCBs that are cut to act as a protective bottom plate and and a mechanically-stabilizing keyboard plate.
Use the included M3 screws to attach the...
In Stock
[Buy Now](https://www.adafruit.com/product/5103)
[Related Guides to the Product](https://learn.adafruit.com/products/5103/guides)
### Kailh Mechanical Key Switches - Linear Red - 12 Pack
[Kailh Mechanical Key Switches - Linear Red - 12 Pack](https://www.adafruit.com/product/5122)
For crafting your very own custom keyboard, these ** Kailh Red Linear mechanical key switches** are deeee-luxe! With smooth actuation and Cherry MX compatibility, they're lovely when you want a **smooth linear ** keystroke:
- Type...
In Stock
[Buy Now](https://www.adafruit.com/product/5122)
[Related Guides to the Product](https://learn.adafruit.com/products/5122/guides)
### Clear Keycaps for MX Compatible Switches - 12-pack
[Clear Keycaps for MX Compatible Switches - 12-pack](https://www.adafruit.com/product/5068)
Here is a **12 pack** of Clear DSA keycaps for your next mechanical keyboard or [NeoKey](https://www.adafruit.com/?q=neokey&sort=BestMatch) project. Snap 'em onto any **Cherry MX or compatible switch ** to turn your
In Stock
[Buy Now](https://www.adafruit.com/product/5068)
[Related Guides to the Product](https://learn.adafruit.com/products/5068/guides)
**or**
### Part: Black Windowed Lamp R4 Keycap
quantity: 12
for MX Compatible Switches
[Black Windowed Lamp R4 Keycap](https://www.adafruit.com/product/5112)
### Pink and Purple Woven USB A to USB C Cable - 1 meter long
[Pink and Purple Woven USB A to USB C Cable - 1 meter long](https://www.adafruit.com/product/5153)
This cable is not only super-fashionable, with a woven pink and purple Blinka-like pattern, it's also made for USB C for our modernized breakout boards, Feathers, and more. [If you want something just like it but for Micro B, we...](https://www.adafruit.com/product/4111)
Out of Stock
[Buy Now](https://www.adafruit.com/product/5153)
[Related Guides to the Product](https://learn.adafruit.com/products/5153/guides)
### Optional for use with 3D Printed Case
[Macropad RP2040 Case model](https://www.thingiverse.com/thing:4910369)
### Black Anodized Aluminum Bumper Feet - Pack of 2
[Black Anodized Aluminum Bumper Feet - Pack of 2](https://www.adafruit.com/product/5051)
Keep your electronics from going barefoot, and give them sleek cyberpunk metal feet! These aluminum bumpers are originally designed for keyboard enclosures that are made of anodized aluminum with a black rubber nubbin embedded inside for no-slip support. They're so cool looking we figure...
In Stock
[Buy Now](https://www.adafruit.com/product/5051)
[Related Guides to the Product](https://learn.adafruit.com/products/5051/guides)
# Ableton Live MacroPad Launcher
## CircuitPython
[CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY** drive to iterate.
## CircuitPython Quickstart
Follow this step-by-step to quickly get CircuitPython running on your board.
[Download the latest version of CircuitPython for this board via circuitpython.org](https://circuitpython.org/board/adafruit_macropad_rp2040/)
**Click the link above to download the latest CircuitPython UF2 file.**
Save it wherever is convenient for you.
Info:
To enter the bootloader, hold down the **BOOT/**** BOOTSEL button**(highlighted in red above), and while continuing to hold it (don't let go!), press and release the**reset button**(highlighted in red or blue above). **Continue to hold the BOOT/BOOTSEL button until the RPI-RP2 drive appears!**
If the drive does not appear, release all the buttons, and then repeat the process above.
You can also start with your board unplugged from USB, press and hold the BOOTSEL button (highlighted in red above), continue to hold it while plugging it into USB, and wait for the drive to appear before releasing the button.
A lot of people end up using charge-only USB cables and it is very frustrating! **Make sure you have a USB cable you know is good for data sync.**
You will see a new disk drive appear called **RPI-RP2**.
Drag the **adafruit\_circuitpython\_etc.uf2** file to **RPI-RP2.**
The **RPI-RP2** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
That's it, you're done! :)
## Safe Mode
You want to edit your **code.py** or modify the files on your **CIRCUITPY** drive, but find that you can't. Perhaps your board has gotten into a state where **CIRCUITPY** is read-only. You may have turned off the **CIRCUITPY** drive altogether. Whatever the reason, safe mode can help.
Safe mode in CircuitPython does not run any user code on startup, and disables auto-reload. This means a few things. First, safe mode _bypasses any code in_ **boot.py** (where you can set **CIRCUITPY** read-only or turn it off completely). Second, _it does not run the code in_ **code.py**. And finally, _it does not automatically soft-reload when data is written to the_ **CIRCUITPY** _drive_.
Therefore, whatever you may have done to put your board in a non-interactive state, safe mode gives you the opportunity to correct it without losing all of the data on the **CIRCUITPY** drive.
### Entering Safe Mode
To enter safe mode when using CircuitPython, plug in your board or hit reset (highlighted in red above). Immediately after the board starts up or resets, it waits 1000ms. On some boards, the onboard status LED (highlighted in green above) will blink yellow during that time. If you press reset during that 1000ms, the board will start up in safe mode. It can be difficult to react to the yellow LED, so you may want to think of it simply as a slow double click of the reset button. (Remember, a fast double click of reset enters the bootloader.)
### In Safe Mode
If you successfully enter safe mode on CircuitPython, the LED will intermittently blink yellow three times.
If you connect to the serial console, you'll find the following message.
```terminal
Auto-reload is off.
Running in safe mode! Not running saved code.
CircuitPython is in safe mode because you pressed the reset button during boot. Press again to exit safe mode.
Press any key to enter the REPL. Use CTRL-D to reload.
```
You can now edit the contents of the **CIRCUITPY** drive. Remember, _your code will not run until you press the reset button, or unplug and plug in your board, to get out of safe mode._
## Flash Resetting UF2
If your board ever gets into a really _weird_ state and CIRCUITPY doesn't show up as a disk drive after installing CircuitPython, try loading this 'nuke' UF2 to RPI-RP2. which will do a 'deep clean' on your Flash Memory. **You will lose all the files on the board** , but at least you'll be able to revive it! After loading this UF2, follow the steps above to re-install CircuitPython.
[Download flash erasing "nuke" UF2](https://cdn-learn.adafruit.com/assets/assets/000/101/659/original/flash_nuke.uf2?1618945856)
# Ableton Live MacroPad Launcher
## Build the MacroPad
Follow the basic instructions for [MacroPad assembly](https://learn.adafruit.com/adafruit-macropad-rp2040/macropad-assembly) in the main guide -- but don't attach the back plate. Switch plate, keyswitches, encoder knob, keycaps, and the MacroPad itself should be assembled first, as shown above.
Print the 3D model using the file linked below. I used these settings:
- PLA filament
- 0.2mm height
- 10% gyroid infill
- overhang support to keep ports nice and straight
[Macropad RP2040 Case model](https://www.thingiverse.com/thing:4910369)
## Optional Feet
If you'd like to use the optional keyboard feet for that sweet angled action, start by placing one of the foot screws into it's hole from the topside of the case.
You'll see there are four of these countersunk, M4 holes to choose from, depending on your preferred board orientation. We'll choose "screen on top" orientation and screw in the feet at the top.
Thread each foot onto its screw from the bottom, and tighten it well, but not so tight as to break anything!
**Forgot to get a keyswitch plate?** This community member [shared a 3D printable model](https://www.thingiverse.com/thing:4944190) that works nicely and fits inside the case!
## Insert Macropad
Insert the Macropad into the case as shown, tilting the USB port into place and then pressing the board in snugly.
## Fasten Case and MacroPad
Thread the four M3 screws into the case and the MacroPad's threaded standoffs.
Plug in USB C cable through the top port.
Access the **STEMMA QT** I2C port and the **reset** button from the left side of the case.
# Ableton Live MacroPad Launcher
## Code the Ableton MacroPad
## Text Editor
Adafruit recommends using the **Mu** editor for editing your CircuitPython code. You can get more info in [this guide](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor).
Alternatively, you can use any text editor that saves simple text files.
## Download the Project Bundle
Your project will use a specific set of CircuitPython libraries and the **code.py** file, along with a folder full of key configuration files. To get everything you need, click on the **Download Project Bundle** link below, and uncompress the .zip file.
Drag the contents of the uncompressed bundle directory onto your MACROPAD board's **CIRCUITPY** drive, replacing any existing files or directories with the same names, and adding any new ones that are necessary.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Macropad_Ableton/code.py
## Use It
The key (pun unavoidable) to all of this is the use of Ableton Live's MIDI control surface setup. Commercial controllers, such as the Novation Launchpad Mini Mk3, communicate bidirectionally with Ableton using MIDI messages for everything from clip launching, to scene navigation, to LED color and animation syncing.
## Controller Setup
With the MacroPad plugged into your computer using a USB data cable, launch Ableton Live.
In Ableton, open the preferences by clicking **Live \> Preferences...**
In the Preference window, click on the tab labeled " **Link Tempo MIDI**"
## Control Surface
In the Control Surface list, select **Launchpad Mini Mk3**. This is the scheme used in the code we put on the MacroPad.
NOTE: Be careful not to pick the similarly named " **Launchkey**" item, this has a different MIDI syncing scheme.
## Input
In the Input list, select the **MacroPad RP2040 (CircuitPython usb midi.ports[0])** item.
This is the device that Ableton will be listening to for MIDI messages.
## Output
In the Output list, select the **MacroPad RP2040 (CircuitPython usb midi.ports[0])** item.
This is the device to which Ableton will send MIDI messages to keep things in sync.
## **Track** and **Remote**
Ableton's Track, Sync, and Remote switches are used to enable different types of MIDI messages between devices and the software. Read more details [here](https://help.ableton.com/hc/en-us/articles/209774205-Live-s-MIDI-Ports).
Turn on both the **Track** and **Remote** switches for the **Input** port, and just the **Remote** switch for the **Output**.
**Sync** is used for MIDI Clock and Timecode, neither of which are needed for this project.
## Clip Setup
The MacroPad will launch clips in the first three tracks (columns) and four scenes (rows) of your Ableton session. Load up some samples, loops, MIDI notes, etc. and you'll see the Macropad LEDs match the colors of the clips!
Leave the fifth scene empty, as this is used for "stopping" clips in the MacroPad code by using the encoder switch combined with any key in a column.
You can also use the rotary encoder knob to adjust CC #74 (customizable in code).
You can read lots of great details in the Novation Launchpad Mini Mk3 [Programmer's Reference guide](https://www.djshop.gr/Attachment/DownloadFile?downloadId=10737). If you'd like to implement other features or customize things to your liking, go for it!
## Featured Products
### Adafruit MacroPad RP2040 Enclosure + Hardware Add-on Pack
[Adafruit MacroPad RP2040 Enclosure + Hardware Add-on Pack](https://www.adafruit.com/product/5103)
Dress up your Adafruit Macropad with PaintYourDragon's fabulous decorative silkscreen enclosure and hardware kit. You get the two custom PCBs that are cut to act as a protective bottom plate and and a mechanically-stabilizing keyboard plate.
Use the included M3 screws to attach the...
In Stock
[Buy Now](https://www.adafruit.com/product/5103)
[Related Guides to the Product](https://learn.adafruit.com/products/5103/guides)
### Adafruit MACROPAD RP2040 Bare Bones - 3x4 Keys + Encoder + OLED
[Adafruit MACROPAD RP2040 Bare Bones - 3x4 Keys + Encoder + OLED](https://www.adafruit.com/product/5100)
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 a speedy...
In Stock
[Buy Now](https://www.adafruit.com/product/5100)
[Related Guides to the Product](https://learn.adafruit.com/products/5100/guides)
### Adafruit MacroPad RP2040 Starter Kit - 3x4 Keys + Encoder + OLED
[Adafruit MacroPad RP2040 Starter Kit - 3x4 Keys + Encoder + OLED](https://www.adafruit.com/product/5128)
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 a speedy...
Out of Stock
[Buy Now](https://www.adafruit.com/product/5128)
[Related Guides to the Product](https://learn.adafruit.com/products/5128/guides)
### Black Windowed Lamp R4 Keycap for MX Compatible Switches
[Black Windowed Lamp R4 Keycap for MX Compatible Switches](https://www.adafruit.com/product/5112)
These stark and elegant **Black Windowed Lamp R4 Keycaps** are made of opaque black plastic with a small cutout in the south-center edge that wraps around the top and bottom. The cut-out has a clear plastic window to allow an LED installed under the switch to glow through. They...
In Stock
[Buy Now](https://www.adafruit.com/product/5112)
[Related Guides to the Product](https://learn.adafruit.com/products/5112/guides)
### Woven USB Cable with USB Type A to Right Angle USB Type C
[Woven USB Cable with USB Type A to Right Angle USB Type C](https://www.adafruit.com/product/5031)
Some days we're feeling extra fancy here at the 'fruit warehouse, and we have a big soft spot for woven fabric cables. Like, peep [this fully reversible pink/purple Blinka-inspired cable](https://www.adafruit.com/product/4111) or
Out of Stock
[Buy Now](https://www.adafruit.com/product/5031)
[Related Guides to the Product](https://learn.adafruit.com/products/5031/guides)
### Black Anodized Aluminum Bumper Feet - Pack of 2
[Black Anodized Aluminum Bumper Feet - Pack of 2](https://www.adafruit.com/product/5051)
Keep your electronics from going barefoot, and give them sleek cyberpunk metal feet! These aluminum bumpers are originally designed for keyboard enclosures that are made of anodized aluminum with a black rubber nubbin embedded inside for no-slip support. They're so cool looking we figure...
In Stock
[Buy Now](https://www.adafruit.com/product/5051)
[Related Guides to the Product](https://learn.adafruit.com/products/5051/guides)
## Related Guides
- [Adafruit MacroPad RP2040](https://learn.adafruit.com/adafruit-macropad-rp2040.md)
- [AdaBox 019](https://learn.adafruit.com/adabox019.md)
- [Keypad and Matrix Scanning in CircuitPython](https://learn.adafruit.com/key-pad-matrix-scanning-in-circuitpython.md)
- [MACROPAD Hotkeys](https://learn.adafruit.com/macropad-hotkeys.md)
- [MacroPad Remote Procedure Calls over USB to Control Home Assistant](https://learn.adafruit.com/macropad-remote-procedure-calls-over-usb-to-control-home-assistant.md)
- [MP3 Playback on RP2040 with CircuitPython](https://learn.adafruit.com/mp3-playback-rp2040.md)
- [3D Printed Stand for MacroPad RP2040](https://learn.adafruit.com/3d-printed-stand-for-macropad-rp2040.md)
- [DIY Decorative Resin Keycaps](https://learn.adafruit.com/diy-decorative-resin-keycaps.md)
- [Using QMK on RP2040 Microcontrollers](https://learn.adafruit.com/using-qmk-on-rp2040-microcontrollers.md)
- [An Introduction to RP2040 PIO with CircuitPython](https://learn.adafruit.com/intro-to-rp2040-pio-with-circuitpython.md)
- [Minecraft Turbopad](https://learn.adafruit.com/minecraft-turbopad.md)
- [MacroPad Braille Keycaps](https://learn.adafruit.com/macropad-braille-keycaps.md)
- [Light Up your Costume with Noods](https://learn.adafruit.com/light-up-your-costume-with-noods.md)
- [Using the OPEN INSTALLER Button on circuitpython.org](https://learn.adafruit.com/using-open-installer-on-circuitpython-org.md)
- [How to use 3D Parts GitHub Repo](https://learn.adafruit.com/how-to-use-3d-parts-github-repo.md)