Initial commit

README.md

@@ -0,0 +1,44 @@
+# sfmacro-client
+
+`sfmacro-client` is a Node.js server that acts as a bridge between a custom Raspberry Pi Pico-based Macropad and your computer. It listens for physical button presses on the Pico over a USB Serial connection and executes corresponding configurable macros (such as simulating key presses, running commands, or toggling application audio). It also controls the RGB LEDs on the Macropad based on the button state or system metrics (e.g., CPU load).
+
+## How It Works
+
+The architecture consists of three main components:
+
+1. **Hardware (Raspberry Pi Pico)**
+   - The Pico is connected via USB and communicates over a Serial port.
+   - It sends serial messages when buttons are pressed (`P,<id>`) and released (`R,<id>`).
+   - It receives serial messages to set the RGB LED color for each button (`C,<id>,<r>,<g>,<b>`).
+
+2. **Node.js Server (`server.js`)**
+   - The server auto-detects the connected Pico (by its Vendor ID `2E8A`) and maintains the serial connection.
+   - It stores the configuration in `config.json`. 
+   - When a button press is detected, it triggers the configured action:
+     - **`key`**: Uses the `@nut-tree-fork/nut-js` library to simulate keyboard keystrokes or complex keyboard combos (e.g., `LeftControl + G`).
+     - **`cmd`**: Runs arbitrary system commands using Node's `child_process.exec`.
+     - **`mute_app`**: Toggles the mute state of specific applications (like `firefox.exe`) using the included `SoundVolumeView.exe` utility.
+     - **`cpu_monitor`**: Instead of triggering an action, a button assigned this action will constantly have its LED color updated based on the host computer's current CPU utilization (Green -> Yellow -> Orange -> Red) by polling with the `systeminformation` library.
+   - It hosts a local REST API and web server on port `3001` to allow configuration changes via a frontend UI.
+
+3. **Web Interface (`ui/` folder)**
+   - A Vite/React-based frontend is bundled into the `ui/dist` folder and served by the Node application.
+   - It allows the user to easily configure each of the 16 buttons, setting their action type, command/key, idle LED color, and pressed LED color.
+
+## Starting the Server
+
+There are a couple of ways to launch the software depending on your needs:
+
+- **Interactive Mode (`Start-Macropad.bat`)**: Starts the Node.js server, displays the console output, and automatically opens your default web browser to the `http://localhost:3001` configuration page.
+- **Background Mode (`Run-Hidden.vbs`)**: Silently launches the Node server in the background without opening a visible command prompt window. This is ideal for adding to your Windows Startup folder for seamless background operation.
+
+## Configuration
+
+Configuration is saved automatically to `config.json` when updated via the web interface. 
+
+Each of the 16 buttons has the following properties:
+- `actionType`: Can be `"key"`, `"cmd"`, `"mute_app"`, `"cpu_monitor"`, or `"none"`.
+- `key`: The keystroke combination to send (e.g., `F20` or `LeftControl + G`). Used for the `key` action type.
+- `cmd`: The command to execute or executable to mute. Used for the `cmd` and `mute_app` action types.
+- `color`: The default RGB LED color when the button is idle.
+- `pressedColor`: The RGB LED color when the button is actively pressed down.