User Manual 12-Key Macro Pad

Setup, configuration, open-source software, icons, scripts, RGB lighting, live PC stats, firmware updates, and troubleshooting for the NexMacro 12-key programmable macro pad with 2 rotary knobs and display.

12 Keys 2 Knobs Display Open Source RGB Scripts
Software Downloads

Download NexMacro Software

Install the NexMacro configuration app for your operating system, view the platform repositories, and download the separate PC Status Monitor app for live system information.

Windows note: Run the NexMacro app and PC Status Monitor app as administrator when using firmware tools, named pipe service, and live system stats.
Recommended

Windows App

Download the main NexMacro configuration app for Windows. Use this for profiles, key mapping, RGB, firmware tools, display settings, and named pipe service.

Download Windows App Windows Repo
Live Stats

PC Status Monitor

Download the separate monitor app used for live CPU, GPU, fan, disk, network, and uptime data. Enable named pipe service in the main NexMacro app first, then run this app as administrator.

Download Monitor App Github Repo
Coming Soon
macOS

macOS App

NexMacro software for macOS is planned. Windows is currently the recommended version for full setup, profiles, firmware tools, display settings, and live system stats.

macOS Coming Soon Repo Coming Soon
Coming Soon
Linux

Linux App

NexMacro software for Linux is planned. Windows is currently the recommended version for full setup, profiles, firmware tools, display settings, and live system stats.

Linux Coming Soon Repo Coming Soon
Device Firmware

Firmware Releases

Download official NexMacro firmware files. Each release includes the required .bin firmware file and matching .json configuration file.

Latest Stable v1.1 28 May 2026
Use the .bin and .json files from the same version only.
NexMacro Guide

Introduction

NexMacro is a 12-key programmable macro pad with 2 rotary knobs and a display. It is designed for creators, developers, gamers, streamers, students, and productivity users who want faster control over their desktop setup without relying only on menus, mouse movement, or memorised shortcuts.

This manual covers the core setup process, software use, RGB control, icon customisation, background images, scripts, firmware updates, factory reset, and troubleshooting.

Fast Workflow

Assign actions to physical keys so repeated tasks are only one tap away.

Visual Profiles

Use the display to show profiles, icons, backgrounds, shortcuts, and system information.

Open Software

Use open-source software and official GitHub releases for updates, issues, and improvements.

Hardware

Product Overview

NexMacro combines programmable mechanical keys, rotary controls, and visual display feedback in one compact control surface. The 12 keys are suited to shortcuts, text, scripts, media controls, profile changes, and app actions. The two knobs are suited to volume, scrolling, zooming, timeline movement, brush size, tab switching, and other continuous controls.

Labelled diagram of the NexMacro 12-key macro pad showing the USB-C port, display, 12 keys, two knobs, and switch layout
  • 12 programmable keys: Shortcuts, scripts, text, media, profile control, and macros.
  • 2 rotary knobs: Rotation and press actions for fast physical control.
  • Large display: Shows profiles, icons, labels, backgrounds, and live status information.
  • USB-C connection: Connects to your computer using a USB-C data cable.
  • Hot-swappable switches: Change compatible mechanical switches without soldering.
  • Open-source software: Configure, improve, and update through official NexMacro software and GitHub resources.
Device Details

Specifications

Specification Details
Product NexMacro 12-Key Programmable Macro Pad with Display
Keys 12 programmable mechanical keys
Rotary Controls 2 rotary knobs with rotation and press input
Display Large colour display for profiles, icons, labels, backgrounds, and system information
Interface USB-C data connection
Power USB bus-powered
Profiles Multiple programmable profiles supported through software
Actions Shortcuts, scripts, text input, media controls, mouse actions, profile changes, app actions, and macros
PC Status Monitoring Supported through compatible NexMacro companion software
Software Open-source NexMacro configuration software and official release tools
Operating Systems Windows, macOS, Linux, and HID-compatible systems depending on feature mode
System Support

