Bluetooth device SDK porting interfaces-Link Living-阿里云帮助中心

Breeze SDK is a solution from Alibaba Cloud IoT that provides secure access over the Bluetooth Low Energy (BLE) protocol stack. It also supports Wi-Fi assisted network provisioning through the Bluetooth channel. This topic describes the Hardware Abstraction Layer (HAL) interfaces of Breeze SDK. Vendors can use this document as a reference for integration.

HAL interface description

The HAL interfaces of Breeze SDK are divided into three parts: protocol stack, OS, and security. These interfaces are defined in the $(SDK Src)/framework/bluetooth/breeze/hal folder.

breeze_hal_ble.h
This file defines the interfaces for connecting the Bluetooth network provisioning SDK to the Bluetooth protocol stacks of different vendors. For a reference implementation, see the breeze_hal_ble.c file.
breeze_hal_os.h
This file defines the interfaces for connecting the Bluetooth network provisioning SDK to different operating systems. For a reference implementation based on AliOS Things, see the breeze_hal_os.c file. If you use AliOS Things, you do not need to integrate these interfaces.
breeze_hal_sec.h
This file defines the interfaces for connecting the Bluetooth network provisioning SDK to different security algorithm implementations. For a reference implementation based on mbedtls, see the breeze_hal_security.c file. If you use AliOS Things, you do not need to integrate these interfaces.

Bluetooth protocol stack HAL list

ble_stack_init

This interface initializes the BLE protocol stack.

Parameters

Name	Type	Description
ais_init	ais_bt_init_t	Specifies the Bluetooth service, characteristics, and related settings such as permissions. It includes the following content. uuid_svc: UUID (type, value) information of the AIS service. rc/wc/ic/nc/ wwnrc: Property information of the characteristics of the AIS service. on_connected: Callback function for Bluetooth connection events. on_disconnected: Callback function for Bluetooth disconnection events.
init_done	stack_init_done_t	Callback function for the completion of protocol stack initialization. After the Bluetooth protocol stack is initialized, this function must be actively called with the success parameter `AIS_ERR_SUCCESS(0)`

Return value

The function returns AIS_ERR_SUCCESS on success. If an error occurs, it returns the corresponding error code defined in breeze_hal_ble.h.

ble_stack_deinit
This interface stops the protocol stack and destroys resources.
Parameters
None
Return value
The function returns AIS_ERR_SUCCESS on success. If an error occurs, it returns the corresponding error code defined in breeze_hal_ble.h.
ble_send_notification
This interface sends data using notifications.
Parameters
Name Type Description
p_data uint8_t* Buffer address of the data to send.
length uint16_t Data length.
Return value
The function returns AIS_ERR_SUCCESS on success. If an error occurs, it returns the corresponding error code defined in breeze_hal_ble.h.

ble_send_indication

This interface sends data using indications.

Parameters

Name	Type	Description
p_data	uint8_t*	Buffer address of the data to send.
length	uint16_t	Data length.
txdone	callback	Callback handler. The HAL implementation code calls this function after the indication data is sent.

Return value

If the operation is successful, the function returns AIS_ERR_SUCCESS. Otherwise, it returns an error code defined in breeze_hal_ble.h.

ble_disconnect

This interface disconnects an existing Bluetooth connection. Unlike ble_stack_deinit, you can establish new connections after calling this interface.

Parameters

Name	Type	Description
reason	uint8_t	The reason why the SDK disconnects the Bluetooth connection. Note that this is not the disconnection reason specified in the Bluetooth specification, such as Remote User Terminated Connect (0x13) or Connection Accept Timeout Exceeded (0x10). You must perform a mapping in the implementation. For example, if the SDK passes `AIS_BT_REASON_REMOTE_USER_TERM_CONN(0x00)`, map it to `BT_HCI_ERR_REMOTE_USER_TERM_CONN(0x13)`

Return value

None

ble_advertising_start
This interface starts Bluetooth advertising.
Parameters
Name Type Description
adv ais_adv_init_t* The input parameter `adv` specifies the required advertising information, including the flag, device name, and manufacturer data segment content.
Return value
The function returns AIS_ERR_SUCCESS on success. If an error occurs, it returns the corresponding error code defined in breeze_hal_ble.h.
ble_advertising_stop
This interface stops Bluetooth advertising.
Parameters
None
Return value
The function returns AIS_ERR_SUCCESS on success. If an error occurs, it returns the corresponding error code defined in breeze_hal_ble.h.

ble_get_mac

