GhostChip ESP32-S3 - Technical Operations Manual

🔌 Physical Power-Up Sequence

The GhostChip ESP32-S3 Security Toolkit is fully pre-flashed out of the box. You do not need to install local tools, command lines, or compilers to initialize the system hardware. Connect standard 5V USB power to boot the module instantly.

Quick Start Video Guide

Watch on YouTube

1

Verify SD Card Mounting

Ensure that a formatted MicroSD card (supports up to 32GB) is inserted fully into the physical slot. (See the MicroSD limits page for partitioning details).

2

Plug in USB-A Connector

Plug the module directly into a computer USB-A socket, a portable power bank, or standard 5V USB charging bricks. Avoid using quick charge ports that fluctuate voltages.

3

Verify Wireless AP Broadcast

Once powered, the internal ESP32-S3 boots up within 3 seconds. Scan for available wireless networks on your mobile phone or PC, select the network named Ghostchip, and enter the password ghostchip@14.

ℹ️ Initial Boot Cycle Hardware boot enumeration takes exactly 3 seconds. After this timing threshold passes, the local Wi-Fi radio wakes up and broadcasts its default Access Point gateway.

🔴 BOOT Button — Hardware Kill Switch Pressing the physical BOOT button on the GhostChip board at any time during operation instantly aborts any running DuckyScript payload and stops any active deauth test. The NeoPixel flashes red briefly to confirm. This is your emergency hardware override — no app connection needed.

💾 MicroSD Card Formatting & Limits

The ESP32-S3 utilizes an SDIO hardware interfacing framework. This places rigid architectural specifications on partition structures and card sizes. GPT configurations or modern partition models are not supported.

⚠️ Formatting Parameters & Storage Restrictions Mounting a card outside these boundaries will cause the local file manager and templates to display mount failure alerts.

Maximum Storage Support: 32GB. Larger card volumes (64GB, 128GB, etc.) formatted using exFAT are not compatible.
Recommended Stable Capacity: Top-tier 16GB or 32GB MicroSD card modules.
Partition Map Type: MBR (Master Boot Record) partition style strictly.
Filesystem Formatting: FAT32 cluster formatting.
Optimal Cluster Allocation Size: 32KB (32,768 bytes). This parameter guarantees maximum stability during rapid, high-frequency exfiltration logging.

Formatting Quick Guide:

Target Host OS	Formatting Utility Tool	Required Settings
Windows 10/11	Standard Disk Management or Rufus	File System: FAT32 \| Cluster Size: 32 Kilobytes \| MBR Style
macOS (Apple Sil.)	Disk Utility Console (Terminal `diskutil`)	Format Scheme: MS-DOS (FAT) \| Scheme: Master Boot Record
Linux (Ubuntu/Arch)	GParted or CLI `mkfs.vfat`	`mkfs.vfat -F 32 -s 64 /dev/sdX1` (64 sectors per cluster = 32KB)

🔍 Hardware Specs & Architecture

The GhostChip unites high-performance RF computing with physical keyboard HID injection circuitry in a micro form-factor.

Dual-Core 240MHz MCU

ESP32-S3 core engine equipped with vector extension instructions for high-speed cryptography, neural prompt structures, and passive WiFi monitoring.

USB-OTG HID Controller

Direct native USB-HID bus interfaces. Simulates standard USB Composite HID device — Keyboard, Mouse, and Gamepad simultaneously — bypassing OS driver warning dialogs. USB Product: GhostChip Pro, PID: 0x8104.

WS2812B NeoPixel RGB

Programmable 24-bit color status indicator. Fully controllable via API commands to allow complete stealth modes or visual payload alerts.

SDIO SD Interface

Direct low-latency data lines running to the MicroSD slot, facilitating instant reads/writes of exfiltrated data blocks.

NVS Persistent Settings

API key, NeoPixel color/brightness/on-off state, and Typing Delay are stored in NVS (Non-Volatile Storage) flash and survive power cycles and reboots automatically — no reconfiguration needed after powering off.

Technical Electrical Tolerances:

Operating voltage requirements: 5V DC via USB connector. Idle power draw ranges around 90mA, whereas active RF scanning or high-speed typing bursts pull up to 310mA peak current. Avoid routing through unpowered USB splitter units.

⚡ USB Firmware Flashing & Recovery Guide

Reload your GhostChip with the official core binaries, re-partition the flash layout, or recover a bricked/bootlooping device over physical USB Web Serial.

💡 Web Serial Advantage: Using the Web Serial protocol, you can program your ESP32-S3 chip directly from your browser without installing the Arduino IDE, Python, drivers, or standard command-line flashing suites.

📥 Step-by-Step Flashing Procedure

1

Launch the Flasher Interface

Open the native Web Serial Flasher Utility inside a Chromium-based browser (Chrome, Edge, or Opera).

2

Connect USB Data Cable

Plug one end of a standard USB-C data cable into the GhostChip module and connect the other end directly to a computer's high-speed USB port.

3

Establish Serial Connection

Select your desired Baud Rate speed (Default 921600 is recommended for low-latency flashing). Click Connect Device and choose the appropriate serial port interface (e.g., ESP32-S3 USB Node or COM3) from the pop-up browser interface.

4

Load Firmware Segments

Choose your binary source type:

Auto-Flash (Preset Firmware): Click Fetch Preset Firmware Files to automatically download the official factory binaries from the remote repository.
Manual Files (Custom Upload): Upload custom-compiled binaries into their dedicated memory offsets:
- 0x0 -> GhostChip.ino.bootloader.bin (Boot Sequence)
- 0x8000 -> GhostChip.ino.partitions.bin (Partition Layout)
- 0x10000 -> GhostChip.ino-4.bin (Core Application code)

5

Trigger Flashing Process

Select Erase all flash partitions before writing if performing a clean install to wipe active settings. Click Start Flashing Firmware and watch the real-time progress indicators. Once complete, unplug and reconnect the USB port to power cycle and boot the new code!

⚠️ Hard Recovery Mode (ROM Bootloader)

If your device fails to sync, is bootlooping continuously, or is completely bricked, you can manually override the active program execution and force the ESP32-S3 processor to initialize its internal read-only ROM bootloader:

1. Press and hold down the physical, miniature BOOT button on the GhostChip board.

2. While keeping the BOOT button pressed, insert the USB cable into your computer's USB port to power up the module.

3. Release the BOOT button. The ESP32-S3's hardware core will now sit in idle ROM Bootloader mode waiting for commands.

4. Click Connect Device inside the Flasher page to establish a secure link and reload your firmware.

📶 Wi-Fi Access Point Credentials

By default, GhostChip initiates its own wireless network immediately upon boot. Connect to this network on any mobile phone, laptop, or tablet to access the controls.

