py_ble_manager.ble_devices package

Submodules

py_ble_manager.ble_devices.BleCentral module

class BleCentral(com_port: str, baud_rate: int = 1000000, ble_config: ~py_ble_manager.ble_api.BleConfig.BleConfigDefault = <py_ble_manager.ble_api.BleConfig.BleConfigDefault object>)[source]

Bases: BleDeviceBase

A BLE central device

Parameters:

  • com_port (str) – COM port of the development kit

  • baud_rate (int) – Baud rate for serial port of the development kit

  • ble_config (BleConfigDefault, optional) – BLE configuration to use, defaults to BleConfigDefault(BLE_DEVICE_TYPE.CENTRAL)

browse(conn_idx: int, uuid: Optional[AttUuid] = None) → BLE_ERROR[source]

Browse services on remote GATT server

This will automatically discover all characteristics and descriptors of a service. To discover services only, use discover_services(). instead.

BleEventGattcBrowseSvc will be sent for each service found. Once completed BleEventGattcBrowseCompleted will be sent.

If uuid is None, all services are returned.

Parameters:

  • conn_idx (int) – connection index

  • uuid (AttUuid) – optional service UUID

Returns:

result code

Return type:

BLE_ERROR

browse_range(conn_idx: int, start_h: int, end_h: int, uuid: Optional[AttUuid] = None) → BLE_ERROR[source]

Browse services on remote GATT server in a given range

This will automatically discover all characteristics and descriptors of a service in the range between start_h and end_h.

BleEventGattcBrowseSvc will be sent for each service found. Once completed BleEventGattcBrowseCompleted will be sent.

If uuid is None, all services in range are returned.

Parameters:

  • conn_idx (int) – connection index

  • start_h (int) – start handle

  • end_h (int) – end handle

  • uuid (AttUuid) – optional service UUID

Returns:

result code

Return type:

BLE_ERROR

connect(peer_addr: BdAddress, conn_params: GapConnParams) → BLE_ERROR[source]

Connect to a device

This call initiates a direct connection procedure to a specified device. The application will get a BleEventGapConnected event when the connection is established and a BleEventGapConnectionCompleted event when the connection procedure is completed either successfully or with error (in the second case, BleEventGapConnected will not be received).

Parameters:

  • peer_addr (BdAddress) – BD address of the peer device

  • conn_params (GapConnParams) – connection parameters to be used

Returns:

result code

Return type:

BLE_ERROR

connect_cancel() → BLE_ERROR[source]

Cancel an initiated connection

This call cancels a previously started connection procedure using connect(). The application will receive a BleEventGapConnectionCompleted event with status set to BLE_ERROR_CANCELED if the connection procedure is successfully canceled.

Returns:

result code

Return type:

BLE_ERROR

discover_characteristics(conn_idx: int, start_h: int, end_h: int, uuid: AttUuid) → BLE_ERROR[source]

Discover characteristics on remote GATT server

BleEventGattcDiscoverChar will be sent for each characteristic found. Once completed BleEventGattcDiscoverCompleted will be sent.

If uuid is None, all characteristics are returned.

Parameters:

  • conn_idx (int) – connection index

  • start_h (int) – start handle of service to discover

  • end_h (int) – end handle of service to discover

  • uuid (AttUuid) – optional characteristic UUID

Returns:

result code

Return type:

BLE_ERROR

discover_descriptors(conn_idx: int, start_h: int, end_h: int) → BLE_ERROR[source]

Discover descriptors on remote GATT server

BleEventGattcDiscoverDesc will be sent for each descriptor found. Once completed BleEventGattcDiscoverCompleted will be sent.

Parameters:

  • conn_idx (int) – connection index

  • start_h (int) – start handle of characteristic to discover

  • end_h (int) – end handle of characteristic to discover

Returns:

result code

Return type:

BLE_ERROR

discover_include(conn_idx: int, start_h: int, end_h: int) → BLE_ERROR[source]

Discover included services on remote GATT server

BleEventGattcDiscoverInclude will be sent for each service found. Once completed BleEventGattcDiscoverCompleted will be sent.

Parameters:

  • conn_idx (int) – connection index

  • start_h (int) – start handle of service to discover

  • end_h (int) – end handle of service to discover

Returns:

result code

Return type:

BLE_ERROR

discover_services(conn_idx: int, uuid: AttUuid) → BLE_ERROR[source]

Discover services on remote GATT server

BleEventGattcDiscoverSvc will be sent for each service found. Once completed BleEventGattcDiscoverCompleted will be sent.

