Package: bluez-peripheral
bluez-peripheralDocumentationPyPiGitHubA bluez-peripheral is a library for building Bluetooth Low Energy (BLE) peripherals/ servers using the Bluez (Linux) GATT API.Who this Library is ForDevelopers using Python and Linux (and Bluez).Wishing to develop a bluetooth compatible peripheral (ie. something that other devices connect to).With low bandwidth requirements (ie. not streaming audio).InstallationInstall bluez (eg.sudo apt-get install bluez)pip install bluez-peripheralGATT OverviewGATT is a BLE protocol that allows you to offer services to other devices.
You can find a list of standardised services on theBluetooth SIG website(you can largely ignore profiles when working with BLE). You should refer to the "Service Characteristics" in these specifications for the purposes of this library.Courtesey of Qt documentation (GNU Free Documentation License)A peripheral defines a list of services that it provides. Services are a collection of characteristics which expose particular data (eg. a heart rate or mouse position). Characteristics may also have descriptors that contain metadata (eg. the units of a characteristic). Services can optionally include other services. All BLE attributes (Services, Characterisics and Descriptors) are identified by a 16-bit numberassigned by the Bluetooth SIG.Characteristics may operate in a number of modes depending on their purpose. By default characteristics are read-only in this library however they may also be writable and provide notification (like an event system) when their value changes. Additionally some characteristics require security protection. You can read more about BLE on theBluetooth SIG blog.UsageThere are a few important things you need to remember when using this library:Do not attempt to create the Generic Access Service or a Client Characteristic Configuration Descriptor(if you don't know what this means don't worry). These are both handled automatically by Bluez and attempting to define them will result in errors.Services are not implicitly threaded.If you register a service in your main thread blocking that thread will stop your service (and particularly notifications) from working. Therefore you must frequently yeild to the asyncio event loop (for example using asyncio.sleep) and ideally use multithreading.The easiest way to use the library is to create a class describing the service that you wish to provide.frombluez_peripheral.gatt.serviceimportServicefrombluez_peripheral.gatt.characteristicimportcharacteristic,CharacteristicFlagsasCharFlagsimportstructclassHeartRateService(Service):def__init__(self):# Base 16 service UUID, This should be a primary service.super().__init__("180D",True)@characteristic("2A37",CharFlags.NOTIFY)defheart_rate_measurement(self,options):# This function is called when the characteristic is read.# Since this characteristic is notify only this function is a placeholder.# You don't need this function Python 3.9+ (See PEP 614).# You can generally ignore the options argument# (see Advanced Characteristics and Descriptors Documentation).passdefupdate_heart_rate(self,new_rate):# Call this when you get a new heartrate reading.# Note that notification is asynchronous (you must await something at some point after calling this).flags=0# Bluetooth data is little endian.rate=struct.pack("<BB",flags,new_rate)self.heart_rate_measurement.changed(rate)Bluez interfaces with bluez-peripheral using dbus for inter-process communication. For Bluez to start offering your service it needs to be registered on this bus. Additionally if you want devices to pair with your device you need to register an agent to decide how pairing should be completed. Finally you also need to advertise the service to nearby devices.frombluez_peripheral.utilimport*frombluez_peripheral.advertimportAdvertisementfrombluez_peripheral.agentimportNoIoAgentimportasyncioasyncdefmain():# Alternativly you can request this bus directly from dbus_next.bus=awaitget_message_bus()service=HeartRateService()awaitservice.register(bus)# An agent is required to handle pairingagent=NoIoAgent()# This script needs superuser for this to work.awaitagent.register(bus)adapter=awaitAdapter.get_first(bus)# Start an advert that will last for 60 seconds.advert=Advertisement("Heart Monitor",["180D"],0x0340,60)awaitadvert.register(bus,adapter)whileTrue:# Update the heart rate.service.update_heart_rate(120)# Handle dbus requests.awaitasyncio.sleep(5)awaitbus.wait_for_disconnect()if__name__=="__main__":asyncio.run(main())To communicate with bluez the default dbus configuration requires that you be in the bluetooth user group (eg.sudo useradd -aG bluetooth spacecheese).
For more examples please read thedocumentation.