blatann.device module

class blatann.device.BleDevice(comport='COM1', baud=1000000, log_driver_comms=False, notification_hw_queue_size=16, write_command_hw_queue_size=16, bond_db_filename='user')

Bases: NrfDriverObserver

Represents the Bluetooth device itself. Provides the high-level bluetooth APIs (Advertising, Scanning, Connections), configuration, and bond database.

Parameters

  • comport – The port the nRF52 device lives on, e.g. "COM3", "/dev/ttyS0"

  • baud – The baud rate to use. By default, the connectivity firmware images for v0.3+ use 1M baud.

  • log_driver_comms – debug flag which will enable extra-verbose logging of all communications to the nRF52 hardware

  • notification_hw_queue_size – Hardware-based queue size to use for notifications. This queue lives within the nRF52 hardware itself and has memory usage implications based on MTU size, etc. This probably won’t need to be changed, and from current testing the queue isn’t fully exercised

  • write_command_hw_queue_size – Hardware-based queue size to use for write commands (write w/o response). Same comments about notification queue apply here.

  • bond_db_filename –

    Optional filename to use for loading/saving the bonding database. The supported file formats/extensions are: “.pkl” (legacy) and “.json”. json is preferred.

    Two special values also exist:

    • "user" [default] - saves the database within the user’s home directory (~/.blatann/bonding_db.json). This is useful for cases where you may not have write access to the python install location, want to persist the bonding database across virtualenvs, or limit the access to just the logged-in user

    • "system" - saves the database within this library’s directory structure, wherever it is installed or imported from. Useful if you want the bonding database to be constrained to just that python/virtualenv installation

configure(vendor_specific_uuid_count=10, service_changed=False, max_connected_peripherals=1, max_connected_clients=1, max_secured_peripherals=1, attribute_table_size=1408, att_mtu_max_size=247, event_length=6)

Configures the BLE Device with the given settings.

Note

Configuration must be set before opening the device

Parameters

  • vendor_specific_uuid_count – The Nordic hardware limits number of 128-bit Base UUIDs that the device can know about. This normally equals the number of custom services that are to be supported, since characteristic UUIDs are usually derived from the service base UUID.

  • service_changed – Whether the Service Changed characteristic is exposed in the GAP service

  • max_connected_peripherals – The maximum number of concurrent connections with peripheral devices

  • max_connected_clients – The maximum number of concurrent connections with client devices (NOTE: blatann currently only supports 1)

  • max_secured_peripherals – The maximum number of concurrent peripheral connections that will need security (bonding/pairing) enabled

  • attribute_table_size – The maximum size of the attribute table. Increase this number if there’s a lot of services/characteristics in your GATT database.

  • att_mtu_max_size – The maximum ATT MTU size supported. The default supports an MTU which will fit into a single transmission if Data Length Extensions is set to its max (251)

  • event_length – The number of 1.25ms event cycles to dedicate for each connection. The default value (6, =7.5ms) will support the max DLE length of 251 bytes. Minimum value is 2, typical values are 3-8 depending on desired throughput and number of concurrent connections

open(clear_bonding_data=False)

Opens the connection to the BLE device. Must be called prior to performing any BLE operations

Parameters

clear_bonding_data – Flag that the bonding data should be cleared prior to opening the device.

close()

Closes the connection to the BLE device. The connection to the device must be opened again to perform BLE operations.

clear_bonding_data()

Clears out all bonding data from the bond database. Any subsequent connections will require re-pairing.

property address: BLEGapAddr

The MAC Address of the BLE device

Getter

Gets the MAC address of the BLE device

Setter

Sets the MAC address for the device to use

Note

The MAC address cannot be changed while the device is advertising, scanning, or initiating a connection

property database: GattsDatabase

Read Only

The local database instance that is accessed by connected clients

property generic_access_service: GenericAccessService

Read Only

The Generic Access service in the local database

property max_mtu_size: int

Read Only

The maximum allowed ATT MTU size that was configured for the device

Note

The Max MTU size is set through configure()

set_tx_power(tx_power)

Sets the radio transmit power. This is used for all connections, advertising, active scanning, etc. Method can be called at any time

Valid transmit power values are -40, -20, -16, -12, -8, -4, 0, 3, and 4 dBm

Parameters

tx_power – The transmit power to use, in dBm

connect(peer_address, connection_params=None)

Initiates a connection to a peripheral peer with the specified connection parameters, or uses the default connection parameters if not specified. The connection will not be complete until the returned waitable either times out or reports the newly connected peer

Parameters
Return type

PeripheralConnectionWaitable

Returns

A Waitable which can be used to wait until the connection is successful or times out. Waitable returns a peer.Peripheral object

set_default_peripheral_connection_params(min_interval_ms, max_interval_ms, timeout_ms, slave_latency=0)

Sets the default connection parameters for all subsequent connection attempts to peripherals. Refer to the Bluetooth specifications for the valid ranges

Parameters

  • min_interval_ms (float) – The minimum desired connection interval, in milliseconds

  • max_interval_ms (float) – The maximum desired connection interval, in milliseconds

  • timeout_ms (int) – The connection timeout period, in milliseconds

  • slave_latency (int) – The connection slave latency

set_default_security_params(passcode_pairing, io_capabilities, bond, out_of_band, reject_pairing_requests=False, lesc_pairing=False)

Sets the default security parameters for all subsequent connections to peripherals.

Parameters

  • passcode_pairing (bool) – Flag indicating that passcode pairing is required

  • io_capabilities (BLEGapIoCaps) – The input/output capabilities of this device

  • bond (bool) – Flag indicating that long-term bonding should be performed

  • out_of_band (bool) – Flag indicating if out-of-band pairing is supported

  • reject_pairing_requests (Union[bool, PairingPolicy]) – Flag indicating that all security requests by the peer should be rejected

  • lesc_pairing (bool) – Flag indicating that LE Secure Pairing methods are supported

set_privacy_settings(enabled, resolvable_address=True, update_rate_seconds=900)

Sets the privacy parameters for advertising and connections to the device. When enabled, a random private address will be advertised and updated at the provided interval.

Parameters

  • enabled (bool) – True to enable device privacy. Note that only device privacy is supported, network privacy is not

  • resolvable_address (bool) – True to use a private random resolvable address. If the address is resolvable, bonded peers can use the device’s IRK to determine the device’s actual public/random address.

  • update_rate_seconds (int) – How often the address should be changed/updated, in seconds. Default is 900 (15min)