bt_le

Bluetooth LE

This module serves as a comprehensive toolkit, offering an array of functionalities to effectively manage the behaviour of Bluetooth Low Energy (LE) in the context of a connection hosted on an Android|iOS|Windows device.

The module is specifically designed for Bluetooth LE, a power-efficient version of Bluetooth intended for short-range communication between devices, making it an ideal tool for managing connections with low-power peripherals such as fitness monitors, smart home devices, and similar Internet of Things (IoT) devices.

With the module's functionalities, developers can have fine-grained control over various aspects of Bluetooth LE behaviour. This could include establishing and managing connections, handling data transmission, scanning for devices, and optimising power usage, all within the Android environment.

Functions

This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.

• bt_le_is_supported
• bt_le_scan_start
• bt_le_scan_stop
• bt_le_scan_is_active
• bt_le_advertise_start
• bt_le_advertise_stop
• bt_le_advertise_is_active
• bt_le_server_open
• bt_le_server_add_service
• bt_le_server_clear_services
• bt_le_server_close
• bt_le_server_respond_read
• bt_le_server_respond_write
• bt_le_server_notify_value
• bt_le_peripheral_open
• bt_le_peripheral_is_open
• bt_le_peripheral_close_all
• bt_le_peripheral_close
• bt_le_peripheral_is_connected
• bt_le_peripheral_is_paired
• bt_le_peripheral_get_services
• bt_le_service_get_characteristics
• bt_le_characteristic_get_descriptors
• bt_le_characteristic_read
• bt_le_characteristic_write_request
• bt_le_characteristic_write_command
• bt_le_characteristic_notify
• bt_le_characteristic_indicate
• bt_le_characteristic_unsubscribe
• bt_le_descriptor_read
• bt_le_descriptor_write

Constants

This module includes a set of predefined constants that can be utilized for various purposes. Browse through the available constants to find values relevant to your needs and enhance the efficiency of your code.

• BluetoothStatus
• BluetoothProperty
• BluetoothPermission
• BluetoothServiceType
• AdvertiseMode
• AdvertiseTxPower

Structs

This module offers a collection of structs, which serve as custom data models for organizing and structuring data. Explore the provided structs to better understand the relationships between data elements and simplify your data manipulation tasks.

• AdvertiseSettings
• AdvertiseData
• AdvertiseServiceData
• AdvertiseManufacturerData
• BluetoothDevice
• BluetoothService
• BluetoothCharacteristic
• BluetoothDescriptor
• ServiceData
• CharacteristicData
• DescriptorData
• NotifiedDevice

---

Back To Top

bt_le_is_supported

This function returns true if the device has the necessary Bluetooth LE features, false otherwise.

Syntax:

bt_le_is_supported()

Returns:

Boolean

---

Back To Top

bt_le_scan_start

This function starts a Bluetooth LE scan with default parameters and no filters. The scan results will be delivered through callback.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_scan_start()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_scan_start"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the scan completed successfully, false otherwise.
error_code	Real	The error code (if the scan failed).

Key	Type	Description
type	String	The value "bt_le_scan_result"
name	String	The name of the device.
address	String	The unique address of the device.
raw_signal	Real	The device signal strength (RSSI)
is_connectable	Boolean	Whether or not the given device is connectable.

---

Back To Top

bt_le_scan_stop

This function stops the scanning process for Bluetooth LE devices.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_scan_stop()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_scan_stop"
async_id	Real	The unique identifier of this async task.
success	Boolean	true if the scan has stopped successfully, false otherwise.

---

Back To Top

bt_le_scan_is_active

This function returns whether or not the scan is currently active.

Syntax:

bt_le_scan_is_active()

Returns:

Boolean

---

Back To Top

bt_le_advertise_start

This function starts Bluetooth LE Advertising.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_advertise_start(settings, data)

