DuckyDeck Studio — User Guide

⚡ Hardware Portability vs. Host-Dependent Capabilities

DuckyDeck Studio combines standalone hardware configuration (compiled onto your duckyPad's microSD card) with host-assisted Linux desktop automation. Throughout the app, every feature is badged as either ✅ Hardware-Portable or 💻 Requires DuckyDeck Studio Running on Host PC so you always know what works when you unplug your duckyPad and move it to another computer.

🎬 Video Tour & Application Screenshots

Watch the full 1080p walkthrough of DuckyDeck Studio in action across profiles for Dolphin, Google Chrome, VS Code, OBS Studio, KDE Konsole, Blender 3D, Spotify, and the Desktop App Launcher:

1. Dolphin File Manager Profile — 20 RGB keys, Dual Rotary Encoders, 128×128 OLED preview & live DSVM v2 compiler.

2. Google Chrome Profile — Browser tab management, navigation, zoom encoders & DevTools shortcuts.

3. Visual Studio Code Profile — Command Palette, build tasks, debugger stepping & Git shortcuts.

4. Blender 3D Profile — Viewport navigation, sculpting brushes, render keys & DuckyScript 3 loops.

📦 1. Downloading from GitHub, Installation & USB HID Permissions

DuckyDeck Studio is open-source and hosted on GitHub at github.com/russellmilliner/duckydeck-studio. It communicates directly with your duckyPad over USB HID (hidraw) for real-time profile switching, LED color previews, RTC clock sync, and Persistent Global Variables (_GV0.._GV31), and mounts or reads the duckyPad microSD card for profile storage.

Step 1: Download or Clone from GitHub

git clone https://github.com/russellmilliner/duckydeck-studio.git
cd duckydeck-studio

curl -L https://github.com/russellmilliner/duckydeck-studio/archive/refs/heads/master.zip -o duckydeck-studio.zip
unzip duckydeck-studio.zip
cd duckydeck-studio-master

Step 2: Install Build Prerequisites

• Arch Linux / CachyOS / EndeavourOS / Manjaro:

  sudo pacman -S --needed base-devel rust clang cmake ninja pkgconf \
      qt6-base qt6-declarative kirigami syntax-highlighting hidapi libusb

• Fedora (40 / 41+):

  sudo dnf install cargo rust clang cmake ninja-build pkgconf-pkg-config \
      qt6-qtbase-devel qt6-qtdeclarative-devel kf6-kirigami-devel \
      kf6-syntax-highlighting-devel hidapi-devel libusb1-devel systemd-devel

• Ubuntu (24.04+) / Debian / KDE Neon:

  sudo apt install build-essential cargo rustc clang cmake ninja-build pkg-config \
      qt6-base-dev qt6-declarative-dev libkf6kirigami-dev \
      libkf6syntaxhighlighting-dev libhidapi-dev libusb-1.0-0-dev libudev-dev

Step 3: Build & Install DuckyDeck Studio

Compile the optimized release binary and install the executable, desktop launcher, icon, and duckyScript 3 syntax highlighting definition:

# 1. Compile optimized release binary
cargo build --release

# 2. Install binary to ~/.local/bin
install -Dm755 target/release/duckydeck-studio ~/.local/bin/duckydeck-studio

# 3. Install duckyScript 3 syntax highlighting for KDE KSyntaxHighlighting
install -Dm644 data/syntax/duckyscript3.xml \
    ~/.local/share/org.kde.syntax-highlighting/syntax/duckyscript3.xml

# 4. Install desktop entry, icon, and documentation
install -Dm644 data/io.github.duckydeck.Studio.desktop \
    ~/.local/share/applications/io.github.duckydeck.Studio.desktop
install -Dm644 data/icons/io.github.duckydeck.Studio.svg \
    ~/.local/share/icons/hicolor/scalable/apps/io.github.duckydeck.Studio.svg
install -Dm644 docs/user-guide.html \
    ~/.local/share/duckydeck-studio/docs/user-guide.html

# 5. Launch DuckyDeck Studio
~/.local/bin/duckydeck-studio

sudo ./data/udev/install-udev-rules.sh

Supported Hardware Matrix

🖥️ 2. The 3-Column Workspace

🗂️ 3. Profiles, Templates & Profile Groups

The duckyPad Pro supports up to 64 profiles (`profile_1` through `profile_64`). Each profile stores its own default background LED color (`BG_COLOR`), per-key custom colors (`SWCOLOR`), key labels (`zN` / `xN`), OLED & Desktop Widget orientations, and compiled bytecode binaries (`.dsb`).

• Create a Profile (Blank or From Template): Click + New at the bottom of the left sidebar, type a name (up to 16 characters), optionally select any built-in or user-saved Template from the dropdown, and press Enter.
• 📋 Profile Templates:
  • Click 📋 Templates... at the bottom of the sidebar (or 📋 Profile Templates... in the `☰` menu) to browse built-in starter templates (Media & Volume Deck, IDE & Git Workflow, Browser & Research, Numeric Keypad (Numpad)) and your own custom templates (`~/.config/duckydeck-studio/profile_templates/`).
  • Copy Any Profile to a Template: Right-click any profile in the sidebar and choose 📋 Save Profile as Template... (or click 📋 Save as Template... in Profile Settings) to save its keys, scripts, colors, and orientations as a reusable template.
  • Apply a Template to an Existing Profile: Open 📋 Templates... and click Apply to Current Profile to overwrite the active profile with that template's layout.
• ⚙ Profile Settings (OLED, Instant Desktop Widget Orientation & Profile Change Webhook): Click the ⚙ Profile Settings button in the center toolbar (or right-click a profile → Profile Properties...) to configure:
  • Hardware OLED Orientation (`0°`, `90°`, `180°`, `270°`): Rotates the physical duckyPad Pro OLED screen and key grid (`180°` & `270°` require DuckyDeck Studio Firmware `v1.0.0`).
  • 💻 Desktop Widget Orientation (`Follow OLED`, `0°`, `90°`, `180°`, `270°`): Independently orient the floating on-screen Desktop Widget without changing how the physical duckyPad sits on your desk! Changes apply immediately and do not require a microSD card sync.
  • 🔔 Profile Change Webhook (On Profile Activated): Configure a per-profile HTTP webhook (`GET`/`POST`/`PUT`/`PATCH`/`DELETE`, URL, custom headers, and JSON body with placeholders `{{profile_number}}`, `{{profile_name}}`, `{{previous_profile_number}}`, `{{previous_profile_name}}`, `{{source}}`, `{{device_serial}}`, `{{timestamp}}`) that fires automatically whenever that profile becomes active.
  • Dim Unused Keys (`DIM_UNUSED_KEYS`): Automatically turns off LEDs on unconfigured keys.
• Reorder Profiles: Drag any profile by its ⠿ handle (or right-click and choose Move Profile Up / Down). Associated Auto-Switcher rules automatically update to follow the moved profile!
• Profile Groups (`.duckygroup.json`): Click Groups ▾ at the bottom of the sidebar (or in the `☰` menu) to save all profiles and Auto-Switcher rules into a single portable `.duckygroup.json` bundle, load an existing bundle, or start a fresh workspace.

🎹 4. Interactive Hardware Canvas & OLED Simulator

• Select / Deselect a Slot: Left-click any key (1–20), encoder action (21–26), or expansion slot (27–58) to open the Right Inspector. Click the selected key again (or click ✕ in the inspector header) to close the inspector.
• Drag-and-Drop Swap vs. Shift:
  • Drag & Drop: Swaps the source key and target key (including scripts, labels, and custom RGB colors).
  • Shift + Drag & Drop: Inserts the dragged key at the target slot and shifts intermediate keys!
• Right-Click Key Context Menu:
  • Copy Key X / Paste → Slot Y: Copy a key's full configuration and paste it onto another key (even across different profiles).
  • Set Key X Color: Opens the Color Picker window with your Saved & Used color palettes.
  • Clear / Reset Key X: Clears labels, scripts, and custom RGB color on that slot.
• Toolbar Toggles:
  • ⚙ Profile Settings: Configure profile name, default LED color, Hardware OLED Orientation (`0°`, `90°`, `180°`, `270°`), instant Desktop Widget Orientation (`Follow OLED`, `0°`, `90°`, `180°`, `270°`), and Per-Profile Change Webhooks.
  • ⚡ 32ch: Show or hide the 4×8 (32-channel) Expansion Module panel (Slots 27–58).
  • OLED: Grid / Script: Preview either the standard 4×5 key label grid or custom `OLED_LINE` / `OLED_CIRCLE` / `OLED_RECT` drawing commands on the simulated 128×128 OLED screen.

🎨 5. Key & Profile Color Picker (Saved & Used Palettes)

Open the Color Picker by right-clicking any keycap and choosing Set Key X Color, clicking Key Color in the right inspector, or clicking Default Color in the top bar / center toolbar / profile sidebar.

🎨 Set Key Color Dialog — Interactive 2D HSV picker, RGB/Hex controls, persistent Saved Colors palette, and automatic Used Colors in Profiles & Keys palette.

💾 6. microSD Sync, Mounting & Firmware Manager (`v1.0.0` & Official Catalog)

Edits you make in DuckyDeck Studio are saved immediately to your local profile cache (`~/.local/share/duckydeck-studio/profiles_cache/`) so you never lose work, even when the duckyPad is unplugged.

• Mount SD Card (`☰ → Mount SD Card`): When an unmounted duckyPad microSD card (or USB Connected Duckypad) is detected, the `☰` menu displays Mount SD Card so you can mount it with one click without triggering a full sync.
• Status Bar Sync Badge: The bottom status bar shows whether your local profiles match the hardware microSD card (✓ SD Synced vs. ⚠ Unsynced Changes). Host-only settings like Desktop Widget Orientation (`DW_ROTATION`) and Profile Change Webhooks apply immediately without requiring an SD sync.
• 📋 Changes Summary: Click the sync status badge (or 📋 Summary) to inspect a per-profile diff of added, modified, or deleted keys before writing to hardware.
• ⬆ Sync to SD: Mounts the duckyPad Pro microSD card (automatically via USB Mass Storage mode `0x1B` + `udisksctl`, or direct SD mount), compiles every `keyN.txt` script into a DSVM v2 `.dsb` binary, writes `config.txt` and `profile_info.txt`, flushes the filesystem, and verifies the written files.
• DuckyDeck Studio Firmware (v1.0.0 — DPP_FW_1.0.0_ad2acc81.bin) & Official Firmware Catalog Downloader:
  • Download Firmware Binary: ⬇ GitHub Release (DPP_FW_1.0.0_ad2acc81.bin)  |  ⬇ Direct Download (DPP_FW_1.0.0_ad2acc81.bin, IEEE CRC32: ad2acc81)
  • DuckyDeck Studio includes its own custom firmware build versioned as 1.0.0 (based on upstream duckyPad-Pro 3.3.5 / DSVM v2, identified by the DuckyDeck Studio icon badge in the status bar and USB HID 0x00 signature bytes 'D','D','S').
  • Download Official Firmware List in Firmware Manager (☰ → Firmware Update...): Click ⬇ Fetch Official List from Site inside the Firmware Manager window to query the official dekuNukem/duckyPad-Pro repository, browse all available official firmware versions, and click ⬇ Download .bin or Download & Install Selected Firmware (with automatic IEEE CRC32 checksum verification).

🔧 What DuckyDeck Studio Firmware v1.0.0 Adds Over Standard duckyPad Pro Firmware (3.3.5)

📜 7. duckyScript 3 & Built-In DSVM v2 Bytecode Compiler

DuckyDeck Studio includes a full, pure-Rust duckyScript 3 → DSVM v2 (`.dsb`) bytecode compiler with real-time syntax checking and KDE `KSyntaxHighlighting`. Standard duckyScript 3 macros are 100% Hardware-Portable once synced to your microSD card.

• Live Bytecode Verification: As you type in the script editor, the header badge shows ✓ Valid DSVM (N B) or highlights the exact line number and syntax error.
• On Press vs. On Release Tabs: Every key and slot supports both an On Press (`keyN.txt`) script and an On Release (`keyN-release.txt`) script.
• 📖 Command Reference Drawer: Click 📖 Reference in the script toolbar to browse and insert all duckyScript 3 commands (`STRING`, `STRINGLN`, `DELAY`, `KEYDOWN`, `KEYUP`, `SWCC`, `SWCF`, `SWCR`, `OLED_PRINT`, `OLED_LINE`, `OLED_RECT`, `OLED_CIRCLE`, `OLED_UPDATE`, `IF/ELSE/END_IF`, `WHILE/END_WHILE`, `FUNCTION/END_FUNCTION`, `GOTO_PROFILE`, `_GV0.._GV31`, etc.).

KDE Konsole Profile — Terminal automation with `STRINGLN` commands and live `.dsb` bytecode verification.

Spotify Media Profile — Hardware media keys (`MK_PLAYPAUSE`, `MK_NEXT`, `MK_VOLUP`) and rotary encoders.

🚀 8. Launch Application Builder

Turn any duckyPad key into a one-press Linux application launcher without writing shell scripts by hand.

1. Select a key (1–20) to open the Right Inspector and click the 🚀 Launch App button in the editor toolbar.
2. Check Launch Application on Key Press.
3. Click 📦 Pick Installed App... to search all installed desktop applications (`.desktop` entries from `/usr/share/applications`, Flatpak exports, and `~/.local/share/applications`) with icons, descriptions, and categories—or type any custom command and arguments.
4. Choose the Trigger Mode:
   • Silent Host Launch (`_GV19`) (Default — No Keyboard Shortcut Needed): Pressing the key on the duckyPad writes a unique profile+slot token to `_GV19`. DuckyDeck Studio's background HID listener detects the change and spawns the application directly on your Linux desktop!
   • F13–F24 Global Hotkey (`evdev`): Emits `F13`–`F24` over USB HID keyboard and triggers the launch via DuckyDeck Studio's background `evdev` listener.
5. Click ▶ Test Launch anytime to test the command immediately and inspect the result in the System Event Log (`APP_LAUNCH`).

🚀 Launch Application Builder — Configure desktop apps (Dolphin, Google Chrome, VS Code, OBS Studio, Konsole, Blender, Spotify, GIMP) with APP keycap badges and instant USB HID host launching.

🌐 9. Web API / Webhook Builder & 🏠 Home Assistant Entity Search

Trigger Home Assistant devices/entities, REST APIs, Miniflux, OBS, or custom HTTP endpoints directly from a duckyPad key:

1. Select a key and click 🌐 Web API in the inspector toolbar (or open the full Web API / HTTP Webhook configurator window).
2. 🏠 Search Home Assistant Devices & Entities:
   • Enter your Home Assistant URL (e.g. http://homeassistant.local:8123) and a Long-Lived Access Token (created in Home Assistant under Profile → Security → Long-Lived Access Tokens), then click Save HA Connection.
   • Select a domain filter (All Domains, light, switch, scene, script, automation, button, input_boolean, media_player, cover, fan, climate, lock), type a search query, and click 🔍 Search Entities.
   • Click ⚡ domain.service (or Turn On / Turn Off) next to any entity to automatically populate the HTTP POST endpoint (/api/services/<domain>/<service>), Authorization: Bearer header, JSON {"entity_id": "..."} body, and OLED feedback text for the selected key!
3. Custom REST / Webhook Endpoints: Configure any HTTP Method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`), URL, custom headers (`Header: Value` per line), and request body (JSON/text).
4. Click Test Webhook Now to fire the HTTP request immediately and view status codes, latency, and errors in the System Event Log (`WEB_API`).

🌐 Web API / Webhook Builder — Triggering a Home Assistant Studio Key Light REST service from Key 17 of the OBS Studio profile with RGB LED status feedback.

🪟 10. KDE Plasma 6 Wayland Auto-Switcher & Floating OLED Desktop Widget

DuckyDeck Studio features a native Rust + `zbus` listener that integrates with KDE Plasma 6's KWin Wayland compositor to automatically switch duckyPad hardware profiles when you focus different windows or browser tabs.

• 🎯 Crosshair Window Picker: Right-click any profile in the sidebar and select Bind Window to This Profile (Pick Window)... (or click Pick Window inside the Rules dialog). Click any open window on your desktop to automatically capture its `resourceClass`, window title, and application icon.
• Browser Tab Title Matching: When picking a web browser (Zen Browser, Firefox, Chrome, Brave, Vivaldi, etc.), DuckyDeck Studio automatically strips the browser suffix so your rule matches the specific web app or tab title (e.g. `Miniflux`, `GitHub`, `YouTube`), or you can use `*browser*` to match all web browsers.
• Automatic Pause While Editing: Whenever the Right Key Inspector is open, the Auto-Switcher automatically pauses (`AUTO-SWITCHER (PAUSED)`) so switching to a browser or terminal to copy a URL or command won't yank the active profile away from the key you're editing!
• Floating OLED Desktop Widget: Mirrors the 128×128 OLED screen on your desktop with configurable scale (`1x`–`3x`), transparency (`0%`–`85%`, persisted across restarts), multi-monitor screen & KWin Wayland position memory, and instant independent per-profile orientation (`Follow OLED`, `0°`, `90°`, `180°`, `270°`) that does not require a microSD card sync.

🪟 KWin Wayland Auto-Switcher Rules — Map window classes and titles (Dolphin, Google Chrome, VS Code, OBS Studio, Konsole, Blender, Spotify) to hardware profiles with 1-click Window Picking.

🔢 11. Persistent Global Variables (`_GV0`..`_GV31`)

Open Variables (`_GV`)... from the `☰` menu to inspect and live-edit all 32 32-bit non-volatile Persistent Global Variables (`_GV0` through `_GV31`) over USB HID commands `0x18` (read) and `0x19` (write) in Signed Decimal, Unsigned Decimal, or Hexadecimal format.

✨ 12. AI Macro Architect

Click ✨ AI in the Right Inspector header (or AI Macro Architect... in the `☰` menu) to generate duckyScript 3 macros using natural language. DuckyDeck Studio grounds prompts with your local KDE shortcuts (`~/.config/kglobalshortcutsrc`) and validates the generated script with the built-in DSVM v2 compiler.

📋 13. System Event Log

Open System Event Log... from the `☰` menu (or from the About window) to view real-time diagnostic events across all subsystems:

• DEVICE — USB HID connection, firmware checks, RTC sync, and reboots
• PROFILE — Profile selection, creation, templates, renaming, reordering, and color changes
• AUTOSWITCH — KWin Wayland window focus changes and automatic profile switches
• SD_SYNC — microSD mounting, `.dsb` bytecode compilation, and file validation
• SCRIPT — Slot script saves and compiler diagnostics
• WEB_API — HTTP webhook triggers, profile-change webhooks, status codes, latency, and response summaries
• APP_LAUNCH — Application launch triggers, desktop IDs, PIDs, and error diagnostics
• SYSTEM — Startup, REST API Server events, configuration persistence, and UI events

Logs are also persisted on disk at ~/.local/share/duckydeck-studio/logs/system_events.log and can be filtered, copied, or exported to a `.log` file.

📋 System Event Log — Live diagnostic log with category & severity pills, keyword search, clipboard copy, and `.log` file export.

⚙️ 14. Settings, HTTP REST API Server & Security Implications

• 🌐 HTTP REST API Server (`Settings → HTTP REST API Server`):
  • Enable or disable the embedded REST API server, choose the Listen IP (default 127.0.0.1) and Port (default 28491), or click Reset Defaults (127.0.0.1:28491).
  • Click Generate Token to generate a new cryptographic Bearer token and Copy Token to copy it to your clipboard.
  • Control all duckyPad functions via JSON endpoints under /api/v1/* (/api/v1/health, /api/v1/status, /api/v1/profiles, /api/v1/profiles/select, /api/v1/profiles/reorder, /api/v1/profiles/{num}, /api/v1/profiles/{num}/slots/{slot}, /api/v1/profiles/{num}/slots/{slot}/trigger, /api/v1/dsvm/compile, /api/v1/templates, /api/v1/pgv, /api/v1/leds, /api/v1/sd/sync, /api/v1/device/sleep|wake|reboot|sync-rtc, /api/v1/logs).
  • OpenAPI 3.0 / Swagger Specification & Reference: View docs/REST_API.md, docs/openapi.yaml, and docs/swagger.json, or fetch the live spec directly from the server at GET /api/v1/openapi.json, GET /api/v1/swagger.json, and GET /api/v1/openapi.yaml.
• 🔔 Global Profile Change Webhook (`Settings → Global Profile Change Webhook`): Configure an HTTP webhook that fires automatically whenever the active profile changes (via UI, physical duckyPad buttons, Window Auto-Switcher, or REST API).
• Global UI Text Zoom (`75%`–`160%`, Minimum `10pt` Base Font): Adjust UI text zoom across the entire application using Ctrl++ / Ctrl+= (zoom in), Ctrl+- (zoom out), or Ctrl+0 (reset to `100%`), or via `Settings → Global Text Scale`. Zoom levels are saved automatically and restored on restart. All popup windows can also be closed with Esc.
• System Tray (`StatusNotifierItem`): DuckyDeck Studio integrates natively with the KDE Plasma 6 System Tray, displaying a custom dynamic icon with your active profile number and color badge, quick profile switching submenu, and optional Minimize / Close to System Tray behavior.

🛠️ 15. Troubleshooting & FAQ

🙏 16. Special Thanks to dekuNukem & Official duckyPad Links