Bluetooth Low Energy peripheral and central operations. More...

Classes
struct	ble_char_def_t
	One characteristic of a plugin GATT service (peripheral role). More...
struct	ble_service_def_t
	A plugin GATT service definition (peripheral role). Always primary. More...
struct	ble_scan_result_t
	One device from a central scan. More...
struct	ble_remote_char_t
	One characteristic discovered on a connected peer (central role). More...

Macros
#define	BLE_PROP_READ 0x02
#define	BLE_PROP_WRITE_NO_RSP 0x04
#define	BLE_PROP_WRITE 0x08
#define	BLE_PROP_NOTIFY 0x10
#define	BLE_PROP_INDICATE 0x20

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

Detailed Description

Bluetooth Low Energy peripheral and central operations.

Plugins can publish GATT services as a peripheral and, with the appropriate capability, scan and talk to remote devices as a central.

Macro Definition Documentation

◆ BLE_PROP_INDICATE

#define BLE_PROP_INDICATE 0x20

Definition at line 477 of file host_api.h.

◆ BLE_PROP_NOTIFY

#define BLE_PROP_NOTIFY 0x10

Definition at line 476 of file host_api.h.

◆ BLE_PROP_READ

#define BLE_PROP_READ 0x02

Definition at line 473 of file host_api.h.

Referenced by host_ble_register_service().

◆ BLE_PROP_WRITE

#define BLE_PROP_WRITE 0x08

Definition at line 475 of file host_api.h.

Referenced by host_ble_register_service().

◆ BLE_PROP_WRITE_NO_RSP

#define BLE_PROP_WRITE_NO_RSP 0x04

Definition at line 474 of file host_api.h.

Referenced by host_ble_register_service().

Function Documentation

◆ host_ble_conn_handle()

uint32_t host_ble_conn_handle ( void )

Current connection handle (central or peripheral), or 0 when idle.

Definition at line 383 of file host_api_ble.cpp.

Referenced by cdc::plugin_manager::w_host_ble_conn_handle().

◆ host_ble_connect()

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

Definition at line 373 of file host_api_ble.cpp.

References HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, and plg_get_active_plugin().

Referenced by cdc::plugin_manager::w_host_ble_connect().

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

Parameters

count In: capacity of out; out: entries written.

Definition at line 411 of file host_api_ble.cpp.

References HOST_ERR_INVALID_ARG, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_ble_consume_discovery().

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

Parameters

value_handle_out Receives the source characteristic value handle.

Returns: Bytes copied (>= 0), or a negative HOST_ERR_* code.

Definition at line 465 of file host_api_ble.cpp.

References HOST_ERR_INVALID_ARG, and HOST_ERR_NOT_FOUND.

Referenced by cdc::plugin_manager::w_host_ble_consume_notification().

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

Returns: Bytes copied (>= 0), or a negative HOST_ERR_* code.

Definition at line 433 of file host_api_ble.cpp.

References HOST_ERR_INVALID_ARG.

Referenced by cdc::plugin_manager::w_host_ble_consume_read().

◆ host_ble_consume_write()

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.

Call from the characteristic's write_action_id handler; the action fires with idx set to the characteristic handle and user_data to the connection handle.

Returns: Bytes copied (>= 0), or a negative HOST_ERR_* code.

Definition at line 334 of file host_api_ble.cpp.

References HOST_ERR_INVALID_ARG.

Referenced by cdc::plugin_manager::w_host_ble_consume_write().

◆ host_ble_device_name()

int host_ble_device_name	(	char *	out,
		size_t	out_size )

Copy the local BLE device name into out.

Definition at line 224 of file host_api_ble.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, HOST_OK, and name.

Referenced by cdc::plugin_manager::w_host_ble_device_name().

◆ host_ble_disconnect()

int host_ble_disconnect ( uint32_t conn )

Disconnect a connection.

Definition at line 390 of file host_api_ble.cpp.

References HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_ble_disconnect().

◆ host_ble_discover()

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

Definition at line 398 of file host_api_ble.cpp.

References BleUuid::from128(), HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, and plg_get_active_plugin().

Referenced by cdc::plugin_manager::w_host_ble_discover().

◆ host_ble_is_enabled()

bool host_ble_is_enabled ( void )

True when the BLE stack is initialised and advertising or connectable.

Definition at line 215 of file host_api_ble.cpp.

Referenced by cdc::plugin_manager::w_host_ble_is_enabled().

◆ host_ble_mac()

int host_ble_mac ( uint8_t out[6] )

Read the local BLE MAC address.

Definition at line 217 of file host_api_ble.cpp.

References HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_ble_mac().

◆ host_ble_read_char()

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

Definition at line 421 of file host_api_ble.cpp.

References HOST_ERR_GENERIC, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, and plg_get_active_plugin().