If uuid is None, all services are returned.

Parameters:

  • conn_idx (int) – connection index

  • uuid (AttUuid) – optional service UUID

Returns:

result code

Return type:

BLE_ERROR

handle_event_default(evt: BleEventBase) → None[source]

Execute default event handler

It’s recommended for application to call this for any event it does not handle. This avoids situation when BLE stack is waiting for response on event which application does not handle.

Parameters:

evt (BleEventBase) – event to handle

pair(conn_idx: int, bond: bool) → BLE_ERROR[source]

Start pairing

This call starts a pairing or bonding procedure. Depending on whether the device is master or slave on the connection, it will send a pairing or a security request respectively.

Parameters:

  • conn_idx (int) – connection index

  • bond (bool) – whether it starts pairing or bonding procedure

Returns:

Return type:

BLE_ERROR

read(conn_idx: int, handle: int, offset: int) → BLE_ERROR[source]

Read attribute from remote GATT server

This uses either the “Read Characteristic Value” procedure or the “Read Characteristic Descriptor” procedure, depending on the attribute handle. If offset is non-zero or the attribute length is larger than the MTU, the “Read Long Characteristic Value” procedure or the “Read Long Characteristic Descriptor” procedure will be used respectively. The complete attribute value will be returned in the BleEventGattcReadCompleted event.

Parameters:

  • conn_idx (int) – connection index

  • handle (int) – attribute handle

  • offset (int) – value offset to start with

Returns:

result code

Return type:

BLE_ERROR

scan_params_get() → Tuple[GapScanParams, BLE_ERROR][source]

Get the scan parameters used for connections

This call retrieves the scan parameters used when a connection is initiated.

Returns:

scan parameters, result code

Return type:

Tuple[GapScanParams, BLE_ERROR]

scan_params_set(scan_params: GapScanParams) → BLE_ERROR[source]

Set the scan parameters used for connections

This call sets the scan parameters used for initiated connections. This call won’t change the scan parameters of a connection attempt which is in progress (the scan parameters will be set for the next connection attempt).

Note

This call should be used prior to ble_gap_connect(). If a connection attempt is in progress, one should cancel it using the ble_gap_connect_cancel() call, set the desired scan parameters, and call ble_gap_connect() again.

Parameters:

scan_params (GapScanParams) – scan parameters

Returns:

result code

Return type:

BLE_ERROR

scan_start(type: GAP_SCAN_TYPE, mode: GAP_SCAN_MODE, interval_ms: int, window_ms: int, filt_wlist: bool, filt_dupl: bool) → BLE_ERROR[source]

Start scanning for devices

This call initiates a scan procedure. The scan duration depends on the scan mode selected. In General-discoverable and Limited-discoverable modes, the scan will stop after 10s of activity. In Observer mode, the scan operation will continue until it is stopped using scan_stop(). Allowed values for interval_ms span in the range of 2.5ms to 10.24s.

Parameters:

  • type (GAP_SCAN_TYPE) – active or passive scanning

  • mode (GAP_SCAN_MODE) – scan for General-discoverable, Limited-discoverable or for all devices

  • interval_ms (int) – scan interval in milliseconds

  • window_ms (int) – scan window in milliseconds

  • filt_wlist (bool) – enable or disable white list filtering, defaults to False

  • filt_dupl (bool) – enable or disable filtering of duplicates

Returns:

result code

Return type:

BLE_ERROR

scan_stop() → BLE_ERROR[source]

Stop scanning for devices

This call stops a scan procedure previously started using scan_start()

Returns:

result code

Return type:

BLE_ERROR

start() → BLE_ERROR[source]

Start the BLE module as a central device

Returns:

result code

Return type:

BLE_ERROR

write(conn_idx: int, handle: int, offset: int, value: bytes) → BLE_ERROR[source]

Write attribute to remote GATT server

This uses either the “Write Characteristic Value” procedure or the “Write Characteristic Descriptor” procedure, depending on the attribute handle. If offset is non-zero or the attribute length is larger than the MTU, the “Write Long Characteristic Value” procedure or the “Write Long Characteristic Descriptor” procedure will be used respectively.

The application will receive a BleEventGattcWriteCompleted event when the write operation is completed.

Parameters:

  • conn_idx (int) – connection index

  • handle (int) – attribute handle

  • offset (int) – value offset to start with

  • value (bytes) – value data

Returns:

result code

Return type:

BLE_ERROR

write_execute(conn_idx: int, commit: bool) → BLE_ERROR[source]

Execute reliable/long write to remote GATT server

