From dfa370b802bf43e8f9dc7aa18053857959b99667 Mon Sep 17 00:00:00 2001 From: ploopyco <54917504+ploopyco@users.noreply.github.com> Date: Wed, 8 Feb 2023 05:21:25 -0500 Subject: [PATCH] Created Appendix C: Firmware programming (markdown) --- Appendix-C:-Firmware-programming.md | 109 ++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 Appendix-C:-Firmware-programming.md diff --git a/Appendix-C:-Firmware-programming.md b/Appendix-C:-Firmware-programming.md new file mode 100644 index 0000000..57d701b --- /dev/null +++ b/Appendix-C:-Firmware-programming.md @@ -0,0 +1,109 @@ +Loading new firmware onto 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. + +## Set up your computer to build new firmwares + +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](https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf). It is very long; we won't have to go through all of it, thankfully. + +To get started: + +- **If you have a Windows machine**: + - Go to section 9.2. + - Follow the steps until you complete section 9.2.4. + - Read, but do not complete, section 9.2.5. +- **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. + +## Add pico-extras to your build environment + +[Go to the pico-extras source page and download the source](https://github.com/raspberrypi/pico-extras). 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. + +## Open up the amplifier board case + +Yup, you'll need access to your amplifier board, so grab a screwdriver and open up that case. You won't break anything, probably. + +## Toggle BOOTSEL vias on the amplifier board + +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. + +![](https://lh3.googleusercontent.com/pw/AMWts8AsqJpv4Z-_AeDbjSMjyK-UbV1nVMO0w8796l3lqY3TrNW8k8H8RnKWoO_k7sRrxzNFnHPSg9ClJ_N5J-iBvtWs_OVIPDFXa26ACGreTc49G5VxxcsP4nmDZSVmglJ04VvuOQ6mhAYSEr4PF2HOshQG=w1434-h955-no?authuser=0) + +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. + +**Bingo, bongo, you're now in boot selector mode!** + +Now, unplug the board, disconnect the two vias, and plug it back in. You should be back in normal operating mode. + +Uploading new firmware requires that the amplifier board be in boot selector mode. So, whenever there are instructions to do that in this (or any other) guide, just follow the instructions in this section. + +## Create your first Ploopy Headphones firmware + +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](https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf).) 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. + +![Engage](https://media.tenor.com/a7AEXVIQdhQAAAAC/sir-patrick-stewart-patrick-stewart.gif) + +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. + +## You're done! + +If you want to tune your headphones, head over to [Appendix E: Tuning the EQ Profile].