Referenced by cdc::plugin_manager::w_host_ble_read_char().

◆ host_ble_register_service()

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.

Fills def->service_handle and each chars[i].char_handle. The service UUID must not be a reserved system UUID and a plugin service slot must be free.

Parameters

def	Service definition; service_handle is written back.
chars	Characteristic array; char_handle is written back per entry.
num_chars	Number of characteristics (1..6).

Definition at line 238 of file host_api_ble.cpp.

References BLE_PROP_READ, BLE_PROP_WRITE, BLE_PROP_WRITE_NO_RSP, ble_char_def_t::char_handle, cdc::hal::GattServiceDef::characteristics, BleUuid::from128(), HOST_ERR_BUSY, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, cdc::hal::GattServiceDef::numCharacteristics, cdc::hal::GattCharacteristic::onWrite, cdc::hal::GattCharacteristic::permissions, plg_get_active_plugin(), ble_char_def_t::properties, cdc::hal::GattCharacteristic::properties, cdc::hal::GattPerm::READ, ble_service_def_t::service_handle, ble_service_def_t::uuid, cdc::hal::GattCharacteristic::uuid, cdc::hal::GattServiceDef::uuid, cdc::hal::GattCharacteristic::valueHandle, cdc::hal::GattPerm::WRITE, and ble_char_def_t::write_action_id.

Referenced by cdc::plugin_manager::w_host_ble_register_service().

◆ host_ble_rssi()

int8_t host_ble_rssi ( void )

Signal strength of the active BLE link in dBm, or 0 when idle.

Definition at line 234 of file host_api_ble.cpp.

Referenced by cdc::plugin_manager::w_host_ble_rssi().

◆ host_ble_scan_done()

bool host_ble_scan_done ( void )

True when the scan started by host_ble_scan_start() has finished.

Definition at line 352 of file host_api_ble.cpp.

Referenced by cdc::plugin_manager::w_host_ble_scan_done().

◆ host_ble_scan_results()

int host_ble_scan_results	(	ble_scan_result_t *	out,
		size_t *	count )

Read results from the last central scan.

Parameters

count In: capacity of out; out: entries written.

Definition at line 354 of file host_api_ble.cpp.

References ble_scan_result_t::addr_type, cdc::hal::BleScanResult::addrType, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, ble_scan_result_t::name, name, ble_scan_result_t::rssi, and cdc::hal::BleScanResult::rssi.

Referenced by cdc::plugin_manager::w_host_ble_scan_results().

◆ host_ble_scan_start()

int host_ble_scan_start ( uint32_t duration_ms )

Start a central scan for duration_ms milliseconds.

Definition at line 345 of file host_api_ble.cpp.

References HOST_ERR_GENERIC, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_ble_scan_start().

◆ host_ble_send_indication()

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.

Definition at line 330 of file host_api_ble.cpp.

References periph_send().

Referenced by cdc::plugin_manager::w_host_ble_send_indication().

◆ host_ble_send_notification()

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.

Definition at line 326 of file host_api_ble.cpp.

References periph_send().

Referenced by cdc::plugin_manager::w_host_ble_send_notification().

◆ host_ble_subscribe()

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

Definition at line 454 of file host_api_ble.cpp.

References HOST_ERR_GENERIC, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, and plg_get_active_plugin().

Referenced by cdc::plugin_manager::w_host_ble_subscribe().

◆ host_ble_unregister_service()

int host_ble_unregister_service ( uint32_t service_handle )

Tear down the plugin's registered GATT service.

Definition at line 301 of file host_api_ble.cpp.

References BleUuid::from128(), HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, and plg_get_active_plugin().

Referenced by cdc::plugin_manager::w_host_ble_unregister_service().

◆ host_ble_write_char()

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.

Definition at line 443 of file host_api_ble.cpp.

References HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_ble_write_char().

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ BLE_PROP_INDICATE

◆ BLE_PROP_NOTIFY

◆ BLE_PROP_READ

◆ BLE_PROP_WRITE

◆ BLE_PROP_WRITE_NO_RSP

Function Documentation

◆ host_ble_conn_handle()

◆ host_ble_connect()

◆ host_ble_consume_discovery()

◆ host_ble_consume_notification()

◆ host_ble_consume_read()

◆ host_ble_consume_write()

◆ host_ble_device_name()

◆ host_ble_disconnect()

◆ host_ble_discover()

◆ host_ble_is_enabled()

◆ host_ble_mac()

◆ host_ble_read_char()

◆ host_ble_register_service()

◆ host_ble_rssi()

◆ host_ble_scan_done()

◆ host_ble_scan_results()

◆ host_ble_scan_start()

◆ host_ble_send_indication()

◆ host_ble_send_notification()

◆ host_ble_subscribe()

◆ host_ble_unregister_service()

◆ host_ble_write_char()