Platypush documentation

bluetooth.ble

bluetooth.ble

class platypush.plugins.bluetooth.ble.BluetoothBlePlugin(interface: str = 'hci0', **kwargs)[source]

Bases: SensorPlugin

Bluetooth BLE (low-energy) plugin

Requires:

  • pybluez (pip install pybluez)

  • gattlib (pip install gattlib)

Note that the support for bluetooth low-energy devices on Linux requires:

  • A bluetooth adapter compatible with the bluetooth 5.0 specification or higher;

  • To run platypush with root privileges (which is usually a very bad idea), or to set the raw net capabilities on the Python executable (which is also a bad idea, because any Python script will be able to access the kernel raw network API, but it’s probably better than running a network server that can execute system commands as root user). If you don’t want to set special permissions on the main Python executable and you want to run the bluetooth LTE plugin then the advised approach is to install platypush in a virtual environment and set the capabilities on the venv python executable, or run your platypush instance in Docker.

    You can set the capabilities on the Python executable through the following shell command:

    [sudo] setcap 'cap_net_raw,cap_net_admin+eip' /path/to/your/python
__init__(interface: str = 'hci0', **kwargs)[source]
Parameters:

interface – Default adapter device to be used (default: ‘hci0’)

connect(device: str, interface: str = None, wait: bool = True, channel_type: str = 'public', security_level: str = 'low', psm: int = 0, mtu: int = 0, timeout: float = 10.0)[source]

Connect to a bluetooth LE device

Parameters:

  • device – Device address to connect to

  • interface – Bluetooth adapter name to use (default configured if None)

  • wait – If True then wait for the connection to be established before returning (no timeout)

  • channel_type – Channel type, usually ‘public’ or ‘random’

  • security_level – Security level - possible values: [‘low’, ‘medium’, ‘high’]

  • psm – PSM value (default: 0)

  • mtu – MTU value (default: 0)

  • timeout – Connection timeout if wait is not set (default: 10 seconds)

disconnect(device: str)[source]

Disconnect from a connected device

Parameters:

device – Device address

discover_characteristics(device: str, interface: str = None, **kwargs) → BluetoothDiscoverCharacteristicsResponse[source]

Discover the characteristics of a LE bluetooth device

Parameters:

  • device – Device address to connect to

  • interface – Bluetooth adapter name to use (default configured if None)

  • kwargs – Extra arguments to be passed to connect()

discover_primary(device: str, interface: str = None, **kwargs) → BluetoothDiscoverPrimaryResponse[source]

Discover the primary services advertised by a LE bluetooth device

Parameters:

  • device – Device address to connect to

  • interface – Bluetooth adapter name to use (default configured if None)

  • kwargs – Extra arguments to be passed to connect()

get_measurement(interface: Optional[str] = None, duration: Optional[int] = 10, *args, **kwargs) → Dict[str, dict][source]

Wrapper for scan that returns bluetooth devices in a format usable by sensor backends.

Parameters:

  • interface – Bluetooth adapter name to use (default configured if None)

  • duration – Scan duration in seconds

Returns:

Device address -> info map.

read(device: str, interface: str = None, uuid: str = None, handle: int = None, binary: bool = False, disconnect_on_recv: bool = True, **kwargs) → str[source]

Read a message from a device

Parameters:

  • device – Device address to connect to

  • interface – Bluetooth adapter name to use (default configured if None)

  • uuid – Service UUID. Either the UUID or the device handle must be specified

  • handle – Device handle. Either the UUID or the device handle must be specified

  • binary – Set to true to return data as a base64-encoded binary string

  • disconnect_on_recv – If True (default) disconnect when the response is received

  • kwargs – Extra arguments to be passed to connect()

scan(interface: Optional[str] = None, duration: int = 10) → BluetoothScanResponse[source]

Scan for nearby bluetooth low-energy devices

Parameters:

  • interface – Bluetooth adapter name to use (default configured if None)

  • duration – Scan duration in seconds

write(device: str, data, handle: int = None, interface: str = None, binary: bool = False, disconnect_on_recv: bool = True, **kwargs) → str[source]

Writes data to a device

Parameters:

  • device – Device address to connect to

  • data – Data to be written (str or bytes)

  • interface – Bluetooth adapter name to use (default configured if None)

  • handle – Device handle. Either the UUID or the device handle must be specified

  • binary – Set to true if data is a base64-encoded binary string

  • disconnect_on_recv – If True (default) disconnect when the response is received

  • kwargs – Extra arguments to be passed to connect()

previous

bluetooth

next

calendar