digi.ccble.service module

class digi.ccble.service.BLEInterface(value)[source]

Bases: Enum

Enumeration class listing all the Bluetooth Low Energy interfaces.

Values:

BLEInterface.ANY = (0, ‘Any’, ‘Use first available interface, starting with native adapters’)
BLEInterface.ADAPTER = (1, ‘Bluetooth adapter’, ‘Use native Bluetooth adapter interface’)
BLEInterface.XBEE3 = (2, ‘XBee 3’, ‘Use XBee 3 Bluetooth interface’)

Class constructor. Instantiates a new BLEInterface entry with the provided parameters.

Parameters:

code (Integer) – BLE interface code.
title (String) – BLE interface title.
description (String) – BLE interface description.

ANY = (0, 'Any', 'Use first available interface, starting with native adapters')

ADAPTER = (1, 'Bluetooth adapter', 'Use native Bluetooth adapter interface')

XBEE3 = (2, 'XBee 3', 'Use XBee 3 Bluetooth interface')

property code

Returns the BLE interface code.

Returns:: BLE interface code.
Return type:: Integer

property title

Returns the BLE interface title.

Returns:: BLE interface title.
Return type:: String

property description

Returns the BLE interface description.

Returns:: BLE interface description.
Return type:: String

classmethod get(code)[source]

Returns the BLE interface corresponding to the given code.

Parameters:: code (Integer) – BLE interface code.
Returns:: BLE interface corresponding to the given code, None if not found.
Return type:: SrpError

digi.ccble.service.get_bluetooth_adapter()[source]

Returns the first available Bluetooth adapter in the system.

Returns:

The first Adapter available in the system, None if: no adapter is found.

Return type:

Adapter

digi.ccble.service.get_xbee_device()[source]

Returns the first available XBee BTLE capable device in the system.

Returns:

The first BTLE XBeeDevice available in the system, None: if no device is found.

Return type:

XBeeDevice

class digi.ccble.service.ConnectCoreBLEService(interface_type)[source]

Bases: ABC

This class offers several methods that can be used to communicate a ConnectCore device working as a Peripheral device with an external device via Bluetooth Low Energy.

The Bluetooth Low Energy communication can be based on native Bluetooth adapters or on the XBee 3 Bluetooth Low Energy interface.

Class constructor. Instantiates a new ConnectCoreBLEService object with the given parameters.

Parameters:: interface_type (BLEInterface) – the BLE interface type to use.

classmethod get_instance(ble_interface=BLEInterface.ANY)[source]

Checks the available Bluetooth interfaces of the device and generates a single instance of the class depending on the preferred interface. If an instance already exist, the method simply returns that instance.

Depending on the preferred interface, the method returns as follows:

If the interface is set to ‘ANY’ or ‘ADAPTER’ and Bluetooth is natively supported in the system, a ConnectCoreBLEServiceNative object is returned.
If the interface is set to ‘ANY’ and the system does not support native Bluetooth or the interface is set to ‘XBEE3’, the method tries to find a BLE capable XBee 3 device connected to the system and returns a ConnectCoreBLEServiceXBee object.

Parameters:: ble_interface (BLEInterface) – the BLE interface type to use.
Returns:: the single service instance.
Return type:: ConnectCoreBLEService
Raises:: BluetoothNotSupportedException – if the system does not have any valid Bluetooth interface.

is_running()[source]

Returns whether the service is running or not.

Returns:: True if service is running, False otherwise.
Return type:: Boolean

get_interface_type()[source]

Returns the interface type.

Returns:: The interface type.
Return type:: BLEInterface

add_data_received_callback(callback)[source]

Adds a new callback to the list of callbacks that will be notified when data is received from the connected device.

Parameters:: callback (Function) – the new callback function.

remove_data_received_callback(callback)[source]

Removes the given callback from the data_received callbacks list.

Parameters:: callback (Function) – the callback function to be removed.

add_connect_callback(callback)[source]

Adds a new callback to the list of callbacks that will be notified when a device connects.