In order to cancel prepared requests, commit shall be set to False.

The application will receive a BleEventGattcWriteCompleted event when write queue is executed. The handle parameter of this event will be set to 0.

Parameters:

  • conn_idx (int) – connection index

  • commit (bool) – true if data shall be written, false otherwise

Returns:

result code

Return type:

BLE_ERROR

write_no_resp(conn_idx: int, handle: int, signed_write: bool, value: bytes) → BLE_ERROR[source]

Write attribute to remote GATT server (without response)

If signed_write is set to False, the “Write Without Response” procedure will be used. If signed_write is set to True, the “Signed Write Without Response” procedure will be used on a link which is not encrypted or will fall back to the “Write Without Response” procedure on a link that is already encrypted.

The application will receive a BleEventGattcWriteCompleted event when the write operation is performed.

Parameters:

  • conn_idx (int) – connection index

  • handle (int) – attribute handle

  • signed_write (bool) – true if signed write should be used if possible/applicable

  • value (bytes) – value data

Returns:

result code

Return type:

BLE_ERROR

write_prepare(conn_idx: int, handle: int, offset: int, value: bytes) → BLE_ERROR[source]

Prepare long/reliable write to remote GATT server

The application will receive a BleEventGattcWriteCompleted event when the write operation is queued.

Parameters:

  • conn_idx (int) – connection index

  • handle (int) – attribute handle

  • offset (int) – value offset

  • value (bytes) – value data

Returns:

result code

Return type:

BLE_ERROR

py_ble_manager.ble_devices.BleDeviceBase module

class BleDeviceBase(com_port: str, baud_rate: int = 1000000, config: ~py_ble_manager.ble_api.BleConfig.BleConfigDefault = <py_ble_manager.ble_api.BleConfig.BleConfigDefault object>)[source]

Bases: object

Base BLE device class. Implements functionality common to BLE central and BLE peripheral devices

Parameters:

  • com_port (str) – COM port of the development kit

  • baud_rate (int) – Baud rate for serial port of the development kit

  • ble_config (BleConfigDefault, optional) – BLE configuration to use, defaults to BleConfigDefault(BLE_DEVICE_TYPE.CENTRAL)

address_get() → Tuple[OwnAddress, BLE_ERROR][source]

Retrieve the currently set BD address

This API call is used to retrieve the currently set BD address of the device.

Note

Value 00:00:00:00:00:00 will be returned when the own address of the device is not yet valid. This may happen when the application has set a private random address using ble_gap_address_set() and before such an address has been generated by the BLE stack (which will typically happen when the next air operation is started). The application will receive a BleEventGapAirOpBdAddr event when the private random address has been generated. Subsequent calls to address_get() will return a valid own address.

Returns:

BD address, result code

Return type:

Tuple[OwnAddress, BLE_ERROR]

address_set(address: OwnAddress, renew_dur: int) → BLE_ERROR[source]

Set the address of the device

This API call is used to set the BD address of the device. If the address type is not PRIVATE_STATIC_ADDRESS the address passed is ignored (public static is set using defaultBLE_STATIC_ADDRESS and private random addresses are automatically generated by the BLE stack every renew_dur seconds).

Note

When the address of a peripheral device is set to be non-resolvable, then the advertising type has to be non-connectable.

Note

This API function has to be called prior to creating the attribute database of the device. This is because the device configuration is going to be modified, which will result in clearing the current attribute database (if it exists).

Parameters:

  • address (OwnAddress) – address to be set

  • renew_dur (int) – random address renew duration in seconds (valid range is 1 to 3600 seconds)

Returns:

result code

Return type:

BLE_ERROR

appearance_get() → Tuple[GAP_APPEARANCE, BLE_ERROR][source]

Get the appearance used for GAP service

Returns:

appearance, result code

Return type:

Tuple[GAP_APPEARANCE, BLE_ERROR]

appearance_set(appearance: GAP_APPEARANCE, perm: ATT_PERM) → BLE_ERROR[source]

Set the appearance used for GAP service

Note

This API function has to be called prior to creating the attribute database of the device. This is because the device configuration is going to be modified, which will result in clearing the current attribute database (if it exists).

Parameters:
Returns:

result code

Return type:

BLE_ERROR

conn_param_update(conn_idx: int, conn_params: GapConnParams) → BLE_ERROR[source]

Initiate a connection parameter update

