Skip to main content

Bluetooth LE

These commands are available three ways — in the FREE-WILi GUI app, in a serial terminal, and on the device itself. See Connecting it to a computer for how to reach them.

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

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.

How to use it — press a. At the prompt, enter: String: Advertising Name.

What you enter — hostname.

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

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.

How to use it — press t.

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.

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.

How to use it — press s. At the prompt, enter: scan duration in milliseconds:

What you enter — durationms.

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.

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.

How to use it — press e.

See also: Bluetooth panel — the on-screen panel for this.