This interface retrieves the MAC address of the Bluetooth device.

Parameters

Name	Type	Description
mac	uint8_t*	Used to store the retrieved Bluetooth MAC address. The address is in a 6 byte binary format: 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF (corresponding to the MAC address "AA:BB:CC:DD:EE:FF").

Return value

The function returns AIS_ERR_SUCCESS on success. If an error occurs, it returns a Breeze error code.

OS HAL list

The OS HAL interfaces provide the following features:

Timer support
System restart interface
System timestamp retrieval and sleep interfaces
Key-value pair read interface

The OS HAL interfaces are as follows.

os_timer_new
This interface creates a timer.
Parameters
Name Type Description
timer os_timer_t* Timer pointer.
cb os_timer_cb_t Callback handler for timer timeout.
arg void** Parameter for the callback function.
ms int* Timeout period.
Return value
Returns 0 on success. Otherwise, it returns a non-zero value.
os_timer_start
This interface starts a timer.
Parameters
Name Type Description
timer os_timer_t* Timer pointer.
Return value
Returns 0 on success. Otherwise, it returns a non-zero value.
os_timer_stop
This interface stops a timer.
Parameters
Name Type Description
timer os_timer_t* Timer pointer.
Return value
Returns 0 on success. Otherwise, it returns a non-zero value.
os_timer_free
This interface destroys timer resources.
Parameters
Name Type Description
timer os_timer_t* Timer pointer.
Return value
Returns 0 on success. Otherwise, it returns a non-zero value.
os_msleep
This interface triggers the system or process to sleep.
Parameters
Name Type Description
ms int Sleep duration in ms.
Return value
None
os_reboot
This interface restarts the OS.
Parameters
None
Return value
None
os_now_ms
This interface retrieves the current system timestamp, which is counted from system startup.
Parameters
None
Return value
The system timestamp in ms.
os_kv_get
This interface reads a key-value pair from persistent storage.
Parameters
Name Type Description
key const char* Key name (string).
buffer void* Key value (any value).
buffer_len int* Pointer to the length of the key value.
Return value
Returns 0 on success. Otherwise, it returns a non-zero value.
os_kv_del
This interface deletes a key-value pair from persistent storage.
Parameters
Name Type Description
key const char* Key name (string).
Return value
Returns 0 on success. Otherwise, it returns a non-zero value.
os_rand
This interface generates a random integer value.
Parameters
None
Return value
A random signed integer value.

Security-related HAL

ais_aes128_init
This interface initializes the context for the AES-128 encryption and decryption algorithm.
Parameters
Name Type Description
key const uint8_t* The key required by the AES-128 algorithm.
iv const uint8_t* The initialization vector (IV) required by the AES-128 CBC algorithm.
Return value
A void pointer to the initialized context. This return value is used in subsequent encryption and decryption processes.
ais_aes128_destroy
This interface destroys the AES-128 encryption and decryption algorithm context and releases related resources.
Parameters
Name Type Description
aes void* The context returned after the interface is initialized.
Return value
Returns 0 on success. Otherwise, it returns -1.

ais_aes128_cbc_encrypt

You can call this interface to perform AES-128 CBC encryption.

Parameters

Name	Type	Description
aes	void*	The context returned after the interface is initialized.
src	const void*	A pointer to the data that needs to be encrypted.
block_num	size_t	The number of data blocks to encrypt. A block is 16 bytes. Data smaller than 16 bytes is counted as one block.
dst	void*	The storage address for the decrypted data.

Return value

Returns 0 on success. Otherwise, it returns -1.

ais_aes128_cbc_decrypt

You can call this interface to perform AES-128 CBC decryption.

Parameters

Name	Type	Description
aes	void*	The context returned after the interface is initialized.
src	const void*	Specifies the data to be encrypted.
block_num	size_t	The number of blocks to encrypt. One block is 16 bytes. Data that is less than 16 bytes is counted as one block.
dst	void*	The storage address for the decrypted data.

Return value

Returns 0 on success. Otherwise, it returns -1.

Name	Type	Description
adv	ais_adv_init_t*	The input parameter `adv` specifies the required advertising information, including the flag, device name, and manufacturer data segment content.

Name	Type	Description
timer	os_timer_t*	Timer pointer.
cb	os_timer_cb_t	Callback handler for timer timeout.
arg	void**	Parameter for the callback function.
ms	int*	Timeout period.

Name	Type	Description
timer	os_timer_t*	Timer pointer.

Name	Type	Description
timer	os_timer_t*	Timer pointer.