This call can be used by both the master and the slave of the connection to initiate a connection parameter update. For the master of the connection, the new connection parameters will be applied immediately. For the slave of the connection, a connection parameter update request will be send to the master. If the master accepts the connection parameters, it will be in charge of applying them (which will result in a BleEventGapConnParamUpdated event message to the slave that initiated the connection parameter update process). If 40s elapse without a response from the master, the connection will be terminated.

Parameters:

  • conn_idx (int) – connection index

  • conn_params (GapConnParams) – connection parameters

Returns:

result code

Return type:

BLE_ERROR

conn_param_update_reply(conn_idx: int, accept: bool) → BLE_ERROR[source]

Reply to a connection parameter update request

This call should be used to reply to a connection parameter update request event (BleEventGapConnParamUpdateReq) message.

Parameters:

  • conn_idx (int) – connection index

  • accept (bool) – accept flag (True to accept, False to reject)

Returns:

result code

Return type:

BLE_ERROR

data_length_set(conn_idx: int, tx_length: int, tx_time: int) → BLE_ERROR[source]

Set the data length used for TX

This function will set the maximum transmit data channel PDU payload length and time depending on the conn_idx provided. If conn_idx is set to BLE_CONN_IDX_INVALID then this API sets the preferred TX data length and time for subsequent connections. If conn_idx corresponds to an existing connection, it will set the TX data length and time for the specific connection (and possibly will initiate a Data Length Update procedure as defined in Bluetooth Core v_4.2).

Note

The application will receive one of the following events as response to this API: BleEventGapDataLengthChanged if data length has been changed BleEventGapDataLengthSetFailed with error code if data length could not be set

Note

If data length is not changed (i.e. if it is set by application to a value larger than the peer’s previously reported RX length) no event will be sent to application. Even though data_length_set() be successfully completed, the data length has not changed.

