macromate-hid 1.0.0-beta.1

package/src/constants.js

@@ -0,0 +1,106 @@
+/**
+ * MacroMate HID Constants
+ * Protocol constants for MacroMate device
+ */
+
+// Device config
+const VID = 0xCAFE;
+const PID = 0x4010;
+const VENDOR_USAGE_PAGE = 0xFF00;
+const REPORT_ID_VENDOR = 3;
+const DEFAULT_TIMEOUT = 2000;  // ms
+const TYPE_STRING_TIMEOUT = 10000;  // ms
+
+// Commands (from protocol.h)
+const CMD = {
+    PING:            0x00,
+    GET_VERSION:     0x01,
+    BOOTLOADER:      0x02,
+    KEY_PRESS:       0x10,
+    KEY_RELEASE:     0x11,
+    KEY_TAP:         0x12,
+    KEY_MODIFIER:    0x13,
+    KEY_RELEASE_ALL: 0x14,
+    KEY_TYPE_STRING: 0x15,
+    MOUSE_MOVE:      0x30,
+    MOUSE_CLICK:     0x32,
+    MOUSE_PRESS:     0x33,
+    MOUSE_RELEASE:   0x34,
+    MOUSE_SCROLL:    0x35,
+    DELAY:           0x50,
+};
+
+// Mouse buttons
+const MOUSE_BTN = {
+    LEFT:   0x01,
+    RIGHT:  0x02,
+    MIDDLE: 0x04
+};
+
+// Keyboard modifiers
+const MOD = {
+    CTRL:  0x01,
+    SHIFT: 0x02,
+    ALT:   0x04,
+    WIN:   0x08
+};
+
+// HID Keycodes
+const KEY = {
+    // Letters
+    A: 0x04, B: 0x05, C: 0x06, D: 0x07, E: 0x08, F: 0x09, G: 0x0A, H: 0x0B,
+    I: 0x0C, J: 0x0D, K: 0x0E, L: 0x0F, M: 0x10, N: 0x11, O: 0x12, P: 0x13,
+    Q: 0x14, R: 0x15, S: 0x16, T: 0x17, U: 0x18, V: 0x19, W: 0x1A, X: 0x1B,
+    Y: 0x1C, Z: 0x1D,
+    
+    // Numbers
+    N1: 0x1E, N2: 0x1F, N3: 0x20, N4: 0x21, N5: 0x22, 
+    N6: 0x23, N7: 0x24, N8: 0x25, N9: 0x26, N0: 0x27,
+    
+    // Special keys
+    ENTER: 0x28, ESC: 0x29, BACKSPACE: 0x2A, TAB: 0x2B, SPACE: 0x2C,
+    MINUS: 0x2D, EQUAL: 0x2E, BRACKET_LEFT: 0x2F, BRACKET_RIGHT: 0x30,
+    BACKSLASH: 0x31, SEMICOLON: 0x33, QUOTE: 0x34, GRAVE: 0x35,
+    COMMA: 0x36, PERIOD: 0x37, SLASH: 0x38, CAPS_LOCK: 0x39,
+    
+    // Function keys
+    F1: 0x3A, F2: 0x3B, F3: 0x3C, F4: 0x3D, F5: 0x3E, F6: 0x3F,
+    F7: 0x40, F8: 0x41, F9: 0x42, F10: 0x43, F11: 0x44, F12: 0x45,
+    
+    // Navigation
+    PRINT_SCREEN: 0x46, SCROLL_LOCK: 0x47, PAUSE: 0x48,
+    INSERT: 0x49, HOME: 0x4A, PAGE_UP: 0x4B,
+    DELETE: 0x4C, END: 0x4D, PAGE_DOWN: 0x4E,
+    RIGHT: 0x4F, LEFT: 0x50, DOWN: 0x51, UP: 0x52,
+    
+    // Numpad
+    NUM_LOCK: 0x53, NUMPAD_SLASH: 0x54, NUMPAD_ASTERISK: 0x55,
+    NUMPAD_MINUS: 0x56, NUMPAD_PLUS: 0x57, NUMPAD_ENTER: 0x58,
+    NUMPAD_1: 0x59, NUMPAD_2: 0x5A, NUMPAD_3: 0x5B,
+    NUMPAD_4: 0x5C, NUMPAD_5: 0x5D, NUMPAD_6: 0x5E,
+    NUMPAD_7: 0x5F, NUMPAD_8: 0x60, NUMPAD_9: 0x61,
+    NUMPAD_0: 0x62, NUMPAD_PERIOD: 0x63,
+};
+
+// Status codes
+const STATUS = {
+    OK:              0x00,
+    ERROR_UNKNOWN:   0x01,
+    ERROR_INVALID:   0x02,
+    ERROR_OVERFLOW:  0x03,
+};
+
+module.exports = {
+    VID,
+    PID,
+    VENDOR_USAGE_PAGE,
+    REPORT_ID_VENDOR,
+    DEFAULT_TIMEOUT,
+    TYPE_STRING_TIMEOUT,
+    CMD,
+    MOUSE_BTN,
+    MOD,
+    KEY,
+    STATUS,
+};
+

