BLE host API for plugins: read-only state, a single reserved GATT server service (peripheral), and the central (GATT client) role. More...

#include "cdc_hal/IBluetoothController.h"
#include "plugin_manager/host_api.h"
#include "esp_attr.h"
#include "plugin_manager/Plugin.h"
#include "plugin_manager/PluginManager.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include <cstring>

Classes
class	IBluetoothController
struct	BleUuid
struct	GattServiceDef
struct	GattCharacteristic
struct	BleScanResult

Functions
void *	plg_get_active_plugin (void)
bool	host_ble_is_enabled (void)
	True when the BLE stack is initialised and advertising or connectable.
int	host_ble_mac (uint8_t out[6])
	Read the local BLE MAC address.
int	host_ble_device_name (char *out, size_t out_size)
	Copy the local BLE device name into out.
int8_t	host_ble_rssi (void)
	Signal strength of the active BLE link in dBm, or 0 when idle.
int	host_ble_register_service (ble_service_def_t def, ble_char_def_t chars, uint32_t num_chars)
	Register the plugin's GATT service and its characteristics.
int	host_ble_unregister_service (uint32_t service_handle)
	Tear down the plugin's registered GATT service.
static int	periph_send (uint32_t char_handle, const uint8_t *data, size_t len, bool indicate)
int	host_ble_send_notification (uint32_t char_handle, const uint8_t *data, size_t len)
	Notify subscribers of a value on one of the plugin's characteristics.
int	host_ble_send_indication (uint32_t char_handle, const uint8_t *data, size_t len)
	Indicate (acknowledged notify) a value on a plugin characteristic.
int	host_ble_consume_write (uint32_t char_handle, uint8_t *buf, size_t buf_size)
	Pull the next queued inbound write for char_handle.
int	host_ble_scan_start (uint32_t duration_ms)
	Start a central scan for duration_ms milliseconds.
bool	host_ble_scan_done (void)
	True when the scan started by host_ble_scan_start() has finished.
int	host_ble_scan_results (ble_scan_result_t out, size_t count)
	Read results from the last central scan.
int	host_ble_connect (const uint8_t addr[6], uint8_t addr_type)
	Connect to a peer. Completion arrives as a BLE_CONNECTED event; read the resulting handle with host_ble_conn_handle().
uint32_t	host_ble_conn_handle (void)
	Current connection handle (central or peripheral), or 0 when idle.
int	host_ble_disconnect (uint32_t conn)
	Disconnect a connection.
int	host_ble_discover (uint32_t conn, const uint8_t uuid[16], uint32_t action_id)
	Discover the characteristics of one service on a connected peer. Completion fires action_id; read entries with host_ble_consume_discovery().
int	host_ble_consume_discovery (ble_remote_char_t out, size_t count)
	Pull discovered characteristics after a discovery action fires.
int	host_ble_read_char (uint32_t conn, uint16_t value_handle, uint32_t action_id)
	Start reading a peer characteristic by value handle. Completion fires action_id; read the value with host_ble_consume_read().
int	host_ble_consume_read (uint8_t *buf, size_t buf_size)
	Pull the value delivered by the last read action.
int	host_ble_write_char (uint32_t conn, uint16_t value_handle, const uint8_t *data, size_t len, uint8_t with_response)
	Write a value to a peer characteristic by value handle.
int	host_ble_subscribe (uint32_t conn, uint16_t cccd_handle, uint32_t action_id)
	Subscribe to notifications on a peer characteristic (by CCCD handle). Each notification fires action_id; read it with host_ble_consume_notification().
int	host_ble_consume_notification (uint16_t value_handle_out, uint8_t buf, size_t buf_size)
	Pull the next queued inbound notification.
void	plg_ble_pump (void)
void	plg_ble_on_unload (void *plugin)
IBluetoothController *	getBluetoothControllerInstance ()
	Returns singleton Bluetooth stub when NimBLE is unavailable.

Detailed Description

BLE host API for plugins: read-only state, a single reserved GATT server service (peripheral), and the central (GATT client) role.

Threading: the NimBLE stack invokes the GATT write / central callbacks on its own task. Those callbacks never call into WASM; they copy the payload into a mutex-protected ring and set a pending flag. plg_ble_pump() runs on the plugin tick task (under the plugin call mutex) and fires the plugin's action, which then pulls the payload with a host_ble_consume_* call - the same deferred pattern the command channel uses.

Only one plugin GATT service slot exists (the reserved BluetoothController slot) and only one BLE connection exists at a time, so peripheral and central state is single-instance rather than a per-plugin table.

Definition in file host_api_ble.cpp.