The Basic Bluew API

This document covers the basic one-time API calls you can make with bluew.

Main Interface

The following 11 functions are accessible directly from bluew.

bluew.connect(mac: str, *args, **kwargs) → None

Connect to a bluetooth device. :param mac: MAC address of bluetooth device.

bluew.disconnect(mac: str, *args, **kwargs) → None

Disconnect from a bluetooth device. :param mac: MAC address of bluetooth device.

bluew.trust(mac: str, *args, **kwargs) → None

Trust a bluetooth device. :param mac: MAC address of bluetooth device.

bluew.distrust(mac: str, *args, **kwargs) → None

Distrust a bluetooth device. :param mac: MAC address of bluetooth device.

bluew.pair(mac: str, *args, **kwargs) → None

Pair with a bluetooth device. :param mac: MAC address of bluetooth device.

bluew.remove(mac: str, *args, **kwargs) → None

Remove a bluetooth device. :param mac: MAC address of bluetooth device.

bluew.devices(*args, **kwargs) → List[bluew.device.Device]

Get list of devices around.

bluew.controllers(*args, **kwargs) → List[bluew.controller.Controller]

Get list of available controllers.

bluew.info(mac: str, *args, **kwargs) → bluew.device.Device

Get device info. :param mac: MAC address of bluetooth device.

bluew.read_attribute(mac: str, attribute: str, *args, **kwargs) → List[bytes]

Read a bluetooth attribute on bluetooth device. :param mac: MAC address of bluetooth device. :param attribute: Bluetooth attribute to read.

bluew.write_attribute(mac: str, attribute: str, data: List[int], *args, **kwargs) → None

Write a bluetooth attribute on bluetooth device. :param mac: MAC address of bluetooth device. :param attribute: Bluetooth attribute to write to. :param data: Data to write to attribute.

Exceptions

exception bluew.errors.BluewError(reason, long_reason='', name='', version='')

For those times when the Engine blows.

exception bluew.errors.DeviceNotAvailable(*args, **kwargs)

This error is raised by when the bluetooth devices specified is not found.

exception bluew.errors.PairError(*args, **kwargs)

This error is raised when a pairing error that can’t be handled is raised.

exception bluew.errors.ReadWriteNotifyError(*args, **kwargs)

This error is raised when a read/write fail that can’t be handled happens.

exception bluew.errors.InvalidArgumentsError(*args, **kwargs)

This error is rasied when arguemnts passed are.. well.. invalid.

exception bluew.errors.NoControllerAvailable(*args, **kwargs)

This error is raised when no bluetooth controllers are found.

exception bluew.errors.ControllerSpecifiedNotFound(*args, **kwargs)

This error is raised when the controller specified is not found by bluew.

exception bluew.errors.ControllerNotReady(*args, **kwargs)

This error is raised when the controller specified or picked by default is not ready.

Bluew Connection

class bluew.Connection(mac, *args, **kwargs)

A Bluew Connection

Provides a persistent connection with one device.

Basic Usage:

>>> import bluew
>>> mac = 'xx:xx:xx:xx:xx'
>>> device = bluew.Connection(mac)
>>> device.info()

chrcs

Get available BLE characteristics of a device.

close()

Close the conncection.

info()

Get device info.

notify(attribute, handler)

Turn on notifications on attribute, and call handler with data.

read_attribute(attribute)

Read a bluetooth attribute.

remove()

Disconnect and unpair device.

services

Get available BLE services of a device.

stop_notify(attribute)

Turn off notifications on attribute.

trust()

Trust a bluetooth device.

write_attribute(attribute, data)

Write to a bluetooth attribute.

Utility Functions

bluew.utils.devs_with_uuid(uuid: str) → List[bluew.device.Device]

Get a list of devices with a specific UUID. This function can be useful when you wanna connect to any device with a certain model, but don’t care which one it is.