Venue Commander — BT Esparagus

When to Use BT Esparagus

Venue Commander has two ways to get Bluetooth audio into a rig:

Built-in Audio Board — a small companion board next to the touchscreen, connected by a short cable. One physical box, one configuration. Use this by default.
External BT Esparagus — a standalone Sonocotta board, controlled over the network. Use this when audio needs to live somewhere the touchscreen doesn't — e.g. a backstage receiver fed into FOH, or multiple receivers driven by one touchscreen, or when you already have an Esparagus board on the shelf.

The two are not mutually exclusive: you can have a built-in audio board and one or more Esparagus receivers, all controlled from the same touchscreen.

What BT Esparagus Provides

Bluetooth audio receiver — music playback with transport and volume
High-quality stereo line-level output
Own web UI — 5-tab interface for status, paired devices, WiFi, config, and firmware updates
OSC control — volume, playback, kick, show mode, all reachable from Venue Commander
Show Mode — lock to a single Bluetooth device for the duration of a show
Device access control — allow/deny per paired device, temporary block, friendly names

Hardware

Esparagus HiFi MediaLink

Power	5 V USB-C
Audio output	3.5 mm line out or header pins
Network	WiFi (2.4 GHz)

What You Need

An Esparagus HiFi MediaLink board from Sonocotta
USB-C cable for power and initial setup
Audio cable (3.5 mm or header) to your amplifier or PA

Loading Firmware

The Esparagus board needs its own custom firmware loaded the first time. Follow the BT Esparagus project's setup instructions to build and load it — it's a separate, developer-oriented process that requires a computer with the ESP-IDF development environment.

Once the firmware is loaded and the board is on your WiFi network, you don't need to touch any of that again. All subsequent updates can be applied wirelessly through the Esparagus board's own web UI.

First Boot

On first power-up (or after a factory reset), the device has no WiFi credentials and starts in Access Point mode.

Default AP Credentials

Network (SSID)	`BT-Esparagus-XXXX` — the last 4 characters are from the device's MAC address
Password	`esparagus`
Setup URL	`http://192.168.4.1`

Connect your phone or laptop to the BT-Esparagus-XXXX WiFi network using password esparagus.
Open a browser and navigate to http://192.168.4.1.
You'll see the BT Esparagus web UI. Go to the WiFi tab to connect to your venue network.

Auto-Generated Secrets

On first boot, the device automatically generates two credentials:

API Key	32-character key required for all REST API calls. Visible in the Config tab. Used by HTTP integrations — not needed for Venue Commander (which uses OSC).
OSC PIN	4-digit numeric code used by Venue Commander for OSC authentication. Visible in the Config tab. You'll need this when setting up the endpoint in Venue Commander.

Tab WiFi Setup

📷 Screenshot: BT Esparagus WiFi tab Network scanner with signal-strength bars, available networks list, and connect form (SSID, password, optional static IP fields), with Save & Reboot button.

In the web UI, tap the WiFi tab.
Tap Scan to search for nearby networks.
Tap a network name to auto-fill the SSID field, or type it manually.
Enter the WiFi password.
Tap Save & Reboot. The device will reboot and connect to your network.

WiFi scanning is disabled while a Bluetooth device is connected (shared radio). Disconnect the BT device first if you need to scan.

After rebooting, find the device's new IP address from your router's DHCP table or the serial monitor output. The device also registers via mDNS as <device-name>.local for ~60 seconds after boot, then stops to reduce radio contention with BT audio.

Tab Configuration

📷 Screenshot: BT Esparagus Config tab Config tab with Device Name, BT Exclusive toggle, API key (read-only) with regenerate, OSC port and PIN, web password field, Reboot and Factory Reset buttons.

Once connected to your WiFi, navigate to the device's IP in a browser and open the Config tab.

Device Settings

Device Name	Friendly name shown in the web UI header, mDNS hostname, and pushed via OSC `/device_name`.
BT Exclusive	When enabled, the device hides from new Bluetooth devices while streaming audio. Existing connections are unaffected.

API Key

A 32-character key auto-generated on first boot. Required as an X-API-Key header for all REST API calls. You can regenerate it if compromised — existing integrations will need the new key.

The API key is for the HTTP REST API only. Venue Commander uses OSC (UDP), which authenticates with the separate 4-digit OSC PIN.

OSC Settings

Port	UDP port for the OSC server. Default: `9000`. Changing this requires a reboot.
PIN	4-digit authentication code for OSC clients. Auto-generated on first boot. Note this value — you'll enter it in Venue Commander's endpoint configuration.

Web Password

Optional HTTP Basic Auth password for the web UI. Leave blank to allow access without login. Username is always admin.

System

Reboot — restarts the device.
Factory Reset — erases all settings (WiFi, name, API key, paired devices, OSC PIN) and reboots. Requires double confirmation.

Factory Reset cannot be undone. All paired devices will need to “Forget” this speaker and re-pair from scratch.

Venue Commander Setup

Once your BT Esparagus is on the network and you've noted the OSC PIN from the Config tab, set it up as an endpoint in Venue Commander.

1. Add the Endpoint

📷 Screenshot: Venue Commander Devices tab with BT Esparagus device Endpoint card with the BT Esparagus preset applied — transport OSC, port 9000, heartbeat /thump at 5 s, value feedback enabled, PIN address /auth, and a 4-digit PIN entered.

Open the Venue Commander web UI and go to the Devices tab.
Click + Add Device.
Set Device Preset to BT Esparagus. This auto-fills the recommended settings.
Enter the Esparagus board's IP address.
Enter the 4-digit OSC PIN from the BT Esparagus Config tab.
Click Save & Restart.

