This website is designed to help you transform an ESP32-S3 microcontroller and a few input components into a fully functioning, customized macropad.
Download and install CircuitPython from circuitpython.org. You may need to unplug the ESP32-S3 during installation or swap between USB-C ports, but the process only takes 60–90 seconds. Once done, your device will appear as a USB drive called CIRCUITPY — this means it is ready to run Python code!
Click ↓ code.py in the toolbar above and copy it to the root of your CIRCUITPY drive. You will also need font5x8.bin in the root folder if you are using an OLED display — download it from Adafruit's GitHub. The serve.py file is only needed to run this configurator website locally on your own computer and does not go on the device.
ⓘ The Adafruit libraries used in this project are open source (MIT licence). You are free to copy and share them with students. Download the full bundle from circuitpython.org/libraries and copy the required libraries listed in the Libraries tab into the CIRCUITPY/lib/ folder.
Drag components from the shelf at the top into the workspace to create your layout. Appearance does not matter for the code, but arranging components close to the pins you plan to use will help you build a cleaner physical product. Lines connect automatically to available GPIO pins — you can click any pin badge on a component to reassign it.
Click any component on the canvas to open its settings in the panel on the right. Set the action each button or encoder should perform. If you want two separate configurations — for example a Mac mode and a PC mode, or a normal layer and an application-specific hotkey layer — enable Config 2 inside a component and make sure at least one button is set to Config Toggle to switch between them.
When the Notes tab shows no errors, click ↓ Download config.json and copy the file to the root of your CIRCUITPY drive. Then open the Libraries tab to see which libraries your build needs, download them from the Adafruit Bundle, and copy them into CIRCUITPY/lib/. Reset the device and your macropad will be active immediately.
Use the wiring diagram on screen as your guide. Connect each component to the GPIO pins shown, then power the device on and try it out. If something does not behave as expected, come back to the configurator, adjust the settings, and re-download config.json — no reflashing required.