Skip to main content

BT Functions

dev.wireless.bluetooth_le - wire path w\b - generated from fwMenuBluetoothLE.

on_start_bt_advertising​

Start BT Advertising. Sets the Host Name for the Bluetooth LE

Start BT Advertising​

Starts BT LE advertising on the FreeWili's ESP32-C5 wireless co-processor using the supplied advertising (host) name. Once advertising, the FreeWili is discoverable by BLE central devices (phones, laptops, scanners, etc.).

Arguments​
  • hostname (string, required) — The BLE advertising name to broadcast.
    • Must be 1–32 characters.
    • Sent as the device's advertised local name.
Returns​
  • success (basic) — true if advertising was started, false otherwise.
Behavior​
  1. Verifies the ESP32-C5 is connected. If not, prints ESP32 Not Connected and returns false.
  2. Validates the hostname (non-empty, within length limits).
  3. Stores the name in persistent menu settings (szBTAdv) and enables BLE (m_bEnableBLE = true).
  4. Pushes the updated configuration to the wireless module via UpdateBottleNoseSettings().
Failure Cases​
  • ESP32-C5 is not connected.
  • hostname is empty.
  • hostname exceeds the maximum allowed length.
  • Stop BT Advertising — stops the BLE advertisement.
  • Enable Terminal API Mode — exposes the FreeWili Terminal API over BLE.
  • Scan for BT Devices — scans for nearby BLE peripherals.
Example​
a
MyFreeWili

Advertises the device as MyFreeWili.

Wire command: w\b\a

ArgWire type
hostnamestring

Returns: none (Ok/Err only)

dev.wireless.bluetooth_le.on_start_bt_advertising(hostname: str) -> Result
ow_status ow_wireless_bluetooth_le_on_start_bt_advertising(ow_device* dev, const char* hostname);
dev.wireless().bluetooth_le().on_start_bt_advertising(hostname: &str) -> Result<(), OwError>

The C and Rust signatures above are also the WASM guest signatures - the device API surface is identical; only the transport differs (ow_open_wasm(&dev) in C, OneWili::open() in Rust).

dev.wireless.bluetooth_le.on_start_bt_advertising(hostname)   # check dev.ok

on_stop_bt_advertising​

Stop BT Advertising. Stops BT Advertising

Stop BT Advertising​

Stops BLE advertising on the FreeWili's ESP32-C5 wireless co-processor. After this command, the FreeWili is no longer discoverable by BLE central devices (phones, laptops, scanners, etc.).

Arguments​

None.

Returns​
  • success (basic) — true if advertising was stopped, false otherwise.
Behavior​
  1. Verifies the ESP32-C5 is connected. If not, prints ESP32 Not Connected and returns false.
  2. Disables BLE in persistent menu settings (m_bEnableBLE = false).
  3. Pushes the updated configuration to the wireless module via UpdateBottleNoseSettings().
Failure Cases​
  • ESP32-C5 is not connected.
  • Start BT Advertising — begins BLE advertising with a chosen host name.
  • Enable Terminal API Mode — exposes the FreeWili Terminal API over BLE.
  • Scan for BT Devices — scans for nearby BLE peripherals.
Example​
t

Stops BLE advertising on the device.

Wire command: w\b\t

Returns: none (Ok/Err only)

dev.wireless.bluetooth_le.on_stop_bt_advertising() -> Result
ow_status ow_wireless_bluetooth_le_on_stop_bt_advertising(ow_device* dev);
dev.wireless().bluetooth_le().on_stop_bt_advertising() -> Result<(), OwError>

The C and Rust signatures above are also the WASM guest signatures - the device API surface is identical; only the transport differs (ow_open_wasm(&dev) in C, OneWili::open() in Rust).

dev.wireless.bluetooth_le.on_stop_bt_advertising()   # check dev.ok

on_scan_bt_devices​

Scan for BT Devices. Scans for BT devices for a given duration

Scan for BT Devices​

Performs a Bluetooth LE scan on the FreeWili's ESP32-C5 wireless co-processor for the specified duration. Discovered peripherals are reported asynchronously as btscan events containing the advertised name, MAC address, and RSSI.

Arguments​
  • durationms (decU32, required) — Scan duration in milliseconds. Must be a positive integer.
Returns​
  • success (basic) — true if the scan was successfully started, false otherwise.
