BotWave - Your Raspberry Pi FM Network

Website | Install | Mentions | Wiki

BotWave lets you broadcast audio over FM radio using Raspberry Pi devices. It supports both single-device setups and multi-Pi networks, with features like remote control, live streaming, automated actions, and more, making it great for learning, experimentation, and creative projects.

Features

• Standalone Client: Run a single Raspberry Pi independently, no server needed.
• Server-Client Architecture: Manage multiple Raspberry Pi clients from a central server.
• Audio Broadcasting: Broadcast audio files over FM radio. Supports MP3, WAV, FLAC, AAC, and more. Files are converted automatically.
• File Upload: Upload audio files to clients for broadcasting.
• Remote Management: Start, stop, and manage broadcasts remotely.
• Authentication: Client-server authentication with passkeys.
• Protocol Versioning: Ensure compatibility between server and clients.
• Live Broadcasting: Stream live output from any application in real time.
• Queue System: Manage playlists and multiple audio files at once.
• Task Automation: Run commands automatically on events and start on system boot.

Requirements

All requirements can be installed automatically via the installer, see below.

Server

• Python >= 3.9

Client

• Raspberry Pi (models 2, 3, 4, or Zero. Pi 5 and Pico are not supported)
• Root access
• Python >= 3.9
• bw_custom
• (Wire or antenna connected to GPIO 4 / pin 7)

Get Started

Note

For a more detailed setup guide, check /wiki/Setup

Warning

• BotWave broadcasts FM signals, which may be regulated in your area.
• Check local laws before use. Unauthorized broadcasts may incur fines.
• Use a band-pass filter to minimize interference with other services.
• The authors are not responsible for legal issues or hardware damage.
• See FAQ for more information: /wiki/FAQ

Installation

For Linux systems (Raspberry Pi OS, Ubuntu, Fedora, Arch, etc.), we provide an install script:

curl -sSL https://botwave.dpip.lol/install | sudo bash

If you'd like to review the script before running it:

curl -sSL https://botwave.dpip.lol/install -o bw_install.sh
cat bw_install.sh
sudo bash bw_install.sh

sudo is required for system-wide installation. BotWave installs to /opt/BotWave with binary symlinks in /usr/local/bin.

During installation, you'll be asked a few questions:

• Installation type: If you have a single Raspberry Pi, choose Client. If you also want to run a server on the same machine, choose Both. Other devices will only be able to run the Server.
• ALSA loopback card: This is only needed if you plan to do live broadcasting (streaming audio in real time). If you're just playing audio files, you can skip it. You can always enable it later with --alsa.

Usage: curl -sSL https://botwave.dpip.lol/install | sudo bash [-s -- [MODE] [OPTIONS]]
Modes:
client              Install client components
server              Install server components
both                Install both client and server components
Options:
-l, --latest        Install from the latest commit (even if unreleased)
-t, --to <version>  Install a specific release version
-b, --branch <name> Install from a specific branch (default: main)
--[no-]alsa         Setup ALSA loopback card
-h, --help          Show this help message

Tip

Not sure which mode to pick?

• One Raspberry Pi: use the Local Client (no server needed). Jump to Using The Local Client.
• Multiple Raspberry Pis: use the Client-Server setup. Jump to Using The Client-Server.

Using The Local Client (Single Pi)

The local client runs entirely on one Raspberry Pi. So no server or second machine required. This is the recommended starting point if you're new to BotWave.

1. Starting the local client

sudo bw-local

usage: bw-local [-h] [--upload-dir UPLOAD_DIR]
                [--handlers-dir HANDLERS_DIR]
                [--skip-checks | --no-skip-checks]
                [--daemon | --no-daemon] [--rc RC]
                [--pk PK] [--talk | --no-talk]
BotWave Standalone CLI Client
options:
-h, --help            show this help message and exit
--upload-dir UPLOAD_DIR
Directory to store uploaded files
--handlers-dir HANDLERS_DIR
Directory to retrieve l_ handlers from
--skip-checks, --no-skip-checks
Skip system requirements checks
--daemon, --no-daemon
Run in daemon mode (non-interactive)
--rc RC               Remote CLI port for remote management
--pk PK               Optional passkey for WebSocket
authentication
--talk, --no-talk     Show output logs
--config CONFIG       Path to a config file to load into environment

Hardware setup

---

To broadcast, connect a wire or antenna to GPIO 4 (pin 7) on your Raspberry Pi. Even a short bare wire improves range significantly over nothing.

---

2. Understanding the local client command line interface

The local client has a CLI to manage it. Type help for a list of all available commands.

3. Getting audio files onto the local client

BotWave supports most common audio formats (MP3, WAV, FLAC, AAC, OGG, and more). Files are converted to WAV automatically when needed.

You have two options to get files onto your Pi:

Option A: Download a file from a URL:

botwave> dl https://cdn.douxx.tech/files/ss.wav

Option B: Upload a file already on the Pi's filesystem:

Note

If you need to transfer a file from your personal computer to the Pi first, use scp from your computer:

scp mysong.mp3 pi@<pi-ip-address>:/home/pi/

Then inside BotWave:

botwave> upload /home/pi/mysong.mp3        # a single file

botwave> upload /home/pi/music/            # every supported file in a folder

4. Starting a broadcast

botwave> start ss.wav 88    # broadcasts ss.wav at 88 MHz

