BLE communications submodule

Communications submodule that is used to deal with BTLE and HID over GATT specifics. More...

Data Structures
struct	m_coms_ble_adv_params_t
	BLE Advertising parameters. More...
struct	m_coms_ble_bond_params_t
	BLE bond behavior parameters. More...
struct	m_coms_ble_device_info_t
	Device Information Service parameters. For more information, see this page . More...
struct	m_coms_ble_evt_adv_data_t
	Advertising state event details. More...
struct	m_coms_ble_evt_alert_t
	Immediate Alert details. More...
struct	m_coms_ble_evt_conn_data_t
	Connection state event details. More...
struct	m_coms_ble_evt_conn_update_t
	Connection update event details. More...
struct	m_coms_ble_evt_data_recv_t
	Data received event details. More...
struct	m_coms_ble_evt_mtu_changed_t
	MTU Changed event details. More...
struct	m_coms_ble_evt_read_req_t
	Read request event details. More...
struct	m_coms_ble_evt_t
	Event structs generated by this module. More...
struct	m_coms_ble_evt_tx_complete_t
	TX Complete event details. More...
struct	m_coms_ble_params_t
	BLE parameters. More...
struct	m_coms_ble_sec_params_t
	BLE security parameters. More...
union	m_coms_hid_boot_pkt_t
	Packet definition used for boot reports. More...

Typedefs
typedef void(*	m_coms_ble_boot_mode_callback )(m_coms_hid_boot_pkt_t *p_boot_pkt, m_coms_ble_hid_boot_type_t *p_pkt_type, const uint8_t *p_data, uint8_t p_len, uint8_t p_hid_interface, uint8_t p_report_idx)
	When in boot mode (BLE HID), a specific format is used for mouse and keyboard packets regardless of the HID descriptor. The application will be tasked to reassemble keyboard and mouse packets to fit the specified format. More...

Enumerations
enum	m_coms_ble_evt_type_t {   M_COMS_BLE_EVT_CONNECTED, M_COMS_BLE_EVT_DISCONNECTED, M_COMS_BLE_EVT_DATA_RECEIVED, M_COMS_BLE_EVT_READ_REQ,   M_COMS_BLE_EVT_CONN_UPDATE, M_COMS_BLE_EVT_CONN_SECURED, M_COMS_BLE_EVT_ADV, M_COMS_BLE_EVT_ADV_BONDABLE,   M_COMS_BLE_EVT_ADV_TIMEOUT, M_COMS_BLE_EVT_ADDR_CHANGED, M_COMS_BLE_EVT_PASSKEY_REQ, M_COMS_BLE_EVT_OOBKEY_REQ,   M_COMS_BLE_EVT_ALERT, M_COMS_BLE_EVT_TX_COMPLETE, M_COMS_BLE_EVT_MTU_CHANGED, M_COMS_BLE_EVT_SHUTDOWN }
	Event types generated by this module. More...
enum	m_coms_ble_hid_boot_type_t { ble_boot_pkt_keyboard = 0x01, ble_boot_pkt_mouse = 0x02, ble_boot_pkt_none = 0x80 }
	When in BLE HID (HID over GATT) boot mode, only keyboard and mouse packets of a specified format can be sent. More...
enum	m_coms_hid_report_type_t
	HID report types.

Functions
ret_code_t	m_coms_ble_advertise (bool bondable)
	Function for starting advertising. More...
ret_code_t	m_coms_ble_battery_level_update (uint8_t p_batt_level)
	Function for updating the battery level. More...
ret_code_t	m_coms_ble_bond_clear (void)
	Function for deleting bonding data stored in flash. More...
bool	m_coms_ble_bond_stored (void)
	Function for checking whether bonding data is kept in flash. More...
ret_code_t	m_coms_ble_bonding_start (void)
	Function for starting the bonding procedure. More...
ret_code_t	m_coms_ble_disconnect (void)
	Function for disconnecting. More...
ret_code_t	m_coms_ble_hid_report_send (uint8_t *p_data, uint8_t p_len, uint8_t p_hid_interface, uint8_t p_report_idx)
	Function for sending a HID report. More...
