BotWave lets you broadcast audio over FM radio using Raspberry Pi devices. It supports server-client management, remote control, automated actions, live streaming, and more. That makes it ideal for learning, experimentation, and creative projects.
Table of Contents
- Features
- Requirements
- Get Started
- Remote Management
- Advanced Usage
- Updating BotWave
- Uninstallation
- BotWave Server For Cloud Instances
- Mentions
- License
- Credits
- Server-Client Architecture: Manage multiple Raspberry Pi clients from a central server.
- Audio Broadcasting: Broadcast audio files over FM radio.
- 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. (Still in development, see
#24)
All requirements can be installed automatically via the installer, see below.
- Python >= 3.9
- Raspberry Pi
- Root access
- Python >= 3.9
- bw_custom
- (Wire or antenna)
Note
If you want a more detailed guide, you might want to 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.
- The authors are not responsible for legal issues or hardware damage.
- See FAQ for more information:
/wiki/FAQ
For debian-like operating systems (Debian, Ubuntu, Raspberry Pi OS, Zorin OS, etc), we provide an install script.
curl -sSL https://botwave.dpip.lol/install | sudo bashIf you wish to review the script before running it, run the following commands:
curl -sSL https://botwave.dpip.lol/install -o bw_install.sh
cat bw_install.sh
sudo bash bw_install.sh
sudois required to access system-wide access. We use it to install BotWave into/opt/BotWaveand binary symlinks into/usr/local/bin.
If you're working on an OS that isn't debian-like, you can either try to tweak our install script, or you can open an issue to get help.
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 -h, --help Show this help message
Adding -s <server, client or both> at the end of the command skips the interactive menu and goes straight to installation.
Use -s -- <server, client or both> <options> to add options flags.
Note that all this is optional and not needed for basic installation.
Tip
If you plan to only use one raspberry pi (not a network of them), we offer a standalone client, that allows you to use BotWave without a server. If you wish to use the "local client", go to Using The Local Client.
In those examples, it is assumed that you have one machine with the server component installed, and one Raspberry Pi with the client component installed. It is also assumed that both are on the same network.
Start by starting the server
bw-serverServer options
Usage: bw-server [OPTIONS]bw-server [-h] [--host HOST] [--port PORT] [--fport FPORT] [--pk PK] [--handlers-dir HANDLERS_DIR] [--start-asap] [--ws WS] [--daemon]
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 Start broadcasts immediately (may cause client desync) --ws WS WebSocket port for remote shell access --daemon Run in non-interactive daemon mode
Once you got your server running, run the client specifying the server IP:
If you don't know your server IP, run
< hostname -Iin the BotWave shell input.
sudo bw-client 192.168.1.10 # assuming that the server ip is the following
sudois used to access the Raspberry Pi hardware and filesystem.
Client options
Usage: sudo bw-client [OPTIONS]sudo bw-client [-h] [--port PORT] [--fhost FHOST] [--fport FPORT] [--upload-dir UPLOAD_DIR] [--pk PK] [--skip-checks] [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 Skip update and requirements checks
Hardware installation for clients
To use BotWave Client for broadcasting, you need to set up the hardware correctly. This involves eventually connecting an antenna or a cable to the Raspberry Pi's GPIO 4 (pin 7).
If everything went well, you should see a message telling that <pi hostname>_<pi ip> successfully connected.
The server has a CLI to manage it. Write help for a list of all commands available.
When performing an action on clients, you will need to specify the target(s). Those can be:
- The
clientID, eg:raspberry_192.168.1.11 - The
clienthostname, eg:raspberry - Multiple clients, eg:
raspberry,raspberry2 - Every connected client:
all
BotWave needs each Pi of the network to locally have the wave (.wav) file, this is mainly to improve bandwidth usage. To upload a file, you have two options:
1. 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 .wav file in the given folder2. Upload a file stored on an external server:
botwave> dl all https://cdn.douxx.tech/files/ss.wav # download the file from cdn.douxx.techbotwave> start all ss.wav 88 # this broadcasts the file ss.wav on 88MHzbotwave> stop allbotwave> exit # this kicks (stops) all clients and cleans up the server properlyThe local client is a standalone tool that doesn't require a server. You can run it and directly access the CLI interface. This part assumes that you have a Raspberry Pi with the client installed.
To start the local client, run the following command:
sudo bw-localLocal client options
Usage: sudo bw-local [OPTIONS]sudo bw-local [-h] [--upload-dir UPLOAD_DIR] [--handlers-dir HANDLERS_DIR] [--skip-checks] [--daemon] [--ws WS] [--pk PK]
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 Skip system requirements checks --daemon Run in daemon mode (non-interactive) --ws WS WebSocket port for remote control --pk PK Optional passkey for WebSocket authentication
Hardware installation for clients
To use BotWave Client for broadcasting, you need to set up the hardware correctly. This involves eventually connecting an antenna or a cable to the Raspberry Pi's GPIO 4 (pin 7).
The local client has a CLI to manage it. Write help for a list of all commands available.
The local client requires wave (.wav) files to play. To upload a file, you have two options:
1. Upload a file stored on the local machine:
botwave> upload /home/server/Downloads/ss.wav ss.wav2. Upload a file stored on an external server:
botwave> dl https://cdn.douxx.tech/files/ss.wav # download the file from cdn.douxx.techbotwave> start ss.wav 88 # This starts broadcasting ss.wav on 88MHzbotwave> stopbotwave> exit # this cleans up and exitsBotWave allows you to manage remotely your server or local client. To do so, we recommend using a tool like BWSC.
npm i -g bwsc # this assumes you have npm and nodejs installedTo allow you to connect remotely, you have to add the --ws [PORT] flag on the start command of the server or the local client. It is also recommended to add the --pk [passkey] flag to reject unauthorized connections.
bw-server --ws 9939 --pk 1234 # for the server component
bw-local --ws 9939 --pk 1234 # for the local client componentnote: if you add a passkey, you'll also have to provide it to the client:
sudo bw-client <server ip> --pk <passkey>.
bwsc 192.168.1.10 1234 # assuming the server to be 192.168.1.10You will now have access to the server/local client CLI.
Please note that the < and exit commands won't be available.
You will also receive the server logs in real time.
botwave> help # server / lc will send the help back to youFor other / more detailed actions please check the following resources:
- Server help:
/server/server.md - Client help:
/client/client.md - Client help:
/local/local.md - AutoRun help:
/autorun/autorun.md - Automated actions help:
/misc_doc/handlers.md - Remote management protocol:
/misc_doc/websocket.md
For debian-like systems, we recommend using our automatic uninstallation scripts, for other operating systems, you're on your own.
sudo bw-updateFor debian-like systems, we recommend using our automatic uninstallation scripts, for other operating systems, you're on your own.
curl -sSL https://botwave.dpip.lol/uninstall | sudo bashYou can directly try BotWave server on Cloud Instances like Google Shell or GitHub Codespaces.
BotWave mentions: Here are some posts that talk about BotWave. Thanks to their creators !
BotWave is licensed under GPLv3.0.
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}