https://github.com/dpipstudio/botwave
BotWave - Your Raspberry Pi FM Network
https://github.com/dpipstudio/botwave
botwave fm good-first-contribution good-first-issue network piwave python radio raspberry-pi rds
Last synced: 4 days ago
JSON representation
BotWave - Your Raspberry Pi FM Network
- Host: GitHub
- URL: https://github.com/dpipstudio/botwave
- Owner: dpipstudio
- License: gpl-3.0
- Created: 2025-07-14T21:24:03.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-27T16:08:27.000Z (8 days ago)
- Last Synced: 2026-01-28T01:21:54.342Z (8 days ago)
- Topics: botwave, fm, good-first-contribution, good-first-issue, network, piwave, python, radio, raspberry-pi, rds
- Language: Python
- Homepage: https://botwave.dpip.lol
- Size: 2.22 MB
- Stars: 113
- Watchers: 3
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
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- Installation
-
Using The Client-Server- Connect the client and the server together
- Understanding the server command line interface
- Uploading files to the client
- Starting a broadcast
- Stopping a broadcast
- Exiting properly
-
Using The Local Client- Starting the local client
- Understanding the local client command line interface
- Uploading files to the local client
- Starting a broadcast
- Stopping a broadcast
- Exiting properly
- Remote Management
- Advanced Usage
- Updating BotWave
- Uninstallation
- BotWave Server For Cloud Instances
- Get Help
- Mentions
- License
- Credits
## Features
- **Server-Client Architecture**: Manage multiple Raspberry Pi clients from a central server.
- **Standalone Client**: Run a client without a central server for single-device broadcasting.
- **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.
- **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
- Root access
- Python >= 3.9
- [bw_custom](https://github.com/dpipstudio/bw_custom)
- (Wire or antenna)
## Get Started
> [!NOTE]
> If you want a more detailed guide, you might want to check [`/wiki/Setup`](https://github.com/dpipstudio/botwave/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`](https://github.com/dpipstudio/botwave/wiki/FAQ)
### Installation
For debian-like operating systems (Debian, Ubuntu, Raspberry Pi OS, Zorin OS, etc), we provide an install script.
```sh
curl -sSL https://botwave.dpip.lol/install | sudo bash
```
If you wish to review the script before running it, run the following commands:
```sh
curl -sSL https://botwave.dpip.lol/install -o bw_install.sh
cat bw_install.sh
sudo bash bw_install.sh
```
> `sudo` is required to access system-wide access. We use it to install BotWave into `/opt/BotWave` and 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 componentsOptions:
-l, --latest Install from the latest commit (even if unreleased)
-t, --to <version> Install a specific release version
--[no-]alsa Setup ALSA loopback card
-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`](#using-the-local-client).
### Using The Client-Server
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.
#### 1. Connect the client and the server together
Start by starting the `server`
```sh
bw-server
```
Server 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 -I` in the BotWave shell input.
```sh
sudo bw-client 192.168.1.10 # assuming that the server ip is the following
```
> `sudo` is 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/IPoptions:
-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 `_` successfully connected.
#### 2. Understanding the server command line interface
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 `client` ID, eg: `raspberry_192.168.1.11`
- The `client` hostname, eg: `raspberry`
- Multiple clients, eg: `raspberry,raspberry2`
- Every connected client: `all`
#### 3. Uploading files to the client
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:**
```sh
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 folder
```
**2. Upload a file stored on an external server:**
```sh
botwave> dl all https://cdn.douxx.tech/files/ss.wav # download the file from cdn.douxx.tech
```
#### 4. Starting a broadcast
```sh
botwave> start all ss.wav 88 # this broadcasts the file ss.wav on 88MHz
```
#### 5. Stopping a broadcast
```sh
botwave> stop all
```
#### 6. Exiting properly
```sh
botwave> exit # this kicks (stops) all clients and cleans up the server properly
```
### Using The Local Client
The `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.
#### 1. Starting the local client
To start the local client, run the following command:
```sh
sudo bw-local
```
Local 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).
#### 2. Understanding the local client command line interface
The `local client` has a CLI to manage it. Write `help` for a list of all commands available.
#### 3. Uploading files to the local client
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:**
```sh
botwave> upload /home/server/Downloads/ss.wav # a single file
botwave> upload /home/server/Downloads/bw_files/ # every .wav file in the given folder
```
**2. Upload a file stored on an external server:**
```sh
botwave> dl https://cdn.douxx.tech/files/ss.wav # download the file from cdn.douxx.tech
```
#### 4. Starting a broadcast
```sh
botwave> start ss.wav 88 # This starts broadcasting ss.wav on 88MHz
```
#### 5. Stopping a broadcast
```sh
botwave> stop
```
#### 6. Exiting properly
```sh
botwave> exit # this cleans up and exits
```
## Remote Management
BotWave allows you to manage remotely your `server` or `local client`. To do so, we recommend using a tool like [`BWSC`](https://github.com/douxxtech/bwsc).
#### 1. Install BWSC
```sh
npm i -g bwsc # this assumes you have npm and nodejs installed
```
#### 1. Setup the server or the local client
To 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.
```sh
bw-server --ws 9939 --pk 1234 # for the server component
bw-local --ws 9939 --pk 1234 # for the local client component
```
> note: if you add a passkey, you'll also have to provide it to the client: `sudo bw-client --pk `.
#### 2. Connect to the server/local client remotely
```sh
bwsc 192.168.1.10 1234 # assuming the server to be 192.168.1.10
```
#### 3. Manage the server/local client remotely
You 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.
```sh
botwave> help # server / lc will send the help back to you
```
## Advanced Usage
For other / more detailed actions please check the following resources:
- **Server help**: [`/server/server.md`](/server/server.md)
- **Client help**: [`/client/client.md`](/client/client.md)
- **Client help**: [`/local/local.md`](/local/local.md)
- **AutoRun help**: [`/autorun/autorun.md`](/autorun/autorun.md)
- **Automated actions help**: [`/misc_doc/handlers.md`](/misc_doc/handlers.md)
- **Remote management protocol**: [`/misc_doc/websocket.md`](/misc_doc/websocket.md)
### Updating BotWave
For debian-like systems, we recommend using our automatic uninstallation scripts, for other operating systems, you're on your own.
```bash
sudo bw-update
```
### Uninstallation
For debian-like systems, we recommend using our automatic uninstallation scripts, for other operating systems, you're on your own.
```bash
curl -sSL https://botwave.dpip.lol/uninstall | sudo bash
```
### BotWave Server For Cloud Instances
You can directly try BotWave `server` on Cloud Instances like Google Shell or GitHub Codespaces.
[](https://shell.cloud.google.com/cloudshell/open?cloudshell_git_repo=https://github.com/dpipstudio/botwave&cloudshell_tutorial=misc_doc/google-shell.md&show=terminal)
[](https://codespaces.new/dpipstudio/botwave)
### Get Help
Got a question or an issue ? Feel free to ask for help !
- Open an [issue](https://github.com/dpipstudio/botwave/issues/new)
- Join the [discord](https://discord.gg/r5ragNsQxp)
## Mentions
**BotWave mentions**: Here are some posts 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](LICENSE).
## Credits
