Merge pull request #7 from myoung34/blescan_docs

Add docs to blescan as well as a few tests

.github/workflows/deploy.yml

@@ -28,10 +28,6 @@ jobs:
       run: echo "::set-env name=PYTHONPATH::$(pwd)"
     - name: pytest
       run: py.test --cov-config .coveragerc --cov tilty --cov-report term-missing --cov-report xml --junitxml junit.xml tests
-    - name: coveralls
-      run: coveralls
-      env:
-        COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
   latest_deploy:
     runs-on: ubuntu-latest
     needs: [test]

.github/workflows/release.yml

@@ -27,10 +27,6 @@ jobs:
       run: echo "::set-env name=PYTHONPATH::$(pwd)"
     - name: pytest
       run: py.test --cov-config .coveragerc --cov tilty --cov-report term-missing --cov-report xml --junitxml junit.xml tests
-    - name: coveralls
-      run: coveralls
-      env:
-        COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
   upload_to_pypi:
     runs-on: ubuntu-latest
     needs: [test]

pyproject.toml

@@ -39,7 +39,6 @@ commands =
     isort -c -rc tilty -sp {toxinidir}
     pylint --rcfile {toxinidir}/.pylintrc -r n tilty
     py.test --cov-config .coveragerc --cov tilty --cov-report term-missing --cov-report xml --junitxml junit.xml tests {posargs}
-    coveralls
 whitelist_externals = make
                       bash
                       pylint

tests/test_blescan.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+from tilty import blescan
+
+
+def test_number_packet():
+    assert blescan.number_packet(b'\x89=') == 35133
+
+
+def test_string_packet():
+    assert blescan.string_packet(b'\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') == 'fe000000000000000000000000000000'  # noqa
+
+
+def test_packed_bdaddr_to_string():
+    assert blescan.packed_bdaddr_to_string(b'ID\x8b\xea&b') == '62:26:ea:8b:44:49'  # noqa

tilty/blescan.py

@@ -39,29 +39,31 @@
 def getBLESocket(devID):
 	return bluez.hci_open_dev(devID)
 
-def returnnumberpacket(pkt):
+def number_packet(pkt):
+    # b'\x89='
     myInteger = 0
     multiple = 256
     for i in range(len(pkt)):
+        # 35072
+        # 61
         myInteger += struct.unpack("B",pkt[i:i+1])[0] * multiple
         multiple = 1
-    return myInteger
+    return myInteger # 35133
 
-def returnstringpacket(pkt):
+def string_packet(pkt):
+    #  UUID is 16 Bytes
+    # b'\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
+    # so len() is 16
+    # loop over each byte, get it to hex, build up the string (uuid is 32 chars, 16bytes)
     myString = "";
-    for i in range(len(pkt)):
+    for i in range(len(pkt)):  # 0-16 loop
         myString += "%02x" %struct.unpack("B",pkt[i:i+1])[0]
     return myString
 
-def get_packed_bdaddr(bdaddr_string):
-    packable_addr = []
-    addr = bdaddr_string.split(':')
-    addr.reverse()
-    for b in addr:
-        packable_addr.append(int(b, 16))
-    return struct.pack("<BBBBBB", *packable_addr)
-
 def packed_bdaddr_to_string(bdaddr_packed):
+    #  iBeacon packets have the mac byte-reversed, reverse with bdaddr_packed[::-1]
+    #  b'ID\x8b\xea&b' -> b'b&\xea\x8bDI'
+    #  decode to int -> (98, 38, 234, 139, 68, 73) , join by : as hex -> '62:26:ea:8b:44:49'
     return ':'.join('%02x'%i for i in struct.unpack("<BBBBBB", bdaddr_packed[::-1]))
 
 def hci_enable_le_scan(sock):
@@ -86,28 +88,24 @@ def parse_events(sock, loop_count=100):
     beacons = []
     for i in range(0, loop_count):
         pkt = sock.recv(255)
-        ptype, event, plen = struct.unpack("BBB", pkt[:3])
-        if event == bluez.EVT_INQUIRY_RESULT_WITH_RSSI:
-            i = 0
-        elif event == bluez.EVT_NUM_COMP_PKTS:
-            i = 0
-        elif event == bluez.EVT_DISCONN_COMPLETE:
-            i = 0
-        elif event == LE_META_EVENT:
-            subevent, = struct.unpack("B", pkt[3:4])
-            pkt = pkt[4:]
-            if subevent == EVT_LE_CONN_COMPLETE:
-                le_handle_connection_complete(pkt)
-            elif subevent == EVT_LE_ADVERTISING_REPORT:
-                num_reports = struct.unpack("B", pkt[0:1])[0]
-                report_pkt_offset = 0
+        # http://www.havlena.net/wp-content/themes/striking/includes/timthumb.php?src=/wp-content/uploads/ibeacon-packet.png&w=600&zc=1
+        #pkt = b'\x04>+\x02\x01\x03\x01r\xed\x08S\x84=\x1f\x1e\xff\x06\x00\x01\t \x02)\xa7\x93\xe2\xfdD\x1b\xafhOH\xef>mn\x91\xcb\x14\x02$\x98\xc7\xef\xb3'
+        #       |      |   |   |   |    |             |                                   |                                          |     |              |
+        #       | event|sub|#rep\  |    |  mac addr   |                                   |    uuid                                  | major\ minor|      |
+        ptype, event, plen = struct.unpack("BBB", pkt[:3])  # b'\x04>(' -> (4, 62, 40)
+        if event == LE_META_EVENT:  # 62 -> 0x3e -> HCI Event: LE Meta Event (0x3e) plen 39
+            subevent, = struct.unpack("B", pkt[3:4]) # b'\x02' -> (2,)
+            # chop off \x04>+\x02 (the event + subevent)
+            pkt = pkt[4:]  # b'\x01\x03\x01r\xed\x08S\x84=\x1f\x1e\xff\x06\x00\x01\t \x02)\xa7\x93\xe2\xfdD\x1b\xafhOH\xef>mn\x91\xcb\x14\x02$\x98\xc7\xef\xb3'
+            if subevent == EVT_LE_ADVERTISING_REPORT:  # if 0x02 (2) -> all iBeacons use this
+                num_reports = struct.unpack("B", pkt[0:1])[0]  # b'\x01' -> (1,) -> number of reports to receive
                 for i in range(0, num_reports):
                     # build the return string
                     beacons.append({
-                        'mac': packed_bdaddr_to_string(pkt[report_pkt_offset + 3:report_pkt_offset + 9]),
-                        'uuid': returnstringpacket(pkt[report_pkt_offset - 22: report_pkt_offset - 6]),
-                        'minor': returnnumberpacket(pkt[report_pkt_offset - 4: report_pkt_offset - 2]),
-                        'major': returnnumberpacket(pkt[report_pkt_offset - 6: report_pkt_offset - 4]),
+                        'mac': packed_bdaddr_to_string(pkt[3:9]),  #  b'r\xed\x08S\x84='
+                        'uuid': string_packet(pkt[22:6]),    #  b'\x93\xe2\xfdD\x1b\xafhOH\xef>mn\x91\xcb\x14'
+                        'minor': number_packet(pkt[4:2]),    #  b'\x98\xc7'
+                        'major': number_packet(pkt[6:4]),    #  b'\x02$'
                     })
     sock.setsockopt( bluez.SOL_HCI, bluez.HCI_FILTER, old_filter )
     return beacons