Argument	Type	Description
settings	AdvertiseSettings	A struct containing all the settings to be applied to the advertisement.
data	AdvertiseData	A struct containing all the data to be applied to the advertisement.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_advertise_start"
async_id	Real	The unique identifier of this async task.
success	Boolean	true if the advertisement has started successfully, false otherwise.
error_code	Real	The error code (if advertise failed).

---

Back To Top

bt_le_advertise_stop

This function stops Bluetooth LE advertising.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_advertise_stop()

Returns:

N/A

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_advertise_stop"
async_id	Real	The unique identifier of this async task.
success	Boolean	true if the advertisement has stopped successfully, false otherwise.

---

Back To Top

bt_le_advertise_is_active

This function checks if advertisement is currently active.

Syntax:

bt_le_advertise_is_active()

Returns:

Boolean

---

Back To Top

bt_le_server_open

This function initialises the GATT server callback handlers (required before any other bt_le_server_* calls). The function call will enable various event callbacks that the user can start listening to.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_server_open()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_server_open"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task completed successfully, false otherwise.

This event is triggered when a client requests a read from a characteristic (it's up to the user to respond to the request).

Key	Type	Description
type	String	The value "bt_le_server_characteristic_read_request"
request_id	Real	The unique async identifier that refers to this request (use in bt_le_server_respond_read)
service_uuid	String	The UUID of the service that hosts the target characteristic.
characteristic_uuid	String	The UUID of the characteristic to be read.

This event is triggered when a client requests a write to a characteristic (it's up to the user to accept the write or not).

Key	Type	Description
type	String	The value "bt_le_server_characteristic_write_request"
request_id	Real	The unique async identifier that refers to this request (use in bt_le_server_respond_write)
service_uuid	String	The UUID of the service that hosts the target characteristic.
characteristic_uuid	String	The UUID of the characteristic to be read.
value	String	The base64 encoded string of the value to be written.

This event is triggered when a client commands a write to a characteristic (it's up to the user to accept the write or not).

Key	Type	Description
type	String	The value "bt_le_server_characteristic_write_command"
service_uuid	String	The UUID of the service that hosts the target characteristic.
characteristic_uuid	String	The UUID of the characteristic to be read.
value	String	The base64 encoded string of the value to be written.

This event is triggered when the connection of a given device changes.

Key	Type	Description
type	String	The value "bt_le_server_connection_state_changed"
success	Boolean	Whether the connection state change was successful.
connected	Boolean	Whether or not the given device has connected or disconnected.
device	BluetoothDevice	A struct holding data about the given device.

This event is triggered when a client requests a read from a descriptor (it's up to the user to respond to the request).

Key	Type	Description
type	String	The value "bt_le_server_descriptor_read_request"
request_id	Real	The unique async identifier that refers to this request (use in bt_le_server_respond_read)
service_uuid	String	The UUID of the service that hosts the target descriptor.
characteristic_uuid	String	The UUID of the characteristic that hosts the target descriptor.
descriptor_uuid	String	The UUID of the descriptor to be read.

This function is triggered when a client requests a write to a descriptor (it's up to the user to accept the write or not).

Key	Type	Description
type	String	The value "bt_le_server_descriptor_write_request"
request_id	Real	The unique async identifier that refers to this request (use in bt_le_server_respond_write)
service_uuid	String	The UUID of the service that hosts the target descriptor.
characteristic_uuid	String	The UUID of the characteristic that hosts the target descriptor.
descriptor_uuid	String	The UUID of the descriptor to be read.
value	String	The base64 encoded string of the value to be written.

This event is triggered as the result of a call to the function bt_le_server_notify_value.

Key	Type	Description
type	String	The value "bt_le_server_notify_value"
async_id	Real	The unique async identifier that refers to this task.
success	Boolean	true if the task was completed successfully, false otherwise.
devices	Array of NotifiedDevice	An array of notified devices and the status of the notification. Note of mobile this will be a JSON encoded string that needs to be parsed using json_parse.

---

Back To Top

bt_le_server_add_service

This function adds a new service to the currently opened server.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_server_add_service(data)

Argument	Type	Description
data	ServiceData	A struct representing the service to be added (on mobile this argument needs to be stringified using json_stringify).

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_server_add_service"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task was completed successfully, false otherwise.
error_code	Real	The error code (if scan failed).
service	String	The UUID of the service being added.

---

Back To Top

bt_le_server_clear_services

This function clears all previously added services to the GATT server.

Syntax:

bt_le_server_clear_services()

Returns:

Boolean

---

Back To Top

bt_le_server_close

This function closes the current GATT server and unregisters all the callback handlers regarding it.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_server_close()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_server_close"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task was completed successfully, false otherwise.

---

Back To Top

bt_le_server_respond_read

You can use this function to respond to an incoming read request.

Syntax:

bt_le_server_respond_read(request_id, status, value)

Argument	Type	Description
request_id	Real	The identifier of the request.
status	BluetoothStatus	The status of the read attempt.
value	String	The base64 encoded string with the value requested (if status is BT_STATUS_FAILURE it is ignored).

Returns:

Boolean

---

Back To Top

bt_le_server_respond_write

You can use this function to respond to an incoming write request.

Syntax:

bt_le_server_respond_write(request_id, status)

Argument	Type	Description
request_id	Real	The identifier of the request.
status	BluetoothStatus	The status of the write attempt.

Returns:

Boolean

---

Back To Top

bt_le_server_notify_value

This function notifies all the subscribers of a given characteristic that its value has changed.

Syntax:

bt_le_server_notify_value(service_uuid, charactertistic_uuid, value)

Argument	Type	Description
service_uuid	String	The UUID of the service the characteristic belongs to.
charactertistic_uuid	String	The UUID of the characteristic.
value	String	The base64 encoded string with the new value.

Returns:

Boolean

---

Back To Top

bt_le_peripheral_open

This function opens a connection between the current client and a peripheral.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_peripheral_open(address)

Argument	Type	Description
address	String	The unique address of the device you want to connect to.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_peripheral_open"
async_id	Real	The unique async identifier that refers to this task
is_paired	Boolean	Are we already paired with the connected device
address	String	The unique address of the peripheral we are connecting to.
name	String	The name of the peripheral (empty string if null).

---

Back To Top

bt_le_peripheral_is_open

This function checks if a GATT connection to a given peripheral is opened.

Syntax:

bt_le_peripheral_is_open(address)

Argument	Type	Description
address	String	The unique address of the peripheral.

Returns:

Boolean

---

Back To Top

bt_le_peripheral_close_all

This function closes all open GATT connections to all peripherals.

Syntax:

bt_le_peripheral_close_all()

Returns:

Boolean

---

Back To Top

bt_le_peripheral_close

This function closes the GATT connection to a given peripheral.

Syntax:

bt_le_peripheral_close(address)

Argument	Type	Description
address	String	The unique address of the peripheral.

Returns:

Boolean

---

Back To Top

bt_le_peripheral_is_connected

This function checks if a given peripheral is connected.

Syntax:

bt_le_peripheral_is_connected(address)

Argument	Type	Description
address	String	The unique address of the peripheral.

Returns:

Boolean

---

Back To Top

bt_le_peripheral_is_paired

This function checks if a given peripheral is paired.

Syntax:

bt_le_peripheral_is_paired(address)

Argument	Type	Description
address	String	The unique address of the peripheral.

Returns:

Boolean

---

Back To Top

bt_le_peripheral_get_services

This function gets the services for a given peripheral.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_peripheral_get_services(address)

Argument	Type	Description
address	String	The unique address of the peripheral.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_peripheral_get_services"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task was completed successfully, false otherwise.
services	Array of BluetoothService	An array of BluetoothService associated with the peripheral. On mobile platforms this will be a JSON encoded string that needs to be parsed using json_parse.

---

Back To Top

bt_le_service_get_characteristics

This function gets the characteristics of a given service.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_service_get_characteristics(address, service_uuid)

Argument	Type	Description
address	String	The unique address of the peripheral.
service_uuid	String	The UUID of the service.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_service_get_characteristics"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task was completed successfully, false otherwise.
characteristics	Array of BluetoothCharacteristic	An array of BluetoothCharacteristic associated with the service. On mobile platforms this will be a JSON encoded string that needs to be parsed using json_parse.

---

Back To Top

bt_le_characteristic_get_descriptors

This function gets the descriptors of a given characteristic.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_characteristic_get_descriptors(address, service_uuid, charactertistic_uuid)

Argument	Type	Description
address	String	The unique address of the peripheral.
service_uuid	String	The UUID of the service the characteristic belongs to.
charactertistic_uuid	String	The UUID of the characteristic.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_characteristic_get_descriptors"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task was completed successfully, false otherwise.
descriptors	Array of BluetoothDescriptor	An array of BluetoothDescriptor associated with the characteristic. On mobile platforms this will be a JSON encoded string that needs to be parsed using json_parse.

---

Back To Top

bt_le_characteristic_read

This function requests a read operation on a peripheral's characteristic.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_characteristic_read(address, service_uuid, charactertistic_uuid)

Argument	Type	Description
address	String	The unique address of the peripheral.
service_uuid	String	The UUID of the service the characteristic belongs to.
charactertistic_uuid	String	The UUID of the characteristic.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_characteristic_read"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task completed successfully, false otherwise.
error_code	Real	The error code if the task was not completed successfully.
value	String	The base64 encoded string with the read value.

---

Back To Top

bt_le_characteristic_write_request

This function requests a write operation on a peripheral's characteristic.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_characteristic_write_request(address, service_uuid, charactertistic_uuid, value)

Argument	Type	Description
address	String	The unique address of the peripheral.
service_uuid	String	The UUID of the service the characteristic belongs to.
charactertistic_uuid	String	The UUID of the characteristic.
value	String	The base64 encoded string with the new value.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_characteristic_write_request"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task was completed successfully, false otherwise.
error_code	Real	The error code if the task was not completed successfully.

---

Back To Top

bt_le_characteristic_write_command

This function commands a write operation on a peripheral's characteristic (note that this might not happen, there is no confirmation).

Syntax:

bt_le_characteristic_write_command(address, service_uuid, charactertistic_uuid, value)

Argument	Type	Description
address	String	The unique address of the peripheral.
service_uuid	String	The UUID of the service the characteristic belongs to.
charactertistic_uuid	String	The UUID of the characteristic.
value	String	The base64 encoded string with the new value.

Returns:

Real

---

Back To Top

bt_le_characteristic_notify

This function enables notifications when then value of a characteristic changes.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_characteristic_notify(address, service_uuid, charactertistic_uuid)

Argument	Type	Description
address	String	The unique address of the peripheral.
service_uuid	String	The UUID of the service the characteristic belongs to.
charactertistic_uuid	String	The UUID of the characteristic.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_characteristic_notify"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task completed successfully, false otherwise.
error_code	Boolean	The error code if the task didn't complete successfully.

This event is triggered when there is a change in the subscribed characteristic.

Key	Type	Description
type	String	The value "bt_le_characteristic_value_changed"
characteristic_uuid	String	The UUID of the characteristic whose value changed.
service_uuid	String	The UUID of the service the characteristic belongs to.
address	String	The unique address of the peripheral we are connecting to.
value	String	The base64 encoded string with the new value.

---

Back To Top

bt_le_characteristic_indicate

This function enables indication of characteristic value changes.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_characteristic_indicate(address, service, characteristic)

Argument	Type	Description
address	String	The unique address of the peripheral.
service	String	The UUID of the service the characteristic belongs to.
characteristic	String	The UUID of the characteristic.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_characteristic_indicate"
async_id	Real	The unique async identifier that refers to this task.
success	Boolean	true if the task completed successfully, false otherwise.
error_code	Boolean	The error code if the task didn't complete successfully.

This event is triggered when there is a change in the subscribed characteristic.

Key	Type	Description
type	String	The value "bt_le_characteristic_value_changed"
characteristic_uuid	Real	The UUID of the characteristic whose value changed.
service_uuid	Boolean	The UUID of the service the characteristic belongs to.
address	String	The unique address of the peripheral where the change occurred.
name	String	The base64 encoded string with the new value.

---

Back To Top

bt_le_characteristic_unsubscribe

This function unsubscribes from any previous notification|indication on a given characteristic.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_characteristic_unsubscribe(address, service, characteristic)

Argument	Type	Description
address	String	The unique address of the peripheral.
service	String	The UUID of the service the characteristic belongs to.
characteristic	String	The UUID of the characteristic.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_characteristic_unsubscribe"
async_id	Real	The unique async identifier that refers to this task.
success	Boolean	true if the task completed successfully, false otherwise.
error_code	Boolean	The error code if the task didn't complete successfully.

---

Back To Top

bt_le_descriptor_read

This function requests a read operation on a characteristic's descriptor.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_descriptor_read(address, service, characteristic, descriptor)

Argument	Type	Description
address	String	The unique address of the peripheral.
service	String	The UUID of the service the characteristic belongs to.
characteristic	String	The UUID of the characteristic the descriptor belongs to.
descriptor	String	The UUID of the descriptor.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_descriptor_read"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task completed successfully, false otherwise.
error_code	Real	The error code if the task didn't complete successfully.
value	String	The base64 encoded string with the read value.

---

Back To Top

bt_le_descriptor_write

This function requests a write operation on a characteristic's descriptor.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

bt_le_descriptor_write(address, service, characteristic, descriptor, value)

Argument	Type	Description
address	String	The unique address of the peripheral.
service	String	The UUID of the service the characteristic belongs to.
characteristic	String	The UUID of the characteristic the descriptor belongs to.
descriptor	String	The UUID of the descriptor.
value	String	The base64 encoded string with the new value.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The value "bt_le_descriptor_write"
async_id	Real	The unique async identifier that refers to this task
success	Boolean	true if the task completed successfully, false otherwise.
error_code	Real	The error code if the task didn't complete successfully.

---

Back To Top

BluetoothStatus

These constants represent the various status responses that can be obtained while using Bluetooth LE.

These constants are referenced by the following functions:

• bt_le_server_respond_read
• bt_le_server_respond_write

These constants are referenced by the following structs:

• NotifiedDevice

Member	Description
BT_STATUS_SUCCESS	A GATT operation completed successfully (0)
BT_STATUS_WRITE_NOT_PERMITTED	GATT write operation is not permitted (3)
BT_STATUS_REQUEST_NOT_SUPPORTED	The given request is not supported (6)
BT_STATUS_READ_NOT_PERMITTED	GATT read operation is not permitted (2)
BT_STATUS_INVALID_OFFSET	A read or write operation was requested with an invalid offset (7)
BT_STATUS_INVALID_ATTRIBUTE_LENGTH	A write operation exceeds the maximum length of the attribute (13)
BT_STATUS_INSUFFICIENT_ENCRYPTION	Insufficient encryption for a given operation (15)
BT_STATUS_INSUFFICIENT_AUTHORIZATION	Insufficient authorization for a given operation (8)
BT_STATUS_INSUFFICIENT_AUTHENTICATION	Insufficient authentication for a given operation (5)
BT_STATUS_CONNECTION_CONGESTED	A remote device connection is congested (143)
BT_STATUS_FAILURE	A GATT operation failed, errors other than the above (257)
BT_STATUS_ACTION_NOT_STARTED	An operation didn't start, for unknown reason (-10)
BT_STATUS_SERVICE_NOT_FOUND	A service with the given UUID was not found (-1)
BT_STATUS_CHARACTERISTIC_NOT_FOUND	A characteristic with the given UUID was not found (-2)
BT_STATUS_DESCRIPTOR_NOT_FOUND	A descriptor with the given UUID was not found (-3)

---

Back To Top

BluetoothProperty

These constants represent the various properties that can be applied to a given characteristic.

These constants are referenced by the following structs:

• BluetoothCharacteristic
• CharacteristicData

Member	Description
BT_PROPERTY_BROADCAST	Characteristic is broadcastable. (1)
BT_PROPERTY_EXTENDED_PROPS	Characteristic has extended properties (128)
BT_PROPERTY_INDICATE	Characteristic supports indication (32)
BT_PROPERTY_NOTIFY	Characteristic supports notification (16)
BT_PROPERTY_READ	Characteristic is readable. (2)
BT_PROPERTY_SIGNED_WRITE	Characteristic supports write with signature (64)
BT_PROPERTY_WRITE	Characteristic can be written. (8)
BT_PROPERTY_WRITE_NO_RESPONSE	Characteristic can be written without response. (4)

---

Back To Top

BluetoothPermission

These constants represent the various permissions that can be applied to a given characteristic.

These constants are referenced by the following structs:

• BluetoothCharacteristic
• CharacteristicData
• DescriptorData

Member	Description
BT_PERMISSION_READ	Characteristic read permission. (1)
BT_PERMISSION_READ_ENCRYPTED	Allow encrypted read operations (2)
BT_PERMISSION_READ_ENCRYPTED_MITM	Allow reading with person-in-the-middle protection (4)
BT_PERMISSION_WRITE	Characteristic write permission (16)
BT_PERMISSION_WRITE_ENCRYPTED	Allow encrypted writes. (32)
BT_PERMISSION_WRITE_ENCRYPTED_MITM	Allow encrypted writes with person-in-the-middle protection (64)
BT_PERMISSION_WRITE_SIGNED	Allow signed write operations. (128)
BT_PERMISSION_WRITE_SIGNED_MITM	Allow signed write operations with person-in-the-middle protection. (256)

---

Back To Top

BluetoothServiceType

These constants represent the various various service types available in Bluetooth LE.

These constants are referenced by the following structs:

• BluetoothService

Member	Description
BT_SERVICE_TYPE_PRIMARY	Primary service (0)
BT_SERVICE_TYPE_SECONDARY	Secondary service - included by primary services (1)

---

Back To Top

AdvertiseMode

These constants represent the mode to control the advertising power and latency.

These constants are referenced by the following structs:

• AdvertiseSettings

Member	Description
BT_ADVERTISE_MODE_BALANCED	Perform Bluetooth LE advertising in balanced power mode. This is balanced between advertising frequency and power consumption. (1)
BT_ADVERTISE_MODE_LOW_LATENCY	Perform Bluetooth LE advertising in low latency, high power mode. This has the highest power consumption and should not be used for continuous background advertising. (2)
BT_ADVERTISE_MODE_LOW_POWER	Perform Bluetooth LE advertising in low power mode. This is the default and preferred advertising mode as it consumes the least power. (0)

---

Back To Top

AdvertiseTxPower

These constants represent the TX power level for advertising.

These constants are referenced by the following structs:

• AdvertiseSettings

Member	Description
BT_ADVERTISE_TX_POWER_HIGH	Advertise using high TX power level. This corresponds to largest visibility range of the advertising packet. (3)
BT_ADVERTISE_TX_POWER_LOW	Advertise using low TX power level. (1)
BT_ADVERTISE_TX_POWER_MEDIUM	Advertise using medium TX power level. (2)
BT_ADVERTISE_TX_POWER_ULTRA_LOW	Advertise using the lowest transmission (TX) power level. Low transmission power can be used to restrict the visibility range of advertising packets. (0)

---

Back To Top

AdvertiseSettings

This struct represents the collection of settings to apply to the advertisement.

This struct is referenced by the following functions:

• bt_le_advertise_start

Member	Type	Description
advertiseMode	AdvertiseMode	Set the advertise mode to control the advertising power and latency.
connectable	Boolean	Whether the device should be connectable.
discoverable	Boolean	Whether the device should be discoverable (Windows and macOS
timeout	Real	Limit advertising to a given amount of time. May not exceed 180000 milliseconds. A value of 0 will disable the time limit.
txPowerLevel	AdvertiseTxPower	Set advertise TX power level to control the transmission power level for the advertising.

---

Back To Top

AdvertiseData

This struct represents the data to be included in the advertisement.

This struct is referenced by the following functions:

• bt_le_advertise_start

Member	Type	Description
name	String	The name to be used.
includeName	Boolean	Whether to include the device name.
includePowerLevel	Boolean	Whether to include the power level.
services	Array of AdvertiseServiceData	Services to be advertised.
manufacturer	AdvertiseManufacturerData	Manufacturer information.

---

Back To Top

AdvertiseServiceData

This struct represents the service data to be included in the advertisement.

This struct is referenced by the following structs:

• AdvertiseData

Member	Type	Description
uuid	String	The UUID of the service to be advertised.

---

Back To Top

AdvertiseManufacturerData

This struct represents the manufacturer data to be included in the advertisement.

This struct is referenced by the following structs:

• AdvertiseData

Member	Type	Description
id	Real	The manufacturer unique ID.
data	String	A base64 encoded string with the data associated with the manufacturer.

---

Back To Top

BluetoothDevice

This struct represents a fetched Bluetooth device.

This struct is referenced by the following functions:

• bt_paired_devices
• bt_le_server_open

Member	Type	Description
name	String	The visible device name.
address	String	The device unique address.
is_paired	Boolean	Whether or not the devices are paired.
type	Real	The Bluetooth device type of the remote device.
alias	String	The locally modifiable name (alias) of the remote Bluetooth device.

---

Back To Top

BluetoothService

This struct represents a fetched Bluetooth service.

This struct is referenced by the following functions:

• bt_le_peripheral_get_services

Member	Type	Description
uuid	String	The service unique UUID.
type	BluetoothServiceType	The type of this service (primary/secondary).

---

Back To Top

BluetoothCharacteristic

This struct represents a fetched Bluetooth characteristic.

This struct is referenced by the following functions:

• bt_le_service_get_characteristics

Member	Type	Description
uuid	String	The characteristic unique UUID.
properties	BluetoothProperty	The properties of this characteristic. The properties contain a bit mask of property flags indicating the features of this characteristic.
permissions	BluetoothPermission	The permissions for this characteristic.

---

Back To Top

BluetoothDescriptor

This struct represents a fetched Bluetooth descriptor.

This struct is referenced by the following functions:

• bt_le_characteristic_get_descriptors

Member	Type	Description
uuid	String	The descriptor unique UUID.

---

Back To Top

ServiceData

This struct represents a service that is being created.

This struct is referenced by the following functions:

• bt_le_server_add_service

Member	Type	Description
uuid	String	The service unique UUID.
charactertistics	Array of CharacteristicData	An array of all the charactertistics contained in this service.

---

Back To Top

CharacteristicData

This struct represents a characteristic that is being created.

This struct is referenced by the following structs:

• ServiceData

Member	Type	Description
uuid	String	The characteristic unique UUID.
properties	BluetoothProperty	The properties to be applied to this characteristic.
permissions	BluetoothPermission	The permissions to be applied to this characteristic.
descriptors	Array of DescriptorData	An array of all the descriptors contained in this characteristic.

---

Back To Top

DescriptorData

This struct represents a descriptor that is being created.

This struct is referenced by the following structs:

• CharacteristicData

Member	Type	Description
uuid	String	The descriptor unique UUID.
permissions	BluetoothPermission	The permissions to be applied to this descriptor.

---

Back To Top

NotifiedDevice

This struct represents a device that was notified of a change in the value of a characteristic.

This struct is referenced by the following functions:

• bt_le_server_open

Member	Type	Description
address	String	The unique address of the device that was notified.
status	BluetoothStatus	The status of the notification operation.