blatann.peer module¶

class blatann.peer.PeerState(value)¶

Bases: Enum

Connection state of the peer

DISCONNECTED = 0¶: Peer is disconnected

CONNECTING = 1¶: Peer is in the process of connecting

CONNECTED = 2¶: Peer is connected

class blatann.peer.Peer(ble_device, role, connection_params=ConnectionParams([15-30] ms, timeout: 4000 ms, latency: 0, security_params=SecurityParameters(passcode_pairing=False, io=<BLEGapIoCaps.KEYBOARD_DISPLAY: 4>, bond=False, oob=False, lesc=False), name='', write_no_resp_queue_size=1)¶

Bases: object

Object that represents a BLE-connected (or disconnected) peer

BLE_CONN_HANDLE_INVALID = 65535¶: Number of bytes that are header/overhead per MTU when sending a notification or indication

NOTIFICATION_INDICATION_OVERHEAD_BYTES = 3¶

property name: str¶

The name of the peer, if known. This property is for the user’s benefit to name certain connections. The name is also saved in the case that the peer is subsequently bonded to and can be looked up that way in the bond database

Note

For central peers this name is unknown unless set by the setter. For peripheral peers the name is defaulted to the one found in the advertising payload, if any.

Getter: Gets the name of the peer
Setter: Sets the name of the peer

property connected: bool¶

Read Only

Gets if this peer is currently connected

property rssi: Optional[int]¶

Read Only

Gets the RSSI from the latest connection interval, or None if RSSI reporting is not enabled.

Note

In order for RSSI information to be available, start_rssi_reporting() must be called first.

property bytes_per_notification: int¶

Read Only

The maximum number of bytes that can be sent in a single notification/indication

property is_peripheral: bool¶

Read Only

Gets if this peer is a peripheral (the local device acting as a central/client)

property is_client: bool¶

Read Only

Gets if this peer is a Client (the local device acting as a peripheral/server)

property is_previously_bonded: bool¶

Read Only

Gets if the peer has bonding information stored in the bond database (the peer was bonded to in a previous connection)

property preferred_connection_params: ConnectionParameters¶

Read Only

The connection parameters that were negotiated for this peer

property active_connection_params: ActiveConnectionParameters¶

Read Only

The active connection parameters in use with the peer. If the peer is disconnected, this will return the connection parameters last used

property mtu_size: int¶

Read Only

The current size of the MTU for the connection to the peer

property max_mtu_size: int¶

Read Only

The maximum allowed MTU size. This is set when initially configuring the BLE Device

property preferred_mtu_size: int¶

The user-set preferred MTU size. Defaults to the Bluetooth default MTU size (23). This is the value that will be negotiated during an MTU Exchange but is not guaranteed in the case that the peer has a smaller MTU

Getter: Gets the preferred MTU size that was configured
Setter: Sets the preferred MTU size to use for MTU exchanges

property preferred_phy: Phy¶

The PHY that is preferred for this connection. This value is used for Peer-initiated PHY update procedures and as the default for update_phy().

Default value is Phy.auto

Getter: Gets the preferred PHY
Setter: Sets the preferred PHY

property phy_channel: Phy¶

Read Only

The current PHY in use for the connection

property database: GattcDatabase¶

Read Only

The GATT database of the peer.

Note

This is not useful until services are discovered first

property on_connect: Event[Peer, None]¶: Event generated when the peer connects to the local device

property on_disconnect: Event[Peer, DisconnectionEventArgs]¶: Event generated when the peer disconnects from the local device

property on_rssi_changed: Event[Peer, int]¶: Event generated when the RSSI has changed for the connection

property on_mtu_exchange_complete: Event[Peer, MtuSizeUpdatedEventArgs]¶: Event generated when an MTU exchange completes with the peer

property on_mtu_size_updated: Event[Peer, MtuSizeUpdatedEventArgs]¶: Event generated when the effective MTU size has been updated on the connection

property on_connection_parameters_updated: Event[Peer, ConnectionParametersUpdatedEventArgs]¶: Event generated when the connection parameters with this peer is updated

property on_data_length_updated: Event[Peer, DataLengthUpdatedEventArgs]¶: Event generated when the link layer data length has been updated

property on_phy_updated: Event[Peer, PhyUpdatedEventArgs]¶: Event generated when the PHY in use for this peer has been updated

property on_database_discovery_complete: Event[Peripheral, DatabaseDiscoveryCompleteEventArgs]¶: Event that is triggered when database discovery has completed

disconnect(status_code=BLEHci.remote_user_terminated_connection)¶

Disconnects from the peer, giving the optional status code. Returns a waitable that will trigger when the disconnection is complete. If the peer is already disconnected, the waitable will trigger immediately

Parameters: status_code – The HCI Status code to send back to the peer
Return type: DisconnectionWaitable
Returns: A waitable that will trigger when the peer is disconnected

set_connection_parameters(min_connection_interval_ms, max_connection_interval_ms, connection_timeout_ms, slave_latency=0)¶

Sets the connection parameters for the peer and starts the connection parameter update process (if connected)

Note

Connection interval values should be a multiple of 1.25ms since that is the granularity allowed in the Bluetooth specification. Any non-multiples will be rounded down to the nearest 1.25ms. Additionally, the connection timeout has a granularity of 10 milliseconds and will also be rounded as such.

Parameters

min_connection_interval_ms (float) – The minimum acceptable connection interval, in milliseconds
max_connection_interval_ms (float) – The maximum acceptable connection interval, in milliseconds
connection_timeout_ms (int) – The connection timeout, in milliseconds
slave_latency – The slave latency allowed, which regulates how many connection intervals the peripheral is allowed to skip before responding

Return type

Optional[EventWaitable[Peer, ConnectionParametersUpdatedEventArgs]]

Returns

If the peer is connected, this will return a waitable that will trigger when the update completes with the new connection parameters. If disconnected, returns None

update_connection_parameters()¶

Starts the process to re-negotiate the connection parameters using the configured preferred connection parameters

Return type: EventWaitable[Peer, ConnectionParametersUpdatedEventArgs]
Returns: A waitable that will trigger when the connection parameters are updated

exchange_mtu(mtu_size=None)¶

Initiates the MTU Exchange sequence with the peer device.

If the MTU size is not provided preferred_mtu_size value will be used. If an MTU size is provided preferred_mtu_size will be updated to the given value.

Parameters: mtu_size – Optional MTU size to use. If provided, it will also updated the preferred MTU size
Return type: EventWaitable[Peer, MtuSizeUpdatedEventArgs]
Returns: A waitable that will trigger when the MTU exchange completes

update_data_length(data_length=None)¶

Starts the process which updates the link layer data length to the optimal value given the MTU. For best results call this method after the MTU is set to the desired size.

Parameters: data_length (Optional[int]) – Optional value to override the data length to. If not provided, uses the optimal value based on the current MTU
Return type: EventWaitable[Peripheral, DataLengthUpdatedEventArgs]
Returns: A waitable that will trigger when the process finishes

update_phy(phy=None)¶

Performs the PHY update procedure, negotiating a new PHY (1Mbps, 2Mbps, or coded PHY) to use for the connection. Performing this procedure does not guarantee that the PHY will change based on what the peer supports.

Parameters: phy (Optional[Phy]) – Optional PHY to use. If None, uses the preferred_phy attribute. If not None, the preferred PHY is updated to this value.
Return type: EventWaitable[Peer, PhyUpdatedEventArgs]
Returns: An event waitable that triggers when the phy process completes

discover_services()¶

Starts the database discovery process of the peer. This will discover all services, characteristics, and descriptors on the peer’s database.

Return type: EventWaitable[Peer, DatabaseDiscoveryCompleteEventArgs]
Returns: a Waitable that will trigger when service discovery is complete

start_rssi_reporting(threshold_dbm=None, skip_count=1)¶

Starts collecting RSSI readings for the connection

Parameters

threshold_dbm (Optional[int]) – Minimum change in dBm before triggering an RSSI changed event. The default value None disables the RSSI event (RSSI polled via the rssi property)
skip_count – Number of RSSI samples with a change of threshold_dbm or more before sending a new RSSI update event. Parameter ignored if threshold_dbm is None

Return type

EventWaitable[Peer, int]

Returns

a Waitable that triggers once the first RSSI value is received, if threshold_dbm is not None

stop_rssi_reporting()¶: Stops collecting RSSI readings. Once stopped, rssi will return None

class blatann.peer.Peripheral(ble_device, peer_address, connection_params=ConnectionParams([15-30] ms, timeout: 4000 ms, latency: 0, security_params=SecurityParameters(passcode_pairing=False, io=<BLEGapIoCaps.KEYBOARD_DISPLAY: 4>, bond=False, oob=False, lesc=False), name='', write_no_resp_queue_size=1)¶

Bases: Peer

Object which represents a BLE-connected device that is acting as a peripheral/server (local device is client/central)

set_conn_param_request_handler(handler)¶

Configures a function callback to handle when a connection parameter request is received from the peripheral and allows the user to decide how to handle the peripheral’s requested connection parameters.

The callback is passed in 2 positional parameters: this Peripheral object and the desired ``ConnectionParameter``s received in the request. The callback should return the desired connection parameters to use, or None to reject the request altogether.

Parameters: handler (Callable[[Peripheral, ConnectionParameters], Optional[ConnectionParameters]]) – The callback to determine which connection parameters to negotiate when an update request is received from the peripheral

accept_all_conn_param_requests()¶

Sets the connection parameter request handler to a callback that accepts any connection parameter update requests received from the peripheral. This is the same as calling set_conn_param_request_handler with a callback that simply returns the connection parameters passed in.

This is the default functionality.

reject_conn_param_requests()¶: Sets the connection parameter request handler to a callback that rejects all connection parameter update requests received from the peripheral. This is same as calling set_conn_param_request_handler with a callback that simply returns None

class blatann.peer.Client(ble_device, connection_params=ConnectionParams([15-30] ms, timeout: 4000 ms, latency: 0, security_params=SecurityParameters(passcode_pairing=False, io=<BLEGapIoCaps.KEYBOARD_DISPLAY: 4>, bond=False, oob=False, lesc=False), name='', write_no_resp_queue_size=1)¶

Bases: Peer

Object which represents a BLE-connected device that is acting as a client/central (local device is peripheral/server)