Parameters:: callback (Function) – the new callback function.

remove_connect_callback(callback)[source]

Removes the given callback from the list of connect callbacks.

Parameters:: callback (Function) – the callback function to be removed.

add_disconnect_callback(callback)[source]

Adds a new callback to the list of callbacks that will be notified when a device disconnects.

Parameters:: callback (Function) – the new callback function.

remove_disconnect_callback(callback)[source]

Removes the given callback from the list of disconnect callbacks.

Parameters:: callback (Function) – the callback function to be removed.

abstract start()[source]

Starts the BLE service.

Raises:: ConnectCoreBLEException – if an error occurs while starting the service.

abstract stop()[source]

Stops the BLE service.

Raises:: ConnectCoreBLEException – if an error occurs while stopping the service.

abstract send_data(data)[source]

Sends the given data to the connected device through the available BLE interface.

Parameters:: data (Bytearray) – data to send.
Raises:: ConnectCoreBLEException – if an error occurs while sending the data.

abstract get_advertising_name()[source]

Changes the currently advertised service name.

Returns:: the current advertising name.
Return type:: String
Raises:: ConnectCoreBLEException – if an error occurs while reading the advertising name.

abstract set_advertising_name(device_name)[source]

Changes the currently advertised service name.

Parameters:: device_name (String) – the new name of the service.
Raises:: ConnectCoreBLEException – if an error occurs while changing the advertising name.

abstract is_device_connected()[source]

Checks whether there is any device connected to the BLE interface or not.

Returns:: True if there is any device connected, False otherwise.
Return type:: Boolean

abstract set_password(new_password)[source]

Sets the new authentication password for the service.

Parameters:: new_password (String) – the new authentication password.
Raises:: ConnectCoreBLEException – if an error occurs while setting the new password.

class digi.ccble.service.ConnectCoreBLEServiceNative(adapter_address)[source]

Bases: ConnectCoreBLEService

This class represents a native ConnectCoreBLEService by creating a local GATT server with an UART peripheral exposing read and write interfaces.

The service uses SRP authentication protocol to encrypt and decrypt data with a default password of ‘1234’.

Class constructor. Instantiates a new ConnectCoreBLEServiceNative object with the given parameters.

Parameters:: adapter_address (String) – the address of the native Bluetooth adapter to use.

start()[source]: Override.

See also

ConnectCoreBLEService.start()

stop()[source]: Override.

See also

ConnectCoreBLEService.stop()

send_data(data)[source]: Override.

See also

ConnectCoreBLEService.send_data()

get_advertising_name()[source]: Override.

See also

ConnectCoreBLEService.get_advertising_name()

set_advertising_name(device_name)[source]: Override.

See also

ConnectCoreBLEService.set_advertising_name()

is_device_connected()[source]: Override.

See also

ConnectCoreBLEService.is_device_connected()

set_password(new_password)[source]: Override.

See also

ConnectCoreBLEService.set_password()

class digi.ccble.service.BLEServiceXBee(open_xbee)[source]

Bases: ConnectCoreBLEService

This class implements the abstract methods of ConnectCoreBLEService by establishing connection with an XBee device and communicating with its GATT server.

The service uses SRP authentication protocol to encrypt and decrypt data managed by the XBee device.

Class constructor. Instantiates a new ConnectCoreBLEService object with the given parameters.

Parameters:: interface_type (BLEInterface) – the BLE interface type to use.

start()[source]: Override.

See also

ConnectCoreBLEService.start()

stop()[source]: Override.

See also

ConnectCoreBLEService.stop()

send_data(data)[source]: Override.

See also

ConnectCoreBLEService.send_data()

get_advertising_name()[source]: Override.

See also

ConnectCoreBLEService.get_advertising_name()

set_advertising_name(device_name)[source]: Override.

See also

ConnectCoreBLEService.set_advertising_name()

is_device_connected()[source]: Override.

See also

ConnectCoreBLEService.is_device_connected()

set_password(new_password)[source]: Override.

See also

ConnectCoreBLEService.set_password()