foodforthought-cli 0.2.7__py3-none-any.whl → 0.3.0__py3-none-any.whl

ate/robot/ble_capture.py

@@ -0,0 +1,1000 @@
+"""
+BLE Protocol Capture and Analysis Tools.
+
+Automates the workflow for reverse-engineering BLE robot protocols by:
+1. Capturing traffic from phone apps (iOS PacketLogger / Android HCI snoop)
+2. Analyzing captures to decode commands
+3. Generating Python code for protocol replay
+
+This addresses a critical gap in open-source robotics: many robots have
+undocumented BLE protocols with only proprietary phone apps for control.
+
+Usage:
+    ate robot ble-capture --platform ios --output capture.pklg
+    ate robot ble-analyze capture.pklg
+    ate robot ble-inspect <address>
+"""
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+from collections import defaultdict
+
+
+@dataclass
+class BLECommand:
+    """Represents a decoded BLE command."""
+    frame: int
+    opcode: str  # 'write' or 'notify'
+    handle: int
+    raw_hex: str
+    decoded: Optional[str] = None
+
+    @property
+    def is_write(self) -> bool:
+        return 'write' in self.opcode.lower() or self.opcode == '0x12'
+
+    @property
+    def is_notify(self) -> bool:
+        return 'notif' in self.opcode.lower() or self.opcode == '0x1b'
+
+
+@dataclass
+class CaptureAnalysis:
+    """Results of analyzing a BLE capture."""
+    file_path: str
+    write_handle: Optional[int] = None
+    notify_handle: Optional[int] = None
+    commands: List[BLECommand] = field(default_factory=list)
+    unique_writes: Dict[str, int] = field(default_factory=dict)  # cmd -> count
+    unique_notifies: Dict[str, int] = field(default_factory=dict)
+    protocol_detected: Optional[str] = None
+
+    def summary(self) -> str:
+        """Generate a human-readable summary."""
+        lines = [
+            "=" * 60,
+            "BLE CAPTURE ANALYSIS",
+            "=" * 60,
+            f"File: {self.file_path}",
+            f"Total packets: {len(self.commands)}",
+            "",
+        ]
+
+        if self.write_handle:
+            lines.append(f"WRITE Handle: 0x{self.write_handle:04x} ({self.write_handle})")
+        if self.notify_handle:
+            lines.append(f"NOTIFY Handle: 0x{self.notify_handle:04x} ({self.notify_handle})")
+
+        if self.protocol_detected:
+            lines.append(f"Protocol: {self.protocol_detected}")
+
+        lines.append("")
+        lines.append("-" * 60)
+        lines.append("WRITE COMMANDS (App → Robot):")
+        lines.append("-" * 60)
+
+        for cmd, count in sorted(self.unique_writes.items(), key=lambda x: -x[1]):
+            lines.append(f"  {cmd:30s} ({count}x)")
+
+        if self.unique_notifies:
+            lines.append("")
+            lines.append("-" * 60)
+            lines.append("NOTIFICATIONS (Robot → App):")
+            lines.append("-" * 60)
+
+            for cmd, count in sorted(self.unique_notifies.items(), key=lambda x: -x[1]):
+                lines.append(f"  {cmd:30s} ({count}x)")
+
+        lines.append("")
+        lines.append("=" * 60)
+
+        return "\n".join(lines)
+
+    def generate_python_code(self) -> str:
+        """Generate Python code to replay the captured protocol."""
+        code_lines = [
+            '"""',
+            f'Auto-generated BLE protocol from: {os.path.basename(self.file_path)}',
+            '',
+            'Usage:',
+            '    python this_file.py',
+            '"""',
+            '',
+            'import asyncio',
+            'from bleak import BleakClient, BleakScanner',
+            '',
+            '# Device configuration',
+            'DEVICE_NAME = "your_device_name"  # Update this',
+            '',
+            '# Characteristic UUIDs (common ESP32/HM-10 serial)',
+            'FFE1_WRITE = "0000ffe1-0000-1000-8000-00805f9b34fb"',
+            'FFE2_NOTIFY = "0000ffe2-0000-1000-8000-00805f9b34fb"',
+            '',
+            '# Discovered commands',
+            'COMMANDS = {',
+        ]
+
+        # Add discovered commands
+        for cmd in sorted(self.unique_writes.keys()):
+            # Try to infer command purpose
+            purpose = self._infer_purpose(cmd)
+            safe_name = re.sub(r'[^a-zA-Z0-9_]', '_', purpose.lower())
+            code_lines.append(f'    "{safe_name}": b"{cmd}",')
+
+        code_lines.extend([
+            '}',
+            '',
+            '',
+            'def notification_handler(sender, data):',
+            '    """Handle responses from the device."""',
+            '    try:',
+            '        decoded = data.decode("ascii")',
+            '        print(f"Response: {decoded}")',
+            '    except:',
+            '        print(f"Response (hex): {data.hex()}")',
+            '',
+            '',
+            'async def main():',
+            '    print("Scanning for device...")',
+            '    ',
+            '    device = None',
+            '    devices = await BleakScanner.discover(timeout=5.0)',
+            '    for d in devices:',
+            '        if d.name and DEVICE_NAME.lower() in d.name.lower():',
+            '            device = d',
+            '            break',
+            '    ',
+            '    if not device:',
+            '        print(f"Device {DEVICE_NAME} not found!")',
+            '        return',
+            '    ',
+            '    print(f"Found: {device.name}")',
+            '    ',
+            '    async with BleakClient(device, timeout=15.0) as client:',
+            '        print("Connected!")',
+            '        ',
+            '        # Subscribe to notifications',
+            '        await client.start_notify(FFE2_NOTIFY, notification_handler)',
+            '        await asyncio.sleep(0.3)',
+            '        ',
+            '        # Test each command',
+            '        for name, cmd in COMMANDS.items():',
+            '            print(f"\\nSending: {name}")',
+            '            await client.write_gatt_char(FFE1_WRITE, cmd)',
+            '            await asyncio.sleep(1.0)',
+            '        ',
+            '        await client.stop_notify(FFE2_NOTIFY)',
+            '        print("\\nDone!")',
+            '',
+            '',
+            'if __name__ == "__main__":',
+            '    asyncio.run(main())',
+        ])
+
+        return "\n".join(code_lines)
+
+    def _infer_purpose(self, cmd: str) -> str:
+        """Try to infer the purpose of a command."""
+        # Common patterns for HiWonder CMD protocol
+        if cmd.startswith("CMD|"):
+            parts = cmd.rstrip("|$").split("|")
+            if len(parts) >= 2:
+                func = parts[1]
+                if func == "0":
+                    return "init"
+                elif func == "1":
+                    if len(parts) >= 3:
+                        sub = parts[2]
+                        if sub == "1":
+                            return "pitch"
+                        elif sub == "2":
+                            return "roll"
+                        elif sub == "3":
+                            return "balance"
+                        elif sub == "4":
+                            return "height"
+                        elif sub == "5":
+                            return "reset_posture"
+                    return "posture"
+                elif func == "2":
+                    return f"action_group_{parts[3] if len(parts) > 3 else '1'}"
+                elif func == "3":
+                    if len(parts) >= 3:
+                        sub = parts[2]
+                        mapping = {
+                            "0": "stop",
+                            "1": "turn_right_small",
+                            "3": "forward",
+                            "4": "turn_left_large",
+                            "5": "turn_left_small",
+                            "7": "backward",
+                        }
+                        return mapping.get(sub, f"locomotion_{sub}")
+                    return "locomotion"
+                elif func == "6":
+                    return "battery_query"
+
+        # Default: use sanitized command
+        return cmd[:20].replace("|", "_").replace("$", "")
+
+
+def check_tshark() -> Optional[str]:
+    """Check if tshark is available and return its path."""
+    # Common paths
+    paths = [
+        "/opt/homebrew/bin/tshark",  # Homebrew on Apple Silicon
+        "/usr/local/bin/tshark",      # Homebrew on Intel Mac
+        "/usr/bin/tshark",            # Linux
+        shutil.which("tshark"),       # PATH lookup
+    ]
+
+    for path in paths:
+        if path and os.path.exists(path):
+            return path
+
+    return None
+
+
+def check_adb() -> Optional[str]:
+    """Check if adb is available and return its path."""
+    paths = [
+        "/opt/homebrew/bin/adb",
+        "/usr/local/bin/adb",
+        shutil.which("adb"),
+    ]
+
+    for path in paths:
+        if path and os.path.exists(path):
+            return path
+
+    return None
+
+
+def check_ios_device() -> Tuple[bool, str]:
+    """Check if an iOS device is connected via USB."""
+    try:
+        result = subprocess.run(
+            ["system_profiler", "SPUSBDataType"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if "iPhone" in result.stdout or "iPad" in result.stdout:
+            return True, "iOS device detected via USB"
+        return False, "No iOS device found. Connect iPhone via USB cable."
+    except Exception as e:
+        return False, f"Could not check for iOS device: {e}"
+
+
+def check_android_device() -> Tuple[bool, str]:
+    """Check if an Android device is connected via ADB."""
+    adb = check_adb()
+    if not adb:
+        return False, "adb not found. Install with: brew install android-platform-tools"
+
+    try:
+        result = subprocess.run(
+            [adb, "devices"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        lines = result.stdout.strip().split("\n")
+        # Skip header line, look for devices
+        devices = [l for l in lines[1:] if l.strip() and "device" in l]
+        if devices:
+            return True, f"Android device connected: {devices[0].split()[0]}"
+        return False, "No Android device found. Enable USB debugging and connect via USB."
+    except Exception as e:
+        return False, f"Could not check for Android device: {e}"
+
+
+def capture_ios_interactive(output_path: str, duration: int = 60) -> bool:
+    """
+    Guide user through iOS BLE capture using PacketLogger.
+
+    Returns True if capture was successful.
+    """
+    print("=" * 60)
+    print("iOS BLE CAPTURE WORKFLOW")
+    print("=" * 60)
+    print()
+
+    # Check prerequisites
+    print("Checking prerequisites...")
+
+    # Check for iOS device
+    ios_ok, ios_msg = check_ios_device()
+    if ios_ok:
+        print(f"  ✓ {ios_msg}")
+    else:
+        print(f"  ✗ {ios_msg}")
+        return False
+
+    # Check for PacketLogger
+    packet_logger_paths = [
+        "/Applications/PacketLogger.app",
+        os.path.expanduser("~/Applications/PacketLogger.app"),
+        "/Applications/Additional Tools/Hardware/PacketLogger.app",
+    ]
+
+    packet_logger = None
+    for path in packet_logger_paths:
+        if os.path.exists(path):
+            packet_logger = path
+            break
+
+    if packet_logger:
+        print(f"  ✓ PacketLogger found at {packet_logger}")
+    else:
+        print("  ✗ PacketLogger not found")
+        print()
+        print("To install PacketLogger:")
+        print("  1. Go to: https://developer.apple.com/download/all/")
+        print("  2. Search for 'Additional Tools for Xcode'")
+        print("  3. Download and open the DMG")
+        print("  4. Copy PacketLogger.app from Hardware folder to /Applications")
+        return False
+
+    # Check for tshark (for analysis)
+    tshark = check_tshark()
+    if tshark:
+        print(f"  ✓ tshark found at {tshark}")
+    else:
+        print("  ⚠ tshark not found (needed for analysis)")
+        print("    Install with: brew install wireshark")
+
+    print()
+    print("-" * 60)
+    print("IMPORTANT: Bluetooth Logging Profile Required")
+    print("-" * 60)
+    print("""
+If you haven't already, install the Bluetooth logging profile on your iPhone:
+
+1. On your iPhone, open Safari
+2. Go to: https://developer.apple.com/bug-reporting/profiles-and-logs/?name=bluetooth
+3. Sign in with your Apple ID (developer account required)
+4. Download and install the 'Bluetooth for iOS' profile
+5. Go to Settings > General > VPN & Device Management
+6. Tap the Bluetooth profile and install it
+7. RESTART YOUR IPHONE (required!)
+
+A pulsing Bluetooth icon in the status bar indicates logging is active.
+""")
+
+    input("Press Enter when your iPhone is ready with the logging profile installed...")
+
+    print()
+    print("-" * 60)
+    print("CAPTURE INSTRUCTIONS")
+    print("-" * 60)
+    print(f"""
+1. PacketLogger will now open
+2. Go to File > New iOS Trace (or Cmd+Shift+I)
+3. Select your iPhone from the device list
+4. Click 'Start' to begin capturing
+5. On your iPhone:
+   - Open your robot's control app (e.g., WonderBot)
+   - Connect to the robot
+   - Perform the actions you want to capture
+   - Disconnect from the robot
+6. In PacketLogger, click 'Stop'
+7. Save the capture to: {output_path}
+   (File > Save As...)
+""")
+
+    # Open PacketLogger
+    print("Opening PacketLogger...")
+    subprocess.run(["open", packet_logger])
+
+    print()
+    input(f"Press Enter after you've saved the capture to {output_path}...")
+
+    # Verify the file exists
+    if os.path.exists(output_path):
+        size = os.path.getsize(output_path)
+        print(f"\n✓ Capture saved: {output_path} ({size:,} bytes)")
+        return True
+    else:
+        print(f"\n✗ Capture file not found at {output_path}")
+        print("  Make sure you saved the file to the correct location.")
+        return False
+
+
+def capture_android_interactive(output_path: str) -> bool:
+    """
+    Guide user through Android BLE capture using HCI snoop log.
+
+    Returns True if capture was successful.
+    """
+    print("=" * 60)
+    print("ANDROID BLE CAPTURE WORKFLOW")
+    print("=" * 60)
+    print()
+
+    # Check prerequisites
+    print("Checking prerequisites...")
+
+    adb = check_adb()
+    if adb:
+        print(f"  ✓ adb found at {adb}")
+    else:
+        print("  ✗ adb not found")
+        print("    Install with: brew install android-platform-tools")
+        return False
+
+    android_ok, android_msg = check_android_device()
+    if android_ok:
+        print(f"  ✓ {android_msg}")
+    else:
+        print(f"  ✗ {android_msg}")
+        print()
+        print("To enable USB debugging:")
+        print("  1. Go to Settings > About Phone")
+        print("  2. Tap 'Build Number' 7 times")
+        print("  3. Go to Settings > Developer Options")
+        print("  4. Enable 'USB Debugging'")
+        print("  5. Connect phone and accept the debugging prompt")
+        return False
+
+    tshark = check_tshark()
+    if tshark:
+        print(f"  ✓ tshark found at {tshark}")
+    else:
+        print("  ⚠ tshark not found (needed for analysis)")
+        print("    Install with: brew install wireshark")
+
+    print()
+    print("-" * 60)
+    print("ENABLE BLUETOOTH HCI SNOOP LOG")
+    print("-" * 60)
+    print("""
+On your Android phone:
+1. Go to Settings > Developer Options
+2. Find 'Enable Bluetooth HCI snoop log'
+   (may be under 'Networking' section)
+3. ENABLE it
+4. RESTART your phone (required for logging to start!)
+
+After restart, the logging will be active.
+""")
+
+    input("Press Enter when you've enabled HCI snoop log and restarted...")
+
+    print()
+    print("-" * 60)
+    print("CAPTURE INSTRUCTIONS")
+    print("-" * 60)
+    print("""
+Now perform the actions you want to capture:
+
+1. Open your robot's control app (e.g., WonderBot)
+2. Connect to the robot
+3. Perform the actions you want to capture
+4. Disconnect from the robot
+5. DISABLE Bluetooth HCI snoop log in Developer Options
+   (This stops logging and finalizes the file)
+""")
+
+    input("Press Enter when you've finished capturing and disabled the snoop log...")
+
+    print()
+    print("Extracting capture via adb bugreport...")
+    print("(This may take 1-2 minutes)")
+
+    # Create temp directory for extraction
+    with tempfile.TemporaryDirectory() as tmpdir:
+        bugreport_zip = os.path.join(tmpdir, "bugreport.zip")
+
+        try:
+            # Get bugreport
+            result = subprocess.run(
+                [adb, "bugreport", bugreport_zip],
+                capture_output=True,
+                text=True,
+                timeout=180,  # 3 minutes timeout
+            )
+
+            if not os.path.exists(bugreport_zip):
+                print(f"✗ Failed to get bugreport: {result.stderr}")
+                return False
+
+            print(f"  ✓ Bugreport saved ({os.path.getsize(bugreport_zip):,} bytes)")
+
+            # Extract and find btsnoop file
+            extract_dir = os.path.join(tmpdir, "extracted")
+            subprocess.run(
+                ["unzip", "-q", bugreport_zip, "-d", extract_dir],
+                check=True,
+            )
+
+            # Find btsnoop files
+            btsnoop_files = []
+            for root, dirs, files in os.walk(extract_dir):
+                for f in files:
+                    if "btsnoop" in f.lower() or f.endswith(".cfa"):
+                        btsnoop_files.append(os.path.join(root, f))
+
+            if not btsnoop_files:
+                print("✗ No btsnoop file found in bugreport")
+                print("  Make sure you enabled HCI snoop log before capturing")
+                return False
+
+            # Use the largest file (most data)
+            btsnoop_file = max(btsnoop_files, key=os.path.getsize)
+            print(f"  ✓ Found: {os.path.basename(btsnoop_file)}")
+
+            # Copy to output
+            shutil.copy2(btsnoop_file, output_path)
+            print(f"  ✓ Saved to: {output_path}")
+
+            return True
+
+        except subprocess.TimeoutExpired:
+            print("✗ Timeout waiting for bugreport")
+            return False
+        except Exception as e:
+            print(f"✗ Error: {e}")
+            return False
+
+
+def analyze_capture(capture_path: str) -> Optional[CaptureAnalysis]:
+    """
+    Analyze a BLE capture file (.pklg or .btsnoop).
+
+    Uses tshark to extract BLE ATT protocol data.
+    """
+    if not os.path.exists(capture_path):
+        print(f"Error: File not found: {capture_path}")
+        return None
+
+    tshark = check_tshark()
+    if not tshark:
+        print("Error: tshark not found. Install with: brew install wireshark")
+        return None
+
+    print(f"Analyzing: {capture_path}")
+    print(f"Size: {os.path.getsize(capture_path):,} bytes")
+    print()
+
+    # Extract BLE ATT data
+    try:
+        result = subprocess.run(
+            [
+                tshark,
+                "-r", capture_path,
+                "-Y", "btatt.value",
+                "-T", "fields",
+                "-e", "frame.number",
+                "-e", "btatt.opcode",
+                "-e", "btatt.handle",
+                "-e", "btatt.value",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+    except subprocess.TimeoutExpired:
+        print("Error: tshark timeout")
+        return None
+    except Exception as e:
+        print(f"Error running tshark: {e}")
+        return None
+
+    if result.returncode != 0:
+        print(f"tshark error: {result.stderr}")
+        return None
+
+    # Parse output
+    analysis = CaptureAnalysis(file_path=capture_path)
+
+    for line in result.stdout.strip().split("\n"):
+        if not line.strip():
+            continue
+
+        parts = line.split("\t")
+        if len(parts) < 4:
+            continue
+
+        frame, opcode, handle_str, value_hex = parts[0], parts[1], parts[2], parts[3]
+
+        if not value_hex:
+            continue
+
+        # Parse handle
+        try:
+            if handle_str.startswith("0x"):
+                handle = int(handle_str, 16)
+            else:
+                handle = int(handle_str)
+        except:
+            continue
+
+        # Decode value
+        try:
+            value_bytes = bytes.fromhex(value_hex.replace(":", ""))
+            decoded = value_bytes.decode("ascii")
+        except:
+            decoded = None
+
+        cmd = BLECommand(
+            frame=int(frame),
+            opcode=opcode,
+            handle=handle,
+            raw_hex=value_hex,
+            decoded=decoded,
+        )
+        analysis.commands.append(cmd)
+
+        # Track writes and notifies
+        display = decoded if decoded else f"[hex:{value_hex[:20]}...]"
+
+        if cmd.is_write:
+            if analysis.write_handle is None:
+                analysis.write_handle = handle
+            analysis.unique_writes[display] = analysis.unique_writes.get(display, 0) + 1
+        elif cmd.is_notify:
+            if analysis.notify_handle is None:
+                analysis.notify_handle = handle
+            analysis.unique_notifies[display] = analysis.unique_notifies.get(display, 0) + 1
+
+    # Detect protocol
+    for cmd in analysis.unique_writes.keys():
+        if cmd.startswith("CMD|") and cmd.endswith("|$"):
+            analysis.protocol_detected = "HiWonder CMD Protocol"
+            break
+        elif cmd.startswith("[hex:5555"):
+            analysis.protocol_detected = "Binary Servo Protocol (0x55 0x55)"
+            break
+
+    return analysis
+
+
+def inspect_ble_device(address: str) -> bool:
+    """
+    Inspect a BLE device's services and characteristics.
+
+    Shows which characteristics support write vs notify to help
+    users understand the correct configuration.
+    """
+    try:
+        import asyncio
+        from bleak import BleakClient, BleakScanner
+    except ImportError:
+        print("Error: bleak not installed. Run: pip install bleak")
+        return False
+
+    async def _inspect():
+        print(f"Scanning for device: {address}")
+
+        # Try to find device
+        device = None
+        devices = await BleakScanner.discover(timeout=5.0)
+        for d in devices:
+            if d.address == address or (d.name and address.lower() in d.name.lower()):
+                device = d
+                break
+
+        if not device:
+            print(f"Device not found: {address}")
+            print("\nAvailable devices:")
+            for d in devices:
+                if d.name:
+                    print(f"  {d.name}: {d.address}")
+            return False
+
+        print(f"Found: {device.name} ({device.address})")
+        print()
+
+        async with BleakClient(device, timeout=15.0) as client:
+            print("=" * 60)
+            print("BLE SERVICE & CHARACTERISTIC MAP")
+            print("=" * 60)
+            print()
+
+            for service in client.services:
+                # Shorten UUID for display
+                uuid = str(service.uuid)
+                short_uuid = uuid.split("-")[0] if "-" in uuid else uuid
+                print(f"Service: {short_uuid}")
+
+                for char in service.characteristics:
+                    char_uuid = str(char.uuid)
+                    char_short = char_uuid.split("-")[0] if "-" in char_uuid else char_uuid
+
+                    props = char.properties
+                    prop_str = ", ".join(props)
+
+                    # Determine usage
+                    usage = []
+                    if "write" in props or "write-without-response" in props:
+                        usage.append("← WRITE commands here")
+                    if "notify" in props or "indicate" in props:
+                        usage.append("→ SUBSCRIBE for responses")
+                    if "read" in props:
+                        usage.append("? Can read")
+
+                    print(f"  ├── {char_short}")
+                    print(f"  │     Handle: 0x{char.handle:04x} ({char.handle})")
+                    print(f"  │     Properties: [{prop_str}]")
+                    if usage:
+                        print(f"  │     {' | '.join(usage)}")
+                    print(f"  │")
+
+            print()
+            print("=" * 60)
+            print("RECOMMENDED CONFIGURATION")
+            print("=" * 60)
+
+            # Find write and notify characteristics
+            write_chars = []
+            notify_chars = []
+
+            for service in client.services:
+                for char in service.characteristics:
+                    if "write" in char.properties or "write-without-response" in char.properties:
+                        write_chars.append(char)
+                    if "notify" in char.properties or "indicate" in char.properties:
+                        notify_chars.append(char)
+
+            if write_chars:
+                print(f"\nWrite commands to:")
+                for c in write_chars:
+                    print(f"  {c.uuid}")
+
+            if notify_chars:
+                print(f"\nSubscribe for responses on:")
+                for c in notify_chars:
+                    print(f"  {c.uuid}")
+
+            if write_chars and notify_chars:
+                print(f"""
+Example Python code:
+
+    FFE1_WRITE = "{write_chars[0].uuid}"
+    FFE2_NOTIFY = "{notify_chars[0].uuid}"
+
+    await client.start_notify(FFE2_NOTIFY, handler)
+    await client.write_gatt_char(FFE1_WRITE, b"your_command")
+""")
+
+            return True
+
+    return asyncio.run(_inspect())
+
+
+async def ble_pickup_sequence(address: str) -> bool:
+    """
+    Execute a ball pickup sequence using pure BLE commands.
+
+    Uses:
+    - Action groups (CMD|2|1|X|$) for arm control (if available)
+    - Locomotion (CMD|3|X|$) for walking
+
+    Note: Action groups are pre-programmed sequences on the robot.
+    Not all robots have pickup-related action groups. If the arm
+    doesn't respond, use USB serial for direct servo control.
+
+    Returns True if sequence completed, False if failed.
+    """
+    try:
+        import asyncio
+        from bleak import BleakClient, BleakScanner
+    except ImportError:
+        print("Error: bleak not installed. Run: pip install bleak")
+        return False
+
+    FFE1_WRITE = "0000ffe1-0000-1000-8000-00805f9b34fb"
+    FFE2_NOTIFY = "0000ffe2-0000-1000-8000-00805f9b34fb"
+
+    responses = []
+
+    def notification_handler(sender, data):
+        try:
+            decoded = data.decode('ascii')
+            responses.append(decoded)
+            print(f"  ✓ Response: {decoded}")
+        except:
+            responses.append(data.hex())
+
+    print(f"Scanning for device: {address}...")
+
+    # Find device
+    devices = await BleakScanner.discover(timeout=5.0)
+    device = None
+    for d in devices:
+        if d.address == address or (d.name and address.lower() in (d.name or "").lower()):
+            device = d
+            break
+
+    if not device:
+        print(f"Device not found: {address}")
+        print("Make sure the robot is powered on and not connected to another app.")
+        return False
+
+    print(f"Found: {device.name} ({device.address})")
+
+    try:
+        async with BleakClient(device, timeout=15.0) as client:
+            print(f"Connected: {client.is_connected}")
+
+            # Subscribe to notifications
+            await client.start_notify(FFE2_NOTIFY, notification_handler)
+            await asyncio.sleep(0.3)
+
+            # Battery check
+            print("\n--- Battery Check ---")
+            await client.write_gatt_char(FFE1_WRITE, b"CMD|6|$")
+            await asyncio.sleep(0.5)
+
+            for resp in responses:
+                if "CMD|6|" in resp:
+                    parts = resp.split("|")
+                    if len(parts) >= 3:
+                        try:
+                            mv = int(parts[2])
+                            print(f"  Battery: {mv/1000:.2f}V")
+                        except:
+                            pass
+
+            # Try action groups to find arm-related sequences
+            # These are pre-programmed on the robot
+            print("\n--- Testing Action Groups (looking for arm movement) ---")
+            print("Watch the robot's arm for any movement...")
+
+            # Action groups 1-5 - one might be arm-related
+            for action_id in [1, 2, 3, 4, 5]:
+                cmd = f"CMD|2|1|{action_id}|$".encode()
+                print(f"\n  Action Group {action_id}: {cmd.decode()}")
+                await client.write_gatt_char(FFE1_WRITE, cmd)
+                await asyncio.sleep(3.0)
+
+            # Now do the locomotion sequence
+            print("\n--- Locomotion Sequence ---")
+
+            # Walk forward
+            print("\n  Walking forward (1.5s)...")
+            await client.write_gatt_char(FFE1_WRITE, b"CMD|3|3|$")
+            await asyncio.sleep(1.5)
+
+            # Stop
+            print("  Stopping...")
+            await client.write_gatt_char(FFE1_WRITE, b"CMD|3|0|$")
+            await asyncio.sleep(0.5)
+
+            # Walk backward
+            print("  Walking backward (1.0s)...")
+            await client.write_gatt_char(FFE1_WRITE, b"CMD|3|7|$")
+            await asyncio.sleep(1.0)
+
+            # Stop
+            print("  Stopping...")
+            await client.write_gatt_char(FFE1_WRITE, b"CMD|3|0|$")
+            await asyncio.sleep(0.5)
+
+            # Reset posture
+            print("  Resetting posture...")
+            await client.write_gatt_char(FFE1_WRITE, b"CMD|1|5|$")
+            await asyncio.sleep(1.0)
+
+            await client.stop_notify(FFE2_NOTIFY)
+
+            print("\n--- Sequence Complete ---")
+            print("\nIf the arm didn't move during action groups, the robot may")
+            print("not have pre-programmed arm sequences. Use USB serial for")
+            print("direct servo control: ate robot test mechdog --port <port>")
+
+            return True
+
+    except Exception as e:
+        print(f"Error: {e}")
+        return False
+
+
+# CLI Integration
+def register_cli_commands(cli):
+    """Register BLE capture commands with the CLI."""
+    import click
+
+    @cli.group()
+    def ble():
+        """BLE protocol capture and analysis tools."""
+        pass
+
+    @ble.command("capture")
+    @click.option("--platform", "-p", type=click.Choice(["ios", "android", "auto"]),
+                  default="auto", help="Mobile platform")
+    @click.option("--output", "-o", default="capture.pklg", help="Output file path")
+    def ble_capture(platform: str, output: str):
+        """Capture BLE traffic from phone app for protocol analysis."""
+        if platform == "auto":
+            # Try to detect
+            ios_ok, _ = check_ios_device()
+            android_ok, _ = check_android_device()
+
+            if ios_ok:
+                platform = "ios"
+            elif android_ok:
+                platform = "android"
+            else:
+                print("No mobile device detected.")
+                print("Connect your iPhone or Android phone via USB.")
+                return
+
+        if platform == "ios":
+            success = capture_ios_interactive(output)
+        else:
+            success = capture_android_interactive(output)
+
+        if success:
+            print()
+            print(f"Next step: Analyze the capture with:")
+            print(f"  ate ble analyze {output}")
+
+    @ble.command("analyze")
+    @click.argument("capture_file")
+    @click.option("--generate", "-g", is_flag=True, help="Generate Python replay code")
+    @click.option("--output", "-o", help="Output file for generated code")
+    def ble_analyze(capture_file: str, generate: bool, output: str):
+        """Analyze a BLE capture file to decode the protocol."""
+        analysis = analyze_capture(capture_file)
+
+        if not analysis:
+            return
+
+        print(analysis.summary())
+
+        if generate or output:
+            code = analysis.generate_python_code()
+
+            if output:
+                with open(output, "w") as f:
+                    f.write(code)
+                print(f"\nGenerated code saved to: {output}")
+            else:
+                print("\n" + "=" * 60)
+                print("GENERATED PYTHON CODE")
+                print("=" * 60)
+                print(code)
+
+    @ble.command("inspect")
+    @click.argument("address")
+    def ble_inspect(address: str):
+        """Inspect a BLE device's characteristics and capabilities."""
+        inspect_ble_device(address)
+
+    return ble
+
+
+if __name__ == "__main__":
+    # Quick test
+    import sys
+
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "analyze" and len(sys.argv) > 2:
+            analysis = analyze_capture(sys.argv[2])
+            if analysis:
+                print(analysis.summary())
+                print("\n" + analysis.generate_python_code())
+        elif sys.argv[1] == "inspect" and len(sys.argv) > 2:
+            inspect_ble_device(sys.argv[2])
+        elif sys.argv[1] == "capture":
+            platform = sys.argv[2] if len(sys.argv) > 2 else "ios"
+            output = sys.argv[3] if len(sys.argv) > 3 else "capture.pklg"
+            if platform == "ios":
+                capture_ios_interactive(output)
+            else:
+                capture_android_interactive(output)
+    else:
+        print("Usage:")
+        print("  python ble_capture.py capture [ios|android] [output.pklg]")
+        print("  python ble_capture.py analyze <capture_file>")
+        print("  python ble_capture.py inspect <device_address>")