Parameters:

  • conn_idx (int) – connection index (if set to :py:data`~py_ble_manager.ble_api.BleGap.BLE_CONN_IDX_INVALID` then the API will set the preferred data length for new connections)

  • tx_length (int) – length for TX data channel PDU payload in octets

  • tx_time (int) – time for TX data channel PDU payload (if set to 0 it will be calculated based on the tx_length (with regard to Bluetooth Core v_4.2)

Returns:

result code

Return type:

BLE_ERROR

device_name_get() → Tuple[bytes, BLE_ERROR][source]

Get the device name used for GAP service

Returns:

device name, result code

Return type:

Tuple[bytes, BLE_ERROR]

device_name_set(name: str, perm: ATT_PERM = ATT_PERM.ATT_PERM_NONE) → BLE_ERROR[source]

Set the device name used for GAP service

Note

This API function has to be called prior to creating the attribute database of the device. This is because the device configuration is going to be modified, which will result in clearing the current attribute database (if it exists).

Parameters:

  • name (str) – device name

  • perm (ATT_PERM, optional) – device name attribute write permission, defaults to ATT_PERM.ATT_PERM_NONE

Returns:

result code

Return type:

BLE_ERROR

disconnect(conn_idx: int, reason: BLE_HCI_ERROR = BLE_HCI_ERROR.BLE_HCI_ERROR_REMOTE_USER_TERM_CON) → BLE_ERROR[source]

Terminate a connection

This call initiates a disconnection procedure on an established link.

Note

Valid reasons for initiating a disconnection are:

BLE_HCI_ERROR_AUTH_FAILURE BLE_HCI_ERROR_REMOTE_USER_TERM_CON BLE_HCI_ERROR_REMOTE_DEV_TERM_LOW_RESOURCES BLE_HCI_ERROR_REMOTE_DEV_POWER_OFF BLE_HCI_ERROR_UNSUPPORTED_REMOTE_FEATURE BLE_HCI_ERROR_PAIRING_WITH_UNIT_KEY_NOT_SUP BLE_HCI_ERROR_UNACCEPTABLE_CONN_INT

If API is called with a different reason, disconnection will fail with return status BLE_ERROR_INVALID_PARAM.

Note

After calling this function, the application will receive one of the following messages: BleEventGapDisconnected when the disconnection procedure was successful. BleEventGapDisconnectFailed with error status when the disconnection procedure failed.

Parameters:

  • conn_idx (int) – connection index

  • reason (BLE_HCI_ERROR, optional) – reason for disconnection, defaults to BLE_HCI_ERROR.BLE_HCI_ERROR_REMOTE_USER_TERM_CON

Returns:

result code

Return type:

BLE_ERROR

exchange_mtu(conn_idx: int) → BLE_ERROR[source]

Exchange MTU

This call will start an MTU exchange procedure with the MTU previously set using mtu_size_set(). If the MTU has been changed during the negotiation, a BleEventGattcMtuChanged event will be sent to the application

Parameters:

conn_idx (int) – connection index

Returns:

result code

Return type:

BLE_ERROR

get_bonded() → Tuple[list[py_ble_manager.ble_api.BleCommon.BdAddress], BLE_ERROR][source]

Get bonded devices list

Addresses for currently bonded devices are returned.

Returns:

list of BdAddress for bonded devices, result code

Return type:

Tuple[list[BdAddress], BLE_ERROR]

get_connected() → Tuple[list[int], BLE_ERROR][source]

Get connected devices list

Connection indexes for currently connected devices are returned

Returns:

list of connection idexes for connected devices, result code

Return type:

_type_

get_event(timeout: Optional[int] = None) → BleEventBase[source]

Get event from BLE event queue

Parameters:

timeout (int, optional) – time (in seconds) to wait for an event on the queue, defaults to None

Returns:

an event from the queue. None if queue empty when timeout is exceeded

Return type:

BleEventBase

get_io_cap() → Tuple[GAP_IO_CAPABILITIES, BLE_ERROR][source]

Get the I/O capabilities of the device

Get the currently set Input/Output Capabilities of the device (combined with the peer’s I/O capabilities, this will determine which pairing algorithm will be used).

Returns:

io capabilities, result code

Return type:

Tuple[GAP_IO_CAPABILITIES, BLE_ERROR]

get_peer_tx_mtu(conn_idx: int) → Tuple[int, BLE_ERROR][source]

Get current TX MTU for peer

Parameters:

conn_idx (int) – connection index

Returns:

peer tx mtu, result code

Return type:

Tuple[int, BLE_ERROR]

get_sec_level(conn_idx: int) → Tuple[GAP_SEC_LEVEL, BLE_ERROR][source]

Get connection security level

Get the currently established security level on a connection.

Parameters:

conn_idx (int) – connection index

Returns:

result code

Return type:

Tuple[GAP_SEC_LEVEL, BLE_ERROR]

init() → None[source]
mtu_size_get() → Tuple[int, BLE_ERROR][source]

Get MTU size

This call retrieves the Maximum Protocol Unit size that is used in exchange MTU transactions with peers.

Returns:

result code, mtu size

Return type:

Tuple[int, BLE_ERROR]

mtu_size_set(mtu_size: int) → BLE_ERROR[source]

Set MTU size

This call sets the Maximum Protocol Unit size that will be used in exchange MTU transactions with peers.

Note

This API function has to be called prior to creating the attribute database of the device. This is because the device configuration is going to be modified, which will result in clearing the current attribute database (if it exists).

Parameters:

mtu_size (int) – MTU size

Returns:

result code

Return type:

BLE_ERROR

numeric_reply(conn_idx: int, accept: bool) → BLE_ERROR[source]

Respond to a numeric comparison request

Respond to a BleEventGapNumericRequest event.

Parameters:

  • conn_idx (int) – connection index

  • accept (bool) – accept flag

Returns:

result code

Return type:

BLE_ERROR

passkey_reply(conn_idx: int, accept: bool, passkey: int) → BLE_ERROR[source]

Respond to a passkey request

Respond to a BLE_EVT_GAP_PASSKEY_REQUEST event.

Parameters:

  • conn_idx (int) – connection index

  • accept (bool) – accept flag

  • passkey (int) – passkey entered by user

Returns:

result code

Return type:

BLE_ERROR

peer_features_get(conn_idx: int) → BLE_ERROR[source]

Get peer’s features

This call initiates a Feature Exchange procedure or retrieves the already exchanged peer’s features on an established connection. Peer’s features will be delivered to the application via BleEventGapPeerFeatures event.

Note

For a mapping between bit values and features, see [Vol 6] Part B, Section 4.6 in Bluetooth Core_v5.0.pdf, or look under “BLE supported features” in co_bt.h.

Parameters:

conn_idx (int) – connection index

Returns:

result code

Return type:

BLE_ERROR

peer_version_get(conn_idx: int) → BLE_ERROR[source]

Get peer’s features

This call initiates a Feature Exchange procedure or retrieves the already exchanged peer’s features on an established connection. Peer’s features will be delivered to the application via BleEventGapPeerVersion event.

Note

For a mapping between bit values and features, see [Vol 6] Part B, Section 4.6 in Bluetooth Core_v5.0.pdf, or look under “BLE supported features” in co_bt.h.

Parameters:

conn_idx (int) – connection index

Returns:

result code

Return type:

BLE_ERROR

set_io_cap(io_cap: GAP_IO_CAPABILITIES) → BLE_ERROR[source]

Set the I/O capabilities of the device

Set the Input/Output Capabilities of the device (combined with the peer’s I/O capabilities, this will determine which pairing algorithm will be used).

Parameters:

io_cap (GAP_IO_CAPABILITIES) – new IO capabilities

Returns:

result code

Return type:

BLE_ERROR

set_sec_level(conn_idx: int, level: GAP_SEC_LEVEL) → BLE_ERROR[source]

Set connection security level

Use this function to set the security level for a connection. If the device is already bonded, it will use the existing LTK or request a new bonding. If the device is not bonded, it will create a pairing or a security request (depending on whether the device is master or slave on the connection) with the bond flag set to false.

Parameters:

  • conn_idx (int) – connection index

  • level (GAP_SEC_LEVEL) – new security level

Returns:

result code

Return type:

BLE_ERROR

start(role: GAP_ROLE) → BLE_ERROR[source]

Start the BLE module

Parameters:

role (GAP_ROLE) – GAP role of the device

Returns:

result code

Return type:

BLE_ERROR

storage_get_buffer(conn_idx: int, key: int) → Tuple[bytes, BLE_ERROR][source]

Get buffer value from storage

Parameters:

  • conn_idx (int) – connection index

  • key (int) – storage key (attribute handle)

Returns:

buffer, result code

Return type:

Tuple[bytes, BLE_ERROR]

storage_get_int(conn_idx: int, key: int) → Tuple[int, BLE_ERROR][source]

Get int value from storage

Parameters:

  • conn_idx (int) – connection index

  • key (int) – storage key (attribute handle)

Returns:

integer value, result code

Return type:

Tuple[int, BLE_ERROR]

storage_put_buffer(conn_idx: int, key: int, value: bytes, persistent: bool) → BLE_ERROR[source]

Store data buffer in storage

Note

While key can be an arbitrary value, it’s recommended to use values within service attribute handles range to avoid collision with other services or applications.

Parameters:

  • conn_idx (int) – connection index

  • key (int) – storage key (attribute handle)

  • value (bytes) – buffer to be stored

  • persistent (bool) – if true, value will be persistent for bonded devices

Returns:

result code

Return type:

BLE_ERROR

storage_put_int(conn_idx: int, key: int, value: int, persistent: bool) → BLE_ERROR[source]

Store signed integer value in storage

Note

While key can be an arbitrary value, it’s recommended to use values within service attribute handles range to avoid collision with other services or applications.

Parameters:

  • conn_idx (int) – connection index

  • key (int) – storage key (attribute handle)

  • value (int) – value to be stored

  • persistent (bool) – if true, value will be persistent for bonded devices

Returns:

result code

Return type:

BLE_ERROR

unpair(addr: BdAddress) → BLE_ERROR[source]

Unpair command

Use this function to unpair a device. This will also remove the device bond data from BLE storage.

Parameters:

addr (BdAddress) – remote device address

Returns:

result code

Return type:

BLE_ERROR

py_ble_manager.ble_devices.BlePeripheral module

class BlePeripheral(com_port: str, baud_rate: int = 1000000, ble_config: ~py_ble_manager.ble_api.BleConfig.BleConfigDefault = <py_ble_manager.ble_api.BleConfig.BleConfigDefault object>)[source]

Bases: BleDeviceBase

advertising_channel_map_get() → Tuple[int, BLE_ERROR][source]

Get the advertising channel map currently set

Note

Resposne will be constructed using the members of GAP_ADV_CHANNEL: GAP_ADV_CHANNEL_37, GAP_ADV_CHANNEL_38, GAP_ADV_CHANNEL_39.

Returns:

channel map currently used for advertising, result code

Return type:

Tuple[int, BLE_ERROR]

advertising_channel_map_set(chnl_map: int) → BLE_ERROR[source]

Set the advertising channel map

Note

This function has to be called prior to an advertising start and it will not modify the channel map of an ongoing advertising operation.

Parameters:

chnl_map (int) – channel map used for advertising

Returns:

result code

Return type:

BLE_ERROR

advertising_data_get() → Tuple[list[py_ble_manager.ble_api.BleGap.BleAdvData], list[py_ble_manager.ble_api.BleGap.BleAdvData], BLE_ERROR][source]

Get currently used Advertising Data and Scan Response Data

Get the Advertising Data and Scan Response Data currently used. This can be used while an advertising operation is in progress.

Returns:

list of AD Structures used for advertising, list AD Structures used for scan response, result code

Return type:

Tuple[list[BleAdvData], list[BleAdvData], BLE_ERROR]

advertising_data_set(adv_data_ad_list: list[py_ble_manager.ble_api.BleGap.BleAdvData] = [], scan_rsp_ad_list: list[py_ble_manager.ble_api.BleGap.BleAdvData] = []) → BLE_ERROR[source]

Set advertising Data and scan response data

This API call is used to modify the advertising data and scan response data used. It can be used while an advertising operation is in progress. If an advertising operation is not in progress, the new Advertising Data and/or new Scan Response Data will be used the next time function advertising_start(). is called. The maximum Advertising Data length for undirected connectable advertising is BLE_ADV_DATA_LEN_MAX bytes (31 minus 3 that are reserved to set the Advertising Data type flags - which shall not be set in Advertising Data using this function). The equivalent max length for non-connectable advertising is BLE_NON_CONN_ADV_DATA_LEN_MAX bytes.

Parameters:

  • adv_data_ad_list (list[BleAdvData], optional) – list of AD Structures used for advertising, defaults to []

  • scan_rsp_ad_list (list[BleAdvData], optional) – list of AD Structures used for scan response, defaults to []

Returns:

result code

Return type:

BLE_ERROR

advertising_interval_get() → Tuple[int, int, BLE_ERROR][source]

Get the currently set advertising interval

Get the minimum and maximum advertising intervals currently set.

Returns:

minimum interval (ms), maximum interval (ms), result code

Return type:

Tuple[int, int, BLE_ERROR]

advertising_interval_set(adv_intv_min_ms: int, adv_intv_max_ms: int) → None[source]

Set the advertising interval

Set the minimum and maximum interval to be used for advertising. Allowed values for intervals span from 20ms to 10.24s, while for non-connectable advertising the range is 100ms to 10.24s.

Note

This function has to be called prior to an advertising start and it will not modify the advertising interval of an ongoing advertising operation.

Parameters:

  • adv_intv_min_ms (int) – minimum interval (ms)

  • adv_intv_max_ms (int) – maximum interval (ms)

advertising_mode_get() → Tuple[GAP_DISC_MODE, BLE_ERROR][source]

Get the discoverability mode used for advertising

Returns:

discoverability mode, result code

Return type:

Tuple[GAP_DISC_MODE, BLE_ERROR]

advertising_mode_set(mode: GAP_DISC_MODE) → BLE_ERROR[source]

Set the discoverability mode used for advertising

Note

This function has to be called prior to an advertising start and it will not modify the discoverability mode of an ongoing advertising operation.

Parameters:

mode (GAP_DISC_MODE) – discoverability mode used for advertising

Returns:

result code

Return type:

BLE_ERROR

advertising_start(adv_type: GAP_CONN_MODE = GAP_CONN_MODE.GAP_CONN_MODE_UNDIRECTED) → BLE_ERROR[source]

Start advertising

This API call is used to start an advertising air operation. If adv_type is set to be GAP_CONN_MODE_NON_CONN or GAP_CONN_MODE_UNDIRECTED, the air operation will go on until it is stopped using advertising_stop(). If adv_type is set to be GAP_CONN_MODE_DIRECTED or GAP_CONN_MODE_DIRECTED_LDC (low duty cycle advertising), the air operation will automatically stop after 1.28s. In both cases, upon advertising completion, a BleEventGapAdvCompleted event will be sent to the application.

Parameters:

adv_type (GAP_CONN_MODE, optional) – type of advertising, defaults to GAP_CONN_MODE.GAP_CONN_MODE_UNDIRECTED

Returns:

result code

Return type:

BLE_ERROR

advertising_stop() → BLE_ERROR[source]

Stop advertising

This API call is used to stop a previously started advertising air operation. If advertising is successfully stopped, the application will receive a BleEventGapAdvCompleted with status set to BLE_ERROR_CANCELED

Returns:

result code

Return type:

BLE_ERROR

get_value(handle: int, max_len: int) → Tuple[bytes, BLE_ERROR][source]

Get attribute value

This retrieves an attribute’s value from the database. Up to max_len size bytes are returned buffer.

Parameters:

  • handle (int) – handle attribute handle

  • max_len (int) – attribute value length

Returns:

buffer to store attribute value, result code

Return type:

Tuple[bytes,BLE_ERROR]

handle_event_default(evt: BleEventBase)[source]

Execute default event handler

It’s recommended for application to call this for any event it does not handle. This avoids situation when BLE stack is waiting for response on event which application does not handle.

Parameters:

evt (BleEventBase) – event to handle

pair_reply(conn_idx: int, accept: bool, bond: bool) → BLE_ERROR[source]

Respond to a pairing request

The application should use this function to respond to a BleEventGapPairReq event.

Parameters:

  • conn_idx (int) – connection index

  • accept (bool) – accept flag

  • bond (bool) – bonding flag

Returns:

result code,

BLE_STATUS_OK if reply has been send successfully BLE_ERROR_FAILED if reply hasn’t been send successfully BLE_ERROR_INS_RESOURCES if there is BLE_GAP_MAX_BONDED number of bonded devices :rtype: BLE_ERROR

per_pref_conn_params_get() → Tuple[GapConnParams, BLE_ERROR][source]

Get the peripheral preferred connection parameters currently set for GAP service

Returns:

preferred connection params, result code

Return type:

Tuple[GapConnParams, BLE_ERROR]

per_pref_conn_params_set(conn_params: GapConnParams) → BLE_ERROR[source]

Set the peripheral preferred connection parameters used for GAP service

Note

This API function has to be called prior to creating the attribute database of the device. This is because the device configuration is going to be modified, which will result in clearing the current attribute database (if it exists).

Parameters:

conn_params (GapConnParams) – preferred connection parameters

Returns:

result code

Return type:

BLE_ERROR

prepare_write_cfm(conn_idx: int, handle: int, length: int, status: ATT_ERROR) → BLE_ERROR[source]

Respond to an attribute prepare write request

The application should use this function to respond to a BleEventGattsPrepareWriteReq event.

Parameters:

  • conn_idx (int) – connection index

  • handle (int) – attribute handle

  • length (int) – attribute value length

  • status (ATT_ERROR) – operation status

Returns:

result code

Return type:

BLE_ERROR

read_cfm(conn_idx: int, handle: int, status: ATT_ERROR, data: bytes) → BLE_ERROR[source]

Respond to an attribute read request

The application should use this function to respond to a BleEventGattsReadReq event.

Parameters:

  • conn_idx (int) – connection index

  • handle (int) – attribute handle

  • status (ATT_ERROR) – operation status

  • data (bytes) – attribute value

Returns:

result code

Return type:

BLE_ERROR

register_service(svc: BleServiceBase) → BLE_ERROR[source]

Register service in database

Adds all attributes previously added to the svc`` to the attribute database.

Parameters:

svc (BleServiceBase) – service to register

Returns:

result code

Return type:

BLE_ERROR

send_event(conn_idx: int, handle: int, type: GATT_EVENT, value: bytes) → BLE_ERROR[source]

Send a characteristic value notification or indication

Send an indication or a notification of an attribute’s value to a connected peer.

The application will receive a BleEventGattsEventSent event when the notification is successfully sent over the air.

Note

If a disconnection happens after calling this function or the notification cannot be successfully sent over the air due to e.g. a bad connection, the BleEventGattsEventSent event may not be received.

Parameters:

  • conn_idx (int) – connection index

  • handle (int) – characteristic value handle

  • type (GATT_EVENT) – indication or notification

  • value (bytes) – characteristic value

Returns:

result code

Return type:

BLE_ERROR

service_handle_event(evt: BleEventBase) → bool[source]

Handle BLE event

This function handles BLE events and passes them to services.

Parameters:

evt (BleEventBase) – BLE event

Returns:

True if event was handled, False otherwise

Return type:

bool

set_value(handle: int, value: bytes) → BLE_ERROR[source]

Set attribute value

This sets an attribute’s value in the internal database. Any read request from any peer will have this value returned. In order for an attribute to have different values for each peer, the application should store them locally and use BleEventGattsReadReq to handle read requests for a given attribute.

Parameters:

  • handle (int) – attribute handle

  • value (bytes) – attribute value

Returns:

result code

Return type:

BLE_ERROR

start() → BLE_ERROR[source]

Start the BLE module as a peripheral device

Returns:

result code

Return type:

BLE_ERROR

write_cfm(conn_idx: int, handle: int, status: ATT_ERROR) → BLE_ERROR[source]

Respond to an attribute write request

The application should use this function to respond to a BleEventGattsWriteReq event.

Note

The application shall also use this to confirm write requests for characteristics with the “Write Without Response” property set.

Parameters:

  • conn_idx (int) – connection index

  • handle (int) – attribute handle

  • status (ATT_ERROR) – operation status

Returns:

result code

Return type:

BLE_ERROR

Module contents