Skip to content
Bluew is a simple and easy to use bluetooth API for python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Build Status codecov version


Bluetooth made simple.

What's bluew?

Bluew started as just a wrapper for bluetoothctl, the client that comes with bluez 5. There are some nice python bluetooth libraries out there, but they either didn't offer the easiness of bluetoothctl or didn't nicely support having multiple connections.

Bluew tries to offer both multiple connections and an easy API, that's heavily influenced by the Requests library.

By now bluew has moved on from wrapping bluetoothctl, and has it's own engine/backend which talks directly to bluez using the D-Bus API.

How to install?'

pip3 install bluew

Globally with sudo:

sudo -H pip3 install bluew

Unfortunately since DBusted (bluew's current backend) is using python-dbus, you also need to install the following packages from your system package manager.


sudo apt-get install python-gi python3-dbus libdbus-1-dev libdbus-glib-1-dev

We're currently looking for more native alternatives.

If you've managed to install bluew, congratulations, you passed the biggest obstacle in using it. From now it should be a smooth ride.


Complete documentation is currenly under construction, but you can access the draft under

Simple use:

If you just wanna do something quickly like connecting to a device, disconnecting, trusting, reading an attribute from it, or writing to one, you can do that in the following way.

>>> import bluew
>>> mac = 'xx:xx:xx:xx:xx'
>>> bluew.pair(mac)
>>> bluew.distrust(mac)
>>> dev =
>>> dev.Trusted
>>> dev.Paired
Reading an attribute (service/characteristic):
>>> uuid = 'someuuid'
>>> bluew.read_attribute(mac, uuid)
[b'x0', b'x0']
Writing an attribute:
>>> bluew.write_attribute(mac, uuid, [0x3, 0x1, 0x1])
>>> bluew.read_attribute(mac, uuid)
[b'x03', b'x01', b'x01']
Scan and get devices around:
>>> bluew.get_devices()
Get bluetooth controllers available:
>>> bluew.get_controllers()
Remove device (distrust and unpair):
>>> bluew.remove(mac)

More advanced use:

If you have a more advanced usage in mind than just pairing with a device or reading an attribute quickly YOU SHOULD use bluew.Connection, for example:

>>> from bluew import Connection
>>> mac = "xx:xx:xx:xx:xx"
>>> with Connection(mac) as con:
>>>     con.pair()
>>>     con.write_attribute(attr1, data)
>>>     con.notify(attr2, handler)

bluew.Connection supports all the functions already shown above and used directly from bluew except for get_devices() and get_controllers and offers two more functions like:

  • notify
  • stop_notify

and two properties/attributes:

  • services
  • chrcs


You can pass to any function/class imported from bluew the following flags:

  • default: True
  • possible: False
  • usage: Keep connection alive after Connection object is closed, or after a command is executed.
  • default: 5 (seconds)
  • possible: N : float
  • usage: Time allowed to find the device, also used with get_devices() for duration of scanning. You can't pass this to Connection methods yet.
  • default: None
  • possible: 'hciN'; N being an integer
  • usage: Controller you'd like to use for the operations, if None is left there's currently no guarantee which controller would be picked.
You can’t perform that action at this time.