Connection Parameter	Assigned Value	Notes / Explanations
SSID (AP Name)	`Ghostchip`	Broadcasted in the 2.4GHz Wi-Fi spectrum.
WPA2 Password	`ghostchip@14`	Secured using WPA2-PSK protocol encryption.
Local Gateway IP	`192.168.4.1`	Hardcoded network gateway of the internal DHCP server.
mDNS Domain Address	`http://ghostchip.local`	Multicast DNS routing enabled for convenient browser access.
DHCP Lease Pool	`192.168.4.2 to 192.168.4.10`	Dynamic IP distribution leases for connected control hosts.

ℹ️ Connection Step: Turn on your smartphone's Wi-Fi, select the SSID Ghostchip, type ghostchip@14, and wait for the connection icon. Some operating systems may show a warning saying "No Internet Access" — this is normal, tap Keep Connected to proceed.

⚡ Control Modes: Direct Web vs PWA App

GhostChip supports two distinct modes of execution to match your operational audit environment.

Direct Web Server Portal

Pulls web assets directly from the ESP32 SPIFFS partition blocks. Requires no internet or external server hosting.

Connect to Ghostchip Wi-Fi AP.
Launch your device's web browser.
Navigate to: http://ghostchip.local (or `http://192.168.4.1`).

Progressive Web App (PWA)

Installs on your mobile screen as a native application with offline service worker caching and fluid UI rendering.

Bridge your phone and ESP32 to the same local internet router.
Visit cloud portal: Hosted PWA App Link
Click your browser drawer -> Add to Home Screen.

💡 Why use the PWA? The installed PWA runs inside a standalone app frame, removing browser navigation bars for optimal screen space. It also provides automatic updates and offline caching.

🤖 Local Wi-Fi Bridging Setup for Groq AI Features

The Groq AI Llama-3 compiler and AI voice assistant require active internet routing to communicate with cloud APIs. Since the GhostChip's isolated Access Point (`Ghostchip`) does not have an internet path, you must bridge the devices onto your own local Wi-Fi router.

⚠️ CRITICAL BRIDGE PROCEDURE (Must Follow Exactly) To enable the AI capabilities, both the ESP32-S3 module and your control mobile phone/PC must be connected to the same internet-enabled local Wi-Fi access point (your home/office router):

1

Initial AP Connection

Connect your mobile phone to the default Ghostchip Wi-Fi AP and open the local dashboard at `http://ghostchip.local` in your browser.

2

Setup WiFi Station on GhostChip

Navigate to the Settings menu page. Find the WiFi Station Setup card, click Scan Networks, select your home/office internet Wi-Fi network SSID, input its security password, and click Connect.

3

Switch Phone to the Same Router

Disconnect your mobile phone from the isolated `Ghostchip` AP. Connect your phone to your own local home/office internet router (the exact same network you selected for the GhostChip in Step 2).

4

Access Bridge Dashboard

Open your mobile web browser and enter: http://ghostchip.local, or simply launch your installed Hosted PWA App. Since mDNS resolution broadcasts seamlessly across your local bridged router subnet, both devices talk locally with no IP configurations needed, while having full cloud access for Llama-3 operations!

📶 Groq API Key Setup Criteria To configure your Groq key, ensure you have signed up for a free developer key at the official Groq Console. Paste this key (starts with `gsk_`) under the Settings panel inside your bridge dashboard.

🔑 Get Free Groq API Key

📂 SD Auto-Connect — Automatic WiFi Bridge on Boot NEW

GhostChip can automatically join your local WiFi router on every boot without any manual Settings step — by reading stored credentials directly from the MicroSD card.

✅ How It Works: On boot, GhostChip scans visible WiFi networks. For each network found, it checks if a file named /wificonnect/<SSID>.txt exists on the SD card. If found, it reads the password and connects automatically in AP+STA mode — enabling AI features without any manual step.

Setup Instructions

1

Create the wificonnect Directory

On your FAT32 MicroSD card, create a folder named exactly wificonnect in the SD root.

2

Create a Credential File

Inside /wificonnect/, create a .txt file named after your WiFi SSID. E.g. for network HomeRouter, create /wificonnect/HomeRouter.txt.

3

Write the Password

Open the file and type the WiFi password as plain text — no quotes, no extra newlines.

YourWiFiPassword123

4

Boot GhostChip

Insert SD and power up. GhostChip scans, finds your SSID, reads the credential file, and auto-connects in AP+STA mode. Multiple networks are supported — first match wins.

⚠️ Security Note: Passwords are stored as plain text on the SD card. Keep the card physically secure.

⚡ DuckyScript Language Reference & Simulator

DuckyScript is the native programming language of the GhostChip HID injector. It converts human-readable key commands into raw USB keyboard descriptors. Below is an exhaustive language catalog and a step-by-step guide on how to build, test, and deploy custom scripts.

1. Complete Syntax Keyword Reference

GhostChip supports the entire classic DuckyScript keyword index along with custom timing configurations:

Keyword Command	Functional Description	Code Syntax Example
`REM`	Remark/Comment block. Lines starting with `REM` are ignored by the parser. Used to document code steps.	`REM This is a comment`
`DELAY`	Pauses execution for a specified duration in milliseconds (1000ms = 1s). Highly critical for synchronizing actions.	`DELAY 1000`
`DEFAULTDELAY`	Applies a standard delay pause (in ms) after every line in the script, pacing inputs safely.	`DEFAULTDELAY 150`
`STRING`	Simulates rapid serial typing of the text string following the keyword. Supports symbols, numbers, and capital letters.	`STRING echo Hello World!`
`STRINGLN` NEW	Types the text following the keyword then immediately presses ENTER. Shorthand for `STRING` + `ENTER` on a single line.	`STRINGLN ipconfig /all`
`ENTER`	Simulates pressing the Standard Enter/Return key. Often used to submit entered command strings.	`ENTER`
`ESCAPE` / `ESC`	Presses the Escape key. Useful for dismissing active system popups or exiting full-screen applications.	`ESCAPE`
`TAB`	Presses the Tab key. Critical for navigating field focus when command-line consoles are unavailable.	`TAB`
`SPACE`	Presses the Spacebar.	`SPACE`
`BACKSPACE`	Simulates hitting the Backspace key to delete a preceding character.	`BACKSPACE`
`DELETE`	Simulates hitting the Forward Delete key.	`DELETE`
`INSERT`	Toggles the standard Insert cursor mode.	`INSERT`
`PAGEUP` / `PAGEDOWN`	Scrolls page text blocks up or down.	`PAGEUP`
`HOME` / `END`	Jumps the editing cursor to the absolute start or end of the current line.	`HOME`

2. Arrow & Directional Controls

Directional arrow keys are indispensable when navigating administrative menus, custom windows, or text lists:

Keyword Option	Alternative Syntax	Operation details
`UPARROW`	`UP`	Simulates pressing the Up Arrow.
`DOWNARROW`	`DOWN`	Simulates pressing the Down Arrow.
`LEFTARROW`	`LEFT`	Simulates pressing the Left Arrow.
`RIGHTARROW`	`RIGHT`	Simulates pressing the Right Arrow.

3. Keyboard Lock Toggles

These commands simulate toggling hardware lock configurations on host machines:

