This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Help us improve Python packaging - Donate today!
Project Description

pygatt - Python Module for Bluetooth LE Generic Attribute Profile (GATT).

This Module allows reading and writing to GATT descriptors on devices such as fitness trackers, sensors, and anything implementing standard GATT Descriptor behavior.

pygatt provides a Pythonic API by wrapping two different backends:

  • BlueZ (requires Linux), using the gatttool command-line utility.
  • Bluegiga’s BGAPI, compatible with USB adapters like the BLED112.

Motivation

Despite the popularity of BLE, we have yet to find a good programming interface for it on desktop computers. Since most peripherals are designed to work with smartphones, this space is neglected. One interactive interface, BlueZ’s gatttool, is functional but difficult to use programatically. BlueZ itself obviously works, but the interface leaves something to be desired and only works in Linux.

Requirements

  • Python 2.7
  • BlueZ 5.18 or greater (with gatttool) - required for the gatttool backend only.
    • Tested on 5.18, 5.21, 5.35 and 5.43
  • GATTToolBackend requires Linux (i.e. not Windows compatible)

Installation

Install pygatt with pip from PyPI:

$ pip install pygatt

The BlueZ backend is not supported by default as it requires pexpect, which can only be installed in a UNIX-based environment. If you wish to use that backend, install the optional dependencies with:

$ pip install "pygatt[GATTTOOL]"

Install the latest development version of pygatt with pip:

$ pip install git+https://github.com/peplin/pygatt

Example Use

The primary API for users of this library is provided by pygatt.BLEBackend and pygatt.BLEDevice. After initializing an instance of the preferred backend (available implementations are found in pygatt.backends, use the BLEBackend.connect method to connect to a device and get an instance of BLEDevice.

import pygatt

# The BGAPI backend will attemt to auto-discover the serial device name of the
# attached BGAPI-compatible USB adapter.
adapter = pygatt.BGAPIBackend()

try:
    adapter.start()
    device = adapter.connect('01:23:45:67:89:ab')
    value = device.char_read("a1e8f5b1-696b-4e4c-87c6-69dfe0b0093b")
finally:
    adapter.stop()

Note that not all backends support connecting to more than 1 device at at time, so calling BLEBackend.connect again may terminate existing connections.

Here’s the same example using the GATTTool backend. It’s identical except for the initialization of the backend:

import pygatt

adapter = pygatt.GATTToolBackend()

try:
    adapter.start()
    device = adapter.connect('01:23:45:67:89:ab')
    value = device.char_read("a1e8f5b1-696b-4e4c-87c6-69dfe0b0093b")
finally:
    adapter.stop()

Debugging

While debugging software using pygatt, it is often useful to see what’s happening inside the library. You can enable debugging logging and have it printed to your terminal with this code:

import pygatt
import logging

logging.basicConfig()
logging.getLogger('pygatt').setLevel(logging.DEBUG)

Can’t find BGAPI device in Windows

You may need to explicitly specify the COM port of your BGAPI-compatible device in windows, e.g.:

adapter = pygatt.BGAPIBackend(serial_port='COM9')

If you provide the COM port name, but still get an error such as WindowsError(2, 'The system cannot find the file specified.'), try changing the COM port of the device to a value under 10, e.g. COM9.

Authors

Releasing to PyPI

For the maintainers of the project, when you want to make a release:

  • Merge all of the changes into master.
  • Update the version in setup.py.
  • Update the CHANGELOG.mkd
  • Tag the commit and push to GitHub (will need to push to a separate branch of PR first since master is a protected branch).
  • Travis CI will take care of the rest - it will build and deploy tagged commits to PyPI automatically.

License

Copyright 2015 Stratos Inc. and Orion Labs

Apache License, Version 2.0 and MIT License. See LICENSE.

Release History

V3.1.1

  • Improvement: Convert documentation to RST for better PyPI integration.

V3.1.0

  • Fix: Support platforms without termios (Windows)
  • Feature: Add char_read_handle to GATTTool backend.
  • Improvement: Warn if hcitool requires a sudo authentication.
  • Improvement: Allow BGAPI device more time to reboot for more reliable discovery.
  • Improvement: Interpret “invalid file descriptor” as a disconnect event.
  • Fix: Correctly handle service class UUIDs that aren’t 16 bytes.
  • Improvement: Support BLE devices with any UTF8 character.
  • Improvement: Make gatttol prompt timeout configurable.
  • Improvement: Gracefully stop lescan to avoid leaving the adapter in a bad state.
  • Improvement: Allow custom timeout for discovery on GATTTool backend.
  • Fix: Make sure responses to char reads on BGAPI backend are from the requested handle.
  • Improvement: Raise and exception if trying to instantiate the GATTTool backend in Windows.
  • Improvement: If no BGAPI device attached, abort immediately.
  • Fix: Use user’s configured HCI device for connection and scanning in GATTTool backend.

V3.0.0

  • [API Change] The BGAPIBackend.connect method now takes the same address_type argument as the GATTTool backend [BGAPI].
  • [API Change] The address_type argument on both backends now requires a value from a new enum, pygatt.BLEAddressType, instead of a string.
  • Made Python 3 support a priority for both GATTTOOL and BGAPI backends.
  • Improve reliability of BGAPI backend by re-setting device for each connection.

V2.1.0

  • Added all standard GATT characteristics. [BGAPI]
  • Move gatttool monitor to a background thread for increased performance. [GATTTOOL]

V2.0.1

  • Feature: Allow unsubscribing from notifications.
  • Improvement: Allow more time to discover characteristics. [GATTTOOL]
  • Improvement: Allow using gatttol backend without root. [GATTTOOL]
  • Improvement: Standardize type of UUID so comparison always works (str vs unicode)
  • Fix: Fix packaging so the version on PyPI can be installed.
  • Fix: Fix Python 3 compatibility.

Thanks to Ilya Sukhanov and Alexey Roslyakov for the changes in this release!

v2.0.0

  • New API with support for multiple BLE adapters.
Release History

Release History

3.1.1

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

3.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

3.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.3.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.2.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pygatt-3.1.1.tar.gz (36.5 kB) Copy SHA256 Checksum SHA256 Source Apr 1, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting