Install

Install

From nothing to the player's face on the panel. No toolchain, no code; one program on your computer, one file on the board, one text file on a card.

What you need

• A Waveshare ESP32-C5-Touch-LCD-2.8 and a USB-C cable that carries data (some charge-only cables do not).
• A microSD card of 32 GB or less, as sold (FAT32). Anything larger must be formatted FAT32 first; a small card is the easy path.
• A computer with Windows, macOS or Linux, and a card reader.
• A Volumio player on the same Wi-Fi, and its IP address (Volumio: Settings > Network).

1. Download two files

From the latest release, under Assets:

Download	What it is
volumio-esp-companion-waveshare-esp32-c5-touch-lcd-28-X.Y.Z.bin	The firmware. One file, the whole image.
volumio.txt	The card template you will edit in step 4.

Ignore the rest: SHA256SUMS is for checking downloads, and the two "Source code" archives are the code, not something to flash.

2. Get esptool

esptool is Espressif's own flashing program. One of these, whichever suits you:

• No Python on your machine: download the standalone program for your OS from esptool's releases (esptool-vX-windows-amd64.zip, esptool-vX-macos-arm64.tar.gz for Apple silicon or -macos-amd64 for Intel, esptool-vX-linux-amd64.tar.gz), unpack it, and run it from that folder.
• Windows with Python: py -m pip install esptool
• macOS or Linux with Python: pip3 install esptool (or pipx install esptool)

Any esptool 5 works. If yours is version 4 (esptool.py version), the command in step 3 is esptool.py ... write_flash with an underscore.

3. Flash

1. Plug the board into the computer by USB-C. No driver is needed.

2. Find the port:

   • Windows: Device Manager > Ports (COM & LPT): USB Serial Device (COM5) or similar. The port is COM5.
   • macOS: in Terminal, ls /dev/cu.usbmodem*. The port is the name it prints.
   • Linux: ls /dev/ttyACM*. The port is /dev/ttyACM0 or similar. If flashing says permission denied, add yourself to the dialout group and log in again, or run the command with sudo.

3. In a terminal (Windows: PowerShell or Command Prompt), in the folder where you saved the download, with your port in place of PORT and the version you downloaded in place of X.Y.Z:

   esptool --chip esp32c5 --port PORT write-flash 0x0 volumio-esp-companion-waveshare-esp32-c5-touch-lcd-28-X.Y.Z.bin
   

   It takes about half a minute and ends with Hash of data verified. and Hard resetting via RTS pin.... The board restarts and after about twenty seconds shows a status page saying it has no network yet. That is right: step 4 gives it one.

If esptool says it cannot connect: unplug the board, hold its BOOT button, plug it in while holding, release, and run the command again.

4. Write the card

1. Put the microSD card in your computer's reader. Copy volumio.txt to the card's top level (not inside a folder).

2. Open it in a text editor (Windows: Notepad; macOS: TextEdit; Linux: anything) and fill in these three lines; leave the rest as it is or read the comments:

   wifi_ssid = Your Network
   wifi_password = your password
   player = http://192.168.1.50:3000
   

   player is your Volumio's IP address with http:// in front and :3000 behind. Not volumio.local: the panel cannot resolve that name.

3. Save, eject the card properly, take it out.

Every line and every option is explained on Card setup.

5. Power on

Put the card in the slot on the board and power it (the same USB-C port, from the computer or any USB charger).

• Within about twenty seconds the screen lights and shows the network it joined and its address.
• As soon as the player answers, the face: what is playing, the cover, the progress. Tap and swipe work from here.
• Every boot after this one takes about seven seconds.

If the screen says it is waiting for the network or the player, take the card out, put it in the reader and open status.txt next to volumio.txt: it says what the panel read, whether it joined, and which lines it did not understand. Fix volumio.txt, put the card back, power the board again.

The card can stay in. The panel keeps the settings in its own memory, so it also works without the card once it has read it.

Updating

Download the new .bin, run the same command from step 3. The settings are cleared by a full flash; with the card in, they are back on the next boot.

Checking a download

Optional. SHA256SUMS from the release lists the checksum of the firmware file; sha256sum -c on Linux and macOS (shasum -a 256 -c), or certutil -hashfile FILE SHA256 on Windows and compare by eye.