ret_code_t	m_coms_ble_init (const m_coms_ble_params_t *p_ble_params, const struct ble_hid_db_s *p_hid_db, bool delete_bonds)
	Function for initializing BLE. More...
ret_code_t	m_coms_ble_oobkey_set (uint8_t *p_key)
	Function for setting the OOB key for encrypted OOB connections. More...
ret_code_t	m_coms_ble_read_respond (uint8_t *p_data, uint8_t p_len)
	Function for responding to a read request (M_COMS_BLE_EVT_READ_REQ). More...
ret_code_t	m_coms_ble_shutdown (void)
	Function for disconnecting and stopping advertising. More...
ret_code_t	m_coms_ble_sl_disable (void)
	Function for disabling slave latency. More...
ret_code_t	m_coms_ble_sl_enable (void)
	Function for enabling slave latency. More...

Detailed Description

Communications submodule that is used to deal with BTLE and HID over GATT specifics.

Typedef Documentation

typedef void(* m_coms_ble_boot_mode_callback)(m_coms_hid_boot_pkt_t *p_boot_pkt, m_coms_ble_hid_boot_type_t *p_pkt_type, const uint8_t *p_data, uint8_t p_len, uint8_t p_hid_interface, uint8_t p_report_idx)

When in boot mode (BLE HID), a specific format is used for mouse and keyboard packets regardless of the HID descriptor. The application will be tasked to reassemble keyboard and mouse packets to fit the specified format.

For more information, see this page . Non-keyboard and mouse packets will be discarded in boot mode.

Parameters

[in,out]	p_boot_pkt	Resulting boot packet.
[in]	p_pkt_type	Boot packet type.
[in]	p_data	Original packet.
[in]	p_len	Length of the original packet.
[in]	p_hid_interface	The interface index on which the packet was sent.
[in]	p_report_idx	Report index used.

Enumeration Type Documentation

enum m_coms_ble_evt_type_t

Event types generated by this module.

Enumerator
M_COMS_BLE_EVT_CONNECTED	Connected.
M_COMS_BLE_EVT_DISCONNECTED	Disconnected.
M_COMS_BLE_EVT_DATA_RECEIVED	Data received.
M_COMS_BLE_EVT_READ_REQ	Read request received.
M_COMS_BLE_EVT_CONN_UPDATE	Connection parameter update.
M_COMS_BLE_EVT_CONN_SECURED	Connection secured.
M_COMS_BLE_EVT_ADV	Non-Bondable advertising is running.
M_COMS_BLE_EVT_ADV_BONDABLE	Bondable advertising is running.
M_COMS_BLE_EVT_ADV_TIMEOUT	Advertising has timed out.
M_COMS_BLE_EVT_ADDR_CHANGED	Address has changed.
M_COMS_BLE_EVT_PASSKEY_REQ	Passkey requested.
M_COMS_BLE_EVT_OOBKEY_REQ	OOB key requested.
M_COMS_BLE_EVT_ALERT	Immediate Alert level changed.
M_COMS_BLE_EVT_TX_COMPLETE	Transmission complete.
M_COMS_BLE_EVT_MTU_CHANGED	Connection MTU has changed.
M_COMS_BLE_EVT_SHUTDOWN	BLE Shutdown complete.

enum m_coms_ble_hid_boot_type_t

When in BLE HID (HID over GATT) boot mode, only keyboard and mouse packets of a specified format can be sent.

Note

Bitmask type enum: valid values are powers of 2.

Enumerator
ble_boot_pkt_keyboard	Keyboard boot report.
ble_boot_pkt_mouse	Mouse boot report.
ble_boot_pkt_none	Not a keyboard/mouse boot report. Will not be sent in boot mode.

Function Documentation

ret_code_t m_coms_ble_advertise

(

bool

bondable

)

Function for starting advertising.

Parameters

[in]

bondable

True, if bondable advertising should be started.

Returns

NRF_SUCCESS on success, otherwise error code.

ret_code_t m_coms_ble_battery_level_update