Compatibility

NexMacro works as a USB input device. Basic keyboard, mouse, and media actions can work through standard HID-style input. Advanced features such as app launching, live PC stats, firmware updates, display syncing, and some automation features may require the NexMacro configuration app or companion software.

Windows

Recommended for the full feature set, including live PC stats, firmware updates, and app actions.

macOS

Suitable for standard shortcuts, media controls, profile use, and supported configuration features.

Linux

Suitable for HID-style inputs and supported open-source workflows depending on software support.

First Setup

Getting Started

  1. Connect NexMacro to your computer using a USB-C data cable.
  2. Wait for your computer to detect the device.
  3. Download or open the official NexMacro configuration software.
  4. On Windows, right-click the app and select Run as administrator.
  5. Select the connected NexMacro device inside the app.
  6. Create or edit your first profile.
  7. Assign simple test actions such as copy, paste, volume, mute, screenshot, or profile switching.
  8. Save or sync the profile to the device.

Recommended First Test

Start simple. Assign one key to copy, one key to paste, one knob to volume, and one key to switch profiles. Once this works, move into scripts, icons, app launching, RGB, backgrounds, and live PC stats.

Important Windows Note

Run as Administrator

On Windows, some functions require extra permissions. Run the NexMacro configuration app as administrator when using firmware updates, PC status monitoring, app launching, local file actions, or advanced system-level controls.

How to Run as Administrator

  1. Find the NexMacro configuration app.
  2. Right-click the app icon.
  3. Select Run as administrator.
  4. Click Yes when Windows asks for permission.
  5. Connect your NexMacro device and confirm it appears in the app.
View NexMacro on GitHub Download Releases Report an Issue
Software Guide

Configuration App

The configuration app is used to assign keys, configure knobs, create profiles, customise icons, change RGB lighting, update firmware, sync display settings, and enable advanced features.

NexMacro configuration app showing RGB lighting settings, trigger modes, profiles, and macro pad setup options

Typical Workflow

  1. Open the configuration app.
  2. Select your connected NexMacro device.
  3. Choose the profile you want to edit.
  4. Select a key, knob, display setting, or lighting setting.
  5. Assign actions or adjust settings.
  6. Click save, sync, or write to device.
Lighting

How to Change RGB Light

NexMacro supports RGB lighting control through the configuration app. You can change the RGB colour, choose different lighting behaviours, and save different effects per profile depending on your setup and firmware version.

The RGB settings include different trigger modes so the lighting can behave differently depending on how you want the macro pad to look on your desk.

Available RGB Modes

Always OnThe selected RGB colour stays on continuously.
When Pressing The KeyThe light activates when a key is pressed.
BreathThe light softly fades in and out.
FlowingThe lighting animates in a flowing effect.
Always OffThe RGB lighting stays disabled.
  1. Open the NexMacro configuration app.
  2. Run as administrator on Windows if lighting settings do not save.
  3. Select your connected NexMacro device from the device list.
  4. Open the RGB, lighting, or device settings panel.
  5. Choose your colour.
  6. Select the trigger mode you want, such as Always On, Breath, or Flowing.
  7. Adjust any extra settings like brightness or effect behaviour if available.
  8. Click save or sync to apply the lighting to the device.
NexMacro configuration app showing RGB lighting settings, trigger modes, profiles, and macro pad setup options

Tip

Use different RGB colours and modes for different profiles. For example, purple in Always On for everyday use, blue in Breath for creator mode, and red in When Pressing The Key for gaming mode.

Display Visuals

How to Customise Key Icons

Custom icons make each profile easier to understand at a glance. You can use icons for apps, games, tools, shortcuts, scripts, media controls, or workflow categories.

Icon File Requirements

NexMacro key icons must be uploaded as .png image files and should be exactly 64 × 64 pixels in size. Using the correct image size helps icons display clearly on the macro pad screen without stretching, cropping, or quality loss.

  1. Open the NexMacro configuration app.
  2. Select the profile you want to edit.
  3. Select the key you want to customise.
  4. Choose the icon or image option.
  5. Upload a 64 × 64 pixel .png icon file.
  6. Preview the display layout.
  7. Save or sync the profile to the device.

