ble: Bluetooth Low Energy (LX)

This Bluetooth library is used to communicate with Bluetooth Low Energy devices.

This API is only supported on LX devices with BLE support. For BLE support on NX devices, see bt: Bluetooth functions (NX32L).

The examples BLE Scanner and BLE Beacon show how this API can be used.

Common Bluetooth Low Energy management

	•blePower	Controls power to the Bluetooth interface.
	•bleObserverStart	Starts listening for advertising data.
	•bleObserverStop	Stops listening for advertising data.
	•bleRegisterAdvData	Register a callback for handling advertising data.
	•bleRegisterAdvRaw	Register a callback for handling raw advertising data.
	•bleAcceptFilterAdd	Adds a device to the accept filter.
	•bleAcceptFilterRemove	Removes a device from the accept filter.
	•bleAcceptFilterClear	Removes all devices from the accept filter.

	•bleConnect	Begins connecting to a device.
	•bleDisconnect	Disconnect from a device
	•bleDeviceStatus	Get the status of the connection to a device.
	•bleDeviceMacGet	Get the MAC address of a device.

	•bleServiceCacheUpdate	Updates the cache for a device.
	•bleDeviceCacheDelete	Deletes the cache for one or all devices.
	•bleServiceGet	Get information about a service on a device.
	•bleCharGet	Get information about a characteristic on a device.
	•bleWriteVal	Writes a value to a characteristic
	•bleReadVal	Reads the value of a characteristic
	•bleNotifyRegister	Registers a notification callback on a characteristic
	•bleNotifyRelease	Releases a notification callback.
	•bleIndicationRegister	Registers an indication callback on a characteristic
	•bleIndicationRelease	Releases an indication callback.

	•bleMacCreate	Combines a simple MAC address with the address type.
	•bleTimeFromMs	Converts a time interval from ms to the number of 0.625ms ticks.

BLE uses different kinds of MAC addresses.

A public MAC address is a standard 48-bit MAC address as assigned by the IEEE Registration Authority.

A random device address is generated on the device and might change on periodically.

To differentiate between these addresses, this API uses strings of the following format to represent MAC addresses:

"yXX:XX:XX:XX:XX:XX"

y is the address type and is 'p' for public addresses and 'r' for random addresses.

X is a hexadecimal value from 0-F, and is part of the normal address.

The MAC address string can be created manually or using the bleMacCreate function.

This API uses the number of 0.625ms ticks for some time intervals. To convert a time in milliseconds to this format, use the bleTimeFromMs function

The BLE API uses a number of common error codes across the functions.

The following table lists the common error codes. The meaning may change slightly from function to function.

1	-	_BLE_OK	Success
0	-	_BLE_ERR_NOT_SUPPORTED	The API is not supported.
-1	-	_BLE_ERR_NOT_OPEN	The interface is not powered(see blePower).
-2	-	_BLE_ERR_ALREADY_OPEN	The interface is already turned on.
-4	-	_BLE_ERR_NOT_FOUND	Could not find device.
-5	-	_BLE_ERR_NO_ADAP	Could not find interface.
-7	-	_BLE_ERR_NO_RES	Could not allocate resources.
-8	-	_BLE_ERR_INVAL	Invalid argument.
-9	-	_BLE_ERR_NODATA	No valid data found.
-13	-	_BLE_ERR_STATE	Invalid state.
-17	-	_BLE_ERR_TIMEOUT	Timeout
-19	-	_BLE_ERR_NOT_CONNECTED	Device not connected.
-20	-	_BLE_ERR_INVAL_HANDLE	Invalid handle.
-21	-	_BLE_ERR_NO_CACHE	No cache found.
-99	-	_BLE_ERR_GENERIC	Unknown error.