Android backend¶
For an example of building an android bluetooth app, see the example folder and its accompanying README file.
There are a handful of ways to run Python on Android. Presently some code has been written for the Python-for-Android build tool, and the code has only been tested using the Kivy Framework. The Kivy framework provides a way to make graphical applications using bluetooth that run on both android and desktop.
An alternative framework is BeeWare. An implementation for BeeWare would likely be very similar to Python-for-Android, if anybody is interested in contributing one. As of 2020, the major task to tackle is making a custom template to embed Java subclasses of the Bluetooth Android interfaces, for forwarding callbacks.
The Python-for-Android backend classes are found in the
bleak.backends.p4android
package and are automatically selected when
building with python-for-android or Buildozer,
Kivy’s automated build tool.
Considerations on Android¶
For one thing, the python-for-android backend has not been fully tested.
Please run applications with adb logcat
or buildozer android logcat
and
file issues that include the output, so that any compatibility concerns with
devices the developer did not own can be eventually addressed. This backend
was originally authored by @xloem for a project that has mostly wrapped up now,
so it would be good to tag him in the issues.
When fixing issues, often the Android documentation is lacking, and other resources may need to be consulted to find information on various device quirks, such as community developer forums.
Sometimes device drivers will give off new, undocumented error codes.
There is a developing list of these at bleak.backends.p4android.defs.GATT_STATUS_NAMES
.
Please add to the list if you find new status codes, which is indicated by a
number being reported instead of a name.
Additionally a few small features are missing. Please file an issue if you need a missing feature, and ideally contribute code, so that soon they will all be implemented.
Two missing features include scanning filters and indications (notifications without replies).
Additionally reading from a characteristic has not been tested at all, as xloem’s test device did not provide for this.
On Android, Bluetooth needs permissions for access. These permissions need to be added to the android application in the buildozer.spec file, and are also requested from the user at runtime. This means that enabling bluetooth may not succeed if the user does not accept permissions.
API¶
Scanner¶
-
class
bleak.backends.p4android.scanner.
BleakScannerP4Android
(detection_callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]], service_uuids: Optional[List[str]], scanning_mode: Literal[active, passive], **kwargs)[source]¶ The python-for-android Bleak BLE Scanner.
- Parameters
detection_callback – Optional function that will be called each time a device is discovered or advertising data has changed.
service_uuids – Optional list of service UUIDs to filter on. Only advertisements containing this advertising data will be received. Specifying this also enables scanning while the screen is off on Android.
scanning_mode – Set to
"passive"
to avoid the"active"
scanning mode.
Client¶
BLE Client for python-for-android
-
class
bleak.backends.p4android.client.
BleakClientP4Android
(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], services: Optional[Set[uuid.UUID]], **kwargs)[source]¶ A python-for-android Bleak Client
- Parameters
address_or_ble_device – The Bluetooth address of the BLE peripheral to connect to or the
BLEDevice
object representing it.services – Optional set of services UUIDs to filter.
-
async
connect
(**kwargs) → bool[source]¶ Connect to the specified GATT server.
- Returns
Boolean representing connection status.
-
async
disconnect
() → bool[source]¶ Disconnect from the specified GATT server.
- Returns
Boolean representing if device is disconnected.
-
async
get_services
() → bleak.backends.service.BleakGATTServiceCollection[source]¶ Get all services registered for this GATT server.
- Returns
A
bleak.backends.service.BleakGATTServiceCollection
with this device’s services tree.
-
property
is_connected
¶ Check connection status between this client and the server.
- Returns
Boolean representing connection status.
-
property
mtu_size
¶ Gets the negotiated MTU.
-
async
pair
(*args, **kwargs) → bool[source]¶ Pair with the peripheral.
You can use ConnectDevice method if you already know the MAC address of the device. Else you need to StartDiscovery, Trust, Pair and Connect in sequence.
- Returns
Boolean regarding success of pairing.
-
async
read_gatt_char
(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID], **kwargs) → bytearray[source]¶ Perform read operation on the specified GATT characteristic.
- Parameters
char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it.
- Returns
(bytearray) The read data.
-
async
read_gatt_descriptor
(desc_specifier: Union[bleak.backends.p4android.descriptor.BleakGATTDescriptorP4Android, str, uuid.UUID], **kwargs) → bytearray[source]¶ Perform read operation on the specified GATT descriptor.
- Parameters
desc_specifier (BleakGATTDescriptorP4Android, str or UUID) – The descriptor to read from, specified by either UUID or directly by the BleakGATTDescriptorP4Android object representing it.
- Returns
(bytearray) The read data.
-
async
start_notify
(characteristic: bleak.backends.characteristic.BleakGATTCharacteristic, callback: Callable[[bytearray], None], **kwargs) → None[source]¶ Activate notifications/indications on a characteristic.
-
async
stop_notify
(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID]) → None[source]¶ Deactivate notification/indication on a specified characteristic.
- Parameters
char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it.
-
async
unpair
() → bool[source]¶ Unpair with the peripheral.
- Returns
Boolean regarding success of unpairing.
-
async
write_gatt_char
(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID], data: bytearray, response: bool = False) → None[source]¶ Perform a write operation on the specified GATT characteristic.
- Parameters
char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it.
data (bytes or bytearray) – The data to send.
response (bool) – If write-with-response operation should be done. Defaults to False.
-
async
write_gatt_descriptor
(desc_specifier: Union[bleak.backends.p4android.descriptor.BleakGATTDescriptorP4Android, str, uuid.UUID], data: bytearray) → None[source]¶ Perform a write operation on the specified GATT descriptor.
- Parameters
desc_specifier (BleakGATTDescriptorP4Android, str or UUID) – The descriptor to write to, specified by either UUID or directly by the BleakGATTDescriptorP4Android object representing it.
data (bytes or bytearray) – The data to send.