Build Specs & Requirements

radio > requirements

Let's Get On The Same Page

This is the official reference for anyone building, contributing to, or modifying the Vintage Radio project. It covers how the radio is expected to behave and what the Music Manager app needs to do. If you're writing code, designing hardware, or building your first radio, start here.

Version 1

Vintage Radio Firmware — V1 Behavior Specs

Version 1 · Jan 2026 · For makers and contributors

Core Experience

Design anchor

Built for gifting to a non-technical parent. The radio should be immediately understandable with no instructions required.

Priorities: simplicity, predictability, reliability
Turn the knob and music starts. That's it.

Power

Power source

AC only. No battery support in V1. The PCB may support future battery integration but it is not active in this version.

Power-on behavior

When the radio is powered on it plays an AM-style startup sound lasting 1 to 3 seconds, then begins playback automatically.

Playback

Soft off

If the radio is turned off softly via the knob and power is not fully lost, it resumes from the last track on next power-on.

Full power loss

If power is completely lost and restored, the radio always starts from Album 1, Track 1.

Album behavior

The current album loops indefinitely. Albums only change via user action, never automatically.

Controls

Knob

The knob controls both power and volume in one control.

Full counterclockwise = instant off, no fade
Turning right increases volume and powers on

Top button

A single button on top of the radio controls track and album navigation.

1 press = next track
2 presses = previous track
3 presses = restart current album
Long hold = next album

Input stability

All button input is ignored during transitions. The radio will not respond to presses while an AM transition sound is playing.

Audio Feedback

AM-style sound

An AM tuning sound plays in two situations only: on startup, and when switching albums. No other UI sounds exist.

Album transitions

When switching albums, the transition takes 1 to 2 seconds total with a smooth fade into the next album.

LED

Single front LED

One LED on the front of the radio indicates power state only.

On = radio is powered
Off = radio is off
No blinking under any condition

Operation

Fully offline

The radio operates with no internet connection, no WiFi, no Bluetooth, and no companion app of any kind.

Error handling

If no SD card is present, the radio plays no sound. There are no error indicators, lights, or sounds to signal a problem.

Firmware

Update policy

End users never update firmware. Makers may update firmware before gifting the radio. V1 is stable and fixed once released.

Non-Goals for V1

WiFi / streaming
No internet connectivity of any kind.

Bluetooth
No wireless audio or control.

Voice assistant
No voice control or smart speaker features.

Screen
No display of any kind.

Shuffle
Tracks always play in order.

Settings
No user-accessible settings or configuration.

Battery
AC power only in V1.

Music Manager App — V1 Requirements

Version 1.1 · April 2026 · For makers and contributors

Overview

Purpose

A desktop app for makers building My Vintage Radios. It does exactly two things: flash firmware onto the RP2040-Zero, and prepare an SD card with music stations. Everything else is out of scope.

Audience

Discord community makers, gift builders, and licensed sellers. Assumed to be intermediate, comfortable with basic maker tools, but not developers. The app should require no technical knowledge to operate.

Platform support

Mac, Windows, and Linux.

Libraries

L1 — Named, saveable libraries

A library holds a complete set of stations and tracks for one radio build. Makers can create, rename, and switch between multiple saved libraries so they never have to rebuild a station lineup from scratch.

Libraries listed in a dropdown at the top of the app
Makers can create, rename, or delete a library
Example use: "Mom's Radio", "Dad's Radio", "Holiday Edition"
Libraries persist between app sessions

Tab 1 — Microprocessor

M1 — Auto-detect RP2040-Zero

When the maker plugs an RP2040-Zero in via USB, the app detects it automatically and shows a clear connected state. No manual port selection required in the normal flow.

Detection happens passively, no button press needed
Show device name and connection status clearly
If multiple devices are detected, prompt the maker to choose

M2 — Firmware selection

Maker chooses which firmware version to flash from a short curated list of named releases, or points to a local file on their computer.