CAPSLOCK: Toggles Caps Lock (all subsequent alphabetic typed inputs will shift case states).
NUMLOCK: Toggles the Numeric Keypad lock state.
SCROLLLOCK: Toggles Scroll Lock.

4. System Modifiers & Complex Combos

Modifiers are keys held down in combination with other characters to trigger special operating system shortcuts. You can define modifiers on their own line with a trailing key:

Modifier Key	Alternative Keywords	Common Combo Examples
GUI	`WINDOWS`, `COMMAND`, `META`	`GUI r` (Opens Run menu on Windows) `GUI SPACE` (Opens Spotlight search on macOS)
ALT	`ALT`	`ALT F4` (Closes active application) `ALT SPACE` (Opens window configurations)
CTRL	`CONTROL`	`CTRL ESCAPE` (Opens Windows Start Menu) `CTRL c` (Copy shortcut)
SHIFT	`SHIFT`	`SHIFT ENTER` (Newline indicator) `SHIFT INSERT` (Paste combo on classic terminals)

🔥 Triple Modifier Key Combinations: You can chain multiple modifiers sequentially on a single line to simulate complex administrative key sequences:

              CTRL ALT DELETE (Launches security options screen)

              CTRL SHIFT ESCAPE (Launches Windows Task Manager directly)

              GUI SHIFT ENTER (Launches administrative terminals on pre-configured layouts)

5a. Function Keys (F1–F12) NEW

Full function key support from F1 through F12. Use alone or combined with modifiers:

F1  F2  F3  F4  F5  F6  F7  F8  F9  F10  F11  F12

Examples:
GUI F4        (Close active window / tab on Windows)
CTRL F5       (Hard-refresh browser)
ALT F4        (Quit active application)
CTRL SHIFT F5 (Force reload)

5b. Special System Keys NEW

Keyword	Aliases	Description
`PRINTSCREEN`	—	Takes a screenshot on the host machine (copies to clipboard on Windows).
`PAUSE`	`BREAK`	Presses the Pause/Break key. Useful for interrupting batch scripts or opening System Properties (`GUI PAUSE`).
`MENU`	`APP`	Presses the Application/Menu key — simulates a right-click context menu on the focused element.

5c. The Repeater Block Command

To avoid copy-pasting the same instruction multiple times, the REPEAT keyword duplicates the exact action from the immediately preceding line:

            DOWNARROW

            REPEAT 4 (Presses the Down Arrow 4 more times, leading to 5 total presses)

🏗️ How to Build & Deploy Your DuckyScript Payload

Designing an effective BadUSB payload requires a structured methodology to ensure reliable execution across different target host machines. Follow these structured operational steps:

1

Determine Target OS Shortcuts

Verify the operating system of the target computer (Windows, macOS, or Linux). Identify the correct shortcut sequence to open a command terminal. For example, use GUI r followed by cmd on Windows, or GUI SPACE followed by terminal on macOS.

2

Establish initial Driver Delay

Always start your payloads with an initial delay buffer (e.g. DELAY 3000). When the hardware is plugged in, the victim operating system requires exactly 2 to 3 seconds to scan, load, and configure standard USB keyboard HID drivers. Typing before this window finishes results in missed keystrokes.

3

Configure typing Pace (Pacing Delay)

Add a DEFAULTDELAY 150 statement directly below your initial setup delay. This instructs the injector core to pause for 150ms between every line, giving slower computers time to parse incoming USB key descriptors without losing keystroke data.

4

Compose Payloads: Code vs Visual vs AI

Choose your preferred authoring method:

Manual Coding: Write clean, standard DuckyScript commands directly into the dynamic text editor panel.
Visual Builder: Drag and drop modular blocks (DELAY, STRING, ENTER) using the Script Builder Tool in the utilities drawer.
AI Compiler: Tell the Groq AI Assistant what you want in plain English (e.g., "Write a Windows script to query IP configurations") to let it compile standard DuckyScript code instantly.

5

Verify in the Sandbox Simulator

Before executing the script on a physical machine, toggle the SIM (Simulator) panel switch. This parses your commands line-by-line in a sandboxed browser terminal, displaying exactly what will be typed, key pause delays, and loop structures. This allows you to verify script logic safely.

6

Save to MicroSD & Run

Click Save in the File Manager tool to write the completed script directly into the `/payloads/` directory on the FAT32 MicroSD card. Finally, select the target payload in your file manager explorer and click the Run (Play) button to physically inject the keystrokes.

⚠️ Keyboard Layout Profiles Warning: Standard BadUSB key injections are mapped to standard US English keyboard layout configurations. If your target computer is set to a different regional layout (e.g., AZERTY, QWERTZ, UK English), some typed characters (like slashes, backslashes, colon, or quotes) will map incorrectly. Ensure the host is set to a US layout or design payloads to handle character deviations accordingly.

⚙️ Typing Speed Control NEW

The firmware caps the per-keystroke delay at 40ms maximum for reliable injection. The global inter-key gap is configurable in Settings → Typing Delay and saved persistently to NVS flash across reboots.

Script Command	Recommended Value	Purpose
`DELAY 3000` (first line)	3000ms	Wait for target OS to enumerate USB HID driver after plug-in.
`DEFAULTDELAY 150`	150ms	Add inter-line pause for slower target systems.
Settings → Typing Delay	0–40ms	Global inter-keystroke gap — saved to NVS flash, persists across reboots.

🚀 AutoRun on Boot NEW

GhostChip can automatically execute a DuckyScript payload 3 seconds after boot with zero user interaction — ideal for fully autonomous drop deployments.

⚠️ Authorized Use Only: AutoRun executes keystrokes on whatever computer the device is plugged into. Only use this on systems you own or have explicit written authorization to test.

How to Set Up AutoRun via SD Card

1

Create the autorun Directory

On your FAT32 MicroSD card, create a folder named autorun in the root directory.

2

Place Your Script

Save your DuckyScript payload as /autorun/autorun.txt. The filename must be exactly autorun.txt.

3

Boot GhostChip

Plug the device into the target computer. After the built-in 3 second delay, the script executes automatically.

Set AutoRun from the Dashboard

You can also configure the autorun script directly from the app: In the DuckyScript editor, click the red AUTORUN button in the toolbar. This saves the current editor script to /autorun/autorun.txt on the SD card automatically — no manual file copying needed.

💡 Best Practice: Always start your autorun script with DELAY 3000 to give the target OS time to load USB HID drivers before any keystrokes are sent.

🔴 Emergency Stop: Press the physical BOOT button on the GhostChip board at any time to instantly abort the running autorun script. The NeoPixel will flash red briefly to confirm the kill.

📡 RF Sniffer Stack (WiFi, BLE, & Deauth Warnings)

The ESP32-S3 is equipped with a passive radio monitor framework, allowing diagnostic site evaluations and wireless audits.

WiFi Diagnostic Scanner

Sweeps channels 1-14 to discover local access points. Gathers detailed infrastructure metadata:

Network SSID name and hardware BSSID.
Signal RSSI value (measured in dBm).
Encryption protocols (WEP, WPA2, WPA3).

