Skip to main content

A python library for controlling Renesas BLE devices

Project description

py_ble_manager

A python library for controlling Renesas BLE devices.

Purpose

The intent of this library is to provide a python interface similar to SDK10 for controlling BLE of DA14xxx devices. This is achieved by communicating with a development kit running Generic Transport Layer (GTL) supported firmware over a USB port on your PC:

The primary intent is for use as a central device for benchtop testing, continuous integration, or as an end-of-line tool. For additional information on the GTL please see the GTL User Manual.

Quick Start

  1. Refer to the hardware setup to setup the jumpers on your development kit.

  2. Call: pip install py-ble-manager[dev] to install the py_ble_manager package and its dependencies.

    NOTE: Specifying [dev] will install optional dependency: prompt_toolkit. prompt_toolkit is used in some of the examples to provide a command line interface.

    NOTE: This library requires Python v3.10.5 or later.

    NOTE: It is recommended to install the library using a virtual environment. To setup a virtual environment using venv call: $ python -m venv ./<name_of_your_env>. Note to create a virtual environment that uses Python 3.10.5, you must already have Python 3.10.5 downloaded on your computer. To use the above command to create a Python 3.10.5 environment, Python 3.10.5 must be configured in your PATH. You can download it from the python website.

  3. Download the py_ble_manager compatible firmware binary to the development kit by calling the py_ble_manager_programmer utility from the terminal.

  4. The package is now installed and you are ready to run one of the examples!

Basic Usage

Create a BLE Central object and perform initialization

import py_ble_manager as ble

central = ble.BleCentral("COM54")

# Initialize the Python BLE Framework
central.init()

# Start operating as a BLE Central 
central.start()

# Set the IO capabilities
central.set_io_cap(ble.GAP_IO_CAPABILITIES.GAP_IO_CAP_KEYBOARD_DISP)

Initiate a BLE Operation

Some examples include:

Scanning:

central.scan_start(type=ble.GAP_SCAN_TYPE.GAP_SCAN_ACTIVE,
                   mode=ble.GAP_SCAN_MODE.GAP_SCAN_GEN_DISC_MODE,
                   interval_ms=100,
                   window_ms=50,
                   filt_wlist=False,
                   filt_dupl=True)

Connecting:

peripheral_addr: ble.BdAddress = ble.BleUtils.str_to_bd_addr("48:23:35:00:1b:53,P") 
connection_params = ble.GapConnParams(interval_min_ms=50, interval_max_ms=70, slave_latency=0, sup_timeout_ms=420)
central.connect(peripheral_addr, connection_params)

Read a characteristic value

central.read(conn_idx=0, handle=24, offset=0) 

Write a characteristic value

central.write(conn_idx=0, handle=24, offset=0, value=1234) 

Disconnect

central.disconnect(conn_idx=0) 

Handle asynchronous events

The framework returns asynchronous events to the application through an event queue. Calling BleCentral.get_event() will get an event from the queue. All of the events returned by BleCentral.get_event() are a subclass of BleEventBase. A variety of different events occur throughout the life a BLE application. Some example events include BleEventGapConnectionCompleted, BleEventGapDisconnected, BleEventGattcReadCompleted, BleEventGattcWriteCompleted. Each event has an evt_code to identify the type of event.

For example, after you initiate a write you will receive a BleEventGattcWriteCompleted event which has an evt_code of BLE_EVT_GATTC.BLE_EVT_GATTC_WRITE_COMPLETED. Your application can handle the event however it sees fit. If your application does not handle the event, call BleCentral.handle_event_default() to have the BLE framework process the event for you.

# This call will block until an event is available. Use the timeout parameter to block for a specified period of time
evt = central.get_event()
    
    # Determine which event occurred. It will be of type BLE_EVT_GAP, BLE_EVT_GATTC, or BLE_EVT_GATTS
    match evt.evt_code:

        # Handle the event
        case ble.BLE_EVT_GAP.BLE_EVT_GAP_ADV_REPORT:
            # Define your own handling function to process the event
            handle_evt_gap_adv_report(evt)
        case ble.BLE_EVT_GAP.BLE_EVT_GAP_SCAN_COMPLETED:
            handle_evt_gap_scan_completed(evt)
        case ble.BLE_EVT_GAP.BLE_EVT_GAP_CONNECTED:
            handle_evt_gap_connected(evt)
        case ble.BLE_EVT_GAP.BLE_EVT_GAP_CONNECTION_COMPLETED:
            handle_evt_gap_connection_completed(evt)
        case ble.BLE_EVT_GAP.BLE_EVT_GAP_DISCONNECTED:
            handle_evt_gap_disconnected(evt)
        case ble.BLE_EVT_GATTC.BLE_EVT_GATTC_BROWSE_SVC:
            handle_evt_gattc_browse_svc(evt)
        case ble.BLE_EVT_GATTC.BLE_EVT_GATTC_BROWSE_COMPLETED:
            handle_evt_gattc_browse_completed(evt)
        case ble.BLE_EVT_GATTC.BLE_EVT_GATTC_NOTIFICATION:
            handle_evt_gattc_notification(evt)
        case ble.BLE_EVT_GATTC.BLE_EVT_GATTC_WRITE_COMPLETED:
            handle_evt_gattc_write_completed(evt)
        case ble.BLE_EVT_GATTC.BLE_EVT_GATTC_READ_COMPLETED:
            handle_evt_gattc_read_completed(evt)

        case _:
            # For any events not handled by your application, call the BleCentral default handler to process the event
            central.handle_event_default(evt)

Architecture

Refer to the architecture description.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_ble_manager-1.0.0.tar.gz (2.5 MB view details)

Uploaded Source

Built Distribution

py_ble_manager-1.0.0-py3-none-any.whl (921.0 kB view details)

Uploaded Python 3

File details

Details for the file py_ble_manager-1.0.0.tar.gz.

File metadata

  • Download URL: py_ble_manager-1.0.0.tar.gz
  • Upload date:
  • Size: 2.5 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.12

File hashes

Hashes for py_ble_manager-1.0.0.tar.gz
Algorithm Hash digest
SHA256 e03905e155b500f3a50bce8acabd42ab16f96daa302f28fb9b9b41bfdabc037a
MD5 73b57e8adae519a1a0fdfee2e3a34993
BLAKE2b-256 90349272caca879464fdf0e5c09d0db3fd6b4733bd8b7d46dbdc54b6d3b467a9

See more details on using hashes here.

File details

Details for the file py_ble_manager-1.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for py_ble_manager-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 b173a42695e64a9f32ce2be1633a6e93e24e5e04f459d007de797dc5c407dc2e
MD5 ae4f3afe851c00e20dd795cb09d27b07
BLAKE2b-256 57489b0c2f8572360e8e2be3633df91c1371ebf5a101dd9f03dc4714c5a17e42

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page