BLE (canvas_ble)

The modules described in this chapter provide the interface to the Bluetooth Low Energy (BLE) stack in the radio module.

class canvas_ble.Advertiser

The Advertiser class provides for two buffers that can be populated by the application: an advertising buffer and a scan response buffer. The application cannot inspect or modify in-place either of these buffers. Instead, methods are provided to clear the buffer and to add data to the buffer. When advertising is started with start() or updated with update(), the current contents of the buffer is copied into the BLE stack to be used. Until either start() or update() are called, the application can clear/update the buffers at will without any consequence.

Data in the buffers needs to be in the BLE LTV (length, tag, value) format. The methods add_ltv() and add_tag_string() will assist with this by adding the length and tag fields. Additional care needs to be taken with the add_data() method to ensure that the data is in the proper format.

Constants for some of the possible tag (sometimes also called type) values exist in the canvas_ble module. The application can also use any other value that is valid for the BLE LTV format. See the canvas_ble.AD_TYPE_* constants.

The size of the advertising buffer is platform- and configuration-dependent. Legacy advertising (non-extended) is limited to 31 bytes in each of the advertising and scan response buffers. Extended advertising allows for considerably larger buffers, but the size is still platform-dependent.

Only one instance of the Advertiser class should ever be created. Multiple advertising sets is not currently implemented.

add_canvas_data(config_version: int, network_id: int, scan: bool)

Add Canvas-specific data to a buffer. This is a convenience function that adds the Canvas-specific data to the buffer. The Canvas-specific data helps to identify the device as a Canvas device that a common set of tools can use.

The Canvas data will take 23 bytes in the buffer. The application should chose to use either the advertising buffer or the scan response buffer to add the Canvas data depending on how the application will be using the advertisement data. There is no reason to include the Canvas data in both buffers.

Parameters:

config_version (int) – Configuration version of the device. This is a 8-bit value that is incremented each time the configuration is changed. The parameter is required, but if an application is not using the configuration version, it can be set to 0.
network_id (int) – Network ID of the device. The parameter is required, but if an application is not using the network ID, it can be set to 0.
scan (bool) – Buffer to which to add. False to add to advertising buffer or True to add to scan response buffer.

add_data(data: any, scan: bool)

Add data to a buffer. This function adds raw data bytes into the selected buffer. The application must ensure that the buffer contents contain proper BLE TLVs.

Parameters:

data (bytes) – Bytes to add to the buffer
scan (bool) – Buffer to which to add. False to add to advertising buffer or True to add to scan response buffer.

add_ltv(tag: int, data: any, scan: bool)

Add a byte-based LTV to a buffer.

Add manufacturer-specific data to the advertising buffer using a manufacturer ID of 0x0201 and data of 0x03, 0x04:

>>> advertiser = canvas_ble.Advertiser()
>>> advertiser.add_ltv(canvas_ble.AD_TYPE_MANU_SPECIFIC, b'\x01\x02\x03\x04', False)

Parameters:

tag (int) – Tag is a one-byte value defined by the BLE specification
data (bytes) – Data to add to the buffer
scan (bool) – Buffer to which to add. False to add to advertising buffer or True to add to scan response buffer.

add_smp_uuid(scan: bool)

Add the SMP UUID to a buffer. This is a convenience function that adds the SMP UUID to the buffer. The SMP UUID is a 128-bit value defined by the BLE specification.

Parameters:: scan (bool) – Buffer to which to add. False to add to advertising buffer or True to add to scan response buffer.

add_tag_string(tag: int, string: str, scan: bool)

Add a string-based LTV to a buffer.

Add a device name to the scan response:

>>> advertiser = canvas_ble.Advertiser()
>>> advertiser.add_tag_string(canvas_ble.AD_TYPE_NAME_COMPLETE, "Canvas", True)

Parameters:

tag (int) – Tag is a one-byte value defined by the BLE specification
string (str) – String to add to the buffer
scan (bool) – Buffer to which to add. False to add to advertising buffer or True to add to scan response buffer.

clear_buffer(scan: bool)

Clears a buffer

Parameters:: scan (bool) – Buffer to clear. False to clear advertising buffer or True to clear scan response buffer

set_channel_mask(mask: any)

Set the channel mask to be used for advertising. The mask is a 37-bit value with each bit corresponding to a channel. A value of 1 indicates that the channel will be used. A value of 0 indicates that the channel will not be used.