BLE Proximity Sniffer

Passively parses the 2.4GHz spectrum for Bluetooth Low Energy advertising packets. Monitors physical beacons:

Broadcast beacon names and UUID indicators.
GATT service profiles.
RSSI distance tracking.

802.11 Deauthentication Monitor

Legacy wireless protocols transmit management frames (such as deauth or disassociation packets) without cryptographic signing. The sniffer scans targeted radio channels and logs deauth attacks instantly:

            [ALERT] 802.11 Deauth frame caught on CH 11 | Source: AA:BB:CC:11:22:33 -> Target: DD:EE:FF:44:55:66 | Packets/sec: 84
          

This serves as an excellent security alert indicator. When active Wi-Fi jamming or client disruption events occur, warning logs are generated inside the live log console pane and trigger high-visibility alerts on your browser web console instantly.

🤖 Groq AI Engine — Qwen 3.8 27B & Voice Controls

The GhostChip features real-time neural payload compilation, translating plain English prompts into standard executable DuckyScript payloads instantly.

1

Groq Llama-3 API Compilation

Input descriptive prompts (e.g. "Open command prompt on Windows, query IP details, and output results"). The neural compiler processes the prompt and builds formatted DuckyScript code blocks. Select targeted operating systems (Windows, macOS, Linux) to optimize modifier sequences automatically.

2

Voice Recognition Interface

Tap the Microphone icon to initiate active voice controls. The dashboard leverages the browser's Web Speech API to capture speech queries, translate your intent, and compile scripts hands-free.

3

EEPROM Credentials Isolation

Your custom Groq API key is written directly to physical EEPROM sectors on the ESP32-S3. Keys remain securely isolated on the device hardware and are transmitted strictly via HTTPS directly to Groq endpoints, completely safeguarding your developer credentials.

📶 Setup Check & Groq API Console To successfully execute Llama-3 compiler logic, verify that you have registered a developer account and copied your key from the official Groq Console. Make sure both the ESP32 and your control phone are bridged onto the same Wi-Fi router with active internet connectivity (See the AI Network Setup page).

🔑 Get Free Groq API Key

GhostESP Third-Party Firmware & Command Center

Unleash the full capability of the GhostESP firmware—a state-of-the-art, third-party operational suite custom-tailored for ESP32-S3 architectures. This specialized toolkit transforms your device into an advanced wireless audit station, providing precision diagnostics for Wi-Fi networks, active client station sniffing, real-time Bluetooth Low Energy (BLE) tracking, and custom RF transmission analysis.

Wi-Fi Diagnostics

Scan wireless spectrums, identify channels, resolve AP conflicts, and map physical beacons.

Client Sniffing

Track client device associations, capture active probe requests, and monitor network usage.

BLE & Beacon Audits

Sniff Bluetooth advertisements, discover nearby Flipper Zero signals, and track AirTags.

🙏 Credits & Licensing:
GhostESP is an independent open-source toolkit developed by the GhostESP Core Team. All copyrights, branding, and binary ownership belong entirely to their respective authors. You can find source files, developer notes, and community updates on the official website:

Official GhostESP Website (ghostesp.net)

🎮 Web Command Center Dashboard

The toolkit includes a high-fidelity GhostESP Command Center Dashboard that connects directly to the flashed hardware over physical Web Serial, providing an interactive mobile-ready dashboard for field audits.

Open GhostESP Command Center

⚡ How to Use the Command Center

1

Flash the GhostESP Firmware

Go to the Web Flasher, click on the Third-Party (GhostESP) tab, select the GhostESP Firmware package, connect your ESP32-S3, and click flash. The flash process automatically partitions and uploads the segment binaries.

2

Initialize Web Serial Connection

Open the Command Center dashboard page (ghostesp.html). Select 115200 Baud (standard connection speed for the GhostESP CLI), click the Connect button, and select your ESP32-S3 device port from the browser prompt. You can also select DEMO SIMULATOR to explore the dashboard offline.

3

Run Scans and Audits Visually

Use the panel tabs at the bottom of the interface to trigger device routines: scan local access points in the WiFi panel, sniff Apple AirTags or Flipper Zero packets in the BLE panel, or launch deauth campaigns in the Threat Console.

4

Utilize the Advanced CLI Drawer

Click the Advanced CLI drawer at the bottom of the screen to open a raw terminal emulator interface. You can input command strings manually, view logs, and monitor serial output directly.

💻 Core CLI Command Reference

When interacting with the GhostESP CLI (either via a terminal program or the Command Center drawer), use the following basic commands:

Command	Arguments / Options	Functional Description
`scanap`	None	Scans for nearby Wi-Fi Access Points (APs) and prints BSSID, SSID, RSSI, channel, and vendor info.
`stopscan`	None	Stops any active Wi-Fi AP or station sniffing scans.
`select`	`-a [index]` `-s [index]`	Selects a target AP index (`-a`) or a client station index (`-s`) to target for subsequent actions (like deauth attacks).
`scansta`	None	Sniffs and maps active client stations connected to the currently selected Wi-Fi Access Point.
`blescan`	`-f` (Flipper) `-a` (AirTag) `-s` (Stop)	Initiates BLE sniffing to scan for Flipper Zero devices (`-f`), Apple AirTag locator beacons (`-a`), or stops the scan (`-s`).
`attack`	`-d` (Deauth)	Starts a deauthentication packet injection campaign (`-d`) targeting the selected Access Point or client device.
`stop`	`deauth` `spam`	Stops the active deauthentication campaign (`deauth`) or ceases BLE beacon/Wi-Fi SSID advertising spam (`spam`).

🖱 Tool: Remote Mouse NEW

Control the target computer's mouse cursor remotely from your phone via USB HID mouse emulation. No drivers needed on the host — all commands are native HID reports.

Touchpad / Trackpad

Swipe on the virtual touchpad area to move the cursor. Relative movement values are sent over HID at each touch event.

Click Buttons

Left click, right click, and middle click buttons with hold support for drag operations.

Scroll Wheel

Scroll up and down by sending USB scroll wheel HID events. Works in any application on any OS.

ℹ️ HID Composite Device: GhostChip presents as a composite USB device — keyboard, mouse, and gamepad are all active simultaneously. No mode switching is needed.

Advanced Gestures & Usage

The Remote Mouse tool supports multi-touch simulation natively. When using a mobile device, tapping on the trackpad area will immediately send a left-click event. For drag-and-drop operations, use the dedicated click-and-hold buttons below the trackpad.

// Internal HID Report Format (For reference):
// Byte 0: Buttons (Bit 0: Left, Bit 1: Right, Bit 2: Middle)
// Byte 1: X displacement (-127 to +127)
// Byte 2: Y displacement (-127 to +127)
// Byte 3: Scroll wheel (-127 to +127)
          

Troubleshooting

If the cursor moves erratically, ensure the target OS does not have extreme mouse acceleration enabled, as absolute physical movements from the phone screen are translated into relative HID displacement ticks.

🎮 Tool: Gamepad Controller NEW

A virtual gamepad that sends USB HID gamepad reports to the target computer. Supports dual analog sticks, 32 buttons, hat switch (D-Pad), and 6 axes — recognized by Windows, macOS, and Linux as a standard USB gamepad.

Dual Analog Sticks

X/Y axes for left stick, RX/RY for right stick. Values range from -127 to +127.

32 Buttons + Hat

Full 32-button bitmask and 8-direction hat switch for D-Pad simulation.

Triggers (Z / RZ)

Z and RZ axes for left and right analog trigger simulation.

Supported Input Mapping

Component	Axis/Button ID	Common Usage
Left Stick	X / Y Axes	Movement / Steering
Right Stick	RX / RY Axes	Camera Control / Aiming
Triggers	Z / RZ Axes	Accelerate / Fire
Face Buttons	Buttons 1-4	A, B, X, Y (or Cross, Circle, Square, Triangle)
D-Pad	Hat Switch (8-way)	Menu Navigation

The gamepad acts as a generic USB Joystick. On Windows, it can be tested natively via joy.cpl in the Run menu. Modern browsers support gamepad APIs, making this tool compatible with cloud gaming services (like Xbox Cloud Gaming or GeForce Now) running on the target machine.

🖱 Tool: Mouse Utility NEW

Advanced mouse automation tools including an auto-clicker, mouse jiggler, and precision cursor control — all delivered as native USB HID mouse reports.

Auto Clicker

Configure interval, button (left/right/middle), and click count. Automated clicking at the set rate — useful for form testing and UI automation.

Mouse Jiggler

Moves the cursor by a tiny random delta at a configurable interval to prevent screen lock or screensaver activation on the host.

Precision Move

Send exact relative X/Y movement values for fine-grained cursor positioning.

Automation Scenarios

1

Preventing System Sleep

Enable the Mouse Jiggler with an interval of 5000ms. The system will receive a micro-movement every 5 seconds, completely preventing screen locks during long audits or data extractions without interfering with user input.

2

Form Spamming / Kiosk Bypasses

Use the Auto Clicker set to a 50ms interval. Position the cursor over the target button and activate. GhostChip will inject rapid left-clicks, useful for testing rate limits or clearing dialog boxes.

💡 Pro Tip: The Mouse Utility tools run autonomously on the ESP32-S3's background thread. You can start the Jiggler, then navigate to other tabs in the GhostChip app (like the AI Agent or Scripts) — the jiggler will continue running in the background until explicitly stopped.

🎵 Tool: Media Remote NEW

Control media playback on the target computer using USB HID Consumer Control reports. Works in any OS with any media player — no focus or app switching needed.

Playback Controls

⏯ Play/Pause, ⏮ Previous Track, ⏭ Next Track — sent as standard HID Consumer Control codes.

Volume Controls

🔉 Volume Down, 🔊 Volume Up, 🔇 Mute — controls OS media volume independently from keyboard HID, without affecting keystroke focus.

OS Compatibility & Behavior

Media keys are sent via the specialized USB HID Consumer Control interface, which operates independently from the standard keyboard interface.

Windows: Controls the global media session (Spotify, Chrome, VLC) regardless of which app is focused. The volume overlay will appear natively.
macOS: Maps directly to the physical media keys (F7-F12 equivalents) on Apple keyboards.
Linux: Handled by the desktop environment's media daemon (e.g., MPRIS).

Prank & Distraction Vectors

Media controls are highly effective for distraction during physical engagements. Rapidly toggling Volume Up to 100% and triggering Play can distract a target or force them to lock their workstation and remove headphones, creating a window of opportunity.

🧠 Tool: AI Agent NEW

An autonomous agent powered by the Groq AI engine that plans and executes multi-step device workflows — combining DuckyScript execution, file management, and system queries in one coordinated operation.

Multi-Step Planning

Describe a complex goal (e.g., "Extract WiFi passwords and save to SD"). The agent breaks it into sub-tasks and executes them in sequence.

Tool Integration

The agent can call device APIs (execute HID, read/write SD files, query device info) as part of its autonomous workflow.

Execution Log

Real-time step-by-step log of every action taken — transparent and auditable. Abort at any time with the BOOT button.

⚠️ Autonomous Operation: The AI Agent can execute keystrokes and file operations without step-by-step confirmation. Review the plan before confirming. Use only on authorized systems.

Agent Workflow Breakdown

When given a high-level task, the Groq-powered AI Agent follows a strict ReAct (Reasoning and Acting) loop:

[THOUGHT] Analyzes the user's prompt and the target operating system.
[PLAN] Generates a sequence of HID commands to achieve the first step.
[ACTION] Executes the commands on the target machine via GhostChip.
[OBSERVATION] Reads results if exfiltrated to the SD card, or assumes success based on timing.
[THOUGHT] Determines if the ultimate goal is met, or if more steps are needed.
          

Example Prompts

"Open a hidden PowerShell window and disable Windows Defender real-time protection."
"Extract the saved WiFi passwords and write them to a file named 'wifi.csv' on my desktop."
"Create a reverse shell connecting back to 10.0.0.5 on port 1337."

💻 Tool: Code Typer NEW

Generate code in any programming language using AI, then physically type it character-by-character into any text editor or terminal on the target machine via USB HID. Perfect for deploying scripts without clipboard access.

AI Code Generation

Describe what you need (e.g., "Python reverse shell to 192.168.1.100:4444"). The Groq AI generates the code in the requested language.

USB Type-Out

Click Type on Target to physically type the generated code as keyboard HID input on the connected computer — no clipboard or paste needed.

Speed Control

Adjust typing speed before execution. Use slower speed for terminals that may drop characters on fast machines.

Overcoming the Clipboard Barrier

During physical access, you often cannot simply "paste" complex scripts into a target machine, especially if clipboard syncing is disabled or if you're restricted to a hypervisor console (like Proxmox or ESXi) or an RDP session that blocks clipboard transfer.

The Code Typer solves this by acting as a physical keyboard. It translates raw code into thousands of sequential keystrokes.

Typing Profiles

Speed Setting	Use Case	Reliability
Instant (0ms)	Modern local OS (Windows/Mac)	High — OS buffers handle it
Fast (10ms)	Standard Terminals	High
Medium (25ms)	Remote Desktop (RDP / VNC)	Medium — Prevents dropped frames
Slow (40ms)	Legacy Systems / BIOS	Maximum

✨ Tool: Prompt Enhancer NEW

Takes a rough payload description or a basic DuckyScript snippet and uses the Groq AI engine to enhance it — adding proper timing, stealth improvements, error handling, and cross-platform compatibility.

Script Enhancement

Paste a basic script and click Enhance. The AI rewrites it with proper DELAY values, DEFAULTDELAY pacing, and inline comments.

Stealth Optimization

Request stealth mode — the AI adds window minimization steps, hides terminal windows, and removes visible artifacts from the script.

Prompt Rewriting

Input a vague description and get a precise, detailed prompt that generates better results from the AI Payload Architect.

