Module capsules_extra::ble_advertising_driver

source ·
Expand description

Bluetooth Low Energy Advertising Driver

A system call driver that exposes the Bluetooth Low Energy advertising channel. The driver generates a unique static address for each process, allowing each process to act as its own device and send or scan for advertisements. Timing of advertising or scanning events is handled by the driver but processes can request an advertising or scanning interval. Processes can also control the TX power used for their advertisements.

Data payloads are limited to 31 bytes since the maximum advertising channel protocol data unit (PDU) is 37 bytes and includes a 6-byte header.

§Allow system calls

There is one ReadWrite and one ReadOnly allow buffers, both at index 0.

  • ReadOnly: Advertising data, containing the full payload (i.e. excluding the header) the process wishes to advertise.
  • ReadWrite: Passive scanning buffer, which is populated during BLE scans with complete (i.e. including headers) advertising packets received on channels 37, 38 and 39.

The possible return codes from the ‘allow’ system call indicate the following:

  • Ok(()): The buffer has successfully been filled
  • NOMEM: No sufficient memory available
  • INVAL: Invalid address of the buffer or other error
  • BUSY: The driver is currently busy with other tasks
  • ENOSUPPORT: The operation is not supported
  • ERROR: Operation map on Option failed

§Subscribe system call

The subscribe system call supports two arguments subscribe number' and callback. The subscribe` is used to specify the specific operation, currently:

  • 0: provides a callback user-space when a device scanning for advertisements and the callback is used to invoke user-space processes.

The possible return codes from the allow system call indicate the following:

  • NOMEM: Not sufficient amount memory
  • INVAL: Invalid operation

§Command system call

The command system call supports two arguments command number and subcommand number. command number is used to specify the specific operation, currently the following commands are supported:

  • 0: start advertisement
  • 1: stop advertisement or scanning
  • 5: start scanning

The possible return codes from the command system call indicate the following:

  • Ok(()): The command was successful
  • BUSY: The driver is currently busy with other tasks
  • ENOSUPPORT: The operation is not supported

§Usage

You need a device that provides the kernel::BleAdvertisementDriver trait along with a virtual timer to perform events and not block the entire kernel

ⓘ

let ble_radio = static_init!(
nrf5x::ble_advertising_driver::BLE<
    'static,
    nrf52::radio::Radio, VirtualMuxAlarm<'static, Rtc>
>,
nrf5x::ble_advertising_driver::BLE::new(
    &mut nrf52::radio::RADIO,
    board_kernel.create_grant(&grant_cap),
    &mut nrf5x::ble_advertising_driver::BUF,
    ble_radio_virtual_alarm));
nrf5x::ble_advertising_hil::BleAdvertisementDriver::set_rx_client(&nrf52::radio::RADIO,
                                                                  ble_radio);
nrf5x::ble_advertising_hil::BleAdvertisementDriver::set_tx_client(&nrf52::radio::RADIO,
                                                                  ble_radio);
ble_radio_virtual_alarm.set_client(ble_radio);

§Authors

Structs§

Constants§