Parameters:: mask (bytes) – Channel mask to use for advertising. Should be 5 bytes in length. The first byte is the LSB of the mask (channel 0).

set_directed(directed: bool, mac: any)

Set the directed advertisement flag and the MAC address of the target device.

Parameters:

directed (bool) – True if the advertisement should be directed
mac (bytes) – MAC address of the target device. This is a required parameter if directed is True. If directed is False, then this parameter must be None.

set_interval(min: int, max: int)

Set the advertising interval range to be used by the BLE stack. Many stacks require a range of values here to allow for some flexibility in the scheduling of advertisement packets. The min and max values are specified in milliseconds and cannot be the same.

Advertise interval set to a value between 100 and 200 milliseconds (selected by the BLE stack):

>>> advertiser = canvas_ble.Advertiser()
>>> advertiser.set_interval(100, 200)

Parameters:

min (int) – Minimum advertising interval in milliseconds
max (int) – Maximum advertising interval in milliseconds

set_phys(primary: int, secondary: int)

Set the PHYs that will be used for advertising. Values for PHYs should be taken from the canvas_ble.PHY_* constants. Only one primary PHY and one secondary PHY can be used at a time (not a bitmask of PHYs).

For legacy (non-extended) advertising, only the 1M PHY can be used and there is no secondary PHY. For extended advertising, the 1M PHY is the default primary PHY and the 2M PHY is the default secondary PHY.

Valid combinations of PHYs:

Primary PHY	Secondary PHY	Lyra 24	Sera NX040
1M	1M	Yes	Yes
1M	2M	Yes	Yes
1M	Coded	Yes	No
2M	1M	No, 2M cannot be used as primary
2M	2M
2M	Coded
Coded	1M	Yes	No
Coded	2M	Yes	No
Coded	Coded	Yes	Yes

Advertise using only the 1M PHY for both primary and secondary:
>>> advertiser = canvas_ble.Advertiser()
>>> advertiser.set_properties(True, False, True)
>>> advertiser.set_phys(canvas_ble.PHY_1M, canvas_ble.PHY_1M)
param int primary:

Primary PHY to use for advertising

param int secondary:

Secondary PHY to use for advertising

set_properties(connectable: bool, scannable: bool, extended: bool)

Set the advertisement properties.

A connectable advertisement allows a BLE central device to connect to this device.

A scannable advertisement allows a BLE central device to scan for this device and receive additional scan response data from the device on top of the regular advertisement data.

An extended advertisement allows the use of PHYs other than the 1M PHY for advertising. Extended advertising is required for the use of the 2M PHY or the coded PHY. The extended advertisement also allows for a considerably larger advertisement buffer (platform-dependent).

An extended advertisement cannot be both connectable and scannable.

For the Lyra products, if a non-extended advertisement is connectable, it must also be scannable.

Use legacy advertising:

>>> advertiser = canvas_ble.Advertiser()
>>> advertiser.set_properties(True, False, False)

Use extended advertising with a connectable advertisement:

>>> advertiser = canvas_ble.Advertiser()
>>> advertiser.set_properties(True, False, True)

Parameters:

connectable (bool) – True if the advertisement should be connectable
scannable (bool) – True if the advertisement should be scannable
extended (bool) – True if extended advertising should be used

start(): Start advertising. The advertising buffer is copied into the BLE stack and the advertising is started. The application can continue to update the advertising buffer and call update() to change the advertising data.

stop(): Stop advertising.

update(): Update the advertising data. The advertising buffer is copied into the BLE stack and the advertising continues.

validate_data() → bool

Perform a validation test on the advertising and scan buffers.

Returns:: True if the buffers contain valid LTVs or False if there is an error in either buffer.

class canvas_ble.Connection

The Connection class provides handling of connections to other BLE devices. Connections can be in either Central or Peripheral roles.

When in a Peripheral role, the set_periph_callbacks() function is used to set up callbacks for connection and disconnection events.

The Connection object is passed into this callback so it can be saved by the script for later use.

When in a Central role, the connect() function is used to initiate a connection. This function takes individual callback functions for when this particular connection is fully connected and for when it is fully disconnected.

The Connection object should not be created directly. Instead, it is created by the BLE stack when a connection is made.