5. Stopping a broadcast

botwave> stop

6. Exiting properly

botwave> exit    # cleans up and exits

Using The Client-Server (Multiple Pis)

This setup lets you manage a network of Raspberry Pis from a central server. It assumes you have one machine with the server component installed and at least one Raspberry Pi with the client component installed, both on the same network.

1. Connect the client and the server together

Start the server on your server machine:

bw-server

usage: bw-server [-h] [--host HOST] [--port PORT] [--fport FPORT]
                 [--pk PK] [--handlers-dir HANDLERS_DIR]
                 [--start-asap | --no-start-asap]
                 [--skip-checks | --no-skip-checks]
                 [--rc RC] [--daemon | --no-daemon]
BotWave Server
options:
-h, --help            show this help message and exit
--host HOST           Server host
--port PORT           Server port
--fport FPORT         File transfer (HTTP) port
--pk PK               Passkey for authentication
--handlers-dir HANDLERS_DIR
Directory to retrieve s_ handlers from
--start-asap, --no-start-asap
Start broadcasts immediately (may cause
client desync)
--skip-checks, --no-skip-checks
Skip system requirements checks
--rc RC               Remote CLI port for remote management
--config CONFIG       Path to a config file to load into environment
--daemon, --no-daemon
Run in non-interactive daemon mode

Then, on the Raspberry Pi, connect it to the server:

If you don't know your server's IP address, run < hostname -I in the BotWave shell.

sudo bw-client 192.168.1.10    # replace with your server's IP

sudo is required to access Raspberry Pi hardware.

usage: bw-client [-h] [--port PORT] [--fhost FHOST]
                 [--fport FPORT] [--upload-dir UPLOAD_DIR]
                 [--pk PK] [--skip-checks | --no-skip-checks]
                 [--talk | --no-talk]
                 [server_host]
positional arguments:
server_host           Server hostname/IP
options:
-h, --help            show this help message and exit
--port PORT           Server port
--fhost FHOST         File transfer server hostname/IP
(defaults to server_host)
--fport FPORT         File transfer (HTTP) port
--upload-dir UPLOAD_DIR
Uploads directory
--pk PK               Passkey for authentication
--skip-checks, --no-skip-checks
Skip update and requirements checks
--talk, --no-talk     Makes PiWave (broadcast manager) output
logs visible.
--config CONFIG       Path to a config file to load into environment

Hardware setup

---

To broadcast, connect a wire or antenna to GPIO 4 (pin 7) on your Raspberry Pi. Even a short bare wire improves range significantly over nothing.

---

If the connection succeeds, you'll see a message confirming that <pi-hostname>_<pi-ip> has connected.

2. Understanding the server command line interface

The server has a CLI to manage it. Type help for a list of all available commands.

When targeting clients, you can use:

• The client ID: raspberry_192.168.1.11
• The client hostname: raspberry
• Multiple clients: raspberry,raspberry2
• All connected clients: all

3. Uploading files to the client

BotWave supports most common audio formats (MP3, WAV, FLAC, AAC, OGG, and more). Files are converted automatically when needed.

Option A: Upload a file stored on the server machine:

botwave> upload all /home/server/Downloads/ss.wav       # a single file

botwave> upload all /home/server/Downloads/bw_files/    # every supported file in a folder

Option B: Have the client download from a URL directly:

botwave> dl all https://cdn.douxx.tech/files/ss.wav

4. Starting a broadcast

botwave> start all ss.wav 88    # broadcasts ss.wav at 88 MHz to all clients

5. Stopping a broadcast

botwave> stop all

6. Exiting properly

botwave> exit    # kicks all clients and shuts down the server cleanly

Remote Management

BotWave lets you manage your server or local client remotely via WebSocket. We recommend using BWSC for this.

1. Install BWSC

npm i -g bwsc

2. Enable remote access on your server or local client

Add the --rc flag when starting BotWave. A passkey is strongly recommended if exposed to the internet:

bw-server --rc 9939 --pk 1234       # for the server component

bw-local --rc 9939 --pk 1234        # for the local client component

If you add a passkey to the server, also pass it to connecting clients: sudo bw-client <server-ip> --pk <passkey>

3. Connect remotely

bwsc 192.168.1.10 1234    # replace with your server IP and passkey

4. Manage remotely

You'll now have access to the full server or local client CLI remotely. Note that the <, |, and exit commands are not available via remote shell.

botwave> help

Advanced Usage

For more detailed documentation, check the following resources:

• Server help: /server/server.md
• Client help: /client/client.md
• Local client help: /local/local.md
• AutoRun help: /autorun/autorun.md
• Automated actions: Main/Automate Your Setup
• Remote management: Main/Connecting remotely

Updating BotWave

sudo bw-update

Uninstallation

curl -sSL https://botwave.dpip.lol/uninstall | sudo bash

Warning

This will delete /opt/BotWave/. Back up any important files (handlers, uploads) before uninstalling.

BotWave Server For Cloud Instances

You can try the BotWave server directly on cloud platforms:

Get Help

Got a question or an issue?

• Open an issue
• Join the Discord

Mentions

BotWave mentions: Here are some posts/websites that talk about BotWave. Thanks to their creators!

Supports

BotWave is supported by donations from the following people and projects. Your contributions help with development, hosting, and hardware costs 🙏

License

BotWave is licensed under GPLv3.0.

Credits