bluetooth

bluetooth#

Description#

Plugin to interact with Bluetooth devices.

This plugin uses Bleak to interact with the Bluetooth stack and Theengs to map the services exposed by the devices into native entities.

The full list of devices natively supported can be found here.

It also supports legacy Bluetooth services, as well as the transfer of files.

Note that the support for Bluetooth low-energy devices requires a Bluetooth adapter compatible with the Bluetooth 5.0 specification or higher.

Configuration#

bluetooth:
  # [Optional]
  # Name of the Bluetooth interface to use (e.g. ``hci0``
  # on Linux). Default: first available interface.
  # interface:   # type=Optional[str]

  # [Optional]
  # Timeout in seconds for the connection to a
  # Bluetooth device. Default: 20 seconds.
  # connect_timeout: 20  # type=float

  # [Optional]
  # List of service UUIDs to discover.
  # Default: all.
  # service_uuids:   # type=Optional[Collection[Union[uuid.UUID, int]]]

  # [Optional]
  # If ``True``, the plugin will not the
  # scanning thread until `BluetoothPlugin.scan_resume <https://docs.platypush.tech/platypush/plugins/bluetooth.html#platypush.plugins.bluetooth.BluetoothPlugin.scan_resume>`_ is called (default:
  # ``False``).
  # scan_paused_on_start: False  # type=bool

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 10.0  # type=float

  # [Optional]
  # Exclude BLE beacons from devices
  # known for being very noisy. It mainly includes tracking services on
  # Google, Apple, Microsoft and Samsung devices. These devices are
  # also known for refreshing their MAC address very frequently, which
  # may result in a large (and constantly increasing) list of devices.
  # Disable this flag if you need to track BLE beacons from these
  # devices, but beware that you may need periodically clean up your
  # list of scanned devices.
  # exclude_known_noisy_beacons: True  # type=bool

  # [Optional]
  # List of device addresses to ignore.
  # ignored_device_addresses:   # type=Optional[Collection[str]]

  # [Optional]
  # List of device names to ignore.
  # ignored_device_names:   # type=Optional[Collection[str]]

  # [Optional]
  # List of device manufacturers to
  # ignore.
  # ignored_device_manufacturers:   # type=Optional[Collection[str]]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install git+https://github.com/pybluez/pybluez bluetooth-numbers git+https://github.com/BlackLight/PyOBEX bleak pydbus TheengsDecoder

Alpine

apk add py3-pydbus git

Debian

apt install libbluetooth-dev git python3-pydbus

Fedora

yum install python-pydbus git

Arch Linux

pacman -S python-pydbus git python-bleak

Triggered events#

Actions#

Module reference#

class platypush.plugins.bluetooth.BluetoothPlugin(*_, **__)[source]#

Bases: RunnablePlugin, EnumSwitchEntityManager

Plugin to interact with Bluetooth devices.

This plugin uses Bleak to interact with the Bluetooth stack and Theengs to map the services exposed by the devices into native entities.

The full list of devices natively supported can be found here.

It also supports legacy Bluetooth services, as well as the transfer of files.

Note that the support for Bluetooth low-energy devices requires a Bluetooth adapter compatible with the Bluetooth 5.0 specification or higher.

__init__(interface: str | None = None, connect_timeout: float = 20, service_uuids: Collection[UUID | int] | None = None, scan_paused_on_start: bool = False, poll_interval: float = 10.0, exclude_known_noisy_beacons: bool = True, ignored_device_addresses: Collection[str] | None = None, ignored_device_names: Collection[str] | None = None, ignored_device_manufacturers: Collection[str] | None = None, **kwargs)[source]#
Parameters:

  • interface – Name of the Bluetooth interface to use (e.g. hci0 on Linux). Default: first available interface.

  • connect_timeout – Timeout in seconds for the connection to a Bluetooth device. Default: 20 seconds.

  • service_uuids – List of service UUIDs to discover. Default: all.

  • scan_paused_on_start – If True, the plugin will not the scanning thread until scan_resume() is called (default: False).

  • exclude_known_noisy_beacons – Exclude BLE beacons from devices known for being very noisy. It mainly includes tracking services on Google, Apple, Microsoft and Samsung devices. These devices are also known for refreshing their MAC address very frequently, which may result in a large (and constantly increasing) list of devices. Disable this flag if you need to track BLE beacons from these devices, but beware that you may need periodically clean up your list of scanned devices.

  • ignored_device_addresses – List of device addresses to ignore.

  • ignored_device_names – List of device names to ignore.

  • ignored_device_manufacturers – List of device manufacturers to ignore.

connect(device: str, port: int | None = None, service_uuid: str | UUID | int | None = None, interface: str | None = None, timeout: float | None = None)[source]#

Pair and connect to a device by address or name.