AI Optimization Techniques

When you click Enhance, the Qwen 3.8 27B model applies several heuristic passes to your raw script:

A

Timing Analysis

Detects OS-level UI interactions (like opening the Run menu or launching apps) and automatically inserts appropriate DELAY commands (e.g., 500ms after GUI r).

B

Syntax Correction

Fixes deprecated or invalid DuckyScript keywords, converting them to the strict format expected by the GhostChip interpreter.

C

Evasion Tactics

If requested, adds commands to shrink windows, clear run history (reg delete HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\RunMRU), and close terminals immediately upon completion.

⏺ Tool: Action Recorder NEW

Record a live sequence of keyboard actions, delays, and macros in real-time, then replay or export them as a DuckyScript payload.

Live Recording

Click Record and use the Live Keyboard tool. All keystrokes, modifier combos, and inter-key delays are captured into a script automatically.

Replay & Edit

Play back the recorded sequence, edit individual steps, adjust timing, or remove unwanted actions before saving or deploying.

Export to DuckyScript

Convert the recorded macro into standard DuckyScript text format — save to SD or share for later deployment.

Creating Perfect Macros

The Action Recorder completely eliminates the guesswork of writing DuckyScript timing delays. By recording your actual human interaction, the resulting script perfectly mirrors the required loading times of the target machine.

✅ Workflow: 1. Hit Record on your mobile device.
2. Switch to the Live Keyboard tab.
3. Perform the desired action (e.g., Windows Key, type 'cmd', wait for it to appear, press Enter).
4. Stop recording.
5. The precise sequence, including your natural pauses (converted to DELAY commands), is instantly generated.

You can then export this recording directly to your SD card as a .txt file, ready for rapid deployment or AutoRun triggering.

⭐ Tool: Favourites NEW

Save frequently used DuckyScript payloads as starred favourites for instant one-tap access from the main Scripts page and the Tools drawer.

Star from Editor

Click the ⭐ button in the DuckyScript editor toolbar to save the current script to Favourites. Optionally link it to an SD card file for auto-sync.

Category Tags

Organize by tag: 🎯 Attack, 📡 Recon, 🔧 Utility, ✦ Custom. Filter the grid by tag for quick access during operations.

One-Tap Execute

Tap a favourite card to load it into the editor instantly, or long-press to execute directly without opening the editor.

Managing the Arsenal

Favourites are stored in the browser's persistent Local Storage, meaning they remain available even when connecting to different GhostChip devices.

Tagging System

Apply tags to organize your scripts for quick retrieval under pressure:

🎯 Attack: Offensive payloads, reverse shells, credential dumpers.
📡 Recon: System enumeration, network mapping, vulnerability scanning.
🔧 Utility: Pranks, automation, OS configuration tweaks.

When editing a favourite, you can enable Auto-Sync to ensure any changes made in the editor are automatically saved back to the linked SD card file, keeping your physical payloads perfectly in sync with your web interface.

🔒 Tool: Vault NEW

A secure credential store for keeping sensitive data (passwords, tokens, API keys) organized and accessible during audits — without embedding them as plaintext in payloads.

Encrypted Storage

Credentials are stored in the browser's local storage with client-side encryption. Never transmitted to the device or any remote server.

Quick Insert

Tap any stored credential to copy it to clipboard, or insert it directly into the DuckyScript editor as a STRING command.

Zero-Knowledge Architecture

The Vault tool is designed to prevent accidental leakage of your sensitive infrastructure data (like C2 IP addresses, API keys, or webhooks) during engagements.

No Plaintext on SD: Instead of hardcoding your webhook URL into a DuckyScript file on the SD card (which could be seized or analyzed), you store it in the Vault on your phone.
Runtime Insertion: During an operation, you inject the credential directly from the Vault into the Live Keyboard stream.
Local Encryption: Data is encrypted at rest using AES-256 within the browser's IndexedDB.

⚠️ Master Password: The Vault requires a master password to decrypt upon opening the app. If you lose this password, the vault contents cannot be recovered.

⚡ Tool: Shortcuts NEW

A curated collection of one-tap system shortcuts that send common OS keyboard combinations to the target via USB HID — faster than opening the Live Keyboard for frequent operations.

Windows Shortcuts

Run dialog (GUI+R), Task Manager (CTRL+SHIFT+ESC), Lock screen (GUI+L), Desktop (GUI+D), System Properties (GUI+PAUSE).

macOS Shortcuts

Spotlight (GUI+SPACE), Finder, Force Quit (GUI+ALT+ESC), Screenshot (GUI+SHIFT+4), Terminal.

Linux Shortcuts

Terminal launchers, workspace switching, application launchers — common across major desktop environments (GNOME, KDE).

Rapid Triage & Evasion

The Shortcuts grid provides massive tactical advantage during physical access scenarios where speed is critical. Instead of navigating menus or fumbling with the Live Keyboard, you can execute complex multi-key macros instantly.

Shortcut Name	Key Combo Sent	Tactical Use
Lock Workstation	`GUI + L` / `CTRL + CMD + Q`	Securely locking the machine if interrupted.
Task Manager	`CTRL + SHIFT + ESC`	Instantly identifying security software.
Minimize All	`GUI + M`	Hiding active terminal windows instantly.
Terminal/Run	`GUI + R`	The universal entry point for payload execution.

Shortcuts are OS-aware. Ensure you have the correct Target OS selected in the app settings so the correct modifier keys (GUI vs CMD) are injected.

📁 Tool: File Manager

The File Manager tool provides a robust explorer interface to manage partitions, view exfiltrated data captures, and deploy custom script binaries on the MicroSD card filesystem.

Wireless File Uploads

Drag and drop or select `.txt` or `.bin` script files directly from your phone's browser cache. The ESP32 writes them to the MicroSD `/payloads/` directory in milliseconds.

Real-time Exfiltration Viewer

When payload scripts output keys or logs, they are written to `/exfil/` logs. You can browse, read raw text in-browser, or download log sheets directly to your device.

Run Payload Trigger

Click the "Run" (Play) icon next to any script. This loads it directly into the active keyboard emulator and starts injection operations instantly.

📂 Folder Mappings: Keep all compiled DuckyScript files in the /payloads/ root folder and exfiltrated payloads under the /exfil/ folder for correct dashboard indexing.

SD Card File Operations

The File Manager provides full CRUD (Create, Read, Update, Delete) access to the GhostChip's MicroSD card over the air.

Upload Payloads

Push new DuckyScript `.txt` files directly from your phone to the device without physically removing the SD card.

Download Loot

Retrieve exfiltrated data files, network captures, or system logs gathered during an operation.

Live Editing

Tap any text file to open it in the built-in code editor. Save changes directly to the SD card.

💡 Speed Limitations: Due to the SPI interface constraints of the ESP32-S3, file transfers are limited to approximately 200-300 KB/s. For large PCAP files or mass exfiltration, removing the physical SD card is recommended.

🤖 Tool: AI Assistant

