btsnoop-parser 0.2.2__tar.gz → 0.3.0__tar.gz

{btsnoop_parser-0.2.2 → btsnoop_parser-0.3.0}/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: btsnoop-parser
-Version: 0.2.2
+Version: 0.3.0
 Summary: Parse and explore Bluetooth HCI btsnoop captures from Android devices.
 Author-email: Kranthi <kdevprofile@gmail.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/devk-op/btsnoop-parser
 Project-URL: Repository, https://github.com/devk-op/btsnoop-parser
 Project-URL: Issues, https://github.com/devk-op/btsnoop-parser/issues
 Keywords: bluetooth,btsnoop,hci,android,parser
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10

{btsnoop_parser-0.2.2 → btsnoop_parser-0.3.0}/btsnoop_parser/analysis.py

@@ -6,7 +6,7 @@ import datetime
 import logging
 from typing import Any, Optional
 
-from .constants import HCI_ERROR_CODES
+from .constants import HCI_ERROR_CODES, HCI_OPCODE_NAMES
 
 LOG = logging.getLogger(__name__)
 
@@ -75,15 +75,18 @@ class CaptureStats:
                 elif reason == 0x13:
                     reason_str += " (Remote Device)"
 
+                # 0x13=Remote User Terminated, 0x14=Remote Low Resources,
+                # 0x15=Remote Power Off, 0x16=Local Terminated
+                _normal_reasons = (0x00, 0x13, 0x14, 0x15, 0x16)
                 self.lifecycle_events.append({
                     "timestamp": ts,
                     "event": "Disconnected",
                     "handle": f"0x{handle:03X}",
                     "details": f"Reason: {reason_str}",
-                    "is_error": reason not in (0x13, 0x16, 0x00) # 0x13=Remote User Terminated, 0x16=Local Terminated
+                    "is_error": reason not in _normal_reasons,
                 })
-                
-                if reason not in (0x13, 0x16, 0x00):
+
+                if reason not in _normal_reasons:
                      self.issues.append({
                          "timestamp": ts,
                          "level": "WARN",
@@ -112,11 +115,18 @@ class CaptureStats:
                         })
                     else:
                         err_str = HCI_ERROR_CODES.get(status, f"0x{status:02X}")
+                        self.lifecycle_events.append({
+                            "timestamp": ts,
+                            "event": "Connect Failed (LE)",
+                            "handle": f"0x{handle:03X}",
+                            "details": f"Device: {bd_addr} — {err_str}",
+                            "is_error": True,
+                        })
                         self.issues.append({
-                             "timestamp": ts,
-                             "level": "WARN",
-                             "title": "LE Connection Failed",
-                             "detail": f"Failed to connect to {bd_addr}: {err_str}"
+                            "timestamp": ts,
+                            "level": "WARN",
+                            "title": "LE Connection Failed",
+                            "detail": f"Failed to connect to {bd_addr}: {err_str}",
                         })
 
                 # LE Enhanced Connection Complete (0x0A) - used in Bluetooth 5.x
@@ -153,12 +163,19 @@ class CaptureStats:
                     })
                 else:
                     err_str = HCI_ERROR_CODES.get(status, f"0x{status:02X}")
+                    self.lifecycle_events.append({
+                        "timestamp": ts,
+                        "event": "Connect Failed (Classic)",
+                        "handle": f"0x{handle:03X}",
+                        "details": f"Device: {bd_addr} — {err_str}",
+                        "is_error": True,
+                    })
                     self.issues.append({
-                         "timestamp": ts,
-                         "level": "WARN",
-                         "title": "Connection Failed",
-                         "detail": f"Failed to connect to {bd_addr}: {err_str}"
-                     })
+                        "timestamp": ts,
+                        "level": "WARN",
+                        "title": "Connection Failed",
+                        "detail": f"Failed to connect to {bd_addr}: {err_str}",
+                    })
 
             # Synchronous Connection Complete (0x2C)
             elif event_code == 0x2C and len(payload) >= 19:
@@ -181,16 +198,16 @@ class CaptureStats:
             # Command Complete (0x0E)
             elif event_code == 0x0E and len(payload) >= 6:
                 opcode = payload[3] | (payload[4] << 8)
-                if len(payload) > 5:
-                    status = payload[5]
-                    if status != 0x00:
-                        err_str = HCI_ERROR_CODES.get(status, f"0x{status:02X}")
-                        self.issues.append({
-                             "timestamp": ts,
-                             "level": "ERROR",
-                             "title": "Command Failure",
-                             "detail": f"Opcode 0x{opcode:04X} failed with status {err_str}"
-                         })
+                status = payload[5]
+                if status != 0x00:
+                    err_str = HCI_ERROR_CODES.get(status, f"0x{status:02X}")
+                    opcode_name = HCI_OPCODE_NAMES.get(opcode, f"0x{opcode:04X}")
+                    self.issues.append({
+                        "timestamp": ts,
+                        "level": "ERROR",
+                        "title": "Command Failure",
+                        "detail": f"{opcode_name} failed: {err_str}",
+                    })
 
             # Command Status (0x0F)
             elif event_code == 0x0F and len(payload) >= 6:
@@ -198,12 +215,13 @@ class CaptureStats:
                 opcode = payload[4] | (payload[5] << 8)
                 if status != 0x00:
                     err_str = HCI_ERROR_CODES.get(status, f"0x{status:02X}")
+                    opcode_name = HCI_OPCODE_NAMES.get(opcode, f"0x{opcode:04X}")
                     self.issues.append({
-                         "timestamp": ts,
-                         "level": "ERROR",
-                         "title": "Command Status Error",
-                         "detail": f"Opcode 0x{opcode:04X} returned status {err_str}"
-                     })
+                        "timestamp": ts,
+                        "level": "ERROR",
+                        "title": "Command Status Error",
+                        "detail": f"{opcode_name} returned status {err_str}",
+                    })
 
             # Hardware Error (0x10)
             elif event_code == 0x10 and len(payload) >= 2:
@@ -229,24 +247,33 @@ class CaptureStats:
         duration = "N/A"
         if self.start_time and self.end_time:
             diff = self.end_time - self.start_time
-            duration = str(diff)
+            total_s = int(diff.total_seconds())
+            h, rem = divmod(total_s, 3600)
+            m, s = divmod(rem, 60)
+            ms = diff.microseconds // 1000
+            if h:
+                duration = f"{h}h {m:02d}m {s:02d}.{ms:03d}s"
+            elif m:
+                duration = f"{m}m {s:02d}.{ms:03d}s"
+            else:
+                duration = f"{s}.{ms:03d}s"
 
-        print(f"\\n{BOLD} Capture Statistics ───{RESET}")
+        print(f"\n{BOLD} Capture Statistics ───{RESET}")
         print(f"  {BOLD}Duration:{RESET}      {duration}")
         print(f"  {BOLD}Total Packets:{RESET} {self.total_packets:,}")
         print(f"  {BOLD}Data Volume:{RESET}   {self.total_bytes / 1024:.2f} KB")
-        
-        print(f"\\n{BOLD}Packet Types:{RESET}")
+
+        print(f"\n{BOLD}Packet Types:{RESET}")
         for ptype, count in self.packets_by_type.most_common():
             print(f"  {ptype:<15} {count:>8,}")
 
         if self.devices:
-            print(f"\\n{BOLD}Detected Devices:{RESET}")
+            print(f"\n{BOLD}Detected Devices:{RESET}")
             for addr, name in self.devices.items():
                 print(f"  {CYAN}{addr}{RESET}  {name}")
-        
+
         if self.lifecycle_events:
-            print(f"\\n{BOLD}Connection History:{RESET}")
+            print(f"\n{BOLD}Connection History:{RESET}")
             # Sort by timestamp just in case
             self.lifecycle_events.sort(key=lambda x: x["timestamp"])
             
