Bluetooth Wifi Onboarding Package (r3onboard)

Configure WiFi and register headless Raspberry Pi and Debian Bookworm devices over Bluetooth LE with r3onboard — no keyboard or monitor required.

Bluetooth WiFi Onboarding Package (r3onboard)

Bluetooth WiFi Onboarding is a solution developed by Remote.It that simplifies setting up new devices. It uses Bluetooth Low Energy (BLE) to let you configure a device's WiFi and register it with the Remote.It service — no keyboard, monitor, or pre-flashed network settings required. This makes it ideal for headless deployments and for devices that will be reconfigured after they ship.

Once a device is on the network and registered, you get secure remote access to services on it (SSH, VNC, web servers, and more) through Remote.It.

r3onboard GitHub Repo

remote.it App for using r3onboard

Key Features

• Easy WiFi configuration: Connect over Bluetooth LE to set WiFi credentials and get your device on the network in seconds.

• Remote access: Register the device with the Remote.It service to reach it from anywhere.

• Automatic WiFi scanning: Available networks are scanned on boot so they're ready to pick from the app.

• Compatibility: Built for Debian Bookworm packages, with a primary focus on Raspberry Pi devices.

How It Works

r3onboard is a Python service that runs on the device and exposes a Bluetooth LE GATT server. The Remote.It app connects to that server to read WiFi status, list nearby networks, send WiFi credentials, and pass a registration code. WiFi is applied through NetworkManager, and registration hands the device off to the Remote.It service for remote access.

Requirements

• A Raspberry Pi (primary target) or another Debian Bookworm device

• Bluetooth Low Energy capability (built in on modern Raspberry Pi models)

• WiFi capability for the network you want to join

• NetworkManager managing the device's networking (the default on Bookworm)

Option 1: Use Our Prebuilt Pi Image

If you're using a Raspberry Pi, the fastest path is our prebuilt image with r3onboard already installed and enabled. See details on using the prebuilt Pi image.

Option 2: Install r3onboard Into Your Own Image

Use this path if you maintain your own Debian/Raspberry Pi OS image and want to add BLE onboarding to it.

Manually Installing the r3onboard Debian Package

1. Download the package to /tmp:

   wget -P /tmp https://downloads.remote.it/r3onboard/latest/r3onboard_all.deb

2. Install it with apt:

   sudo apt update
   sudo apt install /tmp/r3onboard_all.deb

   Installation sets up the service and enables it to start on boot.

3. Verify the service:

   sudo systemctl status r3onboard

   You should see the service as enabled (starts on boot) and, after a reboot, active (running). To start it now without rebooting:

   sudo systemctl start r3onboard

4. Create your image:

   Once r3onboard is installed, use your preferred imaging tool to capture a backup of the system. That image can then be deployed to other devices.

Configuration (optional)

Settings live in /etc/r3onboard/config.ini:

[Settings]
# How long the device advertises over Bluetooth after the service starts.
# Use s, m, or h (e.g. 30s, 10m, 1h). Set -1 to advertise indefinitely.
Duration = 10m
# Log verbosity: debug, info, warning, error, critical
LogLevel = info

By default the device is only discoverable over Bluetooth for 10 minutes after the service starts. For kiosk or long-lived onboarding scenarios, set Duration = -1. After editing the file, restart the service:

sudo systemctl restart r3onboard

Automating the Install

You can use a tool like systemd-nspawn to mount and boot an existing system image on your own machine, then install the Debian package from inside that booted container. The updateImage.sh script in the repo is a good starting point — it's how we build the Raspberry Pi image.

Onboarding a Device

With r3onboard running and the device advertising over Bluetooth:

1. Open the Remote.It app and connect to the device over Bluetooth.

2. Pick a WiFi network from the scanned list and enter the password.

3. Optionally register the device to your Remote.It account with a registration code.

The app reports WiFi and registration status back to you as each step completes.

Building your own BLE client? The GATT service UUID and characteristics — WiFi status, WiFi list, registration status, and the command characteristic (WIFI_SCAN, WIFI_CONNECT, R3_REGISTER) — are documented in the repo README.

Viewing Logs

View recent service logs with:

journalctl -u r3onboard -n 100

Add -f to follow the logs live while you onboard a device:

journalctl -u r3onboard -f

For more detail, set LogLevel = debug in /etc/r3onboard/config.ini and restart the service.

Troubleshooting

Device doesn't appear over Bluetooth

• By default it only advertises for 10 minutes after the service starts. Reboot, restart the service (sudo systemctl restart r3onboard), or set Duration = -1 in the config.

• Confirm the service is running: sudo systemctl status r3onboard.

WiFi won't connect

• Check the logs: journalctl -u r3onboard -n 100.

• Double-check the SSID and password, and confirm the device's WiFi hardware supports that network's band.

• r3onboard applies WiFi through NetworkManager — make sure NetworkManager is installed and running.

Registration fails

• Confirm the registration code is valid and hasn't already been used.

• Check the logs for the specific error returned by the Remote.It service.

Uninstalling

Remove the package (this stops and disables the service and removes its virtual environment):

sudo apt remove r3onboard

To also remove the configuration file at /etc/r3onboard/config.ini:

sudo apt purge r3onboard

Resources

• r3onboard GitHub repo

• Using the prebuilt Raspberry Pi image

• Download the latest Debian package