Skip to main content
Use the box’s own Bluetooth adapter to find your DUT advertising, connect to it, and enumerate its GATT services.

Handle

BLE is a box-level capability, not a net: it drives the box’s own adapter. There is no net name and no name().

Methods

Types

The GATT methods take impl Into<GattChar>, so pass a UUID string or a handle. Use a handle when a device has two characteristics with the same UUID.

Method Reference

scan(timeout: f64) -> Result<Vec<BleDevice>>

Scan for advertising devices for timeout seconds, which must be between 0.1 and 300. Named devices sort first.

scan_named(timeout: f64, name_contains: &str) -> Result<Vec<BleDevice>>

The same scan, filtered by a case-insensitive name substring.

scan_exact(timeout: f64, name: &str) -> Result<Vec<BleDevice>>

Scan for devices with exactly this name.

info(address: &str) -> Result<BleDeviceInfo>

Connect briefly and enumerate the device’s GATT services.

connect(address: &str) -> Result<BleDeviceInfo> and disconnect(address: &str) -> Result<()>

Connect to, or ensure disconnection from, a device by address.

info_with_timeout(address: &str, timeout: f64) and connect_with_timeout(address: &str, timeout: f64)

The same calls, for a device that needs longer than the default 10 s connect timeout.

read(address: &str, characteristic: impl Into<GattChar>) -> Result<Vec<u8>>

Read a GATT characteristic’s value.

write(address: &str, characteristic: impl Into<GattChar>, data: &[u8]) -> Result<()>

Write a GATT characteristic. The box picks write-with-response or write-without-response from the characteristic’s properties. write_with_response(address, characteristic, data, response: bool) lets you choose: true for with-response, false for without.

notify(address: &str, characteristic: impl Into<GattChar>, max_messages: u32, duration: f64) -> Result<BleNotifications>

Subscribe to a characteristic and collect its notifications. Collection stops when max_messages (1-10000) arrive, or after duration seconds (0.1-300). The box then unsubscribes. A short count is not an error: it comes back with timed_out set.

pair(address: &str) -> Result<()>

Pair with a device through the box’s BlueZ, which keeps the bond. The GATT methods and pair() require box software 0.62.0 or later. An older box fails with Error::UnsupportedByBox.

Examples

Assert the DUT advertises with the right service

Notes

  • One adapter per box. The box serializes all BLE and BluFi work on it, so concurrent calls queue rather than fail. A BluFi provisioning run and a BLE scan cannot overlap.
  • capabilities.ble_command being true means the box serves the route, not that it can do the work. A box whose host has no BlueZ running answers with Error::Box and HTTP 502 carrying BlueZ is not running on the box host (an older box image sends The name org.bluez was not provided by any .service files). This happens even with a Bluetooth controller present on the USB bus. Check the error, not just the capability flag. lager update installs BlueZ on the host.
  • The box-side connect timeout for info, connect and disconnect is 10 seconds; the client allows that plus 30.
  • Each GATT call connects, does its one operation and disconnects. So this API cannot drive a device that needs one connection held across operations. Data is bytes in the API and hex on the wire.
  • rssi is a snapshot from the advertisement that happened to be received. Treat it as an ordering hint, not a measurement.