@@ -265,7 +292,7 @@ class CaptureStats:
                 print(f"  {t_str} {c_evt}{etype:<20}{RESET} {handle} -> {details}")
 
         if self.issues:
-            print(f"\\n{BOLD}Potential Issues ({len(self.issues)}):{RESET}")
+            print(f"\n{BOLD}Potential Issues ({len(self.issues)}):{RESET}")
             for issue in self.issues:
                 color = RED if issue["level"] in ("ERROR", "CRITICAL") else YELLOW
                 # Convert to local time and include date for context
@@ -277,4 +304,4 @@ class CaptureStats:
                 t_str = local_ts.strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
                 print(f"  {color}[{issue['level']}] {t_str} - {issue['title']}{RESET}: {issue['detail']}")
         else:
-            print(f"\\n{BOLD}{GREEN}No obvious issues detected.{RESET}")
+            print(f"\n{BOLD}{GREEN}No obvious issues detected.{RESET}")

{btsnoop_parser-0.2.2 → btsnoop_parser-0.3.0}/btsnoop_parser/cli.py

@@ -52,7 +52,12 @@ def main() -> None:
     )
     args = parser.parse_args()
 
-    records = parse_btsnoop_file(args.file)
+    try:
+        records = parse_btsnoop_file(args.file)
+    except FileNotFoundError:
+        parser.error(f"File not found: {args.file}")
+    except PermissionError:
+        parser.error(f"Permission denied: {args.file}")
 
     if args.stats:
         from .analysis import CaptureStats

{btsnoop_parser-0.2.2 → btsnoop_parser-0.3.0}/btsnoop_parser/core.py

