software-bluetooth-wifi-onboarding-package-r3onboard.md
For the complete documentation index, see llms.txt. This page is also available as Markdown.
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.
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.
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.
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)
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.
Use this path if you maintain your own Debian/Raspberry Pi OS image and want to add BLE onboarding to it.
Download the package to /tmp :
Install it with apt:
Installation sets up the service and enables it to start on boot.
Verify the service:
You should see the service as enabled (starts on boot) and, after a reboot, active (running). To start it now without rebooting:
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.
Settings live in /etc/r3onboard/config.ini:
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:
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.
With r3onboard running and the device advertising over Bluetooth:
Open the Remote.It app and connect to the device over Bluetooth.
Pick a WiFi network from the scanned list and enter the password.
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.
View recent service logs with:
Add -f to follow the logs live while you onboard a device:
For more detail, set LogLevel = debug in /etc/r3onboard/config.ini and restart the service.
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.
Remove the package (this stops and disables the service and removes its virtual environment):
To also remove the configuration file at /etc/r3onboard/config.ini:
Using the prebuilt Raspberry Pi image
Download the latest Debian package
PreviousGlossary of TermsNextDevice Package
Last updated 14 days ago
Was this helpful?