package/src/controller.js

@@ -0,0 +1,387 @@
+/**
+ * MacroController - Main class for communicating with MacroMate device
+ * Promise-based API with async/await support
+ */
+
+const HID = require('node-hid');
+const {
+    VID, PID, VENDOR_USAGE_PAGE, REPORT_ID_VENDOR,
+    DEFAULT_TIMEOUT, TYPE_STRING_TIMEOUT,
+    CMD, MOUSE_BTN, MOD, KEY, STATUS
+} = require('./constants');
+
+class MacroController {
+    /**
+     * Create a MacroController instance
+     * @param {Object} options - Configuration options
+     * @param {number} [options.vid=0xCAFE] - Vendor ID
+     * @param {number} [options.pid=0x4010] - Product ID
+     * @param {number} [options.timeout=2000] - Default command timeout (ms)
+     * @param {boolean} [options.debug=false] - Enable debug logging
+     */
+    constructor(options = {}) {
+        this.vid = options.vid || VID;
+        this.pid = options.pid || PID;
+        this.timeout = options.timeout || DEFAULT_TIMEOUT;
+        this.debug = options.debug || false;
+        this.device = null;
+        this.deviceInfo = null;
+    }
+
+    /**
+     * Log debug messages
+     * @private
+     */
+    _log(...args) {
+        if (this.debug) {
+            console.log('[MacroController]', ...args);
+        }
+    }
+
+    /**
+     * Find all matching devices
+     * @returns {Array} Array of device info objects
+     */
+    static findDevices(vid = VID, pid = PID) {
+        const devices = HID.devices();
+        return devices.filter(d =>
+            d.vendorId === vid &&
+            d.productId === pid &&
+            d.usagePage === VENDOR_USAGE_PAGE
+        );
+    }
+
+    /**
+     * List all HID devices with the specified VID
+     * @param {number} [vid=0xCAFE] - Vendor ID to filter by
+     * @returns {Array} Array of device info objects
+     */
+    static listDevices(vid = VID) {
+        return HID.devices().filter(d => d.vendorId === vid);
+    }
+
+    /**
+     * Check if device is connected
+     * @returns {boolean}
+     */
+    get isConnected() {
+        return this.device !== null;
+    }
+
+    /**
+     * Connect to the device
+     * @returns {boolean} True if connected successfully
+     * @throws {Error} If device not found or connection failed
+     */
+    connect() {
+        const devices = HID.devices();
+        
+        this.deviceInfo = devices.find(d =>
+            d.vendorId === this.vid &&
+            d.productId === this.pid &&
+            d.usagePage === VENDOR_USAGE_PAGE
+        );
+
+        if (!this.deviceInfo) {
+            throw new Error(`Device not found (VID=0x${this.vid.toString(16)} PID=0x${this.pid.toString(16)})`);
+        }
+
+        this._log('Found device:', this.deviceInfo.product, this.deviceInfo.path);
+
+        try {
+            this.device = new HID.HID(this.deviceInfo.path);
+            this._log('Connected successfully');
+            
+            this.device.on('error', (err) => {
+                this._log('HID Error:', err.message);
+            });
+            
+            return true;
+        } catch (e) {
+            throw new Error(`Connection failed: ${e.message}`);
+        }
+    }
+
+    /**
+     * Disconnect from the device
+     */
+    disconnect() {
+        if (this.device) {
+            this.device.close();
+            this.device = null;
+            this.deviceInfo = null;
+            this._log('Disconnected');
+        }
+    }
+
+    /**
+     * Send a raw command to the device
+     * @param {number} cmd - Command byte
+     * @param {number[]} args - Command arguments
+     * @param {Object} options - Options
+     * @param {number} [options.timeout] - Command timeout (ms)
+     * @returns {Promise<{status: number, data: Buffer}>}
+     */
+    sendCommand(cmd, args = [], options = {}) {
+        const timeout = options.timeout || this.timeout;
+
+        return new Promise((resolve, reject) => {
+            if (!this.device) {
+                reject(new Error('Device not connected'));
+                return;
+            }
+
+            // Build packet
+            const packet = Buffer.alloc(64);
+            packet[0] = cmd;
+            args.forEach((arg, i) => {
+                packet[1 + i] = arg & 0xFF;
+            });
+
+            // Set up timeout
+            const timeoutId = setTimeout(() => {
+                reject(new Error('Command timeout'));
+            }, timeout);
+
+            // Set up read callback BEFORE writing
+            this.device.read((err, data) => {
+                clearTimeout(timeoutId);
+
+                if (err) {
+                    reject(err);
+                    return;
+                }
+
+                if (data && data.length > 0) {
+                    // First byte is Report ID (0x03), skip it
+                    const payload = data.slice(1);
+                    const status = payload[0];
+
+                    this._log(`Response: status=${status === 0 ? 'OK' : 'ERROR ' + status}`);
+
+                    resolve({ status, data: Buffer.from(payload) });
+                } else {
+                    reject(new Error('Empty response'));
+                }
+            });
+
+            // Send the command
+            try {
+                this.device.write([REPORT_ID_VENDOR, ...packet]);
+                this._log(`Sent cmd=0x${cmd.toString(16).padStart(2, '0')} args=[${args.map(a => '0x' + a.toString(16)).join(', ')}]`);
+            } catch (e) {
+                clearTimeout(timeoutId);
+                reject(e);
+            }
+        });
+    }
+
+    /**
+     * Send command without waiting for response (for bootloader)
+     * @param {number} cmd - Command byte
+     * @param {number[]} args - Command arguments
+     */
+    sendCommandNoWait(cmd, args = []) {
+        if (!this.device) {
+            throw new Error('Device not connected');
+        }
+
+        const packet = Buffer.alloc(64);
+        packet[0] = cmd;
+        args.forEach((arg, i) => {
+            packet[1 + i] = arg & 0xFF;
+        });
+
+        this.device.write([REPORT_ID_VENDOR, ...packet]);
+        this._log(`Sent (no wait) cmd=0x${cmd.toString(16).padStart(2, '0')}`);
+    }
+
+    // ============================================================
+    // HIGH-LEVEL API
+    // ============================================================
+
+    /**
+     * Ping the device
+     * @returns {Promise<{version: string}>} Firmware version
+     */
+    async ping() {
+        const result = await this.sendCommand(CMD.PING);
+        
+        // Check for PONG response
+        if (result.data[1] === 0x50 && result.data[2] === 0x4F && 
+            result.data[3] === 0x4E && result.data[4] === 0x47) {
+            return {
+                version: `${result.data[5]}.${result.data[6]}.${result.data[7]}`
+            };
+        }
+        
+        return { version: 'unknown' };
+    }
+
+    /**
+     * Get firmware version
+     * @returns {Promise<string>} Version string (e.g., "1.0.0")
+     */
+    async getVersion() {
+        const result = await this.sendCommand(CMD.GET_VERSION);
+        return `${result.data[1]}.${result.data[2]}.${result.data[3]}`;
+    }
+
+    /**
+     * Enter bootloader mode (device will reboot)
+     * Connection will be lost after this command
+     */
+    enterBootloader() {
+        this.sendCommandNoWait(CMD.BOOTLOADER);
+    }
+
+    // ============================================================
+    // KEYBOARD API
+    // ============================================================
+
+    /**
+     * Press a key (and hold)
+     * @param {number} keycode - HID keycode (use KEY constants)
+     */
+    async keyPress(keycode) {
+        await this.sendCommand(CMD.KEY_PRESS, [keycode]);
+    }
+
+    /**
+     * Release a key
+     * @param {number} keycode - HID keycode
+     */
+    async keyRelease(keycode) {
+        await this.sendCommand(CMD.KEY_RELEASE, [keycode]);
+    }
+
+    /**
+     * Tap a key (press and release)
+     * @param {number} keycode - HID keycode
+     */
+    async keyTap(keycode) {
+        await this.sendCommand(CMD.KEY_TAP, [keycode]);
+    }
+
+    /**
+     * Set modifier keys (Ctrl, Shift, Alt, Win)
+     * @param {number} modifiers - Modifier flags (use MOD constants, can be combined with |)
+     */
+    async setModifiers(modifiers) {
+        await this.sendCommand(CMD.KEY_MODIFIER, [modifiers]);
+    }
+
+    /**
+     * Release all keys and modifiers
+     */
+    async releaseAll() {
+        await this.sendCommand(CMD.KEY_RELEASE_ALL);
+    }
+
+    /**
+     * Type a string (ASCII only)
+     * @param {string} text - Text to type (max 62 characters per call)
+     */
+    async typeString(text) {
+        const bytes = Buffer.from(text, 'ascii');
+        const len = Math.min(bytes.length, 62);
+        await this.sendCommand(
+            CMD.KEY_TYPE_STRING,
+            [len, ...bytes.slice(0, len)],
+            { timeout: TYPE_STRING_TIMEOUT }
+        );
+    }
+
+    /**
+     * Execute a keyboard shortcut (e.g., Ctrl+C)
+     * @param {number} modifiers - Modifier flags
+     * @param {number} keycode - HID keycode
+     */
+    async shortcut(modifiers, keycode) {
+        await this.setModifiers(modifiers);
+        await this.keyTap(keycode);
+        await this.releaseAll();
+    }
+
+    // ============================================================
+    // MOUSE API
+    // ============================================================
+
+    /**
+     * Move mouse relative to current position
+     * @param {number} x - X movement (-127 to 127)
+     * @param {number} y - Y movement (-127 to 127)
+     */
+    async mouseMove(x, y) {
+        // Convert signed to unsigned byte
+        await this.sendCommand(CMD.MOUSE_MOVE, [x & 0xFF, y & 0xFF]);
+    }
+
+    /**
+     * Click a mouse button
+     * @param {number} [button=MOUSE_BTN.LEFT] - Button to click
+     */
+    async mouseClick(button = MOUSE_BTN.LEFT) {
+        await this.sendCommand(CMD.MOUSE_CLICK, [button]);
+    }
+
+    /**
+     * Press a mouse button (and hold)
+     * @param {number} [button=MOUSE_BTN.LEFT] - Button to press
+     */
+    async mousePress(button = MOUSE_BTN.LEFT) {
+        await this.sendCommand(CMD.MOUSE_PRESS, [button]);
+    }
+
+    /**
+     * Release a mouse button
+     * @param {number} [button=MOUSE_BTN.LEFT] - Button to release
+     */
+    async mouseRelease(button = MOUSE_BTN.LEFT) {
+        await this.sendCommand(CMD.MOUSE_RELEASE, [button]);
+    }
+
+    /**
+     * Scroll the mouse wheel
+     * @param {number} amount - Scroll amount (positive = up, negative = down)
+     */
+    async mouseScroll(amount) {
+        await this.sendCommand(CMD.MOUSE_SCROLL, [amount & 0xFF]);
+    }
+
+    /**
+     * Double-click a mouse button
+     * @param {number} [button=MOUSE_BTN.LEFT] - Button to click
+     * @param {number} [delay=50] - Delay between clicks (ms)
+     */
+    async mouseDoubleClick(button = MOUSE_BTN.LEFT, delay = 50) {
+        await this.mouseClick(button);
+        await this._sleep(delay);
+        await this.mouseClick(button);
+    }
+
+    // ============================================================
+    // UTILITY
+    // ============================================================
+
+    /**
+     * Execute device-side delay
+     * @param {number} ms - Delay in milliseconds
+     */
+    async delay(ms) {
+        const high = (ms >> 8) & 0xFF;
+        const low = ms & 0xFF;
+        await this.sendCommand(CMD.DELAY, [high, low]);
+    }
+
+    /**
+     * Internal sleep helper
+     * @private
+     */
+    _sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+
+module.exports = MacroController;
+

package/src/index.js

@@ -0,0 +1,30 @@
+/**
+ * MacroMate HID - Library for communicating with MacroMate device
+ */
+
+const MacroController = require('./controller');
+const {
+    VID, PID, VENDOR_USAGE_PAGE,
+    CMD, MOUSE_BTN, MOD, KEY, STATUS,
+    DEFAULT_TIMEOUT, TYPE_STRING_TIMEOUT
+} = require('./constants');
+
+module.exports = {
+    // Main class
+    MacroController,
+    
+    // Constants
+    KEY,
+    MOD,
+    MOUSE_BTN,
+    CMD,
+    STATUS,
+    
+    // Device config (for advanced usage)
+    VID,
+    PID,
+    VENDOR_USAGE_PAGE,
+    DEFAULT_TIMEOUT,
+    TYPE_STRING_TIMEOUT,
+};
+