@@ -189,7 +189,7 @@ def iter_records(
                     ts = ts_corrected
             # -----------------------------------------------------------
 
-        except Exception as exc:
+        except (ValueError, OverflowError, OSError) as exc:
             LOG.error("Skipping record with invalid timestamp %s: %s", timestamp, exc)
             continue
 

{btsnoop_parser-0.2.2 → btsnoop_parser-0.3.0}/btsnoop_parser.egg-info/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: btsnoop-parser
-Version: 0.2.2
+Version: 0.3.0
 Summary: Parse and explore Bluetooth HCI btsnoop captures from Android devices.
 Author-email: Kranthi <kdevprofile@gmail.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/devk-op/btsnoop-parser
 Project-URL: Repository, https://github.com/devk-op/btsnoop-parser
 Project-URL: Issues, https://github.com/devk-op/btsnoop-parser/issues
 Keywords: bluetooth,btsnoop,hci,android,parser
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10

{btsnoop_parser-0.2.2 → btsnoop_parser-0.3.0}/btsnoop_parser.egg-info/SOURCES.txt

@@ -15,5 +15,6 @@ btsnoop_parser.egg-info/dependency_links.txt
 btsnoop_parser.egg-info/entry_points.txt
 btsnoop_parser.egg-info/requires.txt
 btsnoop_parser.egg-info/top_level.txt
+tests/test_analysis.py
 tests/test_cli.py
 tests/test_parser.py

{btsnoop_parser-0.2.2 → btsnoop_parser-0.3.0}/pyproject.toml

@@ -1,16 +1,15 @@
 [project]
 name = "btsnoop-parser"
-version = "0.2.2"
+version = "0.3.0"
 description = "Parse and explore Bluetooth HCI btsnoop captures from Android devices."
 authors = [{ name = "Kranthi", email = "kdevprofile@gmail.com" }]
-license = { text = "MIT" }
+license = "MIT"
 readme = "README.md"
 requires-python = ">=3.9"
 keywords = ["bluetooth", "btsnoop", "hci", "android", "parser"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",

btsnoop_parser-0.3.0/tests/test_analysis.py

@@ -0,0 +1,164 @@
+"""Tests for the CaptureStats analysis module."""
+from __future__ import annotations
+
+import datetime
+import struct
+import unittest
+
+from btsnoop_parser.analysis import CaptureStats
+
+
+_UTC = datetime.timezone.utc
+_BASE_TS = datetime.datetime(2024, 1, 1, 12, 0, 0, tzinfo=_UTC)
+
+
+def _record(payload: bytes, ts: datetime.datetime = _BASE_TS) -> dict:
+    """Build a minimal HCI EVENT record."""
+    return {
+        "packet_type": 0x04,
+        "packet_type_name": "EVENT",
+        "payload": payload,
+        "timestamp": ts,
+        "original_length": len(payload),
+    }
+
+
+def _disconnect_payload(handle: int, reason: int, status: int = 0x00) -> bytes:
+    # [Event(0x05), Len, Status, HandleLSB, HandleMSB, Reason]
+    return bytes([0x05, 0x04, status, handle & 0xFF, (handle >> 8) & 0xFF, reason])
+
+
+def _le_conn_complete_payload(status: int, handle: int = 0x001, addr: bytes = b"\x11\x22\x33\x44\x55\x66") -> bytes:
+    # [Event(0x3E), Len, Subevent(0x01), Status, HandleLSB, HandleMSB, Role, AddrType, Addr(6)]
+    return bytes([0x3E, 0x0D, 0x01, status, handle & 0xFF, (handle >> 8) & 0xFF, 0x00, 0x00]) + addr
+
+
+def _classic_conn_complete_payload(status: int, handle: int = 0x001, addr: bytes = b"\x11\x22\x33\x44\x55\x66") -> bytes:
+    # [Event(0x03), Len, Status, HandleLSB, HandleMSB, Addr(6), LinkType, EncMode]
+    return bytes([0x03, 0x0B, status, handle & 0xFF, (handle >> 8) & 0xFF]) + addr + bytes([0x01, 0x00])
+
+
+def _cmd_complete_payload(opcode: int, status: int) -> bytes:
+    # [Event(0x0E), Len, NumCmds, OpcodeLSB, OpcodeMSB, Status]
+    return bytes([0x0E, 0x04, 0x01, opcode & 0xFF, (opcode >> 8) & 0xFF, status])
+
+
+class TestDisconnection(unittest.TestCase):
+    def _stats(self, reason: int) -> CaptureStats:
+        s = CaptureStats()
+        s.analyze_record(_record(_disconnect_payload(0x001, reason)))
+        return s
+
+    def test_normal_remote_disconnect_no_issue(self):
+        s = self._stats(0x13)  # Remote User Terminated
+        self.assertEqual(len(s.issues), 0)
+        self.assertFalse(s.lifecycle_events[0]["is_error"])
+
+    def test_normal_local_disconnect_no_issue(self):
+        s = self._stats(0x16)  # Local Host Terminated
+        self.assertEqual(len(s.issues), 0)
+
+    def test_power_off_disconnect_not_abnormal(self):
+        """0x15 (Remote Power Off) should not be flagged as abnormal."""
+        s = self._stats(0x15)
+        self.assertEqual(len(s.issues), 0)
+        self.assertFalse(s.lifecycle_events[0]["is_error"])
+
+    def test_low_resources_disconnect_not_abnormal(self):
+        """0x14 (Remote Low Resources) should not be flagged as abnormal."""
+        s = self._stats(0x14)
+        self.assertEqual(len(s.issues), 0)
+
+    def test_unexpected_disconnect_raises_issue(self):
+        s = self._stats(0x08)  # Connection Timeout
+        self.assertEqual(len(s.issues), 1)
+        self.assertEqual(s.issues[0]["title"], "Abnormal Disconnect")
+        self.assertTrue(s.lifecycle_events[0]["is_error"])
+
+
+class TestLEConnectionFailed(unittest.TestCase):
+    def test_failed_le_connection_appears_in_lifecycle(self):
+        """A failed LE connection should appear in lifecycle_events, not just issues."""
+        s = CaptureStats()
+        s.analyze_record(_record(_le_conn_complete_payload(status=0x02)))  # 0x02 = No Connection
+        self.assertEqual(len(s.lifecycle_events), 1)
+        self.assertEqual(s.lifecycle_events[0]["event"], "Connect Failed (LE)")
+        self.assertTrue(s.lifecycle_events[0]["is_error"])
+        self.assertEqual(len(s.issues), 1)
+
+    def test_successful_le_connection_no_issue(self):
+        s = CaptureStats()
+        s.analyze_record(_record(_le_conn_complete_payload(status=0x00)))
+        self.assertEqual(len(s.issues), 0)
+        self.assertEqual(s.lifecycle_events[0]["event"], "Connected (LE)")
+
+
+class TestClassicConnectionFailed(unittest.TestCase):
+    def test_failed_classic_connection_appears_in_lifecycle(self):
+        s = CaptureStats()
+        s.analyze_record(_record(_classic_conn_complete_payload(status=0x04)))  # Page Timeout
+        self.assertEqual(len(s.lifecycle_events), 1)
+        self.assertEqual(s.lifecycle_events[0]["event"], "Connect Failed (Classic)")
+        self.assertTrue(s.lifecycle_events[0]["is_error"])
+        self.assertEqual(len(s.issues), 1)
+
+    def test_successful_classic_connection_no_issue(self):
+        s = CaptureStats()
+        s.analyze_record(_record(_classic_conn_complete_payload(status=0x00)))
+        self.assertEqual(len(s.issues), 0)
+        self.assertEqual(s.lifecycle_events[0]["event"], "Connected (Classic)")
+
+
+class TestCommandFailure(unittest.TestCase):
+    def test_command_failure_uses_opcode_name(self):
+        """Command errors should show the opcode name, not raw hex."""
+        s = CaptureStats()
+        # 0x0C03 = Reset
+        s.analyze_record(_record(_cmd_complete_payload(opcode=0x0C03, status=0x01)))
+        self.assertEqual(len(s.issues), 1)
+        self.assertIn("Reset", s.issues[0]["detail"])
+        self.assertNotIn("0x0C03", s.issues[0]["detail"])
+
+    def test_unknown_opcode_falls_back_to_hex(self):
+        s = CaptureStats()
+        s.analyze_record(_record(_cmd_complete_payload(opcode=0xFFFF, status=0x01)))
+        self.assertIn("0xFFFF", s.issues[0]["detail"])
+
+    def test_successful_command_no_issue(self):
+        s = CaptureStats()
+        s.analyze_record(_record(_cmd_complete_payload(opcode=0x0C03, status=0x00)))
+        self.assertEqual(len(s.issues), 0)
+
+
+class TestDurationFormat(unittest.TestCase):
+    def _stats_with_duration(self, seconds: float) -> CaptureStats:
+        s = CaptureStats()
+        s.start_time = _BASE_TS
+        s.end_time = _BASE_TS + datetime.timedelta(seconds=seconds)
+        return s
+
+    def test_seconds_only(self):
+        s = self._stats_with_duration(5.456)
+        # Trigger format by calling print_summary via capturing output
+        import io, unittest.mock
+        with unittest.mock.patch("sys.stdout", new_callable=io.StringIO) as mock_out:
+            s.print_summary()
+        self.assertIn("5.456s", mock_out.getvalue())
+
+    def test_minutes_and_seconds(self):
+        s = self._stats_with_duration(125.0)
+        import io, unittest.mock
+        with unittest.mock.patch("sys.stdout", new_callable=io.StringIO) as mock_out:
+            s.print_summary()
+        self.assertIn("2m", mock_out.getvalue())
+
+    def test_hours_minutes_seconds(self):
+        s = self._stats_with_duration(3661.0)
+        import io, unittest.mock
+        with unittest.mock.patch("sys.stdout", new_callable=io.StringIO) as mock_out:
+            s.print_summary()
+        self.assertIn("1h", mock_out.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

btsnoop_parser-0.2.2/btsnoop_parser/utils.py

@@ -1,2 +0,0 @@
-def hexify(data):
-    return ' '.join(f'{b:02X}' for b in data)