Icon Recommendations

  • Use 64 × 64 pixel images for key icons.
  • Use .png format only.
  • Use clear, high-contrast images.
  • Avoid tiny text inside icons.
  • Use consistent icon styles across each profile.
  • Keep important shortcuts visually distinct.
NexMacro configuration app showing custom 64 by 64 PNG key icons for macro pad profiles
Screen Layout

Customise Background Image

NexMacro background images are stored on the device as binary image files. To change the background, replace the existing bg_dark.bin or bg_bright.bin file inside the app_icons folder on the device mass storage.

The filename you replace depends on the theme currently used by your device. If your device is using the dark theme, replace bg_dark.bin. If your device is using the bright theme, replace bg_bright.bin.

Before You Copy the Image

Your image must be converted into the correct LVGL binary format before it is placed on the device. Standard image files such as PNG or JPG should not be copied directly as the background file. Use the official LVGL Image Converter to convert the image first.

Open LVGL Image Converter

LVGL Image Converter Settings

  1. Open the LVGL Image Converter.
  2. Select the LVGL v8 tab.
  3. Click Select image file(s) and upload your background image.
  4. Set Color format to CF_INDEXED_4_BIT.
  5. Set Output format to Binary RGB565.
  6. Leave Dither images unchecked unless you are testing quality improvements.
  7. Leave Output in big-endian format unchecked.
  8. Do not enable extra alpha settings unless the firmware specifically requires transparency.
  9. Convert the image and download the generated binary file.

Copy the Background to the Device

  1. Connect NexMacro to your computer so the device mass storage appears.
  2. Open the device drive.
  3. Open the app_icons folder.
  4. Rename your converted binary file to either bg_dark.bin or bg_bright.bin.
  5. Copy the renamed file into the app_icons folder.
  6. Replace the old file when your computer asks for confirmation.
  7. Safely eject the device from your computer.
  8. Restart or reconnect NexMacro so the new background can load.

Important File Names

The background file must keep the correct filename. Use bg_dark.bin for the dark theme and bg_bright.bin for the bright theme. If the filename is different, the device may not load the new background.

LVGL Image Converter settings showing LVGL v8, CF_INDEXED_4_BIT color format, and Binary RGB565 output format
Monitoring

How to Enable PC Status Monitoring

PC status monitoring lets NexMacro show live system information on the device display. This feature uses a separate PC status monitor app that connects to the main NexMacro app through the named pipe service.

To use live status information, first enable the named pipe service inside the NexMacro app settings. Then open the separate PC status monitor app as administrator. Once both apps are running correctly, the monitor app will connect and send live system data to NexMacro.

Supported Live Status Information

  • CPU temperature
  • GPU temperature
  • CPU usage
  • GPU usage
  • CPU and GPU power usage
  • CPU and GPU fan speed
  • Disk space
  • Network upload and download speed
  • System uptime

Setup Steps

  1. Connect NexMacro to your computer using USB-C.
  2. Open the main NexMacro app.
  3. Open the app settings.
  4. Enable Named Pipe Service.
  5. Save or apply the setting if required.
  6. Open the separate PC Status Monitor app.
  7. On Windows, right-click the PC Status Monitor app and select Run as administrator.
  8. Wait for the PC Status Monitor app to connect to the NexMacro app through the named pipe service.
  9. Once connected, choose or enable the system stats you want to display.
  10. Keep the PC Status Monitor app running in the background while using live status information.

Important

Live system stats require the main NexMacro app and the separate PC Status Monitor app to communicate with each other. If live stats are not showing, confirm that Named Pipe Service is enabled in the NexMacro app settings and that the PC Status Monitor app is running as administrator.

Advanced Control

Script Usage

