// quick start
This page takes a RadioSonic Rev A board from the box to a working dsp> prompt without installing a compiler or a development environment. On Windows you use Espressif's Flash Download Tool, and on macOS or Linux you use Espressif's command line tool, esptool. Start with step 1, then open the guide for your operating system: Windows, macOS or Linux.
| Item | Notes |
|---|---|
| RadioSonic Rev A board | The board shipped with your course. |
| USB-C data cable | The cable from your cable kit. Some phone charging cables carry power only, and the board will light up but never appear on the computer. |
| A computer | Windows 10 or 11, macOS, or Linux. |
| Flashing tool | On Windows, Espressif's free Flash Download Tool, which needs no installer. On macOS and Linux, Python 3 and Espressif's esptool, which the guide shows you how to install. |
| Firmware image | The .bin file from step 1. |
| Google Chrome | The console at the end of this guide connects to the board directly from this page, which works in Chrome on Windows, macOS and Linux. Chrome is also required for the course. Firefox 151 and later works too, once you allow the permission it asks for, but Safari cannot connect to USB devices from a web page. |
This is a single combined image containing the bootloader, the partition table and the application, so it is written in one piece starting at address 0x0. It is built for the Rev A board, whose silkscreen reads SPL-RS-01-A, and it is the same file for every operating system.
Now open the guide for your operating system. Each one continues from step 2.
The download is a zip file of about 25 MB from Espressif's own server. The tool needs no installer, so unzip it to any folder you like and keep that folder open for step 4.
First make sure the board is switched on: the small slide switch SW8 on the bottom edge of the board must be to the left. With SW8 to the right the board is unpowered and will look dead.
The ESP32-S3 only accepts new firmware while it is in its built-in download mode. The two push buttons you need, SW2 (BOOT) and SW1 (RESET), sit immediately to the left of the metal WROOM module. Use whichever of these methods suits the state of your board:
| Method | How |
|---|---|
| Buttons (always works) | Connect the USB-C cable. Press and hold SW2 (BOOT), press and release SW1 (RESET), then release SW2. |
| Console command | If the board is already running RadioSonic firmware and you have its console open, type bootloader and press Enter, then close the terminal program so it releases the port. |
You will not see an LED signal that download mode has started. In download mode the RadioSonic firmware is not running, so nothing updates the LEDs: the four RGB LEDs freeze on whatever they were showing at the moment of the reset, or usually stay dark if the board has only just been plugged in, and the small heartbeat LED stops blinking. This frozen look is normal and does not mean the board has crashed. The reliable sign that it worked is the board's port appearing in the Flash Download Tool's COM list in step 5.
A board that is still running the factory test image, which shows four RGB LEDs breathing green, is already in a state the tool can program and can usually be flashed without pressing any buttons. If the tool fails to connect, fall back to the button method.
Run flash_download_tool_3.9.x.exe from the folder you unzipped in step 2. Windows may warn that the program is from an unrecognised publisher; it is Espressif's own tool, and you can choose More info and then Run anyway. A small window then asks for three settings:
| Setting | Choose |
|---|---|
| ChipType | ESP32-S3 |
| WorkMode | Develop |
| LoadMode | UART (the USB port on the board shows up as an ordinary COM port, so UART is correct even though you are using a USB cable) |
Click OK and the main download window opens. Its title bar names the chip it was set up for and should start with ESP32S3. If it names a different chip, such as ESP32C3, close the tool and start it again with ChipType set to ESP32-S3.
In the main window, fill in the first row of the file list and the settings below it as shown in the table. You do not need to set SPI SPEED or SPI MODE: current versions of the tool fill those two fields in themselves and grey them out, and they may show 40MHz and DIO. Leave them exactly as the tool shows them.
| Field | Value |
|---|---|
| File (first row) | Click the ... button and select RadioSonic_RevA_0.9.1-107-ge4282e5.bin. |
| Address (after the @) | 0x0 |
| Row checkbox | Ticked. Leave every other row empty and unticked. |
| SPI SPEED, SPI MODE | Leave as the tool shows them, greyed out. |
| COM | Click the arrow at the right of the COM box and choose the board's port from the list, for example COM5. If you type it instead, enter the full name including COM. |
| BAUD | 921600 |
Click START. The status box shows Download while the progress bar fills, and changes to a green FINISH when the image has been written and verified. This takes well under a minute.
Flashing this image clears any settings you have saved on the board, including Wi-Fi credentials and saved presets, and the board starts again with its default configuration. Recordings stored in the board's audio area are not touched.
The chip stays in download mode after the tool finishes, so press SW1 (RESET) once, or slide SW8 to the right and back to the left. Close the Flash Download Tool as well, so it lets go of the port. A few seconds later the board is running its new firmware, and you can continue with connecting to its console below.
esptool is Espressif's command line flashing tool and is written in Python. Open the Terminal app and check that Python 3 is available with python3 --version. If macOS offers to install the command line developer tools instead, accept, wait for it to finish, and run the command again.
Then install esptool into a small private Python environment of its own, which keeps it separate from anything else on your Mac:
python3 -m venv ~/esptool-env ~/esptool-env/bin/python -m pip install esptool
Make sure the slide switch SW8 on the bottom edge of the board is to the left, which is on. Connect the USB-C cable, then press and hold SW2 (BOOT), press and release SW1 (RESET), and release SW2. Both buttons sit immediately to the left of the metal WROOM module. If the board is already running RadioSonic firmware, typing bootloader in its console does the same thing without the buttons.
You will not see an LED signal that download mode has started. In download mode the RadioSonic firmware is not running, so nothing updates the LEDs: the four RGB LEDs freeze on whatever they were showing at the moment of the reset, or usually stay dark if the board has only just been plugged in, and the small heartbeat LED stops blinking. This frozen look is normal and does not mean the board has crashed. The reliable sign that it worked is the board's serial port appearing on the computer, as described next.
Find the board's serial port by listing the USB modem devices:
ls /dev/cu.usbmodem*
If more than one device is listed, unplug the board, run the command again, and the one that disappeared is the board. Plug it back in and repeat the button sequence before continuing.
Change to the folder that holds the firmware file, which is usually Downloads, and run the command below, replacing /dev/cu.usbmodemXXXX with the device you found in step 3:
cd ~/Downloads ~/esptool-env/bin/python -m esptool --chip esp32s3 -p /dev/cu.usbmodemXXXX -b 921600 write_flash 0x0 RadioSonic_RevA_0.9.1-107-ge4282e5.bin
Recent versions of esptool print a warning that write_flash has been renamed write-flash. It is harmless, and the older spelling is used here because it works with every version. The write takes well under a minute and ends with Hash of data verified and Hard resetting, at which point the board restarts by itself. If it does not, press SW1 (RESET). Then continue with connecting to its console below.
Flashing this image clears any settings you have saved on the board, including Wi-Fi credentials and saved presets, and the board starts again with its default configuration. Recordings stored in the board's audio area are not touched.
esptool is Espressif's command line flashing tool and is written in Python. Install it into a small private Python environment of its own, which keeps it separate from your system's Python packages. On Debian and Ubuntu the first line installs the venv module, which those distributions ship separately:
sudo apt install python3-venv python3 -m venv ~/esptool-env ~/esptool-env/bin/python -m pip install esptool
Most distributions only let members of a particular group open serial ports. On Debian, Ubuntu and Fedora that group is dialout, and on Arch it is uucp. Add yourself to it, then log out and back in so the change takes effect:
sudo usermod -aG dialout $USER
Make sure the slide switch SW8 on the bottom edge of the board is to the left, which is on. Connect the USB-C cable, then press and hold SW2 (BOOT), press and release SW1 (RESET), and release SW2. Both buttons sit immediately to the left of the metal WROOM module. If the board is already running RadioSonic firmware, typing bootloader in its console does the same thing without the buttons.
You will not see an LED signal that download mode has started. In download mode the RadioSonic firmware is not running, so nothing updates the LEDs: the four RGB LEDs freeze on whatever they were showing at the moment of the reset, or usually stay dark if the board has only just been plugged in, and the small heartbeat LED stops blinking. This frozen look is normal and does not mean the board has crashed. The reliable sign that it worked is the board's serial port appearing on the computer, as described next.
Find the board's serial port:
ls /dev/ttyACM*
The board is usually /dev/ttyACM0. If more than one device is listed, unplug the board, run the command again, and the one that disappeared is the board. Plug it back in and repeat the button sequence before continuing.
Change to the folder that holds the firmware file, which is usually Downloads, and run the command below, replacing /dev/ttyACM0 if your board is on a different device:
cd ~/Downloads ~/esptool-env/bin/python -m esptool --chip esp32s3 -p /dev/ttyACM0 -b 921600 write_flash 0x0 RadioSonic_RevA_0.9.1-107-ge4282e5.bin
Recent versions of esptool print a warning that write_flash has been renamed write-flash. It is harmless, and the older spelling is used here because it works with every version. The write takes well under a minute and ends with Hash of data verified and Hard resetting, at which point the board restarts by itself. If it does not, press SW1 (RESET). Then continue with connecting to its console below.
Flashing this image clears any settings you have saved on the board, including Wi-Fi credentials and saved presets, and the board starts again with its default configuration. Recordings stored in the board's audio area are not touched.
Once the board has restarted with the new firmware, you can talk to it right here without installing a terminal program. Click Connect and Chrome opens a list of the RadioSonic boards plugged into your computer. Choose your board, which is listed as RadioSonic Console and is usually the only entry, and click Connect in that list. The board's welcome message and its dsp> prompt then appear in the console below.
In Firefox, the first time you click Connect it asks to install a small site permission add-on that lets sigprolabs.com reach serial devices. Choose Continue to Installation and then Add. Firefox then asks which serial port to allow, with RadioSonic Console selected in its drop-down; click Allow. The page can only use the device you allow and cannot see anything else.
| Command | What it shows |
|---|---|
ver | The firmware version, which should read 0.9.1-107-ge4282e5, the version listed in step 1. |
status | The DSP mode, input, gains, SD card, Wi-Fi and processing load. |
help | Every console command, one line each. |
Click anywhere in the console and type at the dsp> prompt, then press Enter to send the command. The up and down arrow keys step through commands you have already sent, and the quick command buttons send a command with one click. When you are finished, click Disconnect so another program can use the board.
If you feed the board's line input from your computer's headphone or line output and hear hiss or hum whenever nothing is playing, see the line input entry under If something goes wrong below.
The board's console is an ordinary USB serial port, so any terminal program works as well. It appears as a different port from the one used for flashing, so look for it again after the board restarts.
| System | How |
|---|---|
| Windows | In PuTTY or the VS Code serial monitor, open the USB Serial Device COM port listed in Device Manager under Ports (COM & LPT), at speed 115200 with flow control set to None. The console does not respond with hardware flow control turned on. |
| macOS | Find the port with ls /dev/cu.usbmodem*, then run screen /dev/cu.usbmodemYYYY 115200. |
| Linux | Find the port with ls /dev/ttyACM*, then run screen /dev/ttyACM0 115200. |
To leave screen, press Ctrl+A, then K, then Y. Only one program can hold the port at a time, so disconnect the console on this page first.
Once the board is running RadioSonic firmware you do not need the buttons to update it. Connect to its console on this page, type bootloader, and the page closes its connection by itself while the board comes back in download mode, ready to be written again exactly as before. If you use your own terminal program instead, close it after typing bootloader. The button sequence remains the dependable fallback whenever a board does not respond.
| What you see | What to do |
|---|---|
| No LEDs and no new port on the computer | Check that SW8 is to the left. Then try a different cable, since a charge-only cable powers the board but carries no data. |
| The board connects and disconnects repeatedly | The board has no valid firmware to run, so it keeps restarting. Use the button sequence from step 3, which holds it still in download mode. |
| The tool cannot connect, or stops at sync | The board is not in download mode, or another program has the port open. Close any terminal, repeat the button sequence, and try again. |
| The tool shows Chip stub error or Guru Meditation Error (IllegalInstruction) | The Flash Download Tool was opened for the wrong chip, which you can confirm in its title bar, for example ESP32C3 FLASH DOWNLOAD TOOL. It then sends the board a small loader program built for that other chip, which the board's ESP32-S3 cannot run. Close the tool, start it again, choose ChipType ESP32-S3 as in Windows step 4, put the board back in download mode and press START. |
| Linux reports Permission denied on the port | Your account is not yet in the dialout (or uucp) group, or you have not logged out and back in since adding it. See Linux step 2. |
| Flashing finishes but no new port shows up | Press SW1 (RESET). The chip stays in download mode until it is reset. |
| No board appears in Chrome's list | Make sure the board has restarted after flashing and that no other program, such as the Flash Download Tool or a terminal, still has the port open. On Linux, check the serial port group from Linux step 2. |
| The console connects but nothing appears | Click in the console and press Enter. If no dsp> prompt appears, press SW1 (RESET), wait a few seconds, then disconnect and connect again. |
| Hiss or hum on the line input when nothing is playing | Many computers power down the DAC that drives their headphone or line output whenever nothing has played for a few seconds. The output then stops actively driving the cable, so the board's line input is connected to an undriven source that picks up hum and noise, and the board's input gain amplifies it. The fix is to keep the computer's output driven: keep a sound playing, or on Windows run Sound Keeper, a free and open-source (MIT licence) utility that keeps the audio output active by playing an inaudible stream. By default it only keeps the primary output active, so if the board is connected to a different output, rename the program to SoundKeeperAll.exe and it will keep every output active. |
| Hum or buzz on the line output | Using the board's USB port and its line output on the same computer can create a ground loop, which adds hum or buzz to the line output. For the cleanest line output signal, run the board on battery with the USB cable disconnected, or connect the USB cable and the line output to different devices. |
| Sound in only one ear, or sound that seems thin or hollow | The included headphones use a 4-contact (TRRS) plug, the type common on phone headsets with a built-in microphone, while the audio jack on RadioSonic is a standard 3-contact (TRS) stereo jack, so the contacts may not line up exactly. Pull the plug back out slightly, about 1 to 2 mm, until you hear sound in both ears. |
If you are still stuck, write to info@sigprolabs.com with what the tool shows and what the LEDs are doing, and we will sort it out with you. Students enrolled in a course can also ask in the course Q&A forum.