TapDucky - Android USB HID Keystroke Injector

Open-source DuckyScript runner for rooted Android with USB Gadget (ConfigFS) support
TapDucky lets you create, customize, schedule, and run DuckyScript on Android by emulating a USB keyboard, mouse, or composite HID device for authorized testing and automation. It includes payload parameterization, multiple scheduler triggers, execution logs, and a GitHub-backed payload library with automatic DuckyScript validation and optional Digispark .ino conversion.

Overview

• USB HID gadget profiles (no external USB dongle required on supported/rooted devices):
  • Keyboard, Mouse, and Composite profiles with configurable VID/PID, manufacturer/product strings, and power draw.
• DuckyScript pipeline:
  • Live validation with human‑readable issues/warnings, placeholder parameters, delay multiplier, and optional jitter for human‑like timing.
• Payload management:
  • Create/edit payloads with name/description/tags/parameters, quick share/export, and built‑in templates/wizard.
• GitHub Payload Store:
  • Add sources, browse repositories, preview files with validation, import supported scripts; auto‑detects DuckyScript and converts Digispark .ino sketches when possible.
• Scheduler:
  • One‑time at date/time, on App cold start, on App foreground, or when HID session is armed (device_connected), with optional daily time window.
• Execution & Logs:
  • Tabbed execute view, parameter prompts, run/cancel, execution history, and structured logs with export/clear and level filter.
• Device diagnostics:
  • Snapshot of device, kernel/gadget status, UDC info, keyboard layouts; copy‑to‑clipboard; emulator detection note.

Note: A rooted device with Linux USB gadget (ConfigFS) support is required. Use a physical device as emulators cannot validate HID behavior.

Features

• Payload Editor & Parameters

  • Create payloads with name/description/tags.
  • Add typed parameters with default values, required flags, and per‑execution overrides.
  • Built‑in DuckyScript validator with line/issue mapping and command counts.
  • Share a single payload or export a pack.

• GitHub Payload Store

  • Manage multiple GitHub sources (user/repo/branch/path).
  • Browse directories and preview files with format detection (DuckyScript, TapDucky JSON, Digispark script (.ino) converted).
  • Import validated scripts directly into your library; failed validations show reasoned previews.

• Execute & Test

  • Validate before run; prompt for parameter values; run or cancel with execution IDs.
  • Quick HID tests: keyboard key press, mouse move, and Ctrl+Alt+Del.
  • Engine-based runtime estimate (matches actual timing model).
  • Wakelock control to keep sessions active during execution.

• Scheduler & Triggers

  • Triggers: one_time, app_cold_start, app_foreground, device_connected (session armed).
  • Optional daily time window (HH:MM → HH:MM), including wrap‑around at midnight.
  • Enable/disable, edit, and delete schedules; last run tracked.
  • Dial shortcut bindings via secret codes (auto‑arm + background execution).
    • Supported codes: ##38250##, ##38251##, ##38252##, ##38253##
    • Binding keys per code: enabled, mode (last executed | selected payload), payload (when mode = selected payload)

• Device & HID Profiles

  • Activate Keyboard, Mouse, or Composite profiles with configurable IDs/strings/power.
  • Keyboard layout selection and code/ID resolution.
  • Status stream shows ACTIVE/IDLE, writer readiness, and host configuration requests.

• Logs & History

  • Logs tab with level filter (all/info/debug/warn/error), export to share, clear all.
  • Execution history details with metadata and share.

User‑facing

• Dashboard with quick status cards, payload/library stats, and scheduler summary.
• Clear empty states and step‑by‑step wizards for first‑time setup/imports.
• Material 3 theming, dynamic light/dark color schemes.

Technical/architectural

• Platform channels (Android):
  • Method Channel: org.kaijinlab.tap_ducky/gadget
    • checkRoot, checkSupport, listUdcs, getStatus, getDiagnostics
    • getKeyboardLayouts, setKeyboardLayout, resolveKeyboardLayoutId, setKeyboardLayoutByCode
    • activateProfile, deactivate, panicStop, retryOpenHidWriters
    • executeDuckyScript(script, delayMultiplier, executionId?), cancelExecution(executionId)
    • Test helpers: testKeyboardKey(label), testMouseMove(dx,dy,wheel,buttons), testCtrlAltDel()
  • Event Channels:
    • org.kaijinlab.tap_ducky/gadget_logs
    • org.kaijinlab.tap_ducky/gadget_status
    • org.kaijinlab.tap_ducky/gadget_exec
• HID Profiles model: keyboard/mouse/composite with VID/PID, strings, serial, power.
• DuckyScript:
  • Parsing to steps; supports DELAY/STRING/keys/raw commands; placeholder resolution; base key delay; jitter.
  • Validator returns issues with severity and line mapping; used across editor/store/execute flows.
  • TRY/CATCH/END_TRY, WAIT_FOR, SLEEP_UNTIL, FUNCTION args, and scoped variables.
  • Unicode fallback modes (warn+skip / skip / ASCII transliteration).
  • Structured exec error codes in the execution stream.
• Scheduling engine:
  • Triggers (cold start, foreground, armed, one‑time), daily time window rules, persistence in SharedPreferences.
• State management: Riverpod 3, go_router navigation, clean repository/services/controllers separation.

DuckyScript / Keystroke Engine

TapDucky includes a full DuckyScript-style engine implemented natively on Android (Kotlin) with expression evaluation and structured control flow. It supports keyboard, mouse/pointer, timing, variables/defines, functions, and simple randomness utilities.