Card setup

Card setup

The companion is configured from a microSD card. You write one text file on any computer, put the card in the slot, power the device; it reads the file on every boot, keeps what it read in its own flash, and writes a report back to the card. No console, no app, no keyboard on the screen.

What you need

• A microSD card of 32 GB or less, formatted FAT32. Cards of that size are FAT32 as sold, so a new one needs nothing. A larger card arrives as exFAT, which the device cannot read, and must be formatted FAT32 first; Windows' own formatter refuses that above 32 GB, so a smaller card is the easy path.
• A card reader on your computer, or a phone that mounts the card.
• The template file sdcard/volumio.txt from the repository (raw: open it, "Save as", keep the name volumio.txt).

The steps

1. Put the card in the reader. It shows as a drive (Windows: a letter such as E:; macOS: under Locations in Finder; Linux: under /media or /run/media).

2. Copy volumio.txt to the root of the card: the top level, not inside a folder.

3. Open it in a text editor (Windows: Notepad; macOS: TextEdit, in plain-text mode, Format > Make Plain Text; Linux: any editor) and fill in at least these three lines:

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

   The player's address is its IP address, as shown in Volumio under Settings > Network, with http:// before and :3000 after. Names ending in .local do not work here: the device has no mDNS resolver. A fourth line, name = kitchen-panel, names the device in your router's device list; without it the device is espressif. Everything else in the file is optional; the template explains each line.

4. Save. Eject the card properly (Windows: "Safely remove"; macOS: the eject arrow; Linux: unmount), then take it out.

5. Put the card in the device's slot and power the device. The screen lights within a few seconds, shows the network it joined and its address, and once the player answers, the face.

6. To see what the device made of the card, put it back in the reader and open status.txt next to volumio.txt. It names the device and its firmware, every key it applied, every line it did not understand (with the line number), and whether the network was joined and at which address. It never contains the password.

The card can stay in the device or come out: the settings live in the device's flash once read. A card left in is read again on every boot, so editing it is how you change a setting; a card taken out leaves things as they were.

The file

One key = value per line. Lines starting with # are comments. Everything after the first = is the value, spaces at both ends trimmed; there are no comments after a value, because # is a legal character in a password. A value wrapped in double quotes keeps its leading or trailing spaces. An empty value (rotation =) puts that setting back to its default. The file is UTF-8 and either Windows or Unix line endings are fine, as is the byte-order mark some Windows editors add.

Key	Value	Default
wifi_ssid	The network's name	none: the device runs without a network
wifi_password	The network's password; empty or absent for an open network	none
name	The device's name on your network, as your router's device list shows it: letters, digits and hyphens, up to 30, no spaces	espressif
player	http://ADDRESS:3000	http://volumio.local:3000, which the device cannot resolve: set it
rotation	0, 90, 180, 270 degrees clockwise	0
theme	ink, dusk, studio, night	ink
text_portrait, text_landscape	status text size, normal or large	normal
gap_portrait, gap_landscape	bar gap, tight, default, roomy	default
strip_portrait, strip_landscape	the strip, progress, stream, off	progress
poll_ms	how often to ask the player for its state, milliseconds	500
debounce_ms	the least time between two taps, milliseconds	50

Keys are case-insensitive (WIFI_SSID works). A key the device does not know is reported in status.txt and ignored; so is a line without =.

Once the device is on the network

status.txt will say which network it joined and at which address, and the screen says the same. If it says the network could not be joined, check the name and password for a typo, and that the network is 2.4 or 5 GHz Wi-Fi (both are fine) rather than something the device cannot do, such as a captive portal or an enterprise login. The password is only ever read from the card and kept in the device; once status.txt reports a join, you may delete the wifi_password line from volumio.txt if you prefer the card not to carry it.

The same file on a desktop

The simulator reads the same file, companion-sim --card volumio.txt, and prints the same complaints about unknown keys and malformed lines. It is how the format is tested before it meets a card.