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
Requirements
- Server
- Client
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.9 ### Client - Raspberry Pi (models 2, 3, 4, or Zero. **Pi 5 and Pico are not supported**) - Root access - Python >= 3.9 - [bw_custom](https://github.com/dpipstudio/bw_custom) - (Wire or antenna connected to GPIO 4 / pin 7) ## Get Started > [!NOTE] > For a more detailed setup guide, 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 with other services. > - **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 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`. **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?** > - **One Raspberry Pi**: use the **Local Client** (no server needed). Jump to [Using The Local Client](#using-the-local-client-single-pi). > - **Multiple Raspberry Pis**: use the **Client-Server** setup. Jump to [Using The Client-Server](#using-the-client-server-multiple-pis). --- ### 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]

BotWave Standalone CLI 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 WebSocket
                        authentication
  --talk, --no-talk     Show output logs
  --config CONFIG       Path to a config file to load into environment

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] [--daemon | --no-daemon]

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
  --config CONFIG       Path to a config file to load into environment
  --daemon, --no-daemon
                        Run in non-interactive daemon mode

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]
                 [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, --no-skip-checks
                        Skip update and requirements checks
  --talk, --no-talk     Makes PiWave (broadcast manager) output
                        logs visible.
  --config CONFIG       Path to a config file to load into environment

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 to 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`](https://github.com/douxxtech/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 1234 # for the server component bw-local --rc 9939 --pk 1234 # for the local client component ``` > If you add a passkey to the server, also pass it to connecting clients: `sudo bw-client --pk ` #### 3. Connect remotely ```sh bwsc 192.168.1.10 1234 # 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: - **Server help**: [`/server/server.md`](/server/server.md) - **Client help**: [`/client/client.md`](/client/client.md) - **Local client help**: [`/local/local.md`](/local/local.md) - **AutoRun help**: [`/autorun/autorun.md`](/autorun/autorun.md) - **Automated actions**: [`Main/Automate Your Setup`](https://github.com/dpipstudio/botwave/wiki/Automate-your-setup) - **Remote management**: [`Main/Connecting remotely`](https://github.com/dpipstudio/botwave/wiki/Connecting-remotely) ### Updating BotWave ```bash sudo bw-update ``` ### 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: [![Run in Cloud Shell](/assets/readme_assets/google_shell.svg)](https://shell.cloud.google.com/cloudshell/open?cloudshell_git_repo=https://github.com/dpipstudio/botwave&cloudshell_tutorial=misc_doc/google-shell.md&show=terminal) [![Open in GitHub Codespaces](/assets/readme_assets/github_codespaces.svg)](https://codespaces.new/dpipstudio/botwave) ### Get Help Got a question or an issue? - Open an [issue](https://github.com/dpipstudio/botwave/issues/new) - Join the [Discord](https://discord.gg/r5ragNsQxp) ## 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](LICENSE). ## Credits ![a DPIP Studio Project](https://madeby.dpip.lol) ![Made by Douxx](https://madeby.douxx.tech)