NuvKey User Guide – AIVA Robotics

No configuration software. No dedicated driver. Just edit a text file.

NuvKey is a programmable USB keyboard for normal keystrokes, shortcuts, media controls and text strings. Connect it normally to use your saved configuration. Hold KEY1 while connecting to edit its configuration through a USB drive.

Quick Start

Disconnect NuvKey from USB.
Hold KEY1 and connect the USB cable. Keep holding the key until the device connects, then release it.
Open the USB drive named NUVKEY.
Edit CONFIG.TXT with a plain-text editor and save it.
Wait for the green success indication and check STATUS.TXT for confirmation of the new save. Validation starts after about two seconds without further drive writes.
If an error is reported, correct the file and save again.
Eject the drive using your operating system, disconnect NuvKey, and reconnect without holding a key.

NuvKey now operates as a USB keyboard. The configuration drive is hidden during normal use.

Normal Mode and Configuration Mode

During normal operation, NuvKey uses standard USB HID keyboard and Consumer Control reports. No configuration application or background service is needed.

Holding KEY1 while connecting selects configuration mode instead. The blue LED blinks and the NUVKEY USB drive appears. The selected mode lasts until the device restarts; releasing KEY1 does not switch it back to keyboard mode.

File	Purpose
`CONFIG.TXT`	Your editable key assignments.
`STATUS.TXT`	Save confirmation or an error message, the active long-press timeout, and the numbers of keys with long-press actions.
`INFO.TXT`	Firmware version, physical row and column counts, and manufacturer information.
`README.HTM`	The user guide supplied with the installed firmware.

This is a small configuration drive. Keep backups on your computer and avoid storing unrelated files on it. Only CONFIG.TXT needs editing.

Configuring Keys

Keys are named KEY1, KEY2, and so on. Only keys physically present on your device can be configured. A four-key NuvKey accepts KEY1 through KEY4; other matrix sizes can support up to 49 keys.

KEY1=A
KEY2=ENTER
KEY3=SPACE
KEY4=ESC

Unassigned keys do nothing. If no valid saved configuration is available, all keys are silent until configured. Each normal assignment and each long-press assignment may appear only once.

Normal Keyboard Keys

Use letters A through Z, digits 0 through 9, or function keys F1 through F24. Common control and navigation names include:

ENTER ESC TAB SPACE BACKSPACE DELETE INSERT
HOME END PAGEUP PAGEDOWN UP DOWN LEFT RIGHT
CAPSLOCK PRINTSCREEN SCROLLLOCK PAUSE NUMLOCK

Use the spellings CAPSLOCK and PRINTSCREEN, without underscores. Punctuation key names include:

MINUS EQUAL LEFTBRACKET RIGHTBRACKET BACKSLASH
SEMICOLON QUOTE GRAVE COMMA PERIOD SLASH

Keypad names include KP0 through KP9, KP_DIVIDE, KP_MULTIPLY, KP_MINUS, KP_PLUS, KP_ENTER and KP_PERIOD. APPLICATION represents the application/menu key.

KEY1=A represents the physical A key. The character produced depends on Shift, Caps Lock and the host keyboard layout. To add Shift explicitly:

KEY1=SHIFT+A

Keyboard Shortcuts

Combine keys with + to send a chord:

KEY1=CTRL+C
KEY2=CTRL+V
KEY3=CTRL+SHIFT+ESC
KEY4=ALT+F4

Modifiers are CTRL, SHIFT, ALT and GUI. These use the left-side modifiers; explicit LCTRL, LSHIFT, LALT, LGUI, RCTRL, RSHIFT, RALT and RGUI are also supported. GUI normally corresponds to the Windows key on Windows and Command on macOS.

A chord can contain up to six distinct non-modifier keys plus modifiers. A chord is simultaneous, not a sequence of separate shortcuts. The effect of a shortcut depends on the active application and operating system.

Long-Press Actions

Add _LONG to a key name to assign an optional action for holding the key:

KEY1=CTRL+C
KEY1_LONG=CTRL+SHIFT+C

Here a short press sends CTRL+C, and a long press sends CTRL+SHIFT+C. Normal and long assignments are independently optional.

Long-Press Time

The global setting LONG_PRESS_MS sets the threshold in milliseconds for all keys with long actions:

LONG_PRESS_MS=600

If omitted, the threshold is 600 ms. Use a decimal whole number from 1 through 2147483647. Zero, signs, fractions, units such as ms, and repeated definitions are rejected. Practical values such as 500, 600 or 1000 make it easy to distinguish a tap from a hold.

Short Press and Long Press

KEY1=A
KEY1_LONG=B

On the initial press, NuvKey waits to distinguish short from long.
Release before the threshold to send the normal action once.
Reach the threshold to trigger the long action once for that physical press.
Releasing after a long trigger does not send the normal action.

Timing starts after key debouncing. A release observed exactly at the threshold counts as long. Each physical key is timed independently.

Keyboard and media actions selected by short/long detection are single press/release taps. Text is typed once. Long actions do not intentionally repeat while the physical key remains held. Action delivery can wait for earlier queued actions or USB availability; see Simultaneous Keys and Rapid Repeats below.

Long Press Only

KEY4_LONG=ESC

A short press does nothing. Holding KEY4 until the threshold triggers ESC once. No normal assignment is required.

Keys Without Long Press

KEY1=A
KEY2=B
KEY2_LONG=ESC

KEY1 keeps its normal immediate behavior: its keyboard action stays held until the physical key is released. Host key-repeat behavior can therefore apply. Only KEY2 waits to distinguish short from long. A normal TEXT action is triggered once on press.

Long-Press Action Types

Long actions use exactly the same syntax and supported commands as normal actions:

KEY1_LONG=CTRL+SHIFT+ESC
KEY2_LONG=MEDIA:MUTE
KEY3_LONG=TEXT:"Hello world!"
KEY4_LONG=F5

Media Controls

Use MEDIA: for USB Consumer Control commands. The supported commands are:

MEDIA:PLAY_PAUSE
MEDIA:STOP
MEDIA:NEXT_TRACK
MEDIA:PREV_TRACK
MEDIA:MUTE
MEDIA:VOLUME_UP
MEDIA:VOLUME_DOWN

KEY1=MEDIA:PLAY_PAUSE
KEY2=MEDIA:NEXT_TRACK
KEY3=MEDIA:VOLUME_UP
KEY4=MEDIA:VOLUME_DOWN

Use PLAY_PAUSE to toggle playback. Separate PLAY and PAUSE commands, FAST_FORWARD, REWIND, RECORD and EJECT are not supported by this firmware. PAUSE without the MEDIA prefix is the keyboard Pause/Break key.

For a key without a long action, its media command remains active while held. Whether holding it repeats an operation depends on the host. Short/long media actions are taps.

Typing Text

Enclose text in double quotation marks:

KEY1=TEXT:"Jonas"
KEY2=TEXT:"Hello world!"
KEY3=TEXT:"jonas@example.com"

Spaces and capitalization inside the quotes are preserved. NuvKey types the string into the currently focused application.

TEXT supports printable US ASCII characters and the escapes below. Accented letters, Swedish letters such as å, ä and ö, and other non-ASCII characters are rejected. The computer’s selected keyboard layout affects the result, especially punctuation. Use a US layout for matching TEXT output. Caps Lock can also change the resulting letter case.

Special Characters in TEXT

Sequence	Meaning
`\n`	Enter / new line
`\t`	Tab
`\b`	Backspace
`\"`	Double quotation mark
`\\`	Backslash

KEY1=TEXT:"Hello\nWorld"
KEY2=TEXT:"Name:\tJonas"
KEY3=TEXT:"He said \"Hello\""
KEY4=TEXT:"C:\\Users\\Jonas"

Use these escapes for control keys inside text. Other escapes are invalid.

Spaces, Case and Comments

Spaces and tabs around separators are ignored. These are equivalent alternatives; use only one assignment for KEY1:

KEY1=SHIFT+A
KEY1 = SHIFT+A
KEY1=SHIFT + A
Key1 = Shift + A

Command names are case-insensitive. Spaces are not allowed inside identifiers: KEY 1 and SH IFT are invalid. Spaces inside quoted text are preserved exactly.

Put comments on their own lines, beginning with #. A comment cannot follow an assignment on the same line.

# Copy and paste
KEY1=CTRL+C
KEY2=CTRL+V

# Media controls
KEY3=MEDIA:PLAY_PAUSE
KEY4=MEDIA:MUTE

Save as plain text. Windows, Unix and classic Mac line endings are accepted, as is an initial UTF-8 byte-order mark.

Example Configuration: Presentations

This four-key example suits presentation software that uses arrow keys, F5, Shift+F5, B and Escape. Confirm the shortcuts in your application.

# NuvKey configuration
# Optional: defaults to 600 ms
LONG_PRESS_MS=600

# Previous slide; hold to start from the beginning
KEY1=LEFT
KEY1_LONG=F5

# Next slide; hold to start from the current slide
KEY2=RIGHT
KEY2_LONG=SHIFT+F5

# Black screen during a presentation
KEY3=B

