Table of Contents
- Features
- Requirements
- Get Started
- Remote Management
- Advanced Usage
- Updating BotWave
- Uninstallation
- BotWave Server For Cloud Instances
- Get Help
- Mentions
- License
- Credits
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: ``sh
curl -sSL https://botwave.dpip.lol/install | sudo bash
`
If you'd like to review the script before running it:
`sh
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 Install a specific release version
-b, --branch 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?
- 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
`sh
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.
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:
`sh
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:
`sh
scp mysong.mp3 pi@:/home/pi/
`
Then inside BotWave:
`sh
botwave › upload /home/pi/mysong.mp3 # a single file
botwave › upload /home/pi/music/ # every supported file in a folder
`
4. Starting a broadcast
`sh
botwave › start ss.wav 88 # broadcasts ss.wav at 88 MHz
`
5. Stopping a broadcast
`sh
botwave › stop
`
6. Exiting properly
`sh
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:
`sh
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.
`sh
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.
If the connection succeeds, you'll see a message confirming that 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:
`sh
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:
`sh
botwave › dl all https://cdn.douxx.tech/files/ss.wav
`
4. Starting a broadcast
`sh
botwave › start all ss.wav 88 # broadcasts ss.wav at 88 MHz with all clients
`
5. Stopping a broadcast
`sh
botwave › stop all
`
6. Exiting properly
`sh
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
`sh
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:
`sh
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
3. Connect remotely
`sh
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.
`sh
botwave › help
`
Advanced Usage
For more detailed documentation, check the following resources:
/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
`bash
sudo bw-update
`
Updater options
`
Usage: bw-update [OPTIONS]
Options:
-l, --latest Update to the latest commit (even if unreleased)
-t, --to Update to a specific release version
-b, --branch 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
`bash
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?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 🙏