Merge pull request #66 from GaLaXy102/master

Create an interface to this ~~script~~ library

Readme.md

@@ -6,7 +6,7 @@ You need python 3.6 or newer to run the script.
 
 # ▶️ How to run
 
-### There are three options:
+### There are four options:
 
 ### Option 1: Install from PyPI
 Please ensure you have the BlueZ and python libraries and header files if you are using Ubuntu/Debian based distros:
@@ -60,6 +60,52 @@ docker run --rm -ti --privileged --net=host bluetooth_battery_level "BT_MAC_ADDR
 
 --------
 
+### Option 4: AUR
+
+You must have AUR access enabled on your Arch or Manjaro machine.
+You can install this library using
+
+```bash
+yay -S bluetooth-headset-battery-level-git
+```
+
+--------
+
+### Library usage
+
+To use this as a library, simply install it using pip or AUR (see above) or require it in your Pipfile. 
+You can then
+```python
+from bluetooth_battery import BatteryStateQuerier, BatteryQueryError, BluetoothError
+ # only for error handling
+```
+and query the Battery State as follows:
+```python
+# Autodetects SPP port
+query = BatteryStateQuerier("11:22:33:44:55:66")
+# or with given port
+query = BatteryStateQuerier("11:22:33:44:55:66", "4")
+
+result = int(query) # returns integer between 0 and 100
+# or
+result = str(query) # returns "0%".."100%"
+```
+
+As errors can occur in a wireless system, you probably want to handle them:
+
+```python
+try:
+ query = BatteryStateQuerier("11:22:33:44:55:66") # Can raise BluetoothError when autodetecting port
+ str(query) # Can raise BluetoothError when device is down or port is wrong
+ # Can raise BatteryQueryError when the device is unsupported
+except BluetoothError as e:
+ # Handle device is offline
+ ...
+except BatteryQueryError as e:
+ # Handle device is unsupported
+ ...
+```
+
 ### GNOME Extension
 
 There is also a GNOME extension for integrating this program with GNOME desktop environment:
@@ -106,6 +152,7 @@ You can open a new issue for discussion or check the existing ones for more info
 ## Tested on
 
 - [x] ArchLinux (5.6.14)
+- [x] Manjaro (5.14.10)
 - [x] NixOS 20.09 (20.09.2386.ae1b121d9a6)
 - [x] Debian GNU/Linux (bullseye 5.9)
 - [x] Ubuntu/Linux (Focal Fossa 20.04.1)

__init__.py

@@ -0,0 +1,2 @@
+from .bluetooth_battery import BatteryStateQuerier, BatteryQueryError
+from bluetooth import BluetoothError

bluetooth_battery.py

@@ -1,119 +1,163 @@
 #!/usr/bin/env python3
 
 """
-A python script to get battery level from Bluetooth headsets
+A python library to get battery level from Bluetooth headsets
 """
 
 # License: GPL-3.0
-# Author: @TheWeirdDev
+# Author: @TheWeirdDev, @GaLaXy102
 # 29 Sept 2019
 
-import sys
+import argparse
 import bluetooth
