Basic usage

In this page are documented the basics of BotWave, along with some additional tips.

Note

In this page, we consider that you already installed and connected the server and clients together.
If not, please read and follow Base/Setup

BotWave supports a variety of different uses cases and functionalities. Here we will only cover the essentials to get it working. Additional features can be found in the Advanced part of the sidebar.

Command line arguments

Before even the startup of SU, CU or SI, we have to configure them correctly.
This is done by adding command arguments or flags:

• Arguments are most of the time required, but can be optional. They usually represent a variable that has to be changed.
• Flags are optional features, that either have a default value that can be changed, or enable / disable features when used. They usually are formed like this: --flag_name optional_flag_value.

In short, arguments are usually required values and flags are optional settings that modify behavior.

Here is a basic command structure:

program argument1 argument2 --flag1 55 --flag2 --flag3 "hi :3"

Now that you know that, here are the supported arguments of the server, client and local units:

Tip

Most of the time, brackets ([]) represent optional values, and crocodiles (<>) required values!

Server

sudo bw-server [--host HOST] [--port PORT] [--fport FPORT] [--pk PASSKEY] [--ws PORT] [--skip-checks] [--start-asap] [--daemon]```

Argument	Type	Default	Description
--host	string	0.0.0.0	Host address to bind the WebSocket server
--port	integer	9938	Port for WebSocket command/control channel
--fport	integer	9921	Port for HTTPS file transfer server
--pk	string	None	Optional passkey for client authentication
--ws	integer	None	Port for remote WebSocket shell
--start-asap	flag	False	Start broadcasts immediately (may cause client desync)
--skip-checks	flag	False	Skip update checks
--daemon	flag	False	Run in non-interactive daemon mode

Client

sudo bw-client [server_host] [--port PORT] [--fport FPORT] [--upload-dir DIR] [--skip-checks] [--pk PASSKEY] [--skip-update-check]

Argument	Type	Default	Description
server_host	string	(prompted)	Hostname or IP address of BotWave server
--port	integer	9938	Port for WebSocket connection to server
--fport	integer	9921	Port for HTTPS file transfer connection
--upload-dir	path	/opt/BotWave/uploads	Directory to store received files
--skip-checks	flag	False	Skip system requirements verification
--pk	string	None	Passkey for server authentication

Local client

sudo bw-local [--upload-dir DIR] [--handlers-dir DIR] [--skip-checks] [--daemon] [--ws PORT] [--pk PASSKEY]

Argument	Type	Default	Description
--upload-dir	path	/opt/BotWave/uploads	Directory containing broadcastable WAV files
--handlers-dir	path	/opt/BotWave/handlers	Directory containing handler files
--skip-checks	flag	False	Skip system requirements verification
--daemon	flag	False	Run in non-interactive daemon mode
--ws	integer	None	Enable WebSocket remote control on specified port
--pk	string	None	Passkey for WebSocket authentication

---

Usage

Now that we know how to launch our apps with the desired settings, let's connect them together. If your apps are exposed to the internet, we recommend you to use a passkey for authentication. Here are both commands we will be using in this tutorial:

• Server: bw-server --pk YouSh0uldStarBW --start-asap
• Client: sudo bw-client botwave.dpip.lol --pk YouSh0uldStarBW --skip-checks

Once both commands have run, our client should be successfully connected to our server and we will be able to move to the next step.

Note

Please note that commands in bw-local are really similar. The only difference is that <targets> doesn't exists. Some commands behaviour may also change.

Basic commands

You should be able to write commands in the botwave > input prompt. Let's start by writing help to see the list of available commands.

Expected result

botwave ›  help
BotWave Server - Help
Available Commands ────────────────────
list
List all connected clients
start <targets> <file> [loop] [freq] [ps] [rt] [pi]
Start broadcasting on client(s)
Example: start all broadcast.wav 100.5 MyRadio
stop <targets>
Stop broadcasting on client(s)
Example: stop all
sstv <image_path> [mode] [output_wav] [frequency] [loop] [ps] [rt] [pi]
Convert an image into a SSTV WAV file, and then broadcast it
Example: sstv /path/to/mycat.png Robot36 cat.wav 90 false PsPs Cutie FFFF
upload <targets> <file|folder>
Upload a WAV file or a folder's files to client(s)
Example: upload all broadcast.wav
Example: upload pi1,pi2 /home/bw/lib
sync <targets|folder/> <source_target|folder/>
Synchronize files across clients or to/from local folders
Examples:
sync all pi1              - Sync from pi1 to all other clients
sync pi2,pi3 /music/      - Sync local folder to clients
sync /backup/ pi1         - Sync from pi1 to local folder
dl <targets> <url>
Request client(s) to download a file from a URL
Example: dl all http://example.com/file.wav
lf <targets>
List broadcastable files on client(s)
Example: lf all
rm <targets> <filename|all>
Remove a file from client(s)
Example: rm all broadcast.wav
kick <targets> [reason]
Kick client(s) from the server
Example: kick pi1 Maintenance
restart <targets>
Request client(s) to restart
Example: restart all
handlers [filename]
List all handlers or commands in a specific handler file
Example: handlers
< <command>
Run a shell command on the main OS
Example: < df -h
exit
Exit the application
help
Display this help message
Targets ─────────
'all' - All connected clients
client_id - Specific client by ID
hostname - Client by hostname
Comma-separated list - Multiple clients
Example: 'pi1,pi2' or 'all' or 'kitchen-pi'

As you can see, a lot of commands are supported. In this page, we will go through most basic commands to broadcast music on FM.

1. list

The list command is one of the most important: it shows you connected clients and basic stats about them. It's very practical since it allows you to know which clients are connected to your server.
This command doesn't take any arguments, so no need to explain them :P Simply write list

Expected result

botwave ›  list
 Connected Clients ───────────────────
ID: botwave-client_192.168.1.96
Hostname: botwave-client
Machine: aarch64
System: Linux
Protocol Version: 2.0.0
Connected: 2025-11-26 23:04:30
Last seen: 2025-11-26 23:04:30

Now that we know that we have the botwave-client connected, let's check what files are on it:

2. lf

The list files command is built like this: lf <targets>.

Tip

Targets are either:

• all - All connected clients
• client_id - Specific client by ID
• hostname - Client by hostname
• Comma-separated list - Multiple clients
  Example: pi1,pi2 or all or kitchen-pi

Knowing this, let's run lf all, since the client is our only connected client.

Expected result

botwave ›  lf all
[INFO] Listing files from 1 client(s)
[OK]   botwave-client (botwave-client_192.168.1.96): 0 file(s)
    No files found

As we can see, no files are found, and thats normal on a fresh install ! So let's directly upload a file to our client:

3. dl

The dl command is made like this: dl <targets> <url>. The url must be a direct link to a .wav file. The client will fetch the file from the external resource and download it in its upload directory.

For this tutorial, we're going to run dl all https://cdn.douxx.tech/files/ss.wav.

Expected result

botwave ›  dl all https://cdn.douxx.tech/files/ss.wav
[BCAST] Requesting download from 1 client(s)...
[FILE]   botwave-client (botwave-client_192.168.1.96): Download request sent
[OK] botwave-client (botwave-client_192.168.1.96): Downloaded ss.wav

Now, if we run the lf all command again, we should see ss.wav (41.6 MB) listed in our clients files.
Now that the client has files, let’s start broadcasting.

4. start

Now that your client has files uploaded, let’s start broadcasting! The start command tells the client to transmit a file over FM.

Think of it as: "Which clients should broadcast what, and how?"

The command looks like this:

start <targets> <file> [frequency] [loop] [PS] [RT] [PI]

Here’s a simple breakdown:

• <targets>: Which clients should broadcast (e.g., all, pi1, pi1,pi2)
• <file>: The file to broadcast (must already be uploaded on the client)
• [frequency]: FM frequency in MHz (default: 90.0, range: 76.0-108.0)
• [loop]: Whether the file should repeat continuously (true or false, default: false)
• [PS]: Radio name (8 characters max)
• [RT]: Radio description (64 characters max)
• [PI]: Program Identifier for FM receivers (optional)

Don’t worry about PS, RT, and PI for now, we'll just use the basic ones to get broadcasting working.

Let’s send a broadcast command to all connected clients (a single one in our case). We’ll broadcast ss.wav at 88.5 MHz and loop it continuously: start all ss.wav 88.5 true

Expected result

botwave ›  start all ss.wav 88.5 true
[BCAST] Starting broadcast ASAP
[BCAST] Starting broadcast on 1 client(s)...
[OK]   botwave-client (botwave-client_192.168.1.96): START command sent
[BCAST] Broadcast start commands sent: 1/1
[OK] botwave-client (botwave-client_192.168.1.96): Broadcasting started

Great! If everything worked correctly, you should be able to catch the radio signal emitted from the rpi with a radio tuned at 88.5 Mhz !

Note that the server said Starting broadcast ASAP because we passed the --start-asap flag. If we didn't, it would plan the broadcast for the current time + 20 seconds per client, if there is more than one client.

Once you’re comfortable with the basics, you can experiment with:

• Changing the frequency to another FM channel
• Using the PS field to set a radio name: start all ss.wav 95 true MyRadio
• Adding RT for extra info: start all ss.wav 95 true MyRadio "Hello listeners!"

You don’t need these options to get started, just know they exist for later.

Tip

Most important things to remember:

• The file must exist in the client’s upload folder.
• Use loop if you want the file to repeat.
• Optional fields (PS, RT, PI) enhance the broadcast, but are not required.

Once you’re happy with the broadcast, we'll see how to stop it in the next section.

5. stop

The stop command is also really simple, it is built like this: stop <targets>, so, for this example, let's use stop all.

Expected result

botwave ›  stop all
[OK]   botwave-client (botwave-client_192.168.1.96): STOP command sent
[BCAST] Broadcast stop commands sent: 1/1
[OK] botwave-client (botwave-client_192.168.1.96): Broadcast stopped

And finally, let's exit from the server by doing a clean exit.

6. exit

This command doesn't take any arguments. It kicks every client and shuts down properly the server.

Expected result

botwave ›  exit
[SERVER] Shutting down server...
[CLIENT] Kicking 1 client(s)...
[OK]   botwave-client (botwave-client_192.168.1.96): Kicked - Server is shutting down
[CLIENT] Kick completed
[SERVER] Main socket stopped
[SERVER] File transfer (HTTP) server stopped
[OK] Server shutdown complete
[dpip@botwave-server] ~ ›

---

You now know the basics of using BotWave: connecting clients and server, transferring files, and broadcasting over FM.
Feel free to explore other commands on your own, or you can follow our guide in Advanced/Commands. Remember to experiment safely and refer back to this guide whenever you need a quick refresher.