Parameters:

  • device – The device address or name.

  • port – The port to connect to. Either port or service_uuid is required for non-BLE devices.

  • service_uuid – The UUID of the service to connect to. Either port or service_uuid is required for non-BLE devices.

  • interface – The Bluetooth interface to use (it overrides the default interface).

  • timeout – The connection timeout in seconds (it overrides the default connect_timeout).

disconnect(device: str, port: int | None = None, service_uuid: UUID | int | None = None)[source]#

Close an active connection to a device.

Note that this method can only close connections that have been initiated by the application. It can’t close connections owned by other applications or agents.

Parameters:

  • device – The device address or name.

  • port – If connected to a non-BLE device, the optional port to disconnect.

  • service_uuid – The optional UUID of the service to disconnect from, for non-BLE devices.

main()[source]#

Implementation of the main loop of the plugin.

publish_entities(entities: Collection[Any] | None, callback: Callable[[Entity], Any] | None = None, **kwargs) → Collection[Entity]#

Publishes a list of entities. The downstream consumers include:

It also accepts an optional callback that will be called when each of the entities in the set is flushed to the database.

You usually don’t need to override this class (but you may want to extend transform_entities() instead if your extension doesn’t natively handle Entity objects).

read(device: str, service_uuid: UUID | int, interface: str | None = None, connect_timeout: float | None = None) → str[source]#

Read a message from a device.

Parameters:

  • device – Name or address of the device to read from.

  • service_uuid – Service UUID.

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

  • connect_timeout – Connection timeout in seconds (default: same as the configured connect_timeout).

Returns:

The base64-encoded response received from the device.

scan(duration: float | None = None, devices: Collection[str] | None = None, service_uuids: Collection[UUID | int] | None = None) → List[BluetoothDevice][source]#

Scan for Bluetooth devices nearby and return the results as a list of entities.

Parameters:

  • duration – Scan duration in seconds (default: same as the plugin’s poll_interval configuration parameter)

  • devices – List of device addresses or names to scan for.

  • service_uuids – List of service UUIDs to discover. Default: all.

scan_pause(duration: float | None = None)[source]#

Pause the scanning thread.

Parameters:

duration – For how long the scanning thread should be paused (default: null = indefinitely).

scan_resume(duration: float | None = None)[source]#

Resume the scanning thread, if inactive.

Parameters:

duration – For how long the scanning thread should be running (default: null = indefinitely).

send_file(file: str, device: str, data: str | bytes | bytearray | None = None, binary: bool = False)[source]#

Send a file to a device that exposes an OBEX Object Push service.

Parameters:

  • file – Path of the file to be sent. If data is specified then file should include the proposed file on the receiving host.

  • data – Alternatively to a file on disk you can send raw (string or binary) content.

  • device – Device address or name.

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

set(entity: str, value: Any, **_)[source]#

Set the value of an entity.

This is currently only supported for SwitchBot devices, where the value can be one among on, off and press.

Parameters:

  • entity – The entity to set the value for. It can be the full entity ID in the format <mac-address>::<service>, or just the MAC address if the plugin supports it.

  • value – The value to set the entity to.

start()#

Start the plugin.

status(*_, duration: float | None = None, devices: Collection[str] | None = None, service_uuids: Collection[UUID | int] | None = None, **__) → List[BluetoothDevice][source]#

Retrieve the status of all the devices, or the matching devices/services.

If scanning is currently disabled, it will enable it and perform a scan.

The differences between this method and scan() are:

  1. status() will return the status of all the devices known to the application, while scan() will return the status only of the devices discovered in the provided time window.

  2. status() will not initiate a new scan if scanning is already enabled (it will only return the status of the known devices), while scan() will initiate a new scan.

Parameters:

  • duration – Scan duration in seconds, if scanning is disabled (default: same as the plugin’s poll_interval configuration parameter)

  • devices – List of device addresses or names to filter for. Default: all.

  • service_uuids – List of service UUIDs to filter for. Default: all.

stop()[source]#

Upon stop request, it stops any pending scans and closes all active connections.

transform_entities(entities: Collection[BluetoothDevice]) → Collection[BluetoothDevice][source]#

This method takes a list of entities in any (plugin-specific) format and converts them into a standardized collection of Entity objects. Since this method is called by publish_entities() before entity updates are published, you may usually want to extend it to pre-process the entities managed by your extension into the standard format before they are stored and published to all the consumers.

wait_stop(timeout=None)#

Wait until a stop event is received.

write(device: str, data: str, service_uuid: UUID | int, interface: str | None = None, connect_timeout: float | None = None)[source]#

Writes data to a device

Parameters:

  • device – Name or address of the device to read from.

  • data – Data to be written, as a base64-encoded string.

  • service_uuid – Service UUID.

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

  • connect_timeout – Connection timeout in seconds (default: same as the configured connect_timeout).