change_security(level: int)

Change the security level of the connection.

Parameters:: level – The new security level to use.

delete_pairing(all: bool)

Delete the pairing information for the connection.

This will cause the device to forget the pairing information and require a new pairing to be established.

Parameters:: all – If True, delete all pairing information for the device. If False, only delete the pairing information for this connection.

disconnect()

Disconnect the connection.

The Connection object should no longer be used after this method is called.

get_addr() → any

Return the address of the connected device for this connection

Returns:: The address of the connected device as a bytes array

get_rssi() → int

Return the RSSI of the connection

Returns:: The RSSI of the connection as a signed value in dBm.

set_security_cb(cb: any)

Set the callback to be used when the security level of the connection changes.

The callback function will take a :py:class:`Connection object and an integer representing the new security level.

Example:

>>> def security_cb(conn, level):
...     print("Security level changed to {}".format(level))
...
>>> conn.set_security_cb(security_cb)

Parameters:: cb – A callback used when the security level changes

class canvas_ble.GattClient(connection: Connection)

The GattClient class allows a device to discover and interact with the GATT server on a remotely-connected BLE device.

Parameters:: connection (Connection) – The Connection object associated with the BLE connection to use for the GATT client.

discover(discover_cb: any = None)

Discover the GATT database of the connected server. If the callback is provided, the function will return immediately and the callback will be called when the discovery is complete. If no callback is provided, the function will block until the discovery is complete.

Parameters:: discover_cb – A callback to be called when the GATT database has been discovered. The callback will be passed a single parameter, the GattClient object.

get_dict() → any

Returns a dictionary describing the discovered GATT database.

The top level of the dictionary is a dictionary of Services. Keys are UUID objects and values are dictionaries of Characteristics belonging to the service. The characteristic dictionary keys are UUID objects and the values are dictionaries of the characteristic properties. Properties supported in the characteristic dictionary are:

“handle”: The integer handle of the characteristic.
“flags” : An integer bitmask of the characteristic flags. Flags are taken from the set of constants named FLAG_*.

An example of the dictionary used to implement the Nordic UART Service is as follows:

gatt_dict = {
    UUID('6e400001-b5a3-f393-e0a9-e50e24dcca9e'): {
        UUID('6e400002-b5a3-f393-e0a9-e50e24dcca9e'): {
            "flags": canvas_ble.GattClient.FLAG_WRITE_NO_ACK,
            "handle": 15,
        },
        UUID('6e400003-b5a3-f393-e0a9-e50e24dcca9e'): {
            "flags": canvas_ble.GattClient.FLAG_NOTIFY,
            "handle": 17,
        }
    }
}

Returns:: a dictionary describing the discovered GATT database.

read(identifier: any, data: bytearray) → int

Read the value of a characteristic identified by the given UUID.

Parameters:

identifier – An identifier present within the GATT database that is to be read. The identifier can be an integer handle, a UUID object or name set by set_name(). If this identifier is not present in the GATT database or is not of a readable type an error will occur.
data – A bytearray to store the data read from the characteristic. The size of the bytearray will determine the maximum amount of data that can be read. If the characteristic has more data than the bytearray can hold, the data will be truncated.

Returns:

The number of bytes read from the characteristic.

set_callback(cb: any = None)

Callbacks can be set for any notifications or indications the GATT Server might make.

The callback function will be passed a named tuple containing the following entries:

client: The GattClient object that the event is associated with.
handle: The GATT handle integer for the characteristic that this event is associated with.
uuid: The UUID if the characteristic that this event is associated with.
name: If a name has been set for the UUID, it is included.
notify: True if this is a notification, False if it is an indication.
data: bytes data attached to the event.

Example:

>>> def notify_cb(event):
...     print("Notification from {} on UUID {} with data {}".format(
...         canvas_ble.addr_to_str(event.connection.get_addr()),
...         event.uuid, binascii.hexlify(event.data).decode()))
...
>>> client.set_callback(notify_cb, None)

Parameters:: cb – A callback to be called when a notification or indication is received from the connected server.

set_name(identifier: any, name: str)

Once a GATT database has been discovered a more descriptive name can be given to the services, characteristics and descriptors stored in it. These names can be given in place of a UUID for identifier parameters to methods.

Parameters:

identifier – A UUID object or handle present in the GATT database.
name (str) – A unique, within the GATT database, string that can be used to refer to GATT object instead of its UUID.

subscribe(identifier: any, notify: bool = False, indicate: bool = False)

Enable or disable notifications or indications for a given characteristic.

Example:

>>> gatt_client.subscribe(canvas_ble.UUID("b8d00002-6329-ef96-8a4d-55b376d8b25a"),
...     True, False)

Parameters:

identifier – An identifier present within the GATT database that is to be read. The identifier can be an integer handle, a UUID object or name set by set_name(). If this identifier is not present in the GATT database or is not a valid type an error will occur.
nofitify – Enable or disable notifications.
indicate – Enable or disable indications.

write(identifier: any, data: any, with_ack: any = None)

Write a value to a characteristic identified by the given identifier.

Parameters:

identifier – An identifier present within the GATT database that is to be read. The identifier can be an integer handle, a UUID object, or name set by set_name(). If this identifier is not present in the GATT database or is not of a writable type an error will occur.
data (bytes) – bytes containing the data to be written
with_ack – If None, the write will be done based on the properties of the characteristic. If True, the write will be done with an acknowledgment. If False, the write will be done without an acknowledgment. If the characteristic does not support the requested acknowledgment type, an error will occur.

FLAG_INDICATE: int

Characteristic can indicate to the client.

FLAG_NOTIFY: int

Characteristic can notify the client.

FLAG_READ: int

Characteristic is readable by the client.

FLAG_WRITE_ACK: int

Characteristic is writable by the client with an acknowledgment.

FLAG_WRITE_NO_ACK: int

Characteristic is writable by the client without an acknowledgment.

class canvas_ble.GattServer

The GattServer class allows creation and use of a GATT Server on the device.

Only one instance of the GattServer class can ever be created. Multiple GattServer instances are not supported at this time.

“Read” and “Write” functionality are from the CLIENT perspective. e.g. A “Read”able characteristic will have data written to it by this GattServer class and be read by the client and vice versa.

GATT Server Event Constants

The GATT server can cause the stack to raise a number of different events for each characteristic. These events can be received by the caller by use of a callback (see build_from_dict()).

As only a single callback is available for each event, the EVENT_* constants are used to indicate the specific event that caused the callback to be triggered.

GATT Server Callbacks

Characteristics can sometimes need to respond to events. This is achieved through the use of a callback system. A callback can be specified for each characteristic in the GATT server dictionary.

A callback is a Python function that recieves a named tuple as a parameter:

def my_callback(event):

Depending on the underlying event causing the callback to be called the event tuple will have various named members. These can be one or more of:

type: The type of event. This is always present. The values are from a set of constants named EVENT_*.
connection: The Connection object of the connection that caused the event. This is always present.
uuid: The UUID object of the characteristic that caused the event.
name: The name of the characteristic that caused the event.
handle: The integer handle of the characteristic that caused the event.
data: The characteristic value as bytes.

If canvas_ble.GattServer.EVENT_INDICATION_TIMEOUT is received, the connection concerned is deemed to have failed. If the disconnect callback from Connection has not been recieved and dealt with then the connection should be closed and deleted when an event of type canvas_ble.GattServer.INDICATION_TIMEOUT is received.

build_from_dict(description: dict)

Builds the GATT server from a correctly formatted dictionary. The format of the GATT server dictionary is as follows.

The top level of the dictionary is a dictionary of Services. Keys are UUID objects and values are dictionaries of Characteristics belonging to the service. The characteristic dictionary keys are UUID objects and the values are dictionaries of the characteristic properties. Properties supported in the characteristic dictionary are:

“name” : A string name for the characteristic.
“flags” : An integer bitmask of the characteristic flags. Flags are taken from the set of constants named FLAG_*.
“length” : The length of the characteristic in bytes.
“callback” : A callback function to be called when events occur on the characteristic.

An example of the dictionary used to implement the Nordic UART Service is as follows:

gatt_dict = {
    UUID('6e400001-b5a3-f393-e0a9-e50e24dcca9e'): {
        UUID('6e400002-b5a3-f393-e0a9-e50e24dcca9e'): {
            "name": "RX",
            "flags": canvas_ble.GattServer.FLAG_WRITE_NO_ACK,
            "length": 200,
            "callback": cb_nus_rx
        },
        UUID('6e400003-b5a3-f393-e0a9-e50e24dcca9e'): {
            "name": "TX",
            "flags": canvas_ble.GattServer.FLAG_NOTIFY,
            "length": 200,
            "callback": cb_nus_tx
        }
    }
}

Once this function has been called, the GATT server is not started. The GATT server must be started using the start() method.

Parameters:: description – The dictionary containing the GATT server description.

indicate(connection: Connection, identifier: any, value: bytes)

Indicates to the client through the named characteristic with a value. The characteristic must have the “Indicate” capability.

Parameters:

connection (Connection) – The connection to be used. This is the Connection class object.
identifier – An identifier present within the GATT database that is to be written. The identifier can be an integer handle, a UUID object, or name found in the GATT database. If this identifier is not present in the database or is not of an appropriate type, an error will occur.
value (bytes) – The value to be used in the indication.

notify(connection: Connection, identifier: any, value: bytes)

Notifies the client through the named characteristic with a value. The characteristic must have the “Notify” capability.

Parameters:

connection (Connection) – The connection to be used. This is the Connection class object.
identifier – An identifier present within the GATT database that is to be written. The identifier can be an integer handle, a UUID object, or name found in the GATT database. If this identifier is not present in the database or is not of an appropriate type, an error will occur.
value (bytes) – The value to be used in the notification.

read(identifier: any) → bytes

Reads the current value of a “Write” characteristic.

Parameters:: identifier – An identifier present within the GATT database that is to be read. The identifier can be an integer handle, a UUID object, or name found in the GATT database. If this identifier is not present in the database or is not of an appropriate type, an error will occur.
Returns:: bytes containing the data read.

start(): Starts the GATT server.

stop(): Stops the GATT server.

write(identifier: any, value: bytes)

Writes a new value into a “Read” characteristic

Parameters:

identifier – An identifier present within the GATT database that is to be written. The identifier can be an integer handle, a UUID object, or name found in the GATT database. If this identifier is not present in the database or is not of an appropriate type, an error will occur.
value (bytes) – The new value to be written.

EVENT_ATTR_VALUE: int

Raised when a client writes to a writeable characteristic.

EVENT_CCCD_BOTH: int

Raised when a client sets a Characteristics CCCD so both notifications and indications are enabled.

EVENT_CCCD_INDICATE: int

Raised when a client sets a Characteristics CCCD so indications are enabled.

EVENT_CCCD_NONE: int

Raised when a client sets a Characteristics CCCD so both notifications and indications are disabled.

EVENT_CCCD_NOTIFY: int

Raised when a client sets a Characteristics CCCD so notifications are enabled.

EVENT_INDICATION_OK: int

Raised when an indication is acknowledged

EVENT_INDICATION_TIMEOUT: int

Raised when an indication exceeds it’s acknowlegement timeout

FLAG_INDICATE: int

Characteristic can indicate to the client.

FLAG_NOTIFY: int

Characteristic can notify the client.

FLAG_READ: int

Characteristic is readable by the client.

FLAG_WRITE_ACK: int

Characteristic is writable by the client with an acknowledgment.

FLAG_WRITE_NO_ACK: int

Characteristic is writable by the client without an acknowledgment.

class canvas_ble.Scanner

Class for BLE scanning. This class is a singleton, only one scanner can be instantiated at a time. Attempting to instantiate a second scanner will return the existing instance.

Example:

>>> def scan_cb(event):
...     print("Received advertisement from {}".format(canvas_ble.addr_to_str(event.addr)))
...     print("  RSSI: {}".format(event.rssi))
...     print("  Type: {}".format(event.type))
...     print("  Data: {}".format(binascii.hexlify(event.data).decode()))
...
>>> scanner = canvas_ble.Scanner(scan_cb)
>>> scanner.start(True)

Parameters:

cb –

Callback function to be called when a BLE advertisement is received. The callback function must accept a single argument, which will be a named tuple of the form (rssi, type, data, addr). The rssi is the received signal strength indicator, the type is the advertisement type, the data is the advertisement data, and the addr is the MAC address of the device that sent the advertisement. ‘type’ will be a bitmask of one or more of the following values:

canvas_ble.Scanner.TYPE_CONNECTABLE: Connectable advertisement.
canvas_ble.Scanner.TYPE_SCANNABLE: Scannable advertisement.
canvas_ble.Scanner.TYPE_DIRECTED: Directed advertisement.
canvas_ble.Scanner.TYPE_SCAN_RESPONSE: Scan response.
canvas_ble.Scanner.TYPE_LEGACY: Legacy advertisement.
canvas_ble.Scanner.TYPE_EXTENDED: Extended advertisement.

filter_add(type: int, data: any)

Add a filter to the scanner.

In areas where there is a lot of BLE advertisements, it may be desirable to filter the advertisements. This function allows the user to set filters on the scanner to only receive advertisements that match the filter. This helps to reduce the processing time needed to handle advertisements and allows the Python application to focus only on the advertisements that are of interest.

The type parameter is the type of the filter to set on the advertisement data. The data parameter is particular to the type of filter being set.

The following filter types are supported:

canvas_ble.Scanner.FILTER_NAME: The data parameter is a string. The name of the device in the advertisement must match the string in its entirety.
canvas_ble.Scanner.FILTER_UUID: The data parameter is a UUID string. The size of the data determines the UUID type to filter on. Two bytes of data are required for a 16-bit UUID, four bytes of data are required for a 32-bit UUID, and 16 bytes of data are required for a 128-bit UUID.
canvas_ble.Scanner.FILTER_ADDR: The data parameter is a BLE address byte string.
canvas_ble.Scanner.FILTER_MANUF_DATA: The data parameter is a byte string of manufacturer data. This data is compared to the manufacturer data in the advertisement. The first two bytes of the data are always the manufacturer ID. The filter data can be smaller than the advertisement data to allow matching only on the manufacturer ID or manufacturer ID and a portion of the manufacturer- specific data.
canvas_ble.Scanner.FILTER_DATA: The data parameter is a byte string of generic data. The filter matches if the data in the advertisement contains the filter data in its entirety at any location.

Example to filter on device name:

>>> scanner = canvas_ble.Scanner(scan_cb)
>>> scanner.filter_add(canvas_ble.Scanner.FILTER_NAME, "Canvas".encode())

Parameters:

type (int) – Type of filter to set.
data (bytes) – Filter data.

filter_reset(): Remove all of the filters from the scanner.

set_phys(phys: int)

Set the PHYs to scan on. The phys parameter is a bitmask of the PHYs to scan on. The bitmask is a combination of the following values: canvas_ble.PHY_1M, canvas_ble.PHY_2M, and canvas_ble.PHY_CODED.

Example:

>>> scanner = canvas_ble.Scanner(scan_cb)
>>> scanner.set_phys(canvas_ble.PHY_1M | canvas_ble.PHY_2M)

Parameters:: phys (int) – Bitmask of the PHYs to scan on.

set_timing(interval_ms: int, window_ms: int)

Set the scan timing. The interval_ms parameter is the scan interval in milliseconds, and the window_ms parameter is the scan window in milliseconds. The scan window must be less than or equal to the scan interval.

Example to scan roughly 50% of the time (50 milliseconds out of every 100 milliseconds):

>>> scanner = canvas_ble.Scanner(scan_cb)
>>> scanner.set_timing(100, 50)

Parameters:

interval_ms (int) – Scan interval in milliseconds.
window_ms (int) – Scan window in milliseconds.

start(active: bool)

Start the scanner. The active parameter is a boolean value that indicates whether the scanner should be active or passive. If the value is True, the scanner will send scan requests to devices that advertise with a scannable advertisement type. If the value is False, the scanner will not send scan requests.

Parameters:: active (bool) – Boolean value indicating whether the scanner should be active (True) or passive (False).

stop(): Stop the scanner.

FILTER_ADDR: int

Filter on device MAC address.

FILTER_DATA: int

Filter on generic bytes in advertisement.

FILTER_MANUF_DATA: int

Filter on bytes from manufacturer-specific data in advertisement.

FILTER_NAME: int

Filter on device name in advertisement.

FILTER_UUID: int

Filter on UUID in advertisement.

TYPE_CONNECTABLE: int

Connectable advertisement.

TYPE_DIRECTED: int

Directed advertisement.

TYPE_EXTENDED: int

Extended advertisement.

TYPE_LEGACY: int

Legacy (not extended) advertisement.

TYPE_SCANNABLE: int

Scannable advertisement.

TYPE_SCAN_RESPONSE: int

Scan response data

class canvas_ble.UUID(uuid)

Class representing a BLE UUID. This class is used to create UUID objects that can be used to identify services, characteristics, and descriptors.

Parameters:: uuid – The UUID to create. This can be a 16-bit integer or a string representation of a 128-bit UUID.

canvas_ble.addr_to_str(addr: any) → str

Convert a BLE address into a printable string.

Example:

>>> mine = canvas_ble.my_addr()
>>> mine
b'\x01\xd3\xae\\~\xa8\xf7'
>>> canvas_ble.addr_to_str(mine)
'01f7a87e5caed3'

Parameters:: addr (bytes) – The BLE address to convert.
Returns:: A string representation of the address.

canvas_ble.connect(addr: any, phy: int, cb_con: any, cb_discon: any) → Connection

Initiate a connection when in a Central role.

Example:

>>> def connection_cb(conn):
...     print("Connection established with {}".format(
...         canvas_ble.addr_to_str(conn.get_addr())))
...
>>> def disconnection_cb(conn):
...     print("Connection closed with {}".format(
...         canvas_ble.addr_to_str(conn.get_addr())))
...
>>> addr = canvas_ble.str_to_addr("01f7a87e5caed3")
>>> conn = canvas_ble.connect(addr, canvas_ble.PHY_1M, connection_cb, disconnection_cb)
Connection established with 01f7a87e5caed3
>>> conn->disconnect()

Parameters:

addr (bytes) – A bytes object containing the BLE address to connect to. canvas_ble.str_to_addr() can be used to create this from an appropriate string.
phy (int) – The PHY to use (one of the canvas_ble.PHY_* constants)
cb_con – A callback used when a connection has been established
cb_discon – A callback used when the connection ends

Returns:

The Connection object for the new connection or None on error.

canvas_ble.find_ltv(type: int, ad: any) → any

Find the first LTV (length, type, value) tuple in the advertisement data that matches the given type. The type parameter is the type of the LTV to find. The ad parameter is the advertisement data to search.

Example:

>>> def scan_cb(data):
...     ltv = canvas_ble.find_ltv(canvas_ble.AD_TYPE_NAME_COMPLETE, data.data)
...     if ltv is not None:
...         print("Device name: {}".format(ltv.decode()))
...
>>> scanner = canvas_ble.Scanner(scan_cb)
>>> scanner.start(True)

Parameters:

type (int) – Type of LTV to find.
ad (bytes) – Advertisement data to search.

Returns:

A bytes object containing the value of the LTV tuple found or None if no LTV tuple matches the given type. If a matching LTV occurs more than once in the advertising data, only the first occurrence will be returned.

canvas_ble.get_actual_tx_power() → int

Get the current actual TX power. This returns the value the module is actually transmitting at. In the example below the region is set to UK, for certain modules this will limit the maximum TX power to 7.0dbm even if a higher power is requested. This function returns that limited value.

Example::

>>> canvas_ble.set_region(canvas_ble.REGION_UK)
>>> canvas_ble.set_tx_power(100)
>>> canvas_ble.get_actual_tx_power()
>>> 70

Returns:: The curent actual TX power in 0.1dbm steps.

canvas_ble.get_region() → int

Get the currnt BLE regulatory region

Example::

>>> canvas_ble.set_region(canvas_ble.REGION_UK)
>>> canvas_ble.get_region()
>>> 2

Returns:: The current BLE regulatory region

canvas_ble.get_tx_power() → int

Get the current requested TX power. This returns the value set by the previous set_tx_power call, or the default value for the module if there has been no previous set_tx_power call.

Example::

>>> canvas_ble.set_tx_power(100)
>>> canvas_ble.get_tx_power()
>>> 100

Returns:: The last requested BLE TX power value in 0.1dbm steps.

canvas_ble.init(): Initialize the BLE stack. This function must be called before any other function in this module. It should only be called once.

canvas_ble.my_addr() → any

Get the local BLE address.

Example:

>>> mine = canvas_ble.my_addr()
>>> mine
b'\x01\xd3\xae\\~\xa8\xf7'
>>> canvas_ble.addr_to_str(mine)
'01f7a87e5caed3'

Returns:: The BLE address of the local device.

canvas_ble.set_periph_callbacks(con: any, discon: any)

Set the callbacks to be used when the device is operating in a Peripheral role. The callback functions will take a Connection object as their parameter.

Example:

>>> def connection_cb(conn):
...     print("Connection established with {}".format(
...         canvas_ble.addr_to_str(conn.get_addr())))
...
>>> def disconnection_cb(conn):
...     print("Connection closed with {}".format(
...         canvas_ble.addr_to_str(conn.get_addr())))
...
>>> canvas_ble.set_periph_callbacks(connection_cb, disconnection_cb)

Parameters:

con – A callback used when a connection is made
discon – A callback used when a disconnection is made

canvas_ble.set_region(region: int)

Set the BLE regulatory region Note: This can only be called successfully when the BLE system is not advertising, scanning, connected, etc. Note: On Zephyr/nRF devices, the region is fixed to :py:data:canvas_ble.REGION_GLOBAL.

Example::

>>> canvas_ble.set_region(canvas_ble.REGION_UK)

Parameters:: region (int) – The region to be used

canvas_ble.set_tx_power(power_dbm10: int)

Set the power used for BLE transmission in 0.1dbm steps. The power level set may differ from that actually used due to the regulatory region set and the module used. This can only be called successfully when the BLE system is not advertising, scanning, connected, etc. Note: On Zephyr/nRF devices, TX power defaults to 0dbm. Fractional power values may be rounded before being applied. Use :py:meth:get_tx_power to see the applied tx power value.

Example::

>>> canvas_ble.set_tx_power(70)

Parameters:: power_dbm10 (int) – The power to be used in 0.1 dbm steps. For example 25 is 2.5dbm

canvas_ble.str_to_addr(addr_str: str) → any

Convert a BLE address string into a binary representation usable by the BLE stack.

Example:

>>> mine = canvas_ble.my_addr()
>>> mine
b'\x01\xd3\xae\\~\xa8\xf7'
>>> mine_str = canvas_ble.addr_to_str(mine)
>>> mine_str
'01f7a87e5caed3'
>>> canvas_ble.str_to_addr(mine_str)
b'\x01\xd3\xae\\~\xa8\xf7'

Parameters:: addr_str (str) – The BLE address string to convert.
Returns:: A binary representation of the address.

canvas_ble.AD_TYPE_FLAGS: int

Advertisement type value for flags

canvas_ble.AD_TYPE_MANU_SPECIFIC: int

Advertisement type value for manufacturer-specific data

canvas_ble.AD_TYPE_NAME_COMPLETE: int

Advertisement type value for a complete device name

canvas_ble.AD_TYPE_NAME_SHORT: int

Advertisement type value for a shortened device name

canvas_ble.AD_TYPE_UUID128_COMPLETE: int

Advertisement type value for a complete list of 128-bit UUIDs

canvas_ble.AD_TYPE_UUID128_INCOMPLETE: int

Advertisement type value for an incomplete list of 128-bit UUIDs

canvas_ble.AD_TYPE_UUID16_COMPLETE: int

Advertisement type value for a complete list of 16-bit UUIDs

canvas_ble.AD_TYPE_UUID16_INCOMPLETE: int

Advertisement type value for an incomplete list of 16-bit UUIDs

canvas_ble.AD_TYPE_UUID32_COMPLETE: int

Advertisement type value for a complete list of 32-bit UUIDs

canvas_ble.AD_TYPE_UUID32_INCOMPLETE: int

Advertisement type value for an incomplete list of 32-bit UUIDs

canvas_ble.PHY_125K: int

Coded PHY at 125kbits/sec

canvas_ble.PHY_1M: int

1M PHY

canvas_ble.PHY_2M: int

2M PHY

canvas_ble.PHY_500K: int

Coded PHY at 500kbits/sec

canvas_ble.PHY_CODED: int

Coded PHY, generic

canvas_ble.REGION_AUSTRALIA: int

Australia region

canvas_ble.REGION_CANADA: int

Canada region

canvas_ble.REGION_EU: int

EU region

canvas_ble.REGION_GLOBAL: int

Global region

canvas_ble.REGION_JAPAN: int

Japan region

canvas_ble.REGION_NEW_ZEALAND: int

New Zealand region

canvas_ble.REGION_SOUTH_KOREA: int

South Korea region

canvas_ble.REGION_UK: int

UK region

canvas_ble.REGION_USA: int

USA region