A conversational dialog system driven by the Groq Llama-3 compiler, translating verbal instructions into working payloads.

1

Voice Capture Module

Click the Microphone icon to initiate web speech recognition. Speak your target instructions clearly (e.g. "Open Notepad, type 'System Audited', and save it").

2

Automatic Payload Compiling

The system passes the voice transcript to the Llama-3 API, which generates properly formatted DuckyScript code blocks automatically.

3

Deploy to Active Editor

Click Load Script to paste the generated code directly into your active workspace for visual validation or timing adjustment edits.

📶 Cloud Requirement Indicator: This tool requires active router bridging and a valid key from the Groq Console.

🔑 Get Free Groq API Key

Context-Aware Assistance

The AI Assistant (powered by the Qwen 3.8 27B model) acts as your co-pilot. It understands the GhostChip's DuckyScript dialect and hardware constraints perfectly.

1

Script Debugging

Paste a failing script. The AI will identify syntax errors, missing DELAY commands, or invalid modifier combinations.

2

Payload Generation

Ask for a payload by intent. Example: "Generate a payload for macOS that opens Terminal and pings google.com".

3

Hardware Queries

Ask questions about GhostChip features, LED status codes, or electrical limits without needing to consult this manual.

Connectivity Required: The AI Assistant requires the GhostChip to have an active internet connection via the WiFi Bridge. It communicates with the Groq Cloud API directly from the ESP32-S3.

🛠️ Tool: Script Builder

Construct payloads visually using block components, eliminating the need to write raw code manually.

Command Block Library

Select from blocks like DELAY, STRING, ENTER, GUI modifier, and REPEAT.

Visual Parameter Forms

Type your strings directly into visual fields and drag sliders to easily adjust delay timers.

Syntax compiler

Click Compile to merge all visual block components into standard, valid DuckyScript text blocks.

💡 Pro-Tip: Use the Script Builder to construct the initial outline of your script, and then load it into the main editor to make fine-tuned timing adjustments.

Visual Payload Construction

The Script Builder offers a drag-and-drop or block-based interface for constructing payloads without memorizing syntax.

Block Type	Functionality
System Actions	Open Run, Open Terminal, Lock Screen, Minimize Windows.
Execution	Typing text, running shell commands, pressing Enter.
Timing	Delays, Wait for Network, Wait for Mount.
Logic	Repeat loops, Conditional OS detection (if supported by payload wrapper).

Once built, the sequence can be exported directly to standard DuckyScript text and loaded into the main editor.

🛡️ Tool: Payload Templates

Quickly deploy pre-configured DuckyScript templates designed for common network diagnostics and security audits.

Auditing Template	Payload Operation Details	Standard Target OS
Network Diagnostics	Gathers IP information, traceroutes DNS configs, and writes output details to local files.	Windows / macOS / Linux
Webhook Exfiltrator	Leverages `curl` to transmit environment parameters straight to custom HTTP endpoints.	macOS / Linux
Stealth Reverse Shell	Spawns background listener interfaces to deploy automated local shells.	Windows PowerShell

⚙️ Webhook Endpoint Substitution: Paste your custom exfiltration URL (e.g. from `ntfy.sh` or `webhook.site`) into the visual configurator card. The template engine automatically substitutes this URL into the payload variables before deployment.

Curated Attack Vectors

The Templates library contains pre-written, highly optimized payloads for common operational scenarios. These templates have been tested across multiple OS environments to ensure maximum reliability.

Reconnaissance

Extract system info, wireless profiles, mapped drives, and active network connections. Often saves data back to the SD card.

Persistence

Establish reverse shells, create hidden administrative accounts, or add scheduled tasks/cron jobs.

Pranks / Annoyances

Harmless scripts for demonstrations: rotating the screen, changing wallpapers, or playing audio.

💡 Customization: Templates are loaded with placeholder variables (e.g., [YOUR_IP_HERE]). The UI will prompt you to fill in these variables before injecting the payload into the editor.

🎹 Tool: Live Keyboard

Transform your mobile phone interface into a real-time remote keyboard controller that types directly onto the target computer.

Modifier Key Combinations

Visual toggle controls for keys like `CTRL`, `ALT`, `SHIFT`, and `GUI (Win/CMD)`. Tap them to simulate hold-key actions.

Real-time Keystrokes

Type text into the visual input form. Characters are immediately transmitted over native USB descriptors with zero delay.

System Quick Macros

Dedicated buttons to trigger shortcuts: open Windows Run dialog (`GUI+R`), open macOS Terminal, or close active application (`ALT+F4`).

Real-Time HID Injection

The Live Keyboard transforms your mobile device or browser into a physical keyboard connected to the target machine. Every keystroke is instantly serialized into a USB HID report and transmitted over the air.

Modifier Lock Toggles

Toggle CTRL, ALT, SHIFT, and GUI (Windows/CMD) buttons. They remain held down until toggled off, allowing for complex multi-key combinations.

Special Keys Drawer

Access Function keys (F1-F12), navigation keys (Home, End, PageUp, PageDown), and system keys (PrintScreen, Insert) that may not exist on your mobile keyboard.

Macro Keys

Assign custom text strings or DuckyScript sequences to quick-access macro buttons for instant deployment during live sessions.

⚠️ Mobile Keyboard Caveats: Virtual mobile keyboards (like iOS or Gboard) handle auto-correction and backspacing uniquely. GhostChip attempts to interpret these intelligently, but for the most reliable results, disable auto-correct during a live session or type deliberately.

💡 Tool: NeoPixel LED

Customize the onboard WS2812B RGB diagnostic LED to change light modes or enable stealth operation.

1

Stealth Mode Switch

Toggle the LED off entirely. This hides all diagnostic flashes and makes the hardware blend in during physical USB deployments.

2

Diagnostic Color Wheel

Set custom colors for active scanning, keyboard injection states, deauth alarms, and file write loops.

3

Brightness Sliders

Fine-tune brightness scales from 0% up to 100% to manage power draw and thermal limits during prolonged audits.

Status Indicators & Stealth

The onboard WS2812B NeoPixel provides immediate visual feedback on the device's state. Using this tool, you can manually override the color or disable it completely.

System Status	Default Color Code
Booting / Connecting	Flashing Blue
AP Mode Active (No Internet)	Solid Cyan
WiFi Bridge Active (Internet)	Solid Green
Executing Payload	Flashing Red
Error / Failure	Rapid Flashing Yellow

Stealth Mode: Toggle the LED off entirely for covert operations. This setting is saved to NVS and persists across reboots. Note that physical execution will still occur; you just won't have visual confirmation.

🌐 Tool: Device Info

Access real-time hardware status metrics, networking details, and operating parameters of the ESP32-S3 module.

Diagnostic Parameter	Value / Specification	System Description
Chip Model	ESP32-S3 Dual-Core Xtensa	Core hardware processor model.
CPU Frequency	240 MHz	Active processing clock speed.
Internal SPIFFS Storage	4 Megabytes (MB)	Onboard flash memory for the Web UI layout.
MicroSD Status	Mounted (FAT32 filesystem)	Indicates MicroSD connection state.
Station IP Address	Dynamic mDNS (`ghostchip.local`)	Assigned IP inside the bridged local network.

