Configuration

Configuration

The player is configured by a text file on the card and by the Settings page on the panel. The two are one store: what is written on the card is applied at boot, and what is changed on the panel is written back to the card. There is nothing to install and no app; a text editor and the card reader you already use for the music are enough.

evoconfig.txt

A file named evoconfig.txt in the root of the FAT32 card, next to the music. The player reads it on every boot. Without it, the defaults stand: Evo Default, the disc, rotation 0, volume 40.

A ready-made copy with every key and a comment on each is in the repository at sdcard/evoconfig.txt. Copy it to the card and edit the values.

The format:

• One key = value per line. Spaces around the = do not matter.
• Lines starting with # or ; are comments. There are no comments after a value: everything after the first = is the value.
• Wrap a value in "double quotes" to keep leading or trailing spaces.
• An empty value puts the setting back to its default.
• UTF-8, with or without a byte-order mark; LF or CRLF line ends. Any text editor on any system produces a file the player reads.

The keys:

Key	Values	What it does
theme	evo-default, night-sky, sunrise, air, liquid	The face's theme; see Face.
style	disc, card	The face's style: art in a ring with the progress round it, or art as a rounded square with the text over its foot.
rotation	0, 90, 180, 270	Screen rotation, degrees clockwise. 0 and 180 are portrait, 90 and 270 landscape. Applied at boot.
volume	0 to 100	The level at power-on.
name	letters, digits, hyphens; up to 30	The player's name on the network: the hostname the router is told, so its device list shows it. evo-player when not set.
wifi_ssid, wifi_password	the network's name and password	The Wi-Fi network to join, 2.4 or 5 GHz, WPA2 or WPA3; an empty password means an open network. See below.
dac	a board name from Audio out	The DAC board on the header, for a board the player cannot tell by itself (one with no I2C part, such as a PCM5102A) or to override what it found. Read and reported; acted on once the register of boards lands.
output	speaker, hat, both	Where the frames go when the board has a speaker and a DAC both. Read and reported; acted on with dac.
shuffle	on, off	The order the queue plays in: dealt, or as listed. on when not set. Also an icon on Now Playing and a row of Settings.
repeat	all, off, one	What happens at the queue's end: it starts again (a fresh deal when shuffled), it stops, or the same track plays again (a track that ends on its own; the next button always moves on). all when not set. Also an icon on Now Playing and a row of Settings.
start	a path on the card	What plays at power-on. Not set: the whole card, every file in every folder, in the order above. A folder: that folder, deep. A file: that file, with its folder round it. A playlist (.m3u, .m3u8, .pls): its stations, from the first, or from the one named after a # — start = Radio/Evo Selection.m3u#Classic FM. A station waits for the network to come up ("waiting for the network" on the status strip meanwhile). A path that is not there is reported in evostatus.txt and the card plays.
snapserver	host or host:port	The Snapcast server to play from; the port is 1704 when left out. Not set: the player looks for one on the network. See Multiroom.

A key the player does not know, a value a key cannot take, or a line with no = is ignored and reported; the rest of the file still applies.

The password is on the card in clear, as it is for the Volumio companion's card. The card stays in the player.

The network

With wifi_ssid set, the player joins the network while the music starts; nothing waits for it. A network it has joined before is found again in about three seconds (it remembers the access point's channel and identity); a new one takes a search of both bands, about fourteen seconds. Once joined, the Wi-Fi row of Settings shows the address, the band and the signal, and evostatus.txt gains a line saying the same; while joining the row says so, and if the network cannot be joined it says why. A link that drops is rejoined.

Prefer 5 GHz where the network offers it. The player takes whichever band the access point gives it, and on 2.4 GHz the status strip says so (2.4 GHz Wi-Fi, between the source and the stream), as it says weak Wi-Fi when the signal is poor on either band. Measured on the bench against the same access point: a round trip of 3 to 9 ms on 5 GHz, 25 to 125 ms on 2.4 GHz; a Snapcast stream played clean on both, but on 2.4 GHz its clock wandered by a few milliseconds where on 5 GHz it held to a fraction of one, so rooms sit less exactly together. The player's radio does not take part in the choice of band beyond the search; a network that puts the player on 2.4 GHz can be given a 5 GHz-only name for it.

The network carries internet radio (below), and the player announces itself on it as an Evo device so a multiroom group can send to it (Multiroom). The Evo id row at the bottom of Settings is the id a group adds.

Joining a network, like anything else that keeps the chip busy for a moment, does not reach the ear: the player decodes up to 600 ms ahead into a reservoir, and a task above everything else carries the audio to the DAC. A pause takes effect within about 70 ms and resumes exactly where it stopped; a seek is immediate; a track started afresh begins after a short gathering pause of a quarter second, and a track that follows another plays on without a gap.

Internet radio

Stations come from playlists on the card. A .m3u, .m3u8 or .pls file in any folder lists them; the playlist is a folder of its own in the library (Radio › Evo Selection › …), its stations in the playlist's order, and a tap plays one once the network is up. The queue is then that playlist: the next button moves to the next station (shuffle and repeat apply as set). To come up on a station at power-on, name it in start (above). The card image in the repository carries Radio/Evo Selection.m3u, a checked selection of UK stations (and Radio Paradise's FLAC streams) drawn from the open radio-browser.info directory. Edit it, or add your own files beside it:

