Android ADB

Using Helper Scripts vs. Raw ADB

Use the scripts in scripts/ as the primary interface for device workflows. References to scripts/... in this skill are relative to this skill directory. They encapsulate solutions to common Android and Wear OS platform quirks:

• Automatic circular display masking and density scaling for Wear OS screenshots
• Device wake-up and keyguard dismissal prior to capture
• Clipboard integration on macOS
• Sensible default filenames and robust error handling

When to use raw adb: For general diagnostic inspection not covered by these scripts (e.g. adb logcat, adb shell pm list), or when building custom pipelines, standard adb commands are appropriate. If a helper script fails or lacks a specific flag you need, inspect its source in scripts/ to understand the underlying dumpsys or input sequence and adapt it.

Quick Start

When multiple devices are connected, pass -s SERIAL or --serial SERIAL before other arguments to any skill script except adb-screenrecord. The flag overrides ANDROID_SERIAL; the environment variable remains available for persistent or inherited device selection.

Highest-Value Commands

• Screenshot (auto-masks circular Wear OS displays): scripts/adb-screenshot

• Wear OS Tile Debugging Workflow: scripts/adb-tile-add com.example/.MyTileService -> output gives INDEX scripts/adb-tile-switch INDEX

• Inspect Wear OS Data Layer: adb exec-out dumpsys activity service WearableService

• Package Information: scripts/packagename tiles PACKAGE_NAME scripts/packagename services PACKAGE_NAME

• Device Info: scripts/adb-device-properties

• Discover Activities: scripts/adb-activities (find launcher, TV, settings activities)

Script Index

See references/command-index.md for detailed usage.

Device Basics

• scripts/adb-device-properties: Show key device properties (model, manufacturer, API level, display size, etc.).
• scripts/adb-log: Write a message to the system log.

For simple one-shot operations (listing device serials, waking or sleeping the device, filtering logcat by tag, sending VIEW intents, toggling "Show touches"), use raw adb commands. See references/command-index.md for the exact invocations, including non-obvious flags.

Media Capture

• scripts/adb-screenshot: Take a screenshot. Always use this instead of raw adb shell screencap. Features: auto-detects square Wear OS displays and applies circular mask, wakes device before capture, copies to macOS clipboard, generates timestamped filenames by default.
• scripts/adb-screenrecord: Record the screen to a file. Automatically detects devices that require raw frame streaming (e.g., Samsung Wear OS watches) and uses ffmpeg for capture, while defaulting to scrcpy for standard devices.

Tile Management (Wear OS)

• scripts/adb-tile-add: Add a tile component for debugging.
• scripts/adb-tile-switch: Switch the active tile.
• scripts/adb-tile-remove: Remove a tile.
• scripts/adb-tiles: List available tiles and indicate which are in the carousel.
• scripts/adb-watchface-set: Set the current watch face.

[!NOTE] Tile Indexing (Index=[0]): When adding a new tile using scripts/adb-tile-add, the output often indicates Index=[0]. This means the tile was added to the first position in the carousel, pushing existing tiles down. It does not mean it has overwritten previous tiles.

Verifying Installed Tiles: Use scripts/adb-tiles to list all available tiles and see which ones are currently in the carousel. The output uses prefixes like UTWC where C indicates it is in the carousel.

Activity Discovery

• scripts/adb-activities: List activities tagged by category (Launcher, Home, TV/Leanback, Settings). Use --launcher-only, --tv-only, --settings-only to filter. Add --all to include system apps.
• scripts/adb-uihierarchy: Dump the UI hierarchy to an XML file.
• scripts/adb-currentfocus: Display the focused package, activity, or detected UI toolkit (--toolkit, --details, --json).

Package Operations

• scripts/packagename: Comprehensive package tool (uninstall, launch, stop, clear-cache, logcat, jobscheduler).
• scripts/adb-packages: List installed packages.

System & Dumpsys

• scripts/adb-battery-stats: Display battery-related information and settings.

Display & Demo Mode

• scripts/adb-demo: Toggle Android demo mode (on / off): clean status bar, fixed clock, show touches, long screen timeout.
• scripts/adb-fontscale: Get or set the system font scale (get / set default|large|NUMBER).
• scripts/adb-theme: Get or set system theme customization (e.g., set to 'lemongrass'). Requires Wear OS 6+ (API 36+).
• scripts/adb-settings-theme: Open system theme settings (requires root/debuggable build).

Safety Notes

• Debug Broadcasts: Tile management relies on Wear OS debug broadcasts (com.google.android.wearable.app.DEBUG_SURFACE) which may not work on production builds without developer options or specific system images.
• USB Debugging: Requires adb authorization.
• Destructive Actions: Scripts like adb-tile-remove or packagename uninstall modify device state.

Reference Material

• Command Reference: Detailed usage and arguments for all scripts. See references/command-index.md.
• Bug Report Capture: How to record markers, logcat, and screen captures for bug reports. See references/bug-report-capture.md.
• Troubleshooting: Solutions for connection issues, missing dependencies, and Wear OS quirks. See references/troubleshooting.md.