Skip to main content

BLE Device Control

Reach a paired device over Bluetooth LE instead of a USB cable — for pairing checks, status queries and device control when the glasses are not tethered.

Experimental — limited platform support

BLE control is experimental. It works on macOS. On Linux it has only been exercised on Fedora, and it is not supported on Ubuntu — neither 22.04 LTS nor 24.04 LTS. The blocker there is the version of bluez those releases ship; Ubuntu support is planned as a follow-up.

Everything else in the Client SDK works normally on Ubuntu — only the --ble flags are affected.

Platform support​

PlatformBLE controlNotes
macOS (Apple Silicon)✅ Supported
Fedora⚠️ Limited testingKnown to work, but not extensively validated
Ubuntu 22.04 / 24.04 LTS❌ Not supportedbluez version; follow-up planned
Windows🚧 PlannedThe SDK itself is not yet supported on Windows

What BLE can and cannot do​

BLE is a control channel, not a data channel.

Over BLE
Pairing checks, device status, device control✅
device list presence reporting✅ (with --ble-scan)
Recording❌ Not available
Streaming❌ Not available

Use BLE for control; use USB or Wi-Fi for data.

Setup​

BLE credentials are installed over an existing authenticated connection — you cannot bootstrap a device over BLE alone.

# 1. Pair normally over USB first, if you have not already
aria_gen2 auth pair

# 2. Install BLE credentials over that authenticated connection
aria_gen2 auth pair --ble

From then on, add --ble to reach the device without a cable:

# With exactly one BLE-paired device, no serial is needed
aria_gen2 --ble device status

# With several, name the one you want
aria_gen2 --ble --serial 1M0YDB5H7B0020 device status

When you need --serial​

--ble picks the device from the BLE credentials stored on this host — those pairings are the whole candidate set, since BLE reaches nothing you have not paired with.

Devices paired over BLE on this host--serial
Exactly oneNot needed — it is selected automatically
Two or moreRequired: Multiple BLE-paired devices are stored. Use --serial to pick one: followed by the list
NoneNothing to select; the command fails
The "no devices paired" error is misleading

With no BLE credentials stored at all, the CLI reports:

[AriaGen2Cli:App][ERROR]: BLE connect requires --serial

It reads as though --serial is mandatory, but adding one will not help — there is simply nothing paired to connect to. Run aria_gen2 auth pair --ble over USB first.

The same confusion is in aria_gen2 --help for 2.5.0, which says --ble "Requires --serial". It does not, when exactly one device is paired.

Automatic fallback to BLE​

You do not have to pass --ble to end up on BLE. When a command cannot find the device over USB or Wi-Fi, the CLI falls back to stored BLE pairings on its own:

  • Exactly one BLE-paired device — it is used automatically: No device found over USB or Wi-Fi; falling back to the only BLE-paired device <serial>
  • A serial was given and that device is BLE-paired — BLE is tried for it: Device <serial> was not found over USB or Wi-Fi; it is BLE-paired, so trying BLE
  • Several BLE-paired devices and no serial — you are asked to choose: No device found over USB or Wi-Fi, and multiple BLE-paired devices are stored (not checked, may be offline). Use --serial to pick one:
A BLE fallback can take 35 seconds or more

The host does not know whether a paired device is actually powered on and in range — stored pairings are not presence-checked. If the device is offline, the attempt runs until it times out. A command that normally returns instantly over USB can therefore hang for 35 s or longer when the device is unplugged and out of range.

If you did not intend to use BLE, that delay usually means USB was not detected at all — check the cable and run aria_doctor.

Discovery​

device list normally reports BLE-paired devices from this host's stored pairings, without checking whether any of them are actually in range. --ble-scan adds that check:

aria_gen2 --ble-scan device list

# Give the scan longer than the default 12 seconds
aria_gen2 --ble-scan --ble-scan-timeout 20 device list

Scanning is off by default because it costs several seconds.

Do not shorten the scan window

BLE discovery latency is irregular — a device that is present has been measured taking anywhere from 0.3 s to 11.6 s to appear. A window shorter than the 12 s default will report present devices as missing.

Managing credentials​

# Revoke this PC's BLE credential on one device, then remove it locally
aria_gen2 --serial 1M0YDB5H7B0020 auth unpair --ble

# Remove the local BLE credentials only, without contacting the device
aria_gen2 --serial 1M0YDB5H7B0020 auth unpair --ble --local-only

# Remove all stored BLE credentials, for every paired device (local only)
aria_gen2 auth remove-ble-creds

auth unpair --ble connects to the glasses over BLE to revoke this PC's credential, so they stop accepting it. The local credentials are removed even when the glasses cannot be reached; the CLI then warns that the glasses may still trust this PC, and you can revoke it in the Companion App. Glasses running firmware that predates self-revocation refuse the request with the same warning. Use --local-only for glasses that are gone or reflashed, to skip the BLE connection attempt.

remove-ble-creds is host-local and needs no connected device. Neither command touches the SSL authentication — the device stays paired for USB and Wi-Fi.

Troubleshooting​

Nothing happens, or the device is never found, on Ubuntu. Expected — BLE control does not work on Ubuntu 22.04 or 24.04. See the platform table above. Fall back to USB.

A device you know is nearby is missing from device list --ble-scan. Most likely the scan window was too short; retry with --ble-scan-timeout 20. Without --ble-scan the listing does not check presence at all, so a device appearing there means only that this host has stored credentials for it.

BLE connect requires --serial. Despite the wording, this means no device is paired over BLE on this host — adding a serial will not fix it. Connect over USB and run aria_gen2 auth pair --ble.

Multiple BLE-paired devices are stored. Use --serial to pick one:. More than one device has credentials here, so the CLI will not guess. Pick one from the list it prints.

No BLE credentials for <serial>; run 'auth pair --ble' first. That specific device has no credentials on this host, or they were removed by auth unpair --ble / auth remove-ble-creds. Reconnect over USB and pair again.

A command hangs for ~35 seconds, then fails. A BLE attempt against a device that is powered off or out of range. Stored pairings are not presence-checked, so the CLI cannot tell in advance. See Automatic fallback to BLE.

Recording or streaming fails over BLE. Not supported — reconnect over USB or Wi-Fi for anything that moves sensor data.

See also​