Appendix C: Firmware programming
This guide is set up into three parts:
- Changing the EQ of the amplifier
- Uploading new firmwares to the amplifier
- Building your own firmwares
Read on to find out more!
If you only want to change the EQ of the amplifier, the fastest, easiest way of changing it is to use George Norton's Headphones Toolbox. It's a powerful GUI tool that allows you to shape the EQ any way that you want to. And, it's completely free! Check it out.
Uploading the latest firmware to your amplifier is very easy! All you need is a pair of tweezers, a screwdriver, and about five minutes. Read on to find out how.
Start by using a screwdriver to open up that case. You won't break anything, probably.
Now, a bit of a background lesson. The Ploopy Headphones amplifier operates in two modes.
The first mode is "normal operation". This mode is used when you plug the amplifier in normally. Pretty normal, really. That's why it's called "normal".
The second mode is "boot selection". This mode is used to load new firmwares onto the board. In order to activate boot selection mode, we need to toggle the BOOTSEL switch.
"But wait!", you may be saying. "There's no switch on the board!" And, you're correct. Sort of. Actually, no, you're wrong.
Take a look at the board.
Do you see those two golden holes in the board? Those are called vias. They act exactly like a switch does. Right now, that switch is OFF. However, if you take a paperclip or a pair of metal tweezers and touch those two vias, the two vias will form an electrical connection. Effectively, that switch turns ON.
Go ahead and connect the two vias, and then (while the vias are connected) plug in the amplifier board into your computer.
The computer should recognise that a mass storage device was just plugged in. Once this is done, you should be able to drag and drop files onto the amplifier board, as if the board was a USB drive. Feel free to remove the tweezers or paperclip at this point.
Bingo, bongo, you're now in boot selector mode! If you want to upload a new firmware file (a ".uf2" file, like "ploopy_headphones_pm420" or something), just drag it into the folder, and it'll automatically install on the amplifier and restart itself, in normal operating mode. You're done!
TIP: If your firmware is in some kind of strange state and uploading new firmware isn't fixing it, try uploading a flash nuke to the amplifier before flashing the new firmware. It wipes the memory of the amplifier completely clean, which can help clear a few types of errors.
To summarise: if you want to upload new firmware,
- Put the amplifier into "BOOTSEL" or "boot selector" mode.
- Wait for your computer to recognise the amplifier as a USB mass storage device.
- Drag and drop your new firmware onto the amplifier.
- Wait a bit as it automatically resets itself.
And boom, you've uploaded new firmware!
Creating new firmware for the amplifier board is a core feature of the Ploopy Headphones. In this section, you'll learn how to do it, from start to finish. Even if you have no programming experience whatsoever, this guide will make it possible for you.
The Ploopy Headphones amplifier board is powered with an RP2040, a chip that is designed by the Raspberry Pi Foundation. Programming it is fairly straightforward.
First, open up this guide. It is very long; we won't have to go through all of it, thankfully.
To get started:
-
If you have a Windows machine:
- Complete section 9.2.1.
-
If you have a Mac machine:
- Go to section 9.1.
- Follow the steps until you complete section 9.1.3.
-
If you have a Linux machine:
- Go to section 1.
- Follow the steps until you completely section 1, except for "Configure the Raspberry Pi UART for use with Raspberry Pi Pico".
For the remainder of this guide, it is assumed that you are using Visual Studio Code to write and build firmwares. If you're not, you're on your own.
Go to the pico-extras source page and download the source. Put it in the same directory that you put the pico-sdk directory.
Open your Developer Command Prompt for VS 2022 and type setx PICO_EXTRAS_PATH "..\..\pico-sdk".
Close the command prompt, as well as VS Code (if it's open).
Reopen the Developer Command Prompt for VS 2022, and launch VS Code from the command prompt (by typing code).
And, congratulations! Your machine is now fully configured to create firmwares for the Ploopy Headphones.
That was probably a lot of work. Have a cookie and celebrate.
"But wait!", you may be asking yourself. "How do I create new firmware?" Great question!
Before you do anything else, there is one thing that you must, must, must do:
For all that is good and holy, for the grace that surrounds and blesses us all, for the love of mothers and the benediction of fathers, for the suffusion of charity that connects the spirits of all mankind...
TAKE THE DAMN HEADPHONES OFF OF YOUR HEAD.
If you build a bad firmware, there is a good chance that the headphones will produce a very loud screeching noise that will damage your hearing or, at the very least, make you think you stuck your head into a cement mixer filled with bowling balls, chalkboards and cats in heat.
So, don't be a dummy. Just take the headphones off when you're building the firmware. In fact, we invented a short, memorable rhyme for you to remember to do so:
Building firmware
is more fun
when you're not
a stupid idiot
Let's move on.
Download the firmware source code, which is in this repository. Make a note of where you put the source code. You'll need to know this for later.
Go back to the Raspberry Pi Pico "Getting Started" PDF. (If you've already closed it, it's here.) Navigate to section 7.2. Use those instructions to load the firmware that you just downloaded into VS Code.
Then, check the CMake mode. Do this by looking at the bottom of the screen: you should see something that looks like "CMake: [Release] Ready", or perhaps "CMake: [Debug] Ready". Make sure that the mode is Release.
Now, hit the Build button.
Once it's built, find the ploopy_headphones.uf2 file that you just made (it'll be in the "build" directory of where the source code is). That's your new firmware.
Did you take the headphones off?
Put the amplifier board into boot selection mode, and drag and drop the ploopy_headphones.uf2 file onto the board. It should automatically reset, and...if everything worked, you'll be listening to that most crisp and refreshing of sounds:
the sound of success.
If you want to tune your headphones, head over to Appendix E: Tuning the EQ Profile.