macromate-hid 1.0.0-beta.1

package/README.md

@@ -0,0 +1,310 @@
+# 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
+
+```bash
+npm install macromate-hid
+```
+
+Or clone and link locally:
+
+```bash
+cd macromate-hid
+npm install
+npm link
+```
+
+## Quick Start
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+// 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
+
+```javascript
+// 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
+
+```javascript
+// 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
+
+```javascript
+// 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
+
+```javascript
+// 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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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:
+
+```bash
+npx macromate
+# or if linked globally
+macromate
+```
+
+The CLI provides an interactive menu for testing all device functions.
+
+## Examples
+
+### Auto-login Script
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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:
+```bash
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+/**
+ * MacroMate CLI - Interactive test tool
+ */
+
+const readline = require('readline-sync');
+const { MacroController, KEY, MOD, MOUSE_BTN } = require('./src');
+
+let controller = null;
+
+//--------------------------------------------------------------------
+// HELPERS
+//--------------------------------------------------------------------
+
+function confirm(msg) {
+    const answer = readline.question(msg + ' (y/n): ').toLowerCase();
+    return answer === 'y' || answer === 'yes';
+}
+
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+//--------------------------------------------------------------------
+// TESTS
+//--------------------------------------------------------------------
+
+async function testPing() {
+    console.log('\n--- Test PING ---');
+    try {
+        const result = await controller.ping();
+        console.log(`[OK] Ping successful! Firmware v${result.version}`);
+    } catch (e) {
+        console.log('[X] Ping failed:', e.message);
+    }
+}
+
+async function testVersion() {
+    console.log('\n--- Get Version ---');
+    try {
+        const version = await controller.getVersion();
+        console.log(`[OK] Version: ${version}`);
+    } catch (e) {
+        console.log('[X] Failed:', e.message);
+    }
+}
+
+async function testMouseMove() {
+    console.log('\n--- Mouse Move Test ---');
+    console.log('    Mouse will move in a small square (50px each side)');
+    
+    if (!confirm('    Continue?')) return;
+    
+    const steps = [[50, 0], [0, 50], [-50, 0], [0, -50]];
+    try {
+        for (const [x, y] of steps) {
+            await controller.mouseMove(x, y);
+            await sleep(200);
+        }
+        console.log('[OK] Mouse move complete');
+    } catch (e) {
+        console.log('[X] Failed:', e.message);
+    }
+}
+
+async function testMouseClick() {
+    console.log('\n--- Mouse Click Test ---');
+    console.log('    WARNING: This will perform a REAL left click!');
+    console.log('    Make sure cursor is in a safe place.');
+    
+    if (!confirm('    Click?')) return;
+    
+    try {
+        await controller.mouseClick(MOUSE_BTN.LEFT);
+        console.log('[OK] Click sent');
+    } catch (e) {
+        console.log('[X] Failed:', e.message);
+    }
+}
+
+async function testKeyTap() {
+    console.log('\n--- Key Press Test ---');
+    console.log('    WARNING: This will type letter "A"!');
+    console.log('    Open a text editor and place cursor.');
+    
+    if (!confirm('    Press A?')) return;
+    
+    console.log('    2 seconds to switch window...');
+    await sleep(2000);
+    
+    try {
+        await controller.keyTap(KEY.A);
+        console.log('[OK] Key tap sent');
+    } catch (e) {
+        console.log('[X] Failed:', e.message);
+    }
+}
+
+async function testCombo() {
+    console.log('\n--- Combo Test: Ctrl+A ---');
+    console.log('    WARNING: This will select all text!');
+    
+    if (!confirm('    Execute Ctrl+A?')) return;
+    
+    console.log('    2 seconds...');
+    await sleep(2000);
+    
+    try {
+        await controller.shortcut(MOD.CTRL, KEY.A);
+        console.log('[OK] Combo sent');
+    } catch (e) {
+        console.log('[X] Failed:', e.message);
+    }
+}
+
+async function testScroll() {
+    console.log('\n--- Scroll Test ---');
+    console.log('    Scroll up 3 steps');
+    
+    if (!confirm('    Continue?')) return;
+    
+    try {
+        for (let i = 0; i < 3; i++) {
+            await controller.mouseScroll(1);
+            await sleep(100);
+        }
+        console.log('[OK] Scroll complete');
+    } catch (e) {
+        console.log('[X] Failed:', e.message);
+    }
+}
+
+async function testTypeString() {
+    console.log('\n--- Type String Test ---');
+    console.log('    WARNING: This will type a string!');
+    console.log('    Open a text editor and place cursor.');
+    
+    const text = readline.question('    Enter text to type (max 62 chars): ');
+    if (!text || text.length === 0) {
+        console.log('    Cancelled');
+        return;
+    }
+    
+    if (!confirm('    Type this string?')) return;
+    
+    console.log('    2 seconds to switch window...');
+    await sleep(2000);
+    
+    try {
+        await controller.typeString(text);
+        console.log('[OK] String typed');
+    } catch (e) {
+        console.log('[X] Failed:', e.message);
+    }
+}
+
+function testBootloader() {
+    console.log('\n--- Bootloader Mode ---');
+    console.log('    WARNING: Device will reboot into USB flash drive mode!');
+    console.log('    You will need to copy new firmware to flash it.');
+    console.log('    Connection will be lost.');
+    
+    if (!confirm('    Enter bootloader mode?')) return;
+    
+    controller.enterBootloader();
+    console.log('\n    Device should now appear as RPI-RP2 drive.');
+    console.log('    Copy macromate.uf2 to flash new firmware.');
+}
+
+async function manualCommand() {
+    console.log('\n--- Manual Command ---');
+    console.log('    Enter bytes (hex), e.g.: 00 10 04');
+    
+    const input = readline.question('    > ');
+    const bytes = input.split(/\s+/).map(s => parseInt(s, 16)).filter(n => !isNaN(n));
+    
+    if (bytes.length === 0) {
+        console.log('    Invalid input');
+        return;
+    }
+    
+    try {
+        await controller.sendCommand(bytes[0], bytes.slice(1));
+        console.log('[OK] Command sent');
+    } catch (e) {
+        console.log('[X] Failed:', e.message);
+    }
+}
+
+//--------------------------------------------------------------------
+// MENU
+//--------------------------------------------------------------------
+
+function showMenu() {
+    console.log('\n' + '='.repeat(45));
+    console.log('        MACROMATE CLI v1.0');
+    console.log('='.repeat(45));
+    console.log('  1. Ping (check connection)');
+    console.log('  2. Get firmware version');
+    console.log('  3. Mouse move (safe)');
+    console.log('  4. Mouse click');
+    console.log('  5. Mouse scroll');
+    console.log('  6. Press key A');
+    console.log('  7. Combo Ctrl+A');
+    console.log('  8. Type string');
+    console.log('  9. Manual command');
+    console.log('  r. Reconnect');
+    console.log('  b. BOOTLOADER MODE (flash new firmware)');
+    console.log('  0. Exit');
+    console.log('='.repeat(45));
+}
+
+async function runTest(testFn) {
+    try {
+        await testFn();
+    } catch (e) {
+        console.log('[X] Test error:', e.message);
+    }
+}
+
+async function main() {
+    console.log('\n=== MacroMate CLI v1.0 ===\n');
+    
+    // Create controller with debug enabled
+    controller = new MacroController({ debug: true });
+    
+    try {
+        controller.connect();
+    } catch (e) {
+        console.log('[X]', e.message);
+        console.log('\nFlash the device first and connect it.');
+        process.exit(1);
+    }
+    
+    while (true) {
+        showMenu();
+        const choice = readline.question('\nChoice: ');
+        
+        switch (choice) {
+            case '1': await runTest(testPing); break;
+            case '2': await runTest(testVersion); break;
+            case '3': await runTest(testMouseMove); break;
+            case '4': await runTest(testMouseClick); break;
+            case '5': await runTest(testScroll); break;
+            case '6': await runTest(testKeyTap); break;
+            case '7': await runTest(testCombo); break;
+            case '8': await runTest(testTypeString); break;
+            case '9': await runTest(manualCommand); break;
+            case 'r':
+            case 'R':
+                controller.disconnect();
+                try {
+                    controller.connect();
+                } catch (e) {
+                    console.log('[X]', e.message);
+                }
+                break;
+            case 'b':
+            case 'B':
+                testBootloader();
+                break;
+            case '0':
+            case 'q':
+                console.log('\nBye!');
+                controller.disconnect();
+                process.exit(0);
+            default:
+                console.log('[?] Unknown command');
+        }
+        
+        readline.question('\n[Press Enter]');
+    }
+}
+
+main().catch(e => {
+    console.error('Fatal error:', e);
+    process.exit(1);
+});
+

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "macromate-hid",
+  "version": "1.0.0-beta.1",
+  "description": "Library for communicating with MacroMate HID device",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "bin": {
+    "macromate": "./cli.js"
+  },
+  "scripts": {
+    "cli": "node cli.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "hid",
+    "usb",
+    "macro",
+    "keyboard",
+    "mouse",
+    "automation",
+    "pico",
+    "rp2040"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "node-hid": "^3.2.0",
+    "readline-sync": "^1.4.10"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "files": [
+    "src/",
+    "types/",
+    "cli.js",
+    "README.md"
+  ]
+}
+