Preset Values (auto-filled)

Transport	OSC
Port	`9000`
Heartbeat Probe	`/thump`
Heartbeat Interval	5 seconds
Value Feedback	Enabled
PIN Address	`/auth`

The BT Esparagus preset uses a more lenient liveness check. The Esparagus board runs WiFi and Bluetooth on the same chip, so the occasional network message gets dropped during active audio streaming. The relaxed check avoids false “dead” warnings during a show.

2. Add Widgets

Switch to the Layout tab and add widgets for the BT Esparagus endpoint. Use the BT Esparagus widget presets for quick setup. Available presets:

Preset	Type	Description
Volume	Fader	Bluetooth volume control (0–100), syncs with the phone in both directions
Now Playing	Info	Shows current track title, artist, and album
Device Name	Info	Shows the connected Bluetooth device's friendly name
Play/Pause	Toggle Button	Stateful play/pause
Kick	Button	Disconnect the current Bluetooth device

3. Verify

After saving, check the Venue Commander Status tab. The BT Esparagus endpoint should show as alive (green indicator).
If it shows as dead, verify the IP address and OSC PIN are correct.
Pair a phone to the BT Esparagus via Bluetooth and start playing music. The Now Playing and Device Name info widgets should update in real time on the touchscreen.
Move the volume fader — the phone's volume should change. Adjusting volume on the phone should move the fader on the touchscreen.

BT Esparagus Web UI Reference

The BT Esparagus web UI has 5 tabs. All status updates push in real time — you never need to refresh. This is the Esparagus board's own web UI, separate from Venue Commander's; you only need it for initial setup, firmware updates, and device-side management.

Tab Status

📷 Screenshot: BT Esparagus Status tab Playback controls (prev/play-pause/next), now-playing metadata, device info card, show-mode toggle with countdown, BT volume slider, output-level slider.

Playback	Prev / Play-Pause / Next buttons. Track title, artist, and album from the connected device. Only visible when a Bluetooth device is connected.
Device	Device name, Bluetooth connection status, connected device name, audio state (playing / paused / stopped), and signal strength.
Show Mode	Lock to the current Bluetooth device for a configurable duration (default 5 hours). While active, all other connections are rejected and kick/unpair controls are disabled. Only visible when a Bluetooth device is connected.
Volume	Bluetooth volume slider (0–100). Syncs with the phone in both directions.
Output Level	Master output level slider (0–100, default 70). Local to the Esparagus board only — doesn't affect the phone. Reduce if audio is distorted or clipping.

Tab Devices

📷 Screenshot: BT Esparagus Devices tab Paired devices list with allow/deny checkbox, friendly-name input, Connect / Kick / Kick 10 min / Unpair buttons per row, and an Unpair All button.

Allow checkbox	Enable or disable a paired device. Denied devices cannot connect.
Friendly name	User-assigned label for each device (e.g. “Stage Manager iPhone”).
Connect	Initiate an outbound connection to a previously paired device.
Kick	Disconnect the currently connected device immediately.
Kick 10min	Disconnect and temporarily block reconnection for 10 minutes. The block clears on reboot.
Unpair	Remove the device from the paired list. Both sides need to re-pair from scratch.
Unpair All	Remove all paired devices. Requires confirmation.

During Show Mode, kick/unpair controls and the allow checkbox are disabled to prevent accidental disconnection.

Tab WiFi

See WiFi Setup above.

Tab Config

See Configuration above.

Tab Update

📷 Screenshot: BT Esparagus Update tab Firmware file upload form with OTA progress bar.

Upload a .bin firmware file to update the Esparagus board wirelessly. The device reboots automatically after a successful upload. If the new firmware fails to boot, the device falls back to the previous version automatically.

OSC Reference

The Esparagus OSC server listens on UDP port 9000 (configurable). All commands require authentication via the 4-digit PIN.

Authentication

Send /auth <PIN> (string argument) to authenticate. The device replies /auth 1 on success or /auth 0 on failure. Sessions expire after 60 seconds of inactivity. Up to 4 concurrent clients.

If any message arrives from an unauthenticated client, the device replies /auth 0. Venue Commander uses this signal to automatically re-authenticate when a session expires (common during BT audio streaming due to WiFi/BT radio coexistence).

Commands (Client → Device)

Address	Args	Description
/auth	string: PIN	Authenticate with 4-digit PIN
/thump	none	Heartbeat — device echoes back
/volume	int: 0–100	Set Bluetooth volume (syncs to phone)
/kick	none	Disconnect current Bluetooth device (blocked while in show mode)
/kick_temp	int: seconds	Kick + block reconnection for N seconds (default 600)
/unpair_all	none	Unpair all paired devices
/playback	string: play, pause, next, prev	Playback control
/show_mode	int: minutes (0 = off)	Lock to current device for a show

State Push (Device → Client)

On any state change, the device pushes updates to all authenticated clients:

Address	Type	Value
/volume	int	Current volume (0–100)
/bt_connected	string	`Connected` or `Not connected`
/audio_state	string	`playing`, `paused`, or `stopped`
/device_name	string	Connected device friendly name (or BT name)
/now_playing	string	`Title\nArtist\nAlbum` (newline-separated)
/show_mode	int	`1` (active) or `0` (off)

Queries

Send any state address with no arguments to query the current value (e.g. send bare /volume to get the current volume back). This matches the Wing/XM32 convention.

/kick and /unpair_all are bare commands, not queries — sending them without args executes them.