# Hold to exit; a short press does nothing
KEY4_LONG=ESC

Saving the Configuration

Save CONFIG.TXT normally in your plain-text editor.
Allow the editor to finish writing. NuvKey starts validation after about two seconds without further drive writes.
Wait for the green success indication and check STATUS.TXT for confirmation of this save. An immediate read may still show the previous status. Reopen the file or refresh the drive if the computer has cached it.
If validation fails, correct the reported error and save again. Invalid configuration text does not replace the previous working configuration.
After success, eject the drive, disconnect NuvKey and reconnect normally.

The saved actions are retained without power. When configuration mode is opened again, CONFIG.TXT is reconstructed from those actions: comments, original spacing and action order are not preserved. A default 600 ms timeout may be omitted from the reconstructed file.

If STATUS.TXT reports a Flash write or verification failure, save again and obtain a success indication before disconnecting. A failed or interrupted storage write can lose the previously saved configuration on restart. Keep a backup on your computer and avoid disconnecting while a save is in progress.

Common Configuration Errors

Example	Problem
`KEY1=FLY`	Unknown keyboard key.
`KEY1=TEXT:"Hello world`	Missing closing quotation mark.
`KEY1=TEXT:"Hello\qWorld"`	Unsupported TEXT escape.
`KEY5=ENTER` on a four-key device	The physical key does not exist.
Two `KEY1=...` lines, or two `KEY1_LONG=...` lines	Duplicate assignment. One normal and one long assignment for the same key are allowed.
`LONG_PRESS_MS=FAST` or `LONG_PRESS_MS=0`	Invalid timeout.
`KEY1=MEDIA:PLAY`	Unsupported media command; use a supported command such as PLAY_PAUSE.

Read STATUS.TXT for details and a line number where applicable. An unsupported command causes the candidate configuration to be rejected.

LED Status

LED	Meaning
Off	Normal keyboard operation.
Slow blue blink	Configuration mode.
Green for about one second	Configuration successfully accepted and saved.
Red blink	An error. In configuration mode, check STATUS.TXT.

After a successful save, the LED returns to the blue configuration indication. A red error indication persists until a later successful save or a restart.

Simultaneous Keys and Rapid Repeats

Held ordinary keyboard chords are combined, including their modifiers. More than six distinct non-modifier keys produces a rollover error report until enough keys are released.
Short/long keyboard taps combine with held ordinary chords; releasing a tap leaves the other keys held. An already-held key usage cannot produce another separate key-down until released.
When several ordinary media keys are held, the lowest-numbered one takes priority. Held ordinary media also delays queued media taps.
TEXT pauses between characters while an ordinary keyboard chord is held, then resumes after release.
TEXT and short/long actions share a queue of 49 triggers. Actions wait their turn; rapid triggering or long strings can delay later actions. New triggers are dropped if the queue is full.
USB delivery can add delay. USB disconnection or deconfiguration clears pending actions and long-press detection; press again after reconnecting.

Configuration Limits

CONFIG.TXT: up to 4096 bytes, including comments and formatting.
Each line: up to 256 bytes, excluding its line ending.
Command-name tokens: up to 31 bytes.
Decoded TEXT content: up to 2048 bytes in total, shared across normal and long actions.
Keyboard chords: up to six distinct non-modifier keys and eight modifiers.

The reconstructed configuration must also fit within 4096 bytes. A configuration that exceeds a limit is rejected. Large editor backup or temporary files can fill the small drive; keep other files on your computer.

Compatibility and Version Information

NuvKey is intended for operating systems with standard USB HID keyboard and Consumer Control support, including Windows, Linux and macOS. Application shortcuts, media handling and keyboard layouts vary between hosts. Mobile devices also need USB-host support and suitable connectivity.

Configuration uses USB Mass Storage and is intended primarily for desktop systems where CONFIG.TXT can be edited, saved and safely ejected. This is a report-protocol keyboard; BIOS boot-keyboard support is not provided.

Open INFO.TXT in configuration mode to check the firmware version and physical matrix dimensions. The guide in README.HTM belongs to the installed firmware; an online guide may describe a newer release.

Quick Reference

These are separate examples. Do not combine repeated assignments for the same key into one configuration.

# Normal key
KEY1=A

# Shortcut
KEY1=CTRL+SHIFT+ESC

# Text with Enter
KEY1=TEXT:"Hello\nWorld"

# Short and long actions
LONG_PRESS_MS=600
KEY1=CTRL+C
KEY1_LONG=F5

# Long press only
KEY2_LONG=MEDIA:MUTE

Configure, wait for success, eject, and reconnect normally. Your assignments stay with NuvKey.