(

uint8_t

p_batt_level

)

Function for updating the battery level.

Parameters

[in]

p_batt_level

Battery level.

Returns

Return values

NRF_SUCCESS
NRF_ERROR_INVALID_PARAM

ret_code_t m_coms_ble_bond_clear

(

void

)

Function for deleting bonding data stored in flash.

Returns

Return values

NRF_SUCCESS

bool m_coms_ble_bond_stored

(

void

)

Function for checking whether bonding data is kept in flash.

Note

The module MUST be initialized prior to calling the function.

Returns

True if the keys from the previous connection are stored in flash.

ret_code_t m_coms_ble_bonding_start

(

void

)

Function for starting the bonding procedure.

Advertising for a new bond will be started according to parameters (m_coms_ble_init).

Note

It will cause a disconnect if connected.

Returns

Return values

NRF_SUCCESS
NRF_ERROR_INVALID_STATE
NRF_ERROR_INTERNAL

ret_code_t m_coms_ble_disconnect

(

void

)

Function for disconnecting.

Note

The time it takes to disconnect properly depends on connection parameters.

Returns

Return values

NRF_SUCCESS
NRF_ERROR_x

ret_code_t m_coms_ble_hid_report_send	(	uint8_t *	p_data,
		uint8_t	p_len,
		uint8_t	p_hid_interface,
		uint8_t	p_report_idx
	)

Function for sending a HID report.

Note

Report length cannot exceed 20 bytes.

Parameters

[in]	p_data	HID report data to send.
[in]	p_len	Length of report data.
[in]	p_hid_interface	HID interface ID.
[in]	p_report_idx	HID Report index.

Returns

Return values

NRF_SUCCESS
NRF_ERROR_INVALID_PARAM
NRF_ERROR_INVALID_STATE
BLE_ERROR_NO_TX_BUFFERS

ret_code_t m_coms_ble_init	(	const m_coms_ble_params_t *	p_ble_params,
		const struct ble_hid_db_s *	p_hid_db,
		bool	delete_bonds
	)

Function for initializing BLE.

SoftDevice, Battery service, and Device Information Service will be initialized. p_ble_params may be 0 if m_coms_ble_init() is called multiple times, as the parameters are saved in flash. The first execution must always have non-zero parameters.

Note

SoftDevice will be enabled.

Parameters

[in]	p_ble_params	BLE parameters. Must be persistent.
[in]	p_hid_db	HID database.
[in]	delete_bonds	If true, all bonds will be deleted during initialization.

Returns

Return values

NRF_SUCCESS
NRF_ERROR_INVALID_PARAM
NRF_ERROR_NO_MEM

ret_code_t m_coms_ble_oobkey_set

(

uint8_t *

p_key

)

Function for setting the OOB key for encrypted OOB connections.

Note

The key should be 128 bits in a 16-byte array.

Parameters

[in]

p_key

16-byte byte array or NULL.

Returns

Return values

NRF_SUCCESS
NRF_ERROR_INVALID_STATE
NRF_ERROR_INVALID_PARAM

ret_code_t m_coms_ble_read_respond	(	uint8_t *	p_data,
		uint8_t	p_len
	)

Function for responding to a read request (M_COMS_BLE_EVT_READ_REQ).

Parameters

[in]	p_data	Data to respond with.
[in]	p_len	Length of data.

Return values

NRF_SUCCESS
NRF_ERROR_INVALID_PARAM
NRF_ERROR_INVALID_STATE

ret_code_t m_coms_ble_shutdown

(

void

)

Function for disconnecting and stopping advertising.

All activity is stopped. The SoftDevice is not disabled. The necessary bond management is also done when this happens.

Returns

Return values

NRF_SUCCESS
NRF_ERROR_INTERNAL

ret_code_t m_coms_ble_sl_disable

(

void

)

Function for disabling slave latency.

Returns

NRF_SUCCESS on success, otherwise error code.

ret_code_t m_coms_ble_sl_enable

(

void

)

Function for enabling slave latency.

Returns

NRF_SUCCESS on success, otherwise error code.