Skip to content
BranchesTags

Repository files navigation

BotWave

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.

Table of Contents

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.
Installer options 
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

Adding -s -- <server, client or both> --alsa at the end of the command skips the interactive menu and goes straight to installation.

Note that all this is optional and not needed for basic installation.

Tip

Not sure which mode to pick?

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
Local client options 
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.

GPIO diagram Example wiring

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
Server options 
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.

Client options 
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.

GPIO diagram Example wiring

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:

Updating BotWave

sudo bw-update
Updater options 
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:

Run in Cloud Shell Open in GitHub Codespaces

Get Help

Got a question or an issue?

Mentions

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

eutech.directory awesome-selfhosted nigthrunners tom-doerr peppe8o show hn le site de korben cyberplanete

Supports

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

vocal

License

BotWave is licensed under GPLv3.0.

Credits

a DPIP Studio Project Made by Douxx

About

BotWave - Your Raspberry Pi FM Network

botwave.dpip.lol

Topics

automationbotwavebroadcastingfmfm-transmittergood-first-contributiongood-first-issuenetworkpiwavepythonradioraspberry-pirds

Resources

Readme
GPL-3.0 license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

142 stars

Watchers

1 watching

Forks

7 forks
Report repository

Releases

Sponsor this project

Contributors

Languages