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.10

Client

• Raspberry Pi (models 2, 3, 4, or Zero. Pi 5 and Pico are not supported)
• Root access
• Python >= 3.10
• 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.

Or, alternatively, you can install BotWave manually following our guide at Advanced/Installing BotWave manually.

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] [--config CONFIG]
                [-v]

BotWave Local 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 remote management authentication
  --talk, --no-talk     Show debug logs
  --config CONFIG       Path to a config file to load into environment
  -v, --version         Display version information

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]
                 [--talk | --no-talk] [--config CONFIG]
                 [--daemon | --no-daemon] [-v]

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
  --talk, --no-talk     Show debug logs
  --config CONFIG       Path to a config file to load into environment
  --daemon, --no-daemon
                        Run in non-interactive daemon mode
  -v, --version         Display version information

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]
                 [--config CONFIG] [-v]
                 [server_host]

BotWave Client

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     Show debug logs
  --config CONFIG       Path to a config file to load into environment
  -v, --version         Display version information

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 MyPass       # for the server component

bw-local --rc 9939 --pk MyPass        # 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:9939 MyPass    # 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:

• Full wiki (mirrored, for offline/agent use): /wiki
• 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

Usage: bw-update [OPTIONS]

Options:
  -l, --latest        Update to the latest commit (even if unreleased)
  -t, --to <version>  Update to a specific release version
  -b, --branch <name> Install from a specific branch (default: main)
  -h, --help          Show this help message

Examples:
  bash                    # Update to latest release
  bash --latest           # Update to latest commit
  bash --to v1.0.0-oak

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