List shows named versions (e.g. V1, V1.1, V2 beta) with a short description
Latest stable release is selected by default
Option to browse for a local .uf2 or firmware file
List is maintainable without requiring an app update if possible

M3 — Confirmation before flashing ⚠ Safety

Before any flash operation begins, the app shows a confirmation dialog that clearly identifies the target device and requires the maker to explicitly approve.

Dialog shows: device name, detected device ID or serial, and firmware version being written
Warning copy reads: "This will overwrite everything on this device. Make sure this is your RP2040-Zero."
Confirmation requires clicking a clearly labeled button, not just dismissing a dialog
If the device does not look like an RP2040-Zero, show a stronger warning and require the maker to type "flash" to proceed
Cancel is always the default and most prominent option

M4 — Flash with step-by-step feedback

Once confirmed, the app walks the maker through each step with plain-language status messages. No silent spinners.

Steps shown in sequence: preparing, writing, verifying, complete
Each step uses plain language, not technical jargon
If flashing fails, show a clear error message with a suggested fix
No warning shown if firmware is already present, just flash after confirmation

Tab 2 — SD Card

S1 — Auto-detect SD card

When a maker inserts an SD card via reader, the app detects it and shows it as the sync target. No manual path selection in the normal flow.

Detection is passive, no button press needed
Show card name, total size, and free space
If multiple removable drives are present, prompt to choose, never auto-select

S2 — Drive identity verification before sync ⚠ Safety

Before syncing, the app takes active steps to verify the selected drive is actually a radio SD card and not an unrelated drive on the maker's computer.

App only lists removable drives as valid sync targets, internal drives are never shown
If the selected drive is larger than a reasonable SD card threshold (e.g. 64 GB), show an extra warning
If the drive contains no recognizable radio folder structure, warn the maker it may not be a radio SD card
Confirmation dialog shows: drive name, mount path, total size, and a summary of what will be deleted and written
Warning copy reads: "This will erase everything on [Drive Name] and replace it with your stations. This cannot be undone."
Confirmation requires clicking a clearly labeled button, cancel is always the default
Never proceed if the drive cannot be positively identified as removable

S3 — Station management

Makers create stations by giving them a name. Each station becomes one album on the radio.

Create a station with just a name, no other fields required
Rename or delete existing stations
Station order determines album order on the radio, reorder by dragging

S4 — Adding tracks to a station

Makers add music by dragging files in or using a file picker. Any common audio format is accepted, the app converts automatically at sync time.

Drag and drop audio files onto a station, or use a file picker
Accepted: any common audio format (MP3, WAV, FLAC, AAC, etc.)
App converts to DFPlayer-compatible format automatically on sync
Track order within a station is set by dragging

S5 — Sync to SD card

After confirmation passes, one button syncs everything. Full replace every time. Conversion happens at sync time.

Validates before syncing: warns if any station is empty or has no tracks
Shows progress during conversion and writing
Shows a clear success or failure message when complete, including a summary of what was written
Offers a "safely eject" option after a successful sync

Advanced / Debug Tools

A1 — Hidden by default

All advanced and debug features are hidden from the main UI. Accessible via a clearly labeled toggle or menu item.

Console output, raw serial commands, EQ settings, and manual port selection are all advanced
Toggle lives in a menu bar item or a small "Advanced" link at the bottom of each tab
Advanced mode resets to hidden on every app relaunch

Support the Project?

This project exists because of hours of testing, failed prints, redesigns, and revisions. If you’ve found it useful and want to support future mounts, PCBs, and new designs, you can contribute here. Every spool helps! 🥰

🧵 Buy Me Some Filament

Let's Stay Connected

This project is evolving. When I release new mounts, updated files, PCB revisions, hardware improvements, firmware changes, or entirely new designs, you’ll hear about it first. I’ll also share builder showcases and practical updates that make the radio easier and better to build. No noise. Just relevant information for people actually working on the project. You can unsubscribe anytime.