System Diagnostics

The Device Info panel provides real-time telemetry and hardware status straight from the ESP32-S3 core.

Heap Memory: Monitor available RAM. Important if running extremely large DuckyScript strings.
SD Card Status: Verify mount status, format (must be FAT32), total capacity, and free space.
WiFi Signal (RSSI): Check the signal strength of the bridged network. Useful for positioning the device.
Uptime: See how long the device has been powered on.

This page also displays your unique Device ID (MAC address), which is useful if you are managing a fleet of GhostChips and need to distinguish them on a network.

💾 Tool: Payload Simulator

Safely run and dry-test payloads inside an isolated browser-shell sandbox before physical execution.

Syntax Analyzer

Scans scripts for syntax errors and highlights typos in keywords like STRING or modifier keys.

Virtual Shell Terminal

Shows a simulated terminal screen displaying typing speeds, pauses, and keystroke repeats visually.

Step-by-Step Debugging

Step through lines one by one to verify delay timings and keyboard modifier combos safely.

Safe Sandboxed Testing

The Payload Simulator parses your DuckyScript and provides a visual timeline of exactly what it will do, without actually sending any keystrokes to the host machine.

1

Execution Timeline

Calculates the total runtime based on DELAY and DEFAULTDELAY values, helping you predict how long an operation will take.

2

Key Sequence Visualization

Shows exactly which modifier keys will be held down and in what order, making it easy to spot logic errors in complex combos.

3

OS Warning Checks

Flags commands that might behave differently on Windows vs macOS (e.g., warning you if you use GUI in a script intended for Linux).

💿 Tool: OTA Flash Updater

Easily upgrade the GhostChip firmware wirelessly with zero cables or programming interfaces required.

1

Drag and Drop Firmware Binary

Drag your updated firmware file (`ghostchip.bin`) directly into the OTA drag-and-drop zone.

2

Dynamic Progress Bar

Monitor transmission metrics. The dashboard shows real-time progress bars as the file writes to the OTA partition.

3

Automatic Soft Reboot

Once writing is complete, the chip automatically reboots to run the new firmware safely.

⚠️ IMPORTANT: Do not disconnect USB power or interrupt the connection during the OTA flash write cycle. Doing so will corrupt the partition and require physical flashing.

🔌 Direct USB Web Serial Flashing

If the wireless network is unavailable or if the active partition is corrupted, you can flash the core factory binaries directly over a standard USB cable using our native Web Serial Flasher tool:

Launch Web Serial Flasher

Over-The-Air Updates

Update the GhostChip firmware wirelessly without needing USB data cables, esptool, or command-line flashing utilities.

✅ Update Process: 1. Download the latest .bin firmware file from the official repository.
2. Connect to the GhostChip dashboard.
3. Open the OTA Updater tool and select the .bin file.
4. Click Flash. The device will upload the binary, write it to the OTA partition, and automatically reboot into the new firmware.

⚠️ Critical Warning: Do not disconnect power during an OTA update. If the flash is interrupted, the device may soft-brick. If this happens, you will need to recover the device using a wired USB connection and standard ESP32 flashing tools.

💾 Troubleshooting: SD Card Mount Failures

Symptom: The File Manager or Preset libraries display empty files lists, or show mount failure toasts.

Root Cause Analysis: The ESP32-S3's hardware SDIO driver is restricted to parsing strictly MBR (Master Boot Record) partition tables, FAT32 cluster structures, and volumes up to 32GB maximum. Modern GUID Partition Tables (GPT), exFAT, or NTFS schemes are not recognized.

Diagnostic & Action Steps:

Connect your card reader to a PC/macOS host. Open your Disk Utility or Disk Management dashboard.
Confirm the capacity of the MicroSD card does not exceed 32GB. (16GB or 32GB cards are highly recommended).
Re-partition the card, changing the partition scheme explicitly from GPT (GUID) to MBR (Master Boot Record).
Format the volume as FAT32 with the Allocation Unit (Cluster) Size set to 32KB (32,768 bytes).
Ensure the MicroSD card is completely seated inside the physical card slot before plugging in USB power. The card reader is mounted strictly during the early boot sequence.

📶 Troubleshooting: Invisible AP Gateway

Symptom: The local wireless AP `Ghostchip` SSID does not appear in your smartphone's Wi-Fi network sweep.

Root Cause Analysis: Insufficient power supply, local radio frequency interference (specifically surrounding Wi-Fi channel overlaps), or active loop anomalies.

Diagnostic & Action Steps:

Verify the ESP32 receives standard 5V USB power (minimum 500mA output threshold). Avoid powering the device via high-voltage fast chargers that lack standard legacy 5V fallbacks.
Ensure the onboard status RGB LED flashes or illuminates during power-up, indicating the chip is booted.
If the AP is still missing, trigger a system clear: Disconnect USB power. Hold down the physical BOOT button on the ESP32 chip module. Reconnect USB power while holding the button, then release it to clear loop state anomalies.
Ensure the device is not sitting directly next to high-power RF sources (routers, microwaves) that can degrade the local AP signal.

🤖 Troubleshooting: Groq AI & Assistant Compile Errors

Symptom: The AI prompts page or assistant display API communication errors, or generation hangs indefinitely.

Root Cause Analysis: The ESP32 module or control mobile device lack active internet connectivity, or your saved API Key is invalid or expired.

Diagnostic & Action Steps:

Network Verification: Confirm that both your control mobile phone and the GhostChip are connected to your own local Wi-Fi router (access point) with active internet. If your phone is connected to your home router but the GhostChip is still connected only to its default `Ghostchip` local network, API calls will fail. (See the AI Network Setup page).
Ensure you can load `http://ghostchip.local` on your browser while connected to the router network. If the name fails to resolve on legacy devices, use the router IP shown on the connections dashboard.
Confirm your saved Groq API Key is active. Retrieve a free key (starts with `gsk_`) from the official Groq Console and re-save it inside Settings.
Check if your Groq request limits have been exceeded.

🔑 Open Groq Console Website

⌨️ Troubleshooting: Missed Keystrokes & Timings

Symptom: The HID injector types too fast, misses opening target windows, or types incorrect characters.

Root Cause Analysis: The host operating system requires a few seconds to configure USB keyboard drivers. Fast keystrokes can also exceed target keyboard buffer limits, and incorrect layout profiles map physical keys differently.

Diagnostic & Action Steps:

Insert a DELAY 3000 command at the very beginning of your DuckyScript payloads. This gives the host OS time to enumerate the USB keyboard driver before keystrokes are typed.
Insert a DEFAULTDELAY 150 statement as the second line in your script. This adds a short delay after each keystroke, helping slower target systems process the inputs correctly.
Ensure the target host's input language layout is set to US English. Different regional keyboard layouts (such as UK, AZERTY) map characters to different physical keys and will result in character mapping errors.