How the BLEShark Nano Mini Keypad Works: Macros in Your Pocket
Dedicated macro keypads are useful. A three-button device that pairs over Bluetooth and fires keyboard shortcuts on press is the kind of thing you use every day once you set it up. The BLEShark Nano ($36.99+) already has three physical buttons and a BLE 5.0 radio built in - the Mini Keypad app combines those into a programmable shortcut device that connects to any computer, phone, or tablet without extra hardware.
This article covers how the Mini Keypad app works, how Bluetooth HID functions under the hood, how to configure your key assignments, which key names the firmware understands, and where this actually pays off in practice.
graph TD
subgraph "BLEShark Nano Mini Keypad Architecture"
subgraph "Hardware Layer"
BTN1["Button 1"]
BTN2["Button 2"]
BTN3["Button 3"]
BTN4["Button 4"]
GPIO["GPIO Pins
(interrupt-driven)"]
end
subgraph "Firmware Layer"
DEBOUNCE["Button Debounce
(software filter)"]
MACRO["Macro Engine
(lookup button mapping)"]
HID_RPT["HID Report Generator
(keystroke sequences)"]
end
subgraph "BLE HID Stack"
GATT["GATT Server
(HID Service UUID
0x1812)"]
HID_DESC["HID Report Map
(keyboard descriptor)"]
NOTIFY["BLE Notification
(key press/release)"]
end
subgraph "Host Device"
OS_BLE["OS BLE Stack"]
HID_DRV["HID Driver"]
APP["Active Application
(receives keystrokes)"]
end
end
BTN1 & BTN2 & BTN3 & BTN4 --> GPIO
GPIO --> DEBOUNCE --> MACRO --> HID_RPT
HID_RPT --> GATT --> NOTIFY
NOTIFY -->|"BLE connection"| OS_BLE
OS_BLE --> HID_DRV --> APP
graph TD
subgraph "BLEShark Nano Mini Keypad Architecture"
subgraph "Hardware Layer"
BTN1["Button 1"]
BTN2["Button 2"]
BTN3["Button 3"]
BTN4["Button 4"]
GPIO["GPIO Pins
(interrupt-driven)"]
end
subgraph "Firmware Layer"
DEBOUNCE["Button Debounce
(software filter)"]
MACRO["Macro Engine
(lookup button mapping)"]
HID_RPT["HID Report Generator
(keystroke sequences)"]
end
subgraph "BLE HID Stack"
GATT["GATT Server
(HID Service UUID
0x1812)"]
HID_DESC["HID Report Map
(keyboard descriptor)"]
NOTIFY["BLE Notification
(key press/release)"]
end
subgraph "Host Device"
OS_BLE["OS BLE Stack"]
HID_DRV["HID Driver"]
APP["Active Application
(receives keystrokes)"]
end
end
BTN1 & BTN2 & BTN3 & BTN4 --> GPIO
GPIO --> DEBOUNCE --> MACRO --> HID_RPT
HID_RPT --> GATT --> NOTIFY
NOTIFY -->|"BLE connection"| OS_BLE
OS_BLE --> HID_DRV --> APP
Mini keypad data flow - from physical button press through the BLE HID stack to keystroke delivery on the host device
Table of Contents- How Bluetooth HID Works
- The Three Buttons
- Configuring Key Combos
- Supported Key Names
- Use Cases: Streaming, Productivity, Gaming, and More
- Range, Battery, and Practical Notes
- Mini Keypad in a Shiver Mesh Setup
How Bluetooth HID Works
Bluetooth keyboards (and mice, gamepads, and similar input devices) use the HID profile - Human Interface Device. It's a standardized protocol that describes input devices to operating systems. When a Bluetooth device advertises a valid HID profile during pairing, the OS accepts it as a trusted input device and begins processing its reports.
Each keypress on a Bluetooth keyboard results in an HID report being sent to the host. For keyboard input, that report has a specific structure:
- Modifier byte - 8 bits, one per modifier key (left and right versions of CTRL, SHIFT, ALT, and GUI/WIN/CMD)
- Reserved byte - always 0x00
- Key code slots - 6 bytes, each holding a USB HID key code; 0x00 means that slot is empty
This structure tells the OS: which modifiers are currently held, and which up to six non-modifier keys are pressed simultaneously. The BLEShark Nano's Mini Keypad app builds and sends exactly these reports when you press a button.
One important thing about HID trust: the OS has no mechanism for verifying that a Bluetooth HID device is a genuine keyboard from a known manufacturer. Any device that advertises a properly-structured HID profile gets treated as a trusted keyboard. Your OS pairs with the Nano, recognizes it as a keyboard, and processes its key reports without questioning the source. This is the same trust model that makes HID injection a useful security testing vector - and it is also what makes the Mini Keypad work on any operating system without drivers.
The BLEShark Nano uses its ESP32-C3's BLE 5.0 radio to advertise and maintain the HID connection. Once paired, the connection persists in the background. Button presses generate HID reports with round-trip latency well under 20ms in typical conditions - imperceptible for macro use.
The Three Buttons
The BLEShark Nano has three physical buttons on its face. In most apps they serve as navigation controls: back, select, and forward. In Mini Keypad mode, each button sends its configured key combo to the connected host device.
Each button supports both short press and long press detection, which effectively doubles the available macro slots. A short press and a long press on the same button can map to completely different combos. With three buttons and two press types each, you have six distinct macro triggers from one pocket-sized device.
The Mini Keypad app runs on the device itself. Navigate to it from the main menu, and the Nano switches its BLE radio into HID advertising mode. Pair your computer to it the same way you would pair any Bluetooth keyboard - through Bluetooth settings on Windows, macOS, iOS, or Android. Once paired, the buttons fire your configured shortcuts immediately.
Configuring Key Combos
Configuration happens through the BLEShark Nano's file portal. When the device is connected to your network (or to its own hosted access point), the portal lets you upload and download files. Mini Keypad configuration is a plain text file that maps each button and press type to a key combo.
The format uses a simple label and value structure:
BUTTON_1_SHORT: CTRL+C
BUTTON_1_LONG: CTRL+SHIFT+C
BUTTON_2_SHORT: ALT+TAB
BUTTON_2_LONG: GUI+L
BUTTON_3_SHORT: CTRL+Z
BUTTON_3_LONG: CTRL+SHIFT+ZKey names are separated by plus signs. Modifiers go first. You can combine as many modifiers as needed - stacking three or four is fine for unusual system shortcuts. The configuration takes effect at the start of the next Mini Keypad session; no firmware update or reboot is needed for config changes.
You can also edit common presets directly from the on-device settings menu for quick adjustments without accessing the file portal. The on-device options cover the most common shortcut categories. For custom or complex combos, the file portal gives full control.
Supported Key Names
The firmware maps human-readable key names to USB HID key codes. Here is what the Mini Keypad understands:
Modifier Keys
- CTRL (or LCTRL, RCTRL for left/right specific)
- SHIFT (or LSHIFT, RSHIFT)
- ALT (or LALT, RALT - RALT is used for AltGr on European keyboards)
- GUI (Windows key, CMD on Mac, Super on Linux) - also LGUI, RGUI
Alphanumeric
All letters A through Z and digits 0 through 9. Key names are always the unshifted character - whether the host sees uppercase or lowercase depends on whether SHIFT is in the combo and whether Caps Lock is active on the host.
Function Keys
F1 through F12. F13 through F24 are included for hosts that support the extended range - macOS uses some of these for system functions.
Navigation Keys
- ARROW_UP, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT
- HOME, END
- PAGE_UP, PAGE_DOWN
- INSERT
Action Keys
- ENTER (also RETURN)
- BACKSPACE
- DELETE
- TAB
- ESCAPE
- SPACE
- CAPS_LOCK, SCROLL_LOCK, NUM_LOCK
- PRINT_SCREEN, PAUSE
Media and Consumer Control Keys
These use the HID Consumer Control profile, a separate report type for media functions:
- VOLUME_UP, VOLUME_DOWN, MUTE
- PLAY_PAUSE, STOP
- NEXT_TRACK, PREV_TRACK
- BRIGHTNESS_UP, BRIGHTNESS_DOWN
Consumer control keys are broadly supported on Windows, macOS, iOS, and Android. Brightness controls work reliably on macOS; Windows and Linux support varies by hardware and may need additional configuration.
Numpad Keys
NUMPAD_0 through NUMPAD_9, NUMPAD_PLUS, NUMPAD_MINUS, NUMPAD_MULTIPLY, NUMPAD_DIVIDE, NUMPAD_ENTER, NUMPAD_DOT. Numpad-specific HID codes are useful for applications that treat numpad numbers differently from the main keyboard row numbers - common in accounting and data entry software.
Use Cases: Streaming, Productivity, Gaming, and More
Streaming and Content Creation
OBS Studio uses keyboard shortcuts for almost everything: start and stop recording, switch scenes, mute the microphone, toggle the webcam. Three buttons with short and long press detection gives you six actions - enough to cover the most common in-stream controls without reaching for the keyboard mid-stream.
A practical OBS layout:
- Button 1 short: start/stop streaming shortcut
- Button 1 long: start/stop recording shortcut
- Button 2 short: mute microphone shortcut
- Button 2 long: switch to fullscreen scene
- Button 3 short: switch to scene 1
- Button 3 long: switch to scene 2
The exact key bindings depend on your OBS hotkey configuration. The pattern generalizes to any streaming software with configurable shortcuts - Streamlabs, XSplit, Restream Studio.
Productivity Shortcuts
Copy, paste, undo - these get used hundreds of times in a workday. Mapping them to physical buttons reduces total finger travel and repetitive keystroke strain. Other high-value mappings include locking your workstation (GUI+L on Windows, CTRL+CMD+Q on macOS), triggering screenshots, and switching between windows.
For developers, save (CTRL+S), run/build (F5 in most IDEs), comment/uncomment (CTRL+/ in many editors), and terminal focus shortcuts are useful candidates. Identifying your most-used shortcuts and mapping the top six to the Mini Keypad saves time in aggregate across a full workday.
Gaming
Push-to-talk is a common mapping - dedicated physical feedback for a key you need to hit instantly without looking. Ability keybinds that land on awkward positions on the main keyboard, consumable use keys, or any action where tactile confirmation matters can go on the Nano.
This works best for keys you want immediate physical feedback on. The Nano's buttons are tactile and positioned so you can hit them without taking your eyes off the screen.
Creative Tools
Photoshop, Lightroom, Premiere, DaVinci Resolve - all have workflows that benefit from dedicated shortcut keys. Brush size up/down in Photoshop ([ and ]), rating adjustments in Lightroom, cut and ripple delete in Premiere, mark in/out in video editors. The specific combos depend on your workflow, but the pattern is the same: identify the shortcuts you reach for most often and give them physical buttons you can hit without losing flow.
Accessibility
For users dealing with repetitive strain or limited hand mobility, reducing the total input required for common operations has real ergonomic value. One button press instead of a three-key chord adds up over a full workday. The Nano can be positioned wherever it is most accessible, independent of keyboard placement.
Range, Battery, and Practical Notes
BLE 5.0 in a typical indoor environment gives you roughly 10 meters of reliable range. Walls and interference from other 2.4GHz devices reduce this, but for desk use it is a non-issue. Moving around a room - during a presentation or while working at a standing desk - staying within 6-7 meters of the paired host keeps the connection solid.
Battery consumption in Mini Keypad mode is low. BLE in connected HID mode draws around 10-25mA. With a 500mAh battery, you get many hours of active connection time before needing to charge via USB-C.
Pairing works the same as any Bluetooth keyboard: Bluetooth settings on Windows, System Preferences > Bluetooth on macOS, Bluetooth menu on iOS or Android. Once paired, the Nano reconnects automatically when the Mini Keypad app is active and the paired host is in range.
If you use multiple computers, BLE HID pairing is one-to-one. You can re-pair to a different host, but simultaneous connection to multiple hosts is not supported in standard BLE HID. The simplest workflow for multi-computer use is to clear the existing pairing and pair to whichever computer you want to use the Nano with at that moment.
The Mini Keypad app is one of several BLE utility apps on the BLEShark Nano. PC Monitor, Scroller, Media Controls, and Mini Keypad all share the same underlying BLE infrastructure. Switching between them from the main menu does not require re-pairing.
Mini Keypad in a Shiver Mesh Setup
The BLEShark Nano's ESP32-C3 has a single 2.4GHz radio shared between BLE and the Shiver mesh (which runs over ESP-NOW). Mesh communication between nodes runs over ESP-NOW - Espressif's connectionless WiFi protocol. BLE is used only for the initial pairing step; once paired, the radio operates exclusively in ESP-NOW mode. The two modes use the same radio and cannot run concurrently on a single device.
In a Shiver pack setup - the Nano is available in 3, 5, 7, 12, and 16-node packs - this is worth planning around. If your deployment uses multiple nodes and you also want one as a Mini Keypad, designate that specific node for BLE HID duty. The remaining nodes maintain the Shiver mesh and handle distributed tasks: coordinated WiFi scanning, multi-channel deauth detection, captive portal deployment, or whatever your current setup requires. The BLE node handles macro key functions independently.
sequenceDiagram
participant USR as User
participant BTN as Physical Button
participant FW as Nano Firmware
participant BLE as BLE HID Service
participant HOST as Host Computer
USR->>BTN: Press Button 2
BTN->>FW: GPIO interrupt fired
FW->>FW: Debounce check (10ms)
FW->>FW: Lookup macro for Button 2
Note over FW: Macro: Ctrl+V (Paste)
FW->>BLE: HID Report: Left Ctrl DOWN
BLE->>HOST: BLE notification (modifier)
FW->>BLE: HID Report: 'V' key DOWN
BLE->>HOST: BLE notification (key)
HOST->>HOST: OS processes Ctrl+V
HOST->>HOST: Paste from clipboard
FW->>BLE: HID Report: 'V' key UP
BLE->>HOST: BLE notification (release)
FW->>BLE: HID Report: Left Ctrl UP
BLE->>HOST: BLE notification (release)
Note over HOST: Paste complete in
active application
Macro execution sequence for a single button press - the firmware translates the physical input into a timed sequence of BLE HID reports
When you exit the Mini Keypad app and the BLE connection drops, the device returns to Shiver mesh operation. The configurations for each mode are stored separately and do not interfere with each other.
Get the BLEShark Nano