Scripts allow a key to perform a sequence of actions, such as pressing keyboard shortcuts, typing text, opening a website, clicking the mouse, moving the cursor, waiting between actions, or switching profiles. This is useful for repetitive workflows and multi-step commands.

Example: Open a Website

WINDOWS r DELAY 500 STRING www.nexmacro.com ENTER

Example: Screenshot Shortcut

WINDOWS SHIFT s

Example: Double Left Click

LMOUSE REPEAT 1

Script Safety

Test scripts slowly before using them in important workflows. Scripts can type, click, open apps, or run shortcuts quickly, so make sure each command does exactly what you expect.

Reference

Supported Script Commands

Command Function Example
DELAY Pauses script execution for a set number of milliseconds. DELAY 500
STRING Types text as keyboard input. STRING hello world
REPEAT Repeats the previous script line. REPEAT 1
MOUSE_MOVE Moves the mouse cursor by X and Y values. MOUSE_MOVE 100 -20
LMOUSE Left mouse click. LMOUSE
MMOUSE Middle mouse click. MMOUSE
RMOUSE Right mouse click. RMOUSE
GOTO_PROFILE Switches to a specific profile index. GOTO_PROFILE 5
PREV_PROFILE Switches to the previous profile. PREV_PROFILE
NEXT_PROFILE Switches to the next profile. NEXT_PROFILE
DEFAULTDURATION Sets the delay between pressing and releasing a single key. DEFAULTDURATION 35
DEFAULTCHARDELAY Sets the delay between characters when typing strings. DEFAULTCHARDELAY 35
DEFAULTDELAY Sets the delay between script lines. DEFAULTDELAY 35

Global Delay Note

Default delay settings can affect future script execution and may remain stored after powering off, depending on firmware behaviour. Avoid extremely low delay values if an app or game detects very fast input as non-human input.

Reference

Special Function Keys

Category Supported Keywords
Modifier Keys CONTROL, SHIFT, ALT, WINDOWS, COMMAND, OPTION
Navigation / Editing ESC, ENTER, UP, DOWN, LEFT, RIGHT, SPACE, BACKSPACE, TAB, INSERT, DELETE, HOME, END, PAGEUP, PAGEDOWN
System Keys PRINTSCREEN, SCROLLLOCK, PAUSE, BREAK, MENU, POWER
Function Keys F1 through F24
Media Keys VOLUP, VOLDOWN, MUTE, PREV, NEXT, PP, STOP
Numeric Keypad NUMLOCK, KP_SLASH, KP_ASTERISK, KP_MINUS, KP_PLUS, KP_ENTER, KP_DOT, KP_EQUAL, KP_0 through KP_9

Common Shortcut Examples

Function Script
Copy CONTROL c
Paste CONTROL v
Task Manager CONTROL SHIFT ESC
Windows Screenshot WINDOWS SHIFT s
Open Run Dialog WINDOWS r
Updates

Upgrade Firmware

Firmware updates can add features, improve compatibility, fix bugs, and improve device behaviour. Always use the latest official NexMacro firmware files when updating the device.

Before Updating

  • Download the latest official NexMacro firmware files.
  • Make sure you have both the .bin firmware file and the matching .json configuration file.
  • Use a reliable USB-C data cable.
  • Connect the NexMacro device directly to your computer where possible.
  • Do not disconnect the device while copying files or while the upgrade is running.
  • Export or backup profiles if the software supports it.

Update Steps

  1. Connect the NexMacro device to your computer using USB-C.
  2. Open the device disk or mass storage drive when it appears on your computer.
  3. Copy the latest .bin firmware file and matching .json configuration file into the root directory of the device disk.
  4. If older firmware files already exist in the root directory, replace them with the new files.
  5. Open the NexMacro configuration app.
  6. Go to the firmware update or upgrade option inside the app.
  7. Click Upgrade.
  8. If the app prompts you to copy the firmware files first, confirm that the .bin and .json files have already been copied to the root of the device disk.
  9. Wait for the app to complete the upgrade process.
  10. Do not unplug the device until the app confirms the update has finished.
  11. After the update is complete, safely eject the device if required, then disconnect and reconnect it normally.

