Get started with ConnectCore Bluetooth Low Energy Python library

This getting started guide describes how to set up your environment and use the ConnectCore Bluetooth Low Energy library to communicate your Digi ConnectCore devices with mobile applications. It explains how to install the software and write your first application.

The guide is split into 2 main sections:

Install your software

The following software components are required to write and run your first application:

Python 3

The ConnectCore Bluetooth Low Energy Python library requires Python 3. If you don’t have Python 3, you can get it from https://www.python.org/getit/.

Warning

The XBee Python library is currently only compatible with Python 3.

Bluezero

When Bluetooth is natively supported in your ConnectCore device, the library will make use of it through the D-Bus communication interface. For that functionality, the ConnectCore BLE Python library uses the Bluezero module, which provides an abstraction layer to access and interact with Bluetooth over this bus.

This module is automatically downloaded when you install the library.

XBee Python

If Bluetooth is not natively supported in your ConnectCore device, the library will try to find a valid BLE capable XBee 3 module attached to your device and use it as the communication interface. For that functionality, the ConnectCore BLE Python library uses the XBee Python module.

This module is automatically downloaded when you install the library.

SRP

The ConnectCore BLE Python library uses the SRP module to authenticate with mobile applications over Bluetooth Low Energy.

This module is automatically downloaded when you install the ConnectCore BLE Python library.

ConnectCore Bluetooth Low Energy library software

The best way to install the ConnectCore Bluetooth Low Energy library is with the pip tool (which is what Python uses to install packages). The pip tool comes with recent versions of Python.

To install the library, run this command in your terminal application:

$ pip install digi-connectcore-ble

The library is automatically downloaded and installed in your Python interpreter.

Get the source code

The ConnectCore Bluetooth Low Energy python library is actively developed on GitHub, where the code is always available. You can clone the repository with:

$ git clone git@github.com:digi-embedded/connectcore-ble-python.git

Run your first ConnectCore Bluetooth Low Energy application

The ConnectCore BLE Python application demonstrated in the guide waits for incoming data from the connected device and prints it in the console.

For this guide, you will need a mobile phone with the Digi XBee Mobile application already installed to test.

Follow these steps to register the data callback and start the service:

  1. Open the Python interpreter and write the application commands.

    1. Import the ConnectCoreBLEService class by executing the following command:

      > from digi.ccble.service import ConnectCoreBLEService

    2. Instantiate the ConnectCore BLE service:

      > cc_ble_service = ConnectCoreBLEService.get_instance()

    3. Define the data received callback function:

      > data_callback = lambda data: print("Received data: %s" % data.decode())

    4. Register a data received callback:

      > cc_ble_service.add_data_received_callback(data_callback)

    5. Start the service:

      > cc_ble_service.start()

Follow these steps to test the above code with the Digi XBee Mobile application:

  1. Open the Digi XBee Mobile application.

  2. Select the device from the list. Enter the password (1234) when asked.

  3. In the device page, open the options menu located at the top-right corner of the application and select the Relay Console option.

  4. In the Relay Console, click the + button of the Send frames section.

  5. Set the ‘XBee interface’ to ‘BLUETOOTH’ in the Add new frame popup.

  6. Set ‘Hello World’ as the Data to be sent and click ‘Add’ button.

  7. Now, select the frame that you have just added from the Send frames list and click Send selected frame.

  8. The data should be received by the service and printed int the console:

    Received data: Hello World