Behavior​

  1. Verifies the ESP32-C5 is connected. If not, prints ESP32 Not Connected and returns false.

  2. Parses durationms from the input. On parse failure, returns false.

  3. Starts a BLE scan via startBluetoothLEScan(true, durationms).

  4. For each device discovered, an event is emitted under the btscan channel with the format:

    <deviceName> <AA:BB:CC:DD:EE:FF> <rssi>
    • deviceName — advertised local name (up to 32 characters; may be empty)
    • MAC address — 6 bytes, colon-separated, lowercase hex
    • rssi — signed received signal strength in dBm
Failure Cases​
  • ESP32-C5 is not connected.
  • durationms is missing or not a valid unsigned integer.
  • Start BT Advertising — begins BLE advertising with a chosen host name.
  • Stop BT Advertising — stops the BLE advertisement.
  • Enable Terminal API Mode — exposes the FreeWili Terminal API over BLE.
Example​
s
5000

Scans for nearby BLE devices for 5 seconds, streaming each discovery as a btscan event.

Wire command: w\b\s

ArgWire type
durationmsdecU32

Returns: none (Ok/Err only)

dev.wireless.bluetooth_le.on_scan_bt_devices(durationms: int) -> Result
ow_status ow_wireless_bluetooth_le_on_scan_bt_devices(ow_device* dev, int32_t durationms);
dev.wireless().bluetooth_le().on_scan_bt_devices(durationms: i32) -> Result<(), OwError>

The C and Rust signatures above are also the WASM guest signatures - the device API surface is identical; only the transport differs (ow_open_wasm(&dev) in C, OneWili::open() in Rust).

dev.wireless.bluetooth_le.on_scan_bt_devices(durationms)   # check dev.ok

on_enable_terminal​

Toggle Enable Terminal API Mode. Enables BLE to FreeWili Terminal API Mode

Toggle Enable Terminal API Mode​

Toggles the FreeWili Terminal API exposure over BT LE on the ESP32-C5 wireless co-processor. When enabled, BLE central devices (phones, laptops, scripts, agents) can connect to the FreeWili and drive the same Terminal/CLI API that is normally available over USB. When disabled, the BLE GATT service for the Terminal API is torn down.

This is a toggle: each invocation flips the current state.

Arguments​

None.

Returns​
  • success (basic) — true if the toggle was applied and pushed to the wireless module, false otherwise.
Behavior​
  1. Verifies the ESP32-C5 is connected. If not, prints ESP32 Not Connected and returns false.
  2. Inverts the persistent setting m_bEnableBLETerm (on ↔ off).
  3. Pushes the updated configuration to the wireless module via UpdateBottleNoseSettings().
  4. Returns true.
Notes​
  • BLE advertising must be running (see Start BT Advertising) for central devices to discover and connect to the Terminal API.
  • Because this is a toggle, run it twice to return to the original state.
  • The new state is persisted in menu settings and survives subsequent setting updates.
Failure Cases​
  • ESP32-C5 is not connected.
  • Start BT Advertising — begins BLE advertising with a chosen host name.
  • Stop BT Advertising — stops the BLE advertisement.
  • Scan for BT Devices — scans for nearby BLE peripherals.
Example​
e

Toggles Terminal API over BLE. Run once to enable, again to disable.

Wire command: w\b\e

Returns: none (Ok/Err only)

dev.wireless.bluetooth_le.on_enable_terminal() -> Result
ow_status ow_wireless_bluetooth_le_on_enable_terminal(ow_device* dev);
dev.wireless().bluetooth_le().on_enable_terminal() -> Result<(), OwError>

The C and Rust signatures above are also the WASM guest signatures - the device API surface is identical; only the transport differs (ow_open_wasm(&dev) in C, OneWili::open() in Rust).

dev.wireless.bluetooth_le.on_enable_terminal()   # check dev.ok

ble_open_settings​

Bluetooth LE Settings. Opens the Bluetooth LE settings menu

Wire command: w\b\b

Returns: none (Ok/Err only)

dev.wireless.bluetooth_le.ble_open_settings() -> Result
ow_status ow_wireless_bluetooth_le_ble_open_settings(ow_device* dev);
dev.wireless().bluetooth_le().ble_open_settings() -> Result<(), OwError>

The C and Rust signatures above are also the WASM guest signatures - the device API surface is identical; only the transport differs (ow_open_wasm(&dev) in C, OneWili::open() in Rust).

dev.wireless.bluetooth_le.ble_open_settings()   # check dev.ok