> 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)

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

r3onboard lets you set up WiFi on a headless device and register it with Remote.It over Bluetooth LE, from the Remote.It mobile app. No keyboard, monitor or preset network settings needed. Once registered, you can reach the device remotely over SSH, VNC, a web server, or any other service you add.

* **Easy WiFi configuration** over Bluetooth LE
* **Remote access** as soon as registration finishes
* **Automatic WiFi scanning** on boot
* **Built for Debian Bookworm,** with a primary focus on Raspberry Pi

{% hint style="info" %}
**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 it to read WiFi status, list nearby networks, and send WiFi credentials and a registration code. WiFi is applied through NetworkManager, and registration hands the device off to Remote.It for remote access.
{% endhint %}

## Requirements

* A Raspberry Pi, or another device running Debian Bookworm
* Bluetooth LE, which is built in on modern Raspberry Pi models
* WiFi for the network you want to join
* NetworkManager managing the device's networking, which is the default on Bookworm

## Install r3onboard

There are two ways to get r3onboard onto a device.

| If you...                                         | Use                                                                              |
| ------------------------------------------------- | -------------------------------------------------------------------------------- |
| Want the fastest path on a Raspberry Pi           | [Option 1: the prebuilt Pi image](#option-1-use-the-prebuilt-pi-image)           |
| Maintain your own Debian or Raspberry Pi OS image | [Option 2: install the package](#option-2-install-r3onboard-into-your-own-image) |

### Option 1: Use the prebuilt Pi image

The prebuilt image has r3onboard installed and ready to advertise on first boot. See [Using the prebuilt Raspberry Pi image](https://link.remote.it/getting-started/rpi-ble-image).

### Option 2: Install r3onboard into your own image

{% stepper %}
{% step %}

### Download the package

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

{% endstep %}

{% step %}

### Install it with apt

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

Installation enables the service to start on boot.
{% endstep %}

{% step %}

### Verify the service

```sh
sudo systemctl status r3onboard
```

It should show `enabled`, and `active (running)` after a reboot. To start it now without rebooting:

```sh
sudo systemctl start r3onboard
```

{% endstep %}

{% step %}

### Create your image

Capture a system image with your usual imaging tool, so you can deploy it to other devices.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**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 [r3onboard repo](https://link.remote.it/github/ble) is a good starting point. It's how we build the Raspberry Pi image.
{% endhint %}

### 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 advertises for 10 minutes after the service starts. Set `Duration = -1` to advertise indefinitely, which suits kiosk or long-lived onboarding scenarios. After changing the file, restart the service:

```sh
sudo systemctl restart r3onboard
```

## Onboard a device

{% stepper %}
{% step %}

### Connect over Bluetooth

In the Remote.It app, connect to the device over Bluetooth.
{% endstep %}

{% step %}

### Choose a WiFi network

Pick the network and enter its password.
{% endstep %}

{% step %}

### Register (optional)

Enter a registration code to register the device to your Remote.It account.
{% endstep %}
{% endstepper %}

The app shows the WiFi and registration status as it goes.

{% hint style="info" %}
**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 [r3onboard repo README](https://link.remote.it/github/ble).
{% endhint %}

## Viewing logs

Show the last 100 log lines:

```sh
journalctl -u r3onboard -n 100
```

Follow the log live:

```sh
journalctl -u r3onboard -f
```

For more detail, set `LogLevel = debug` in the config file and restart the service.

## Troubleshooting

**The device doesn't appear over Bluetooth**

* Advertising stops after 10 minutes by default. Reboot the device, restart the service with `sudo systemctl restart r3onboard`, or set `Duration = -1` in the config file.
* Check the service is running with `sudo systemctl status r3onboard`.

**WiFi won't connect**

* Check the logs with `journalctl -u r3onboard -n 100`.
* Verify the SSID and password, and that the device supports the network's band.
* 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.

## Uninstalling

Removing the package stops and disables the service and removes its virtual environment:

```sh
sudo apt remove r3onboard
```

To also remove the config file:

```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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.remote.it/software/bluetooth-wifi-onboarding-package-r3onboard.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
