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
-
Refer to the hardware setup to setup the jumpers on your development kit.
-
Call:
pip install py-ble-manager[dev]
to install thepy_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. -
Download the py_ble_manager compatible firmware binary to the development kit by calling the
py_ble_manager_programmer
utility from the terminal. -
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | e03905e155b500f3a50bce8acabd42ab16f96daa302f28fb9b9b41bfdabc037a |
|
MD5 | 73b57e8adae519a1a0fdfee2e3a34993 |
|
BLAKE2b-256 | 90349272caca879464fdf0e5c09d0db3fd6b4733bd8b7d46dbdc54b6d3b467a9 |
File details
Details for the file py_ble_manager-1.0.0-py3-none-any.whl
.
File metadata
- Download URL: py_ble_manager-1.0.0-py3-none-any.whl
- Upload date:
- Size: 921.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.10.12
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | b173a42695e64a9f32ce2be1633a6e93e24e5e04f459d007de797dc5c407dc2e |
|
MD5 | ae4f3afe851c00e20dd795cb09d27b07 |
|
BLAKE2b-256 | 57489b0c2f8572360e8e2be3633df91c1371ebf5a101dd9f03dc4714c5a17e42 |