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

btsnoop_parser-0.4.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: btsnoop-parser
+Version: 0.4.0
+Summary: Parse and explore Bluetooth HCI btsnoop captures from Android devices.
+Author-email: Kranthi <kdevprofile@gmail.com>
+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: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# btsnoop-parser
+
+[![CI](https://github.com/devk-op/btsnoop-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/devk-op/btsnoop-parser/actions?query=workflow%3A"CI%2FCD+Pipeline")
+[![PyPI](https://img.shields.io/pypi/v/btsnoop-parser)](https://pypi.org/project/btsnoop-parser/)
+[![Docs](https://readthedocs.org/projects/btsnoop-parser/badge/?version=latest)](https://btsnoop-parser.readthedocs.io)
+[![Python](https://img.shields.io/pypi/pyversions/btsnoop-parser)](https://pypi.org/project/btsnoop-parser/)
+
+`btsnoop-parser` is a small library and CLI for exploring Bluetooth `btsnoop_hci.log`
+captures produced on Android devices.  It is a lightweight alternative to Wireshark
+when you need a quick look at packet metadata or want to script over captures in Python.
+
+```
+$ btsnoop_parser capture.log --stats
+
+ Capture Statistics ───
+  Duration:      4m 32.871s
+  Total Packets: 1,842
+  Data Volume:   142.67 KB
+
+Packet Types:
+  ACL Data            1,204
+  Event                 512
+  Command               126
+
+Detected Devices:
+  AA:BB:CC:DD:EE:FF  Unknown
+  11:22:33:44:55:66  Unknown
+
+Connection History:
+  2024-06-01 09:12:03.441  Connected (LE)        0x001 -> Device: AA:BB:CC:DD:EE:FF
+  2024-06-01 09:14:21.009  Disconnected          0x001 -> Reason: Remote User Terminated Connection (Remote Device)
+  2024-06-01 09:15:44.230  Connect Failed (LE)   0x002 -> Device: 11:22:33:44:55:66 — Page Timeout
+
+Potential Issues (1):
+  [WARN] 2024-06-01 09:15:44.230 - LE Connection Failed: Failed to connect to 11:22:33:44:55:66: Page Timeout
+```
+
+## Features
+
+- Parses BTSnoop HCI logs into friendly Python dicts — zero dependencies.
+- Wireshark-style CLI table with direction colouring.
+- **`--filter`** — filter by packet type and direction before processing.
+- **`--pcap`** — export to PCAP (link type 201) for Wireshark / tshark.
+- **`--stats`** — connection history, device list, and issue detection.
+- Decodes common HCI command/event payloads.
+- Corrects the Android ±378-day timestamp bug automatically.
+
+## Installation
+
+```bash
+pip install btsnoop-parser
+```
+
+## CLI Usage
+
+```bash
+# Wireshark-style table, first 20 packets
+btsnoop_parser capture.log --limit 20
+
+# Show only HCI events
+btsnoop_parser capture.log --filter type:event
+
+# Show only TX commands
+btsnoop_parser capture.log --filter type:command --filter dir:tx
+
+# Export filtered records to a PCAP file — open directly in Wireshark
+btsnoop_parser capture.log --filter type:event --pcap events.pcap
+
+# Convert the whole capture to PCAP
+btsnoop_parser capture.log --pcap full.pcap
+
+# Capture statistics and issue detection
+btsnoop_parser capture.log --stats
+
+# JSON output for scripting
+btsnoop_parser capture.log --json | jq '[.[] | select(.direction=="RX")]'
+```
+
+Run `btsnoop_parser --help` for the full option list.
+
+### `--filter` expressions
+
+| Key    | Values                                          | Example                  |
+|--------|-------------------------------------------------|--------------------------|
+| `type` | `command`, `acl`, `event`, `sco`, `iso`, `0xNN` | `--filter type:event`    |
+| `dir`  | `tx`, `rx`                                      | `--filter dir:tx`        |
+
+Comma-separate types for OR logic: `--filter type:command,event`
+Repeat the flag to AND filters: `--filter type:event --filter dir:rx`
+
+## Python API
+
+```python
+from btsnoop_parser import (
+    parse_btsnoop_file,
+    iter_records,
+    filter_records,
+    write_pcap,
+    decode_hci_packet,
+)
+
+# Load all records
+records = parse_btsnoop_file("btsnoop_hci.log")
+
+# Filter to HCI events only
+events = filter_records(records, ["type:event"])
+
+# Export to Wireshark-compatible PCAP
+write_pcap(records, "capture.pcap")
+
+# Stream large files without loading everything into memory
+for record in iter_records("btsnoop_hci.log"):
+    decoded = decode_hci_packet(record["packet_type"], record["payload"])
+    if decoded.get("type") == "COMMAND":
+        print(record["timestamp"], decoded["name"])
+```
+
+Full API reference: **[btsnoop-parser.readthedocs.io](https://btsnoop-parser.readthedocs.io)**
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check
+```
+
+## License
+
+MIT © Kranthi
+
+## Contributing
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on setting up your
+environment, running tests, and submitting pull requests.

btsnoop_parser-0.4.0/README.md

@@ -0,0 +1,135 @@
+# btsnoop-parser
+
+[![CI](https://github.com/devk-op/btsnoop-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/devk-op/btsnoop-parser/actions?query=workflow%3A"CI%2FCD+Pipeline")
+[![PyPI](https://img.shields.io/pypi/v/btsnoop-parser)](https://pypi.org/project/btsnoop-parser/)
+[![Docs](https://readthedocs.org/projects/btsnoop-parser/badge/?version=latest)](https://btsnoop-parser.readthedocs.io)
+[![Python](https://img.shields.io/pypi/pyversions/btsnoop-parser)](https://pypi.org/project/btsnoop-parser/)
+
+`btsnoop-parser` is a small library and CLI for exploring Bluetooth `btsnoop_hci.log`
+captures produced on Android devices.  It is a lightweight alternative to Wireshark
+when you need a quick look at packet metadata or want to script over captures in Python.
+
+```
+$ btsnoop_parser capture.log --stats
+
+ Capture Statistics ───
+  Duration:      4m 32.871s
+  Total Packets: 1,842
+  Data Volume:   142.67 KB
+
+Packet Types:
+  ACL Data            1,204
+  Event                 512
+  Command               126
+
+Detected Devices:
+  AA:BB:CC:DD:EE:FF  Unknown
+  11:22:33:44:55:66  Unknown
+
+Connection History:
+  2024-06-01 09:12:03.441  Connected (LE)        0x001 -> Device: AA:BB:CC:DD:EE:FF
+  2024-06-01 09:14:21.009  Disconnected          0x001 -> Reason: Remote User Terminated Connection (Remote Device)
+  2024-06-01 09:15:44.230  Connect Failed (LE)   0x002 -> Device: 11:22:33:44:55:66 — Page Timeout
+
+Potential Issues (1):
+  [WARN] 2024-06-01 09:15:44.230 - LE Connection Failed: Failed to connect to 11:22:33:44:55:66: Page Timeout
+```
+
+## Features
+
+- Parses BTSnoop HCI logs into friendly Python dicts — zero dependencies.
+- Wireshark-style CLI table with direction colouring.
+- **`--filter`** — filter by packet type and direction before processing.
+- **`--pcap`** — export to PCAP (link type 201) for Wireshark / tshark.
+- **`--stats`** — connection history, device list, and issue detection.
+- Decodes common HCI command/event payloads.
+- Corrects the Android ±378-day timestamp bug automatically.
+
+## Installation
+
+```bash
+pip install btsnoop-parser
+```
+
+## CLI Usage
+
+```bash
+# Wireshark-style table, first 20 packets
+btsnoop_parser capture.log --limit 20
+
+# Show only HCI events
+btsnoop_parser capture.log --filter type:event
+
+# Show only TX commands
+btsnoop_parser capture.log --filter type:command --filter dir:tx
+
+# Export filtered records to a PCAP file — open directly in Wireshark
+btsnoop_parser capture.log --filter type:event --pcap events.pcap
+
+# Convert the whole capture to PCAP
+btsnoop_parser capture.log --pcap full.pcap
+
+# Capture statistics and issue detection
+btsnoop_parser capture.log --stats
+
+# JSON output for scripting
+btsnoop_parser capture.log --json | jq '[.[] | select(.direction=="RX")]'
+```
+
+Run `btsnoop_parser --help` for the full option list.
+
+### `--filter` expressions
+
+| Key    | Values                                          | Example                  |
+|--------|-------------------------------------------------|--------------------------|
+| `type` | `command`, `acl`, `event`, `sco`, `iso`, `0xNN` | `--filter type:event`    |
+| `dir`  | `tx`, `rx`                                      | `--filter dir:tx`        |
+
+Comma-separate types for OR logic: `--filter type:command,event`
+Repeat the flag to AND filters: `--filter type:event --filter dir:rx`
+
+## Python API
+
+```python
+from btsnoop_parser import (
+    parse_btsnoop_file,
+    iter_records,
+    filter_records,
+    write_pcap,
+    decode_hci_packet,
+)
+
+# Load all records
+records = parse_btsnoop_file("btsnoop_hci.log")
+
+# Filter to HCI events only
+events = filter_records(records, ["type:event"])
+
+# Export to Wireshark-compatible PCAP
+write_pcap(records, "capture.pcap")
+
+# Stream large files without loading everything into memory
+for record in iter_records("btsnoop_hci.log"):
+    decoded = decode_hci_packet(record["packet_type"], record["payload"])
+    if decoded.get("type") == "COMMAND":
+        print(record["timestamp"], decoded["name"])
+```
+
+Full API reference: **[btsnoop-parser.readthedocs.io](https://btsnoop-parser.readthedocs.io)**
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check
+```
+
+## License
+
+MIT © Kranthi
+
+## Contributing
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on setting up your
+environment, running tests, and submitting pull requests.

{btsnoop_parser-0.2.2 → btsnoop_parser-0.4.0}/btsnoop_parser/__init__.py

@@ -1,11 +1,14 @@
-from .core import iter_records, parse_btsnoop_file, print_table, slice_records
+from .core import filter_records, iter_records, parse_btsnoop_file, print_table, slice_records
 from .hci_decoder import decode_hci_packet
+from .pcap import write_pcap
 
 __all__ = [
     "decode_hci_packet",
+    "filter_records",
     "iter_records",
     "parse_btsnoop_file",
     "print_table",
     "slice_records",
+    "write_pcap",
 ]
 

{btsnoop_parser-0.2.2 → btsnoop_parser-0.4.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.4.0}/btsnoop_parser/cli.py

@@ -2,7 +2,7 @@ import argparse
 import json
 from typing import Any
 
-from .core import parse_btsnoop_file, print_table, slice_records
+from .core import filter_records, parse_btsnoop_file, print_table, slice_records
 from .hci_decoder import decode_hci_packet
 
 
@@ -25,6 +25,18 @@ def main() -> None:
     parser = argparse.ArgumentParser(description="Parse Android btsnoop_hci.log captures.")
     parser.add_argument("file", help="Path to a btsnoop_hci.log file")
     parser.add_argument("--limit", type=int, help="Limit the number of records shown")
+    parser.add_argument(
+        "--filter",
+        dest="filters",
+        metavar="EXPR",
+        action="append",
+        default=[],
+        help=(
+            "Filter expression as key:value.  May be repeated. "
+            "Supported keys: type (command/acl/event/sco/iso or 0xNN), dir (tx/rx). "
+            "Example: --filter type:event --filter dir:rx"
+        ),
+    )
     parser.add_argument(
         "--json",
         action="store_true",
@@ -45,6 +57,11 @@ def main() -> None:
         action="store_true",
         help="Analyze capture and show high-level statistics and issues",
     )
+    parser.add_argument(
+        "--pcap",
+        metavar="OUTPUT.pcap",
+        help="Write records to a PCAP file (Wireshark-compatible, link type 201)",
+    )
     parser.add_argument(
         "--no-color",
         action="store_true",
@@ -52,7 +69,26 @@ 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}")
+
+    # Apply filters before any other processing
+    if args.filters:
+        try:
+            records = filter_records(records, args.filters)
+        except ValueError as exc:
+            parser.error(str(exc))
+
+    # --pcap: write and exit (can combine with --filter)
+    if args.pcap:
+        from .pcap import write_pcap
+        n = write_pcap(records, args.pcap)
+        print(f"Wrote {n} packets to {args.pcap}")
+        return
 
     if args.stats:
         from .analysis import CaptureStats
@@ -76,4 +112,3 @@ def main() -> None:
         for record in limited:
             decoded = decode_hci_packet(record["packet_type"], record["payload"])
             print(f"{record['index']:>4} {decoded}")
-

{btsnoop_parser-0.2.2 → btsnoop_parser-0.4.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
 
@@ -288,3 +288,82 @@ def slice_records(records: Sequence[Mapping[str, object]], limit: Optional[int])
     if limit is None or limit >= len(records):
         return records
     return records[:limit]
+
+
+# Normalised aliases accepted by filter_records for the "type" key.
+_TYPE_ALIASES: dict[str, set[int]] = {
+    "command": {0x01},
+    "cmd":     {0x01},
+    "acl":     {0x02},
+    "sco":     {0x03},
+    "event":   {0x04},
+    "evt":     {0x04},
+    "iso":     {0x05},
+}
+
+
+def filter_records(
+    records: Sequence[Mapping[str, object]],
+    filters: Sequence[str],
+) -> list[Mapping[str, object]]:
+    """Return records that match *all* of the supplied filter expressions.
+
+    Each expression is a ``key:value`` string.  Supported keys:
+
+    * ``type`` — packet type name or number, e.g. ``type:event``, ``type:acl``,
+      ``type:0x04``.  Multiple values may be comma-separated:
+      ``type:command,event``.
+    * ``dir`` — direction: ``dir:tx`` or ``dir:rx``.
+
+    Examples::
+
+        filter_records(records, ["type:event"])
+        filter_records(records, ["type:command,event", "dir:tx"])
+    """
+    if not filters:
+        return list(records)
+
+    # Pre-parse filter expressions once
+    type_ids: Optional[set[int]] = None
+    dir_value: Optional[str] = None
+
+    for expr in filters:
+        if ":" not in expr:
+            raise ValueError(f"Invalid filter expression {expr!r} — expected 'key:value'")
+        key, _, value = expr.partition(":")
+        key = key.strip().lower()
+        value = value.strip().lower()
+
+        if key == "type":
+            ids: set[int] = set()
+            for part in value.split(","):
+                part = part.strip()
+                if part.startswith("0x"):
+                    ids.add(int(part, 16))
+                elif part.isdigit():
+                    ids.add(int(part))
+                elif part in _TYPE_ALIASES:
+                    ids.update(_TYPE_ALIASES[part])
+                else:
+                    raise ValueError(
+                        f"Unknown packet type {part!r}. "
+                        f"Valid values: {', '.join(sorted(_TYPE_ALIASES))}, or a hex/int."
+                    )
+            type_ids = ids if type_ids is None else type_ids & ids
+
+        elif key == "dir":
+            if value not in ("tx", "rx"):
+                raise ValueError(f"Invalid dir value {value!r} — use 'tx' or 'rx'")
+            dir_value = value.upper()
+
+        else:
+            raise ValueError(f"Unknown filter key {key!r}. Supported keys: type, dir")
+
+    result = []
+    for record in records:
+        if type_ids is not None and record["packet_type"] not in type_ids:
+            continue
+        if dir_value is not None and record["direction"] != dir_value:
+            continue
+        result.append(record)
+    return result