#EXTM3U
#EXTINF:-1 tvg-logo="https://www.classicfm.com/assets_v4r/classic/img/favicon-196x196.png",Classic FM
http://media-ice.musicradio.com/ClassicFMMP3
#EXTINF:-1 tvg-logo="logos/mine.png",My Station
http://host.example/stream

Each #EXTINF line names the station on the URL line below it; a station without one is named by its host. tvg-logo (the attribute IPTV lists use) is the station's picture: a URL, or a path on the card relative to the playlist's folder; PNG (with transparency, which is composed onto the theme's background) or JPEG. A logo is set whole on a square of the background, since its width is its shape, where a cover is cropped to its centre. A station without a logo shows its name in the art square instead. .pls files take FileN= and TitleN= pairs and have no logo.

While a station plays, its name is the album line; where the server sends what is playing (Icecast and SHOUTcast metadata), the title and artist follow the songs. A line too long for its width ends in an ellipsis; a tap on the text raises the details sheet, a card over the middle of the face with the whole title, artist, station and format, and a tap anywhere puts it down (the navigation works through it; a track change puts it down by itself). Nothing on the face moves on its own. Stations have no end and no seek, and the boot's run through the card leaves them out.

What plays from the air: MP3, AAC (AAC-LC and HE-AAC, through Espressif's decoder), FLAC and Ogg Vorbis, http:// and https:// (redirects followed), as one long stream or as HLS — a playlist of short MPEG-TS segments, the way the BBC broadcasts: the player follows a master playlist to the audio variant nearest 160 kb/s from below, starts three segments behind the live edge, fetches each segment in turn and hands the audio inside to the decoder as if it were one stream. Segments in fragmented MP4 are not played; the status strip says so. An AAC station costs about 50 KB of internal SRAM while open and a third of the core, an MP3 station a fifth; the shipped list prefers a broadcaster's MP3 feed where it offers both. The BBC's national stations are in the shipped list by their stable manifests (a.files.bbci.co.uk), on the international 96 kb/s HE-AAC feeds that play anywhere; a listener in the UK can change nonuk to uk and low_sbr to high_sbr in a BBC address for the 320 kb/s AAC-LC feed.

A station that will not open stays on the face with the reason on the status strip — "Jazz24: not found (404)", "Absolut Relax: could not connect", "Radio 4: HLS in fragmented MP4 is not played" — rather than the player moving on to another station unasked; a file that will not open is passed over, as before. A connection that drops while a station plays is opened again, three times with a lengthening pause, and the music resumes where the stream is; a station that ends for good holds with "the stream ended", and Play tries it again. The stream is fetched by a thread of its own into a 512 KB ring in PSRAM, a second and a half ahead before the first note, so the decoder never waits on the network. Expect the heartbeat's internal figure to be around 20 KB lower while a station plays.

evostatus.txt

On every boot the player writes evostatus.txt next to evoconfig.txt, so a card taken back to a computer says what the player did with the file. It carries the player's version and build, what is running (theme, style, rotation, volume, how many tracks the card has), one read: line per setting the file supplied (the password shown only by its length), one line per setting that was read but not acted on by this firmware, and one line, with its line number, per entry that was ignored and why. A card with no evoconfig.txt gets a status file saying so and that the defaults apply.

Settings on the panel

The third item of the navigation (the bar along the foot in portrait, the rail on the left in landscape) is Settings: the player's facts, one a row. Rows marked with › are settings; a tap changes them, on the panel and in the file:

• Theme › steps through the five themes. The face repaints in the new one.
• Style › switches between the disc and the card. The face repaints, and the album's picture is fetched again at the new size.
• Rotation › turns a quarter clockwise. The panel is oriented when the player starts, so this writes the setting and restarts the player, which comes up turned; about three seconds.
• Shuffle › turns the shuffle on or off. On, the tracks not yet played are dealt afresh; off, the queue goes on in the listed order from the track in hand. What is playing is not interrupted.
• Repeat › steps through all, one and off.

The other rows are facts: the player and its build, the network's address, the board, and the card's size and track count. The list is longer than the page; a drag scrolls it.

Changing a setting on the panel rewrites that one line of evoconfig.txt in place. Every other line, comment and blank stays as it was written. A card with no evoconfig.txt gets one with the changed key the first time a setting is tapped.

The controls, by style

Now Playing takes touch. Where the controls are depends on the style:

	Disc	Card
Play/pause, previous, next	The three buttons under the text. Next and previous move through the queue in its order (shuffled or listed); after the queue's end, Play starts it again; on a held station, Play tries it again.	The same.
Shuffle, repeat	The two flat icons outside previous and next (portrait), or on the row under the transport (landscape): lit in the accent when on; repeat shows a 1 for repeat-one. One tap toggles shuffle, one tap steps repeat through all, one and off; the file on the card is updated. They apply to files and are not shown while a station plays.	The same.
Seek	Touch the ring around the art and lift where the track should go.	The strip with the times at its ends; drag along it.
Volume	The strip under the text in portrait, under the art in landscape; drag along it.	Its own row: under the seek strip in portrait, above it in landscape; drag along it.
Library	The second item of the navigation: the card's folders and tracks. A tap on a folder opens it, on a track plays it and makes its folder the queue from there; the chevron at the head goes up a folder; a drag scrolls. A greyed row is a track above the board's rate ceiling (see Hardware) or an AAC station.	The same.

The volume slider's and the seek strip's touch reaches extend a few pixels above and below the bar; on the landscape card, where the two rows are close, the nearer bar takes the finger.