macromate-hid

Node.js library for communicating with MacroMate HID device (Pico RP2040-based).

Features

• 🎮 Full keyboard & mouse control via USB HID
• ⌨️ Key press, release, tap, and string typing
• 🖱️ Mouse movement, clicks, scrolling
• ⚡ Promise-based async API
• 📝 Full TypeScript support
• 🔧 CLI tool included

Installation

npm install macromate-hid

Or clone and link locally:

cd macromate-hid
npm install
npm link

Quick Start

const { MacroController, KEY, MOD, MOUSE_BTN } = require('macromate-hid');

async function main() {
    const controller = new MacroController();
    
    // Connect to device
    controller.connect();
    
    // Ping and get version
    const { version } = await controller.ping();
    console.log('Firmware:', version);
    
    // Type some text
    await controller.typeString('Hello, World!');
    
    // Press Ctrl+S to save
    await controller.shortcut(MOD.CTRL, KEY.S);
    
    // Move mouse and click
    await controller.mouseMove(100, 50);
    await controller.mouseClick();
    
    // Disconnect
    controller.disconnect();
}

main();

API Reference

Constructor

const controller = new MacroController({
    vid: 0xCAFE,      // Vendor ID (default: 0xCAFE)
    pid: 0x4010,      // Product ID (default: 0x4010)
    timeout: 2000,    // Command timeout in ms (default: 2000)
    debug: false      // Enable debug logging (default: false)
});

Connection

// Connect to device
controller.connect();

// Check if connected
if (controller.isConnected) { ... }

// Disconnect
controller.disconnect();

// Find all matching devices
const devices = MacroController.findDevices();

// List all devices with VID
const allDevices = MacroController.listDevices(0xCAFE);

System Commands

// Ping and get firmware version
const { version } = await controller.ping();

// Get version only
const version = await controller.getVersion();

// Enter bootloader mode (device will reboot)
controller.enterBootloader();

Keyboard

// Tap a key (press and release)
await controller.keyTap(KEY.A);
await controller.keyTap(KEY.ENTER);

// Press and hold a key
await controller.keyPress(KEY.SPACE);

// Release a key
await controller.keyRelease(KEY.SPACE);

// Set modifier keys
await controller.setModifiers(MOD.CTRL);
await controller.setModifiers(MOD.CTRL | MOD.SHIFT);

// Release all keys and modifiers
await controller.releaseAll();

// Type a string (ASCII, max 62 chars)
await controller.typeString('Hello!');

// Execute keyboard shortcut
await controller.shortcut(MOD.CTRL, KEY.C);  // Ctrl+C
await controller.shortcut(MOD.CTRL | MOD.SHIFT, KEY.S);  // Ctrl+Shift+S

Mouse

// Move mouse (relative, -127 to 127)
await controller.mouseMove(50, -30);

// Click
await controller.mouseClick();  // Left click
await controller.mouseClick(MOUSE_BTN.RIGHT);
await controller.mouseClick(MOUSE_BTN.MIDDLE);

// Press and hold
await controller.mousePress(MOUSE_BTN.LEFT);
await controller.mouseRelease(MOUSE_BTN.LEFT);

// Double click
await controller.mouseDoubleClick();

// Scroll (positive = up, negative = down)
await controller.mouseScroll(3);   // Scroll up
await controller.mouseScroll(-3);  // Scroll down

Raw Commands

// Send raw command
const result = await controller.sendCommand(0x00, [0x01, 0x02]);
console.log(result.status, result.data);

// Send command without waiting (for bootloader)
controller.sendCommandNoWait(0x02);

Constants

KEY - Keyboard Keycodes

const { KEY } = require('macromate-hid');

// Letters: KEY.A - KEY.Z
// Numbers: KEY.N0 - KEY.N9
// Function: KEY.F1 - KEY.F12
// Special: KEY.ENTER, KEY.ESC, KEY.BACKSPACE, KEY.TAB, KEY.SPACE
// Navigation: KEY.UP, KEY.DOWN, KEY.LEFT, KEY.RIGHT
// Etc: KEY.HOME, KEY.END, KEY.PAGE_UP, KEY.PAGE_DOWN, KEY.DELETE, KEY.INSERT

MOD - Modifier Keys

const { MOD } = require('macromate-hid');

MOD.CTRL   // 0x01
MOD.SHIFT  // 0x02
MOD.ALT    // 0x04
MOD.WIN    // 0x08

// Combine with |
const modifiers = MOD.CTRL | MOD.ALT;

MOUSE_BTN - Mouse Buttons

const { MOUSE_BTN } = require('macromate-hid');

MOUSE_BTN.LEFT    // 0x01
MOUSE_BTN.RIGHT   // 0x02
MOUSE_BTN.MIDDLE  // 0x04

CLI Tool

After installing, you can use the CLI tool:

npx macromate
# or if linked globally
macromate

The CLI provides an interactive menu for testing all device functions.

Examples

Auto-login Script

const { MacroController, KEY, MOD } = require('macromate-hid');

async function autoLogin(username, password) {
    const ctrl = new MacroController();
    ctrl.connect();
    
    // Type username
    await ctrl.typeString(username);
    await ctrl.keyTap(KEY.TAB);
    
    // Type password
    await ctrl.typeString(password);
    await ctrl.keyTap(KEY.ENTER);
    
    ctrl.disconnect();
}

Game Macro

const { MacroController, KEY } = require('macromate-hid');

async function burstFire(controller, times = 3) {
    for (let i = 0; i < times; i++) {
        await controller.mouseClick();
        await sleep(50);
    }
}

async function reload(controller) {
    await controller.keyTap(KEY.R);
}

Window Management

const { MacroController, KEY, MOD } = require('macromate-hid');

async function switchWindow(controller) {
    // Alt+Tab
    await controller.shortcut(MOD.ALT, KEY.TAB);
}

async function closeWindow(controller) {
    // Alt+F4
    await controller.shortcut(MOD.ALT, KEY.F4);
}

async function lockScreen(controller) {
    // Win+L
    await controller.shortcut(MOD.WIN, KEY.L);
}

Device Setup

1. Flash the MacroMate firmware to your Pico
2. Connect via USB
3. Device should appear as VID:CAFE PID:4010

Troubleshooting

Device not found

• Make sure device is connected and firmware is flashed
• Check USB connection
• On Linux, you may need udev rules for HID access

Permission denied (Linux)

Create udev rule /etc/udev/rules.d/99-macromate.rules:

SUBSYSTEM=="usb", ATTR{idVendor}=="cafe", ATTR{idProduct}=="4010", MODE="0666"
KERNEL=="hidraw*", ATTRS{idVendor}=="cafe", ATTRS{idProduct}=="4010", MODE="0666"

Then reload:

sudo udevadm control --reload-rules
sudo udevadm trigger

License

MIT