> For the complete documentation index, see [llms.txt](https://docs.remote.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.remote.it/software/bluetooth-wifi-onboarding-package-r3onboard.md). # Bluetooth Wifi Onboarding Package (r3onboard) ## 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](https://link.remote.it/github/ble) #### [remote.it App for using r3onboard](https://link.remote.it/getting-started/rpi-ble-image) #### 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.](https://link.remote.it/getting-started/rpi-ble-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](https://downloads.remote.it/r3onboard/latest/r3onboard_all.deb) 1. **Download the package to `/tmp`:** ```sh wget -P /tmp https://downloads.remote.it/r3onboard/latest/r3onboard_all.deb ``` 2. **Install it with apt:** ```sh 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:** ```sh 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: ```sh 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`: ```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: ```sh 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](https://link.remote.it/github/ble). ### Viewing Logs View recent service logs with: ```sh journalctl -u r3onboard -n 100 ``` Add `-f` to follow the logs live while you onboard a device: ```sh 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): ```sh sudo apt remove r3onboard ``` To also remove the configuration file at `/etc/r3onboard/config.ini`: ```sh sudo apt purge r3onboard ``` ### Resources * [r3onboard GitHub repo](https://link.remote.it/github/ble) * [Using the prebuilt Raspberry Pi image](https://link.remote.it/getting-started/rpi-ble-image) * [Download the latest Debian package](https://downloads.remote.it/r3onboard/latest/r3onboard_all.deb) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.remote.it/software/bluetooth-wifi-onboarding-package-r3onboard.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.