Important

A factory reset is not normally required for a firmware upgrade. Only use factory reset in an emergency situation, such as when the device cannot boot correctly because of incorrect icon files, background files, or other broken device storage files.

Root Directory Note

The root directory means the first/main folder that opens when you access the NexMacro device disk. Do not place the .bin or .json firmware files inside the app_icons folder or another subfolder unless official instructions specifically say to do so.

Advanced Setup

How to Configure NexMacro Locally

Local configuration means editing and saving your device setup directly from your computer without relying on cloud-based configuration. This is useful for privacy, faster testing, offline setup, or developer workflows.

  1. Download the official NexMacro configuration app or release package.
  2. Connect NexMacro by USB-C.
  3. Open the app locally on your computer.
  4. Select your device from the list.
  5. Edit profiles, keys, knobs, icons, RGB, and display settings.
  6. Save the configuration to the device.
Recovery

Restore to Factory Settings

A factory reset can help when profiles, display settings, RGB settings, scripts, or saved layouts are not working as expected. Resetting may remove saved profiles and custom settings, so export your configuration first if possible.

  1. Disconnect the NexMacro device from your computer.
  2. Hold down the first rotary knob.
  3. While continuing to hold the first knob, connect the device to your computer using USB-C.
  4. Keep holding the first knob for around 5 seconds while the device boots.
  5. Release the knob after 10 seconds.
  6. The device will restore to factory settings.
  7. Wait for the device to finish restarting.
  8. Reconnect the device if needed, then open the NexMacro configuration app to set up your profiles again.

Warning

Factory reset will remove custom profiles, icons, RGB settings, scripts, display backgrounds, and saved layouts. Export your setup before resetting if you want to restore it later.

Trust & Safety

Security Concern

Macro pads can send keyboard, mouse, and shortcut inputs quickly. Only download software, firmware, presets, and scripts from trusted NexMacro sources. Be careful with scripts from unknown users because scripts may type commands, open websites, launch apps, or perform repeated actions.

  • Download software only from official NexMacro links or GitHub releases.
  • Review scripts before importing or running them.
  • Do not run unknown scripts that open system tools or execute commands.
  • Use administrator mode only when needed.
  • Keep firmware and software updated from official releases.
Fixes

Troubleshooting

Device Not Recognised

  1. Try a different USB-C data cable.
  2. Use a different USB port.
  3. Connect directly to the computer instead of a hub.
  4. Restart your computer.
  5. Open the app as administrator.
  6. Refresh the device list.

Keys Not Working

  1. Check the active profile.
  2. Confirm the key has an assigned action.
  3. Save or sync the profile again.
  4. Test with a simple shortcut before using scripts.
  5. If switches were changed, confirm the switch is seated correctly.

RGB Not Changing

  1. Check RGB settings in the app.
  2. Confirm brightness is not set to zero.
  3. Save or sync lighting settings again.
  4. Try a different RGB mode.
  5. Update firmware if lighting options do not work.

PC Stats Not Showing

  1. Keep the companion software open.
  2. Run the app as administrator on Windows.
  3. Enable the correct stats in the app.
  4. Check hardware sensor support.
  5. Reconnect the device and restart the app.

Firmware Update Fails

  1. Use a direct USB connection.
  2. Use a different USB-C data cable.
  3. Close other device software.
  4. Run the app as administrator.
  5. Try again with the latest official firmware file.
Help

Support

Use official NexMacro channels for software downloads, GitHub releases, presets, firmware updates, setup guides, troubleshooting, and community help.

NexMacro Website GitHub Join Discord
Thank you for choosing NexMacro.
This manual is for the NexMacro 12-Key Programmable Macro Pad with 2 Knobs and Display. Features, software, firmware, and interface details may change as the open-source software improves.