+from typing import Optional, Union, List, Dict
+
+
+class BatteryQueryError(bluetooth.BluetoothError):
+ pass
+
+
+class SocketDataIterator:
+ def __init__(self, sock: bluetooth.BluetoothSocket, chunk_size: int = 128):
+ """
+ Create an Iterator over the given Socket
+
+ chunk_size defines the amount of data in Bytes to be read per iteration
+ """
+ self._sock = sock
+ self._chunk_size = chunk_size
+
+ def __next__(self):
+ """
+ Receive chunks
+ """
+ return self._sock.recv(self._chunk_size)
+
+
+class RFCOMMSocket(bluetooth.BluetoothSocket):
+
+ def __init__(self, proto=bluetooth.RFCOMM, _sock=None):
+ super().__init__(proto, _sock)
+
+ def __iter__(self):
+ """
+ Iterate over incoming chunks of 128 Bytes
+ """
+ return SocketDataIterator(self)
+
+ @staticmethod
+ def find_rfcomm_port(device_mac) -> int:
+ """
+ Find the RFCOMM port number for a given bluetooth device
+ """
+ uuid = "0000111e-0000-1000-8000-00805f9b34fb"
+ services: List[Dict] = bluetooth.find_service(address=device_mac, uuid=uuid)
+
+ for service in services:
+ if "protocol" in service.keys() and service["protocol"] == "RFCOMM":
+ return service["port"]
+ # Raise Interface error when the required service is not offered my the end device
+ raise bluetooth.BluetoothError("Couldn't find the RFCOMM port number. Perhaps the device is offline?")
+
+ def send(self, data):
+ """
+ This function sends a message through a bluetooth socket with added line separators
+ """
+ return super().send(b"\r\n" + data + b"\r\n")
+
+
+class BatteryStateQuerier:
+
+ def __init__(self, bluetooth_mac: str, bluetooth_port: Optional[Union[str, int]] = None):
+ """
+ Prepare a query for the end devices' battery state
+
+ bluetooth_mac is the MAC of the end device, e.g. 11:22:33:44:55:66
+ bluetooth_port is the Port of the RFCOMM/SPP service of the end device.
+ It will be determined automatically if not given.
+
+ The actual query can be performed using the int() and str() method.
+ """
+ self._bt_settings = bluetooth_mac, int(bluetooth_port or RFCOMMSocket.find_rfcomm_port(bluetooth_mac))
+
+ def __int__(self):
+ """
+ Perform a reading and get the result as int between 0 and 100
+ """
+ return self._perform_query()
+
+ def __str__(self):
+ """
+ Perform a reading and get the result as str between 0% and 100%
+ """
+ return "{:.0%}".format(self._perform_query() / 100)
+
+ def _perform_query(self) -> int:
+ """
+ Will try to get and print the battery level of supported devices
+ """
+ result = None
+ sock = RFCOMMSocket()
+ sock.connect(self._bt_settings)
+ # Iterate received packets until there is no more or a result was found
+ for line in sock:
+ if b"BRSF" in line:
+ sock.send(b"+BRSF: 1024")
+ sock.send(b"OK")
+ elif b"CIND=" in line:
+ sock.send(b"+CIND: (\"battchg\",(0-5))")
+ sock.send(b"OK")
+ elif b"CIND?" in line:
+ sock.send(b"+CIND: 5")
+ sock.send(b"OK")
+ elif b"BIND=?" in line:
+ # Announce that we support the battery level HF indicator
+ # https://www.bluetooth.com/specifications/assigned-numbers/hands-free-profile/
+ sock.send(b"+BIND: (2)")
+ sock.send(b"OK")
+ elif b"BIND?" in line:
+ # Enable battery level HF indicator
+ sock.send(b"+BIND: 2,1")
+ sock.send(b"OK")
+ elif b"XAPL=" in line:
+ sock.send(b"+XAPL=iPhone,7")
+ sock.send(b"OK")
+ elif b"IPHONEACCEV" in line:
+ parts = line.strip().split(b',')[1:]
+ if len(parts) > 1 and (len(parts) % 2) == 0:
+ parts = iter(parts)
+ params = dict(zip(parts, parts))
+ if b'1' in params:
+ result = (int(params[b'1']) + 1) * 10
+ break
+ elif b"BIEV=" in line:
+ params = line.strip().split(b"=")[1].split(b",")
+ if params[0] == b"2":
+ result = int(params[1])
+ break
+ elif b"XEVENT=BATTERY" in line:
+ params = line.strip().split(b"=")[1].split(b",")
+ result = int(params[1]) / int(params[2]) * 100
+ break
+ else:
+ sock.send(b"OK")
+ sock.close()
+ # Check whether the result was found, otherwise raise an Error
+ if result is None:
+ raise BatteryQueryError("Could not query the battery state.")
+ return result
 
 
-def send(sock, message):
- """
- This function sends a message through a bluetooth socket
- """
- sock.send(b"\r\n" + message + b"\r\n")
-
-
-def get_at_command(sock, line, device):
- """
- Will try to get and print the battery level of supported devices
- """
- blevel = -1
-
- if b"BRSF" in line:
- send(sock, b"+BRSF: 1024")
- send(sock, b"OK")
- elif b"CIND=" in line:
- send(sock, b"+CIND: (\"battchg\",(0-5))")
- send(sock, b"OK")
- elif b"CIND?" in line:
- send(sock, b"+CIND: 5")
- send(sock, b"OK")
- elif b"BIND=?" in line:
- # Announce that we support the battery level HF indicator
- # https://www.bluetooth.com/specifications/assigned-numbers/hands-free-profile/
- send(sock, b"+BIND: (2)")
- send(sock, b"OK")
- elif b"BIND?" in line:
- # Enable battery level HF indicator
- send(sock, b"+BIND: 2,1")
- send(sock, b"OK")
- elif b"XAPL=" in line:
- send(sock, b"+XAPL=iPhone,7")
- send(sock, b"OK")
- elif b"IPHONEACCEV" in line:
- parts = line.strip().split(b',')[1:]
- if len(parts) > 1 and (len(parts) % 2) == 0:
- parts = iter(parts)
- params = dict(zip(parts, parts))
- if b'1' in params:
- blevel = (int(params[b'1']) + 1) * 10
- elif b"BIEV=" in line:
- params = line.strip().split(b"=")[1].split(b",")
- if params[0] == b"2":
- blevel = int(params[1])
- elif b"XEVENT=BATTERY" in line:
- params = line.strip().split(b"=")[1].split(b",")
- blevel = int(params[1]) / int(params[2]) * 100
- else:
- send(sock, b"OK")
-
- if blevel != -1:
- print(f"Battery level for {device} is {blevel}%")
- return False
-
- return True
-
-
-def find_rfcomm_port(device):
- """
- Find the RFCOMM port number for a given bluetooth device
- """
- uuid = "0000111e-0000-1000-8000-00805f9b34fb"
- proto = bluetooth.find_service(address=device, uuid=uuid)
- if len(proto) == 0:
- print("Couldn't find the RFCOMM port number")
- return 4
-
- for pr in proto:
- if 'protocol' in pr and pr['protocol'] == 'RFCOMM':
- port = pr['port']
- return port
- return 4
-
-
-def main():
+if __name__ == "__main__":
  """
  The starting point of the program. For each device address in the argument
  list a bluetooth socket will be opened and the battery level will be read
  and printed to stdout
  """
- if len(sys.argv) < 2:
- print("Usage: bluetooth_battery.py BT_MAC_ADDRESS_1.PORT ...")
- print(" Port number is optional")
- sys.exit()
- else:
- for device in sys.argv[1:]:
- i = device.find('.')
- if i == -1:
- port = find_rfcomm_port(device)
- else:
- port = int(device[i+1:])
- device = device[:i]
- try:
- sock = bluetooth.BluetoothSocket(bluetooth.RFCOMM)
- sock.connect((device, port))
- while get_at_command(sock, sock.recv(128), device):
- pass
- sock.close()
- except OSError as err:
- print(f"{device} is offline", err)
-
-
-if __name__ == "__main__":
- main()
+ parser = argparse.ArgumentParser(description="Get battery level from Bluetooth headsets")
+ parser.add_argument("devices", metavar="DEVICE_MAC[.PORT]", type=str, nargs="+",
+ help="(MAC address of target)[.SPP Port]")
+ args = parser.parse_args()
+ for device in args.devices:
+ query = BatteryStateQuerier(*device.split("."))
+ print("Battery level for {} is {}".format(device, str(query)))