@thalaguer/buzzer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thalaguer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -0,0 +1,198 @@
+# @thalaguer/buzzer
+
+**The easiest way to control your Buzz! wireless controllers in Node.js**  
+Light up the LEDs, detect every button press, and bring back the PS2 game show vibes — with zero hassle. 🔔🔥
+
+> **Note**: This library supports the **wired** Buzz! controllers (with USB dongle), not the wireless versions.
+
+## Features
+
+- ✅ Automatic detection and initialization
+- ✅ Real-time button press/release events
+- ✅ Individual LED control for up to 4 players
+- ✅ Clean event-based API
+- ✅ Cross-platform support (Windows, macOS, Linux)
+- ✅ Built-in startup LED animation
+
+## Installation
+
+This package depends on `node-hid` which requires native compilation.
+
+**Recommended installation command:**
+
+```bash
+npm install @thalaguer/buzzer --ignore-scripts
+```
+
+## Usage
+
+```javascript
+import Buzzer from '@thalaguer/buzzer';
+
+const buzzers = Buzzer();
+
+// Called when the system is fully initialized
+buzzers.onReady(() => {
+  console.log("Buzzers are ready & functional.");
+  
+  // Turn on player 1's LED
+  buzzers.setLeds(true, false, false, false);
+  
+  // Or using array syntax
+  buzzers.setLedsarray([true, false, true, false]); // Players 1 & 3 on
+});
+
+// Button press events
+buzzers.onPress((data) => {
+  console.log(`Buzzer #${data.controller} pressed the ${data.color} button(${data.button}).`);
+  console.log(`Full event: ${JSON.stringify(data)}`);
+});
+
+// Button release events
+buzzers.onRelease((data) => {
+  console.log(`Buzzer #${data.controller} released the ${data.color} button.`);
+});
+
+// Any state change (press or release)
+buzzers.onChange((data) => {
+  console.log(`Buzzer #${data.controller} ${data.state} the ${data.color} button.`);
+});
+
+buzzers.onError((data) => {
+  console.log(`An error occurred : ${data.message}`);
+})
+
+// Clean up when done (optional)
+// await buzzers.close();
+```
+
+## API Reference
+
+### `Buzzer()`
+Creates a new buzzer manager instance.
+
+### `onReady(callback)`
+Registers a callback when the system is fully initialized. The startup LED animation will play when ready.
+
+### `onPress(callback)`
+Registers a callback for button press events. The callback receives an event object with:
+- `controller`: Player number (1-4)
+- `color`: Button color ('RED', 'BLUE', 'ORANGE', 'GREEN', 'YELLOW')
+- `button`: Button identifier ( 0=> red, 1=> blue, 2=> orange, 3=> green, 4=> yellow)
+- `state`: Event state ('press', 'released') - mostly useful for `onChange(callback)`.
+### `onRelease(callback)`
+Registers a callback for button release events (same event object structure as `onPress`).
+
+### `onChange(callback)`
+Registers a callback for any button state change (both press and release).
+
+### `onError(callback)`
+Registers a callback for any error happening.
+
+### `setLeds(player1, player2, player3, player4)`
+Controls the red LEDs for each player:
+- `player1` - Player 1 LED (boolean)
+- `player2` - Player 2 LED (boolean)
+- `player3` - Player 3 LED (boolean)
+- `player4` - Player 4 LED (boolean)
+
+### `setLedsarray([player1, player2, player3, player4])`
+Convenience method that accepts an array of boolean values.
+
+### `close()`
+Closes connections and releases resources. Returns a Promise.
+
+## Windows Driver Setup (ZADIG)
+
+On Windows, the Buzz! dongle might not work with the default driver. You need to install the WinUSB driver using ZADIG:
+
+1. **Download ZADIG** from https://zadig.akeo.ie/
+
+2. **Run ZADIG** as Administrator
+
+3. **Configure ZADIG**:
+   - Go to `Options` → `List All Devices`
+   - Check both `Ignore Hubs or Composite Parents` and `Show only current configuration`
+
+4. **Select the Buzz! Dongle**:
+   - From the dropdown, select the Buzz! device (should appear as "Buzz!" or with VID `054C` and PID `1000`)
+   - If you don't see it, try:
+     - Unplugging and replugging the dongle
+     - Checking if it appears under a different name
+     - Trying with and without controllers connected
+
+5. **Install/Replace Driver**:
+   - Ensure the driver selected is `WinUSB` (not libusb)
+   - Click `Replace Driver` or `Install Driver`
+   - Wait for the installation to complete
+
+6. **Test**:
+   - Unplug and replug the dongle
+   - Run your application again
+
+**Note**: If you have multiple Buzz! dongles, repeat these steps for each one.
+
+## Linux Permissions
+
+On Linux, you may need to add a udev rule or run with `sudo`:
+
+```bash
+# Temporary solution (run with sudo)
+sudo node your-app.js
+
+# Permanent solution (create udev rule):
+sudo nano /etc/udev/rules.d/99-buzz.rules
+```
+
+Add this line:
+```
+SUBSYSTEM=="usb", ATTR{idVendor}=="054c", ATTR{idProduct}=="1000", MODE="0666"
+```
+
+Then reload udev rules:
+```bash
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+## Troubleshooting
+
+### Dongle not found
+1. Check the USB connection
+2. Verify the driver is installed (Windows: ZADIG)
+3. Check if another application is using the device
+4. Try a different USB port
+
+### Different VID/PID
+Most Buzz! dongles use `VID: 0x054c` and `PID: 0x1000`. If yours is different:
+
+```javascript
+// In your node_modules/@thalaguer/buzzer/src/config.js
+export const VID = 0x054c;    // ← change to your VID
+export const PID = 0x1000;    // ← change to your PID
+```
+
+To find your dongle's VID/PID:
+- **Windows**: Device Manager → Properties → Details → Hardware IDs
+- **Linux**: `lsusb` command
+- **macOS**: System Information → USB
+
+### No button events
+1. Ensure controllers are connected to the dongle (press any button to pair)
+2. Check that the dongle LED is solid (not blinking)
+3. Verify your event listeners are set up before initialization completes
+
+## Supported Controllers
+
+This library supports the **wireless** Buzz! controllers that come with a USB dongle. Each dongle supports up to 4 controllers.
+
+**Known compatible models:**
+- Buzz! Buzzers Wireless (PS2/PS3/PC)
+- Most Buzz! controllers with model number "BUZZ001" or similar
+
+**Not tested:**
+- Buzz! Wireless controllers
+
+## License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

package/index.js

@@ -0,0 +1,3 @@
+import Buzzer from "./src/Buzzer.js";
+
+export default Buzzer;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@thalaguer/buzzer",
+  "version": "1.0.0",
+  "description": "Node.js driver for Sony Buzz! wireless controllers (PS2/PS3 quiz buzzers) using HID/USB",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "node-hid": "^3.2.0",
+    "usb": "^2.16.0"
+  },
+  "keywords": [
+    "buzz",
+    "buzzer",
+    "ps2",
+    "ps3",
+    "playstation",
+    "hid",
+    "usb",
+    "node-hid",
+    "game-controller",
+    "quiz-controller"
+  ],
+  "author": "Thalaguer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thalaguer/buzzer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thalaguer/buzzer/issues"
+  },
+  "homepage": "https://github.com/thalaguer/buzzer#readme",
+  "files": [
+    "index.js",
+    "src/**/*.js",
+    "!**/*.test.js",
+    "!**/__tests__/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"No tests yet – coming soon!\" && exit 0",
+    "prepublishOnly": "npm run lint && npm run test",
+    "lint": "echo \"Add eslint/prettier later\" && exit 0"
+  }
+}

package/src/Buzzer.js

@@ -0,0 +1,507 @@
+// ──────────────────────────────────────────────────────────────
+// Error handling 
+// ──────────────────────────────────────────────────────────────
+const isDebug = process.env.DEBUG === 'true' || process.argv.includes('--debug');
+
+process.on('uncaughtException', (error) => {
+  if (isDebug) {
+    console.error(colors.red + colors.bright + '┌────────────────────────────────────────────────────────────┐' + colors.reset);
+    console.error(colors.red + colors.bright + '│ CRITICAL: Uncaught EXCEPTION (synchronous)                │' + colors.reset);
+    console.error(colors.red + colors.bright + '└────────────────────────────────────────────────────────────┘' + colors.reset);
+    console.error(colors.yellow + 'Message:' + colors.reset, error.message || error);
+    console.error(colors.yellow + 'Stack:' + colors.reset, error.stack || error);
+    console.error(colors.dim + `Time: ${new Date().toISOString()}` + colors.reset);
+  }
+});
+
+process.on('unhandledRejection', (reason, promise) => {
+  if (isDebug) {
+    console.error(colors.magenta + colors.bright + '┌────────────────────────────────────────────────────────────┐' + colors.reset);
+    console.error(colors.magenta + colors.bright + '│ UNHANDLED PROMISE REJECTION                               │' + colors.reset);
+    console.error(colors.magenta + colors.bright + '└────────────────────────────────────────────────────────────┘' + colors.reset);
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    if (error instanceof CustomError) {
+      console.error(colors.yellow + 'Message:' + colors.reset, `[${error.timestamp}] ${error.name}: ${error.message}`);
+      console.error(colors.yellow + 'Details:' + colors.reset, error.details || 'none');
+      console.error(colors.yellow + 'Stack:' + colors.reset, error.stack);
+    } else {
+      console.error(colors.yellow + 'Unexpected rejection:' + colors.reset, error.message);
+      console.error(error.stack || error);
+    }
+    console.error(colors.dim + `Time: ${new Date().toISOString()}` + colors.reset);
+  }
+});
+
+import { findByIds } from "usb";
+import { EventEmitter } from 'node:events';
+import HID from 'node-hid';
+
+import { VID, PID, prefix } from './config.js';
+import { BUTTONS_DATA, colors } from "./constants.js";
+import { EVENTS } from "./event.js";
+import { formatEvent } from "./utils.js";
+import { CustomError } from "./error/CustomError.js";
+
+/**
+ * Creates and manages a Buzz! controller dongle instance.
+ * 
+ * Handles connection to the Buzz! wireless dongle, button event detection,
+ * LED control, and provides an event-based API for button interactions.
+ * 
+ * @returns {Object} Buzzer manager object with public methods.
+ * 
+ * @example
+ * const buzz = Buzzer();
+ * 
+ * // Wait for initialization
+ * buzz.onReady(() => {
+ *   console.log('Buzzers ready!');
+ *   buzz.setLeds(true, false, false, false); // Turn on player 1 LED
+ * });
+ * 
+ * // Listen for button events
+ * buzz.onPress((event) => {
+ *   console.log(`Button pressed: ${event.button} on controller ${event.controller}`);
+ * });
+ * 
+ * // Clean up when done
+ * // await buzz.close();
+ */
+export default function Buzzer() {
+  const ee = new EventEmitter();
+
+  let device = null;
+  let iface = null;
+  let endpoint = null;
+  let hidDevice = null;
+  let currentStates = new Array(BUTTONS_DATA.length).fill(false);
+
+  // "Ready" state management
+  let isReady = false;
+  let readyPromise = null;
+
+  // ──────────────────────────────────────────────────────────────
+  // USB device management 
+  // ──────────────────────────────────────────────────────────────
+
+  /**
+   * Opens the USB device with the specified VID/PID and claims interface 0.
+   *
+   * This function:
+   * - Searches for the Buzz! dongle using VID and PID
+   * - Opens the device
+   * - Gets interface 0
+   * - Detaches kernel driver if active (Linux/macOS only)
+   * - Claims the interface for exclusive access
+   *
+   * @async
+   * @returns {Promise<{device: import('usb').Device, iface: import('usb').Interface}>}
+   *          Object containing the opened device and claimed interface
+   * @throws {CustomError} If the device is not found
+   * @throws {CustomError} If interface 0 is not available
+   * @throws {CustomError} If any other USB operation fails (open, claim, etc.)
+   */
+  async function openAndClaim() {
+    try {
+      device = findByIds(VID, PID);
+      if (!device) {
+        const errMsg = "Dongle not found. Check connection and VID/PID.";
+        ee.emit(EVENTS.ERROR, errMsg);
+        throw new CustomError(errMsg);
+      }
+
+      device.open();
+
+      iface = device.interface(0);
+      if (!iface) {
+        const errMsg = "Interface 0 not found";
+        ee.emit(EVENTS.ERROR, errMsg);
+        throw new CustomError(errMsg);
+      }
+
+      if (process.platform !== 'win32' && iface.isKernelDriverActive?.()) {
+        iface.detachKernelDriver();
+      }
+
+      iface.claim();
+
+      return { device, iface };
+    } catch (err) {
+      const errMsg = "Failed to open the connection to the dongle.";
+      ee.emit(EVENTS.ERROR, errMsg);
+      throw new CustomError(errMsg, { cause: err });
+    }
+  }
+
+  /**
+   * Finds and returns the interrupt IN endpoint from the given USB interface.
+   *
+   * This function searches through all endpoints of the interface for one that:
+   * - Has direction 'in' (device → host)
+   * - Uses interrupt transfer type (transferType === 3)
+   *
+   * If no suitable endpoint is found, it throws an error with a detailed list
+   * of all available endpoints for debugging purposes.
+   *
+   * @param {import('usb').Interface} iface - The USB interface to search endpoints in
+   * @returns {import('usb').Endpoint} The interrupt IN endpoint found
+   * @throws {CustomError} If no interrupt IN endpoint is found.
+   *                 The error message includes a formatted list of all available endpoints.
+   */
+  function findInterruptEndpoint(iface) {
+    const endpoint = iface.endpoints.find(ep =>
+      ep.direction === 'in' && ep.transferType === 3
+    );
+
+    if (!endpoint) {
+      const errMsg = "No INTERRUPT IN endpoint found!\n" +
+        "Available endpoints:\n" +
+        iface.endpoints.map(e => `  - ${e.direction} ${e.transferType} (addr 0x${e.address.toString(16)})`).join("\n");
+      ee.emit(EVENTS.ERROR, errMsg);
+      throw new CustomError(errMsg);
+    }
+
+    return endpoint;
+  }
+
+  // ──────────────────────────────────────────────────────────────
+  // LEDs
+  // ──────────────────────────────────────────────────────────────
+
+  /**
+   * Internal LED control without initialization check.
+   * Used during boot sequence to avoid circular dependencies.
+   *
+   * @private
+   * @param {boolean} [player1=false] - Turn on the LED for player 1
+   * @param {boolean} [player2=false] - Turn on the LED for player 2
+   * @param {boolean} [player3=false] - Turn on the LED for player 3
+   * @param {boolean} [player4=false] - Turn on the LED for player 4
+   * @returns {void}
+   */
+  function privateSetLeds(player1 = false, player2 = false, player3 = false, player4 = false) {
+    if (!hidDevice) {
+      console.warn(`${prefix} HID device not available`);
+      return;
+    }
+
+    const report = Buffer.alloc(8);
+    report[0] = 0x00;
+    report[1] = 0x00;
+    report[2] = player1 ? 0xFF : 0x00;
+    report[3] = player2 ? 0xFF : 0x00;
+    report[4] = player3 ? 0xFF : 0x00;
+    report[5] = player4 ? 0xFF : 0x00;
+    report[6] = 0x00;
+    report[7] = 0x00;
+
+    try {
+      hidDevice.write(report);
+    } catch (err) {
+      const shortReport = Buffer.from([
+        0x00, 0x00,
+        player1 ? 0xFF : 0x00,
+        player2 ? 0xFF : 0x00,
+        player3 ? 0xFF : 0x00,
+        player4 ? 0xFF : 0x00
+      ]);
+      try {
+        hidDevice.write(shortReport);
+      } catch (innerErr) {
+        ee.emit(EVENTS.ERROR, "Failed to set LEDs");
+        if (isDebug) {
+          console.error(`${prefix} LED set error:`, innerErr.message);
+        }
+      }
+    }
+  }
+
+  /**
+   * Controls the LEDs on the Buzz! controllers.
+   * 
+   * Ensures the system is ready before setting LEDs.
+   * 
+   * @param {boolean} [player1=false] - Turn on LED for player 1
+   * @param {boolean} [player2=false] - Turn on LED for player 2
+   * @param {boolean} [player3=false] - Turn on LED for player 3
+   * @param {boolean} [player4=false] - Turn on LED for player 4
+   * @returns {Promise<void>}
+   */
+  async function setLeds(player1 = false, player2 = false, player3 = false, player4 = false) {
+    await ensureReady();
+    privateSetLeds(player1, player2, player3, player4);
+  }
+
+  /**
+   * Controls the LEDs using an array of boolean values.
+   * 
+   * @param {boolean[]} players - Array of 4 booleans for players 1-4
+   * @returns {Promise<void>}
+   * @throws {CustomError} If array length is not 4
+   */
+  async function setLedsarray(players) {
+    if (!Array.isArray(players) || players.length !== 4) {
+      throw new CustomError("Invalid array: must be boolean[4]");
+    }
+    await setLeds(...players);
+  }
+
+  // ──────────────────────────────────────────────────────────────
+  // Setup 
+  // ──────────────────────────────────────────────────────────────
+
+  /**
+   * Sets up the listener for Buzz! controller events.
+   * 
+   * Initializes USB connection, HID device, starts polling for button data,
+   * and emits events on button press/release.
+   * 
+   * @async
+   * @returns {Promise<void>}
+   * @throws {CustomError} If setup fails
+   * @fires press   When a button is pressed (payload: button object)
+   * @fires release When a button is released (payload: button object)
+   * @fires error   When a critical error occurs during setup
+   */
+  async function setupBuzzListener() {
+    try {
+      const result = await openAndClaim();
+      device = result.device;
+      iface = result.iface;
+
+      hidDevice = new HID.HID(VID, PID);
+
+      endpoint = findInterruptEndpoint(iface);
+
+      endpoint.startPoll(3, endpoint.descriptor.wMaxPacketSize);
+
+      endpoint.on('data', (data) => {
+        if (data.length < 5) return;
+
+        const previousStates = [...currentStates];
+        const pressedBits = data.readUInt16LE(2) | (data.readUInt8(4) << 16);
+
+        BUTTONS_DATA.forEach((button, index) => {
+          const isPressedNow = (pressedBits & button.bit) !== 0;
+          const wasPressed = previousStates[index];
+
+          currentStates[index] = isPressedNow;
+
+          if (isPressedNow !== wasPressed) {
+            const eventType = isPressedNow ? EVENTS.PRESS : EVENTS.RELEASE;
+            ee.emit(eventType, { ...button, type: eventType });
+          }
+        });
+      });
+
+     if(isDebug) console.log(colors.magenta + colors.bright + `${prefix} Listening started` + colors.reset);
+    } catch (err) {
+      throw new CustomError("Buzzers setup failed", { cause: err });
+    }
+  }
+
+  // ──────────────────────────────────────────────────────────────
+  // Events methods 
+  // ──────────────────────────────────────────────────────────────
+
+  /**
+   * Internal function to ensure the buzzer system is ready.
+   * Initializes the system if not already initialized.
+   *
+   * @private
+   * @async
+   * @returns {Promise<void>}
+   * @throws {CustomError} If initialization fails
+   */
+  async function ensureReady() {
+    if (isReady) return;
+    if (readyPromise) return readyPromise;
+
+    readyPromise = setupBuzzListener()
+      .then(() => {
+        const cycles = 3;
+        const onTime = 350;   // clearly visible
+        const offTime = 200;
+
+        return new Promise((resolve) => {
+          let delay = 0;
+          for (let i = 0; i < cycles; i++) {
+            setTimeout(() => {
+              privateSetLeds(true, true, true, true);
+            }, delay);
+            delay += onTime;
+
+            setTimeout(() => {
+              privateSetLeds(false, false, false, false);
+            }, delay);
+            delay += offTime;
+          }
+
+          setTimeout(() => {
+            isReady = true;
+            if(isDebug) console.log(colors.yellow + colors.bright + `${prefix} Buzzers are ready` + colors.reset);
+            ee.emit(EVENTS.READY);
+            resolve();
+          }, delay + 200);
+        });
+      })
+      .catch(err => {
+        const customError = new CustomError(err.message || "Setup failed", { cause: err });
+        ee.emit(EVENTS.ERROR, customError);
+        throw customError;
+      });
+
+    return readyPromise;
+  }
+
+  /**
+   * Registers a callback to be called when the buzzer system is fully initialized.
+   *
+   * @param {function} callback - Function called when system is ready
+   * @returns {void}
+   */
+  function onReady(callback) {
+    ee.on(EVENTS.READY, callback);
+  }
+
+  /**
+   * Registers a callback to be called when any buzzer button is pressed.
+   *
+   * The callback receives a simplified event object with the following properties:
+   * - `controller`: The controller number (1 to 4)
+   * - `button`: The button name (e.g., 'RED', 'BLUE', etc.)
+   * - `Name`: The full button identifier (e.g., 'C1_RED', 'C2_BLUE')
+   *
+   * Returns a cleanup function to remove the listener.
+   *
+   * @param {function(Object): void} callback - Function called when a button is pressed
+   * @returns {function(): void} Cleanup function to remove the listener
+   */
+  function onPress(callback) {
+    ensureReady().catch((err) => {
+      ee.emit(EVENTS.ERROR, err);
+    });
+    const handler = (originalEvent) => {
+      callback(formatEvent(originalEvent, EVENTS.PRESS));
+    };
+
+    ee.on(EVENTS.PRESS, handler);
+    return () => ee.off(EVENTS.PRESS, handler);
+  }
+
+  /**
+   * Registers a callback to be called when any buzzer button is released.
+   *
+   * The callback receives a simplified event object with the following properties:
+   * - `controller`: The controller number (1 to 4)
+   * - `button`: The button name (e.g., 'RED', 'BLUE', etc.)
+   * - `Name`: The full button identifier (e.g., 'C1_RED', 'C2_BLUE')
+   *
+   * Returns a cleanup function to remove the listener.
+   *
+   * @param {function(Object): void} callback - Function called when a button is released
+   * @returns {function(): void} Cleanup function to remove the listener
+   */
+  function onRelease(callback) {
+    ensureReady().catch((err) => {
+      ee.emit(EVENTS.ERROR, err);
+    });
+    const handler = (originalEvent) => {
+      callback(formatEvent(originalEvent, EVENTS.RELEASE));
+    };
+
+    ee.on(EVENTS.RELEASE, handler);
+    return () => ee.off(EVENTS.RELEASE, handler);
+  }
+
+  /**
+   * Registers a callback to be called whenever a button state changes
+   * (either pressed or released).
+   *
+   * The callback receives a simplified event object with the following properties:
+   * - `controller`: The controller number (1 to 4)
+   * - `button`: The button name (e.g., 'RED', 'BLUE', etc.)
+   * - `Name`: The full button identifier (e.g., 'C1_RED', 'C2_BLUE')
+   *
+   * Returns a cleanup function to remove the listener.
+   *
+   * @param {function(Object): void} callback - Function called on any button state change
+   * @returns {function(): void} Cleanup function to remove the listener
+   */
+  function onChange(callback) {
+    ensureReady().catch((err) => {
+      ee.emit(EVENTS.ERROR, err);
+    });
+
+    const handler = (originalEvent) => {
+      callback(formatEvent(originalEvent, originalEvent.type));
+    };
+
+    ee.on(EVENTS.PRESS, handler);
+    ee.on(EVENTS.RELEASE, handler);
+
+    return () => {
+      ee.off(EVENTS.PRESS, handler);
+      ee.off(EVENTS.RELEASE, handler);
+    };
+  }
+
+  /**
+   * Registers a callback to be called when an error occurs.
+   *
+   * @param {function(CustomError|string): void} callback - Function called on error
+   * @returns {function(): void} Cleanup function to remove the listener
+   */
+  function onError(callback) {
+    ensureReady().catch((err) => {
+      callback(err);
+    });
+    ee.on(EVENTS.ERROR, callback);
+    return () => ee.off(EVENTS.ERROR, callback);
+  }
+
+  /**
+   * Closes all connections and releases resources.
+   * Should be called when the application is done using the buzzer system.
+   *
+   * @async
+   * @returns {Promise<void>}
+   */
+  async function close() {
+    return new Promise((resolve) => {
+      try {
+        if (endpoint) endpoint.stopPoll();
+        if (iface) {
+          iface.release(true, () => {
+            if (device) device.close();
+            if (hidDevice) hidDevice.close();
+            isReady = false;
+            readyPromise = null;
+            if(isDebug) console.log(`${prefix} Resources released`);
+            resolve();
+          });
+        } else {
+          resolve();
+        }
+      } catch (err) {
+        console.warn(`${prefix} Close error:`, err.message);
+        resolve();
+      }
+    });
+  }
+
+  // ──────────────────────────────────────────────────────────────
+  // public API
+  // ──────────────────────────────────────────────────────────────
+
+  return {
+    setLeds,
+    setLedsarray,
+    onReady,
+    onPress,
+    onRelease,
+    onChange,
+    onError,
+    close
+  };
+}

package/src/config.js

@@ -0,0 +1,14 @@
+/**
+ * Configuration constants for the Buzz! controller dongle.
+ * 
+ * @module config
+ */
+
+/** USB Vendor ID for the Buzz! dongle */
+export const VID = 0x054c;
+
+/** USB Product ID for the Buzz! dongle */
+export const PID = 0x1000;
+
+/** Prefix used for logging messages */
+export const prefix = '[Buzzer]';

package/src/constants.js

@@ -0,0 +1,51 @@
+/**
+ * Constants for button data and console colors.
+ * 
+ * @module constants
+ */
+
+/** Array of button configurations for all controllers */
+export const BUTTONS_DATA = [
+  // Controller 1
+  { name: 'C1_RED', color: 'red', controller: 1, button: 0, bit: 0x000001 },
+  { name: 'C1_BLUE', color: 'blue', controller: 1, button: 1, bit: 0x000010 },
+  { name: 'C1_ORANGE', color: 'orange', controller: 1, button: 2, bit: 0x000008 },
+  { name: 'C1_GREEN', color: 'green', controller: 1, button: 3, bit: 0x000004 },
+  { name: 'C1_YELLOW', color: 'yellow', controller: 1, button: 4, bit: 0x000002 },
+
+  // Controller 2
+  { name: 'C2_RED', color: 'red', controller: 2, button: 0, bit: 0x000020 },
+  { name: 'C2_BLUE', color: 'blue', controller: 2, button: 1, bit: 0x000200 },
+  { name: 'C2_ORANGE', color: 'orange', controller: 2, button: 2, bit: 0x000100 },
+  { name: 'C2_GREEN', color: 'green', controller: 2, button: 3, bit: 0x000080 },
+  { name: 'C2_YELLOW', color: 'yellow', controller: 2, button: 4, bit: 0x000040 },
+
+  // Controller 3
+  { name: 'C3_RED', color: 'red', controller: 3, button: 0, bit: 0x000400 },
+  { name: 'C3_BLUE', color: 'blue', controller: 3, button: 1, bit: 0x004000 },
+  { name: 'C3_ORANGE', color: 'orange', controller: 3, button: 2, bit: 0x002000 },
+  { name: 'C3_GREEN', color: 'green', controller: 3, button: 3, bit: 0x001000 },
+  { name: 'C3_YELLOW', color: 'yellow', controller: 3, button: 4, bit: 0x000800 },
+
+  // Controller 4
+  { name: 'C4_RED', color: 'red', controller: 4, button: 0, bit: 0x008000 },
+  { name: 'C4_BLUE', color: 'blue', controller: 4, button: 1, bit: 0x080000 },
+  { name: 'C4_ORANGE', color: 'orange', controller: 4, button: 2, bit: 0x040000 },
+  { name: 'C4_GREEN', color: 'green', controller: 4, button: 3, bit: 0x020000 },
+  { name: 'C4_YELLOW', color: 'yellow', controller: 4, button: 4, bit: 0x010000 },
+];
+
+/** ANSI color codes for console logging */
+export const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  bgRed: '\x1b[41m',
+};

package/src/error/CustomError.js

@@ -0,0 +1,20 @@
+/**
+ * Custom error class that extends the built-in Error class.
+ * Includes additional details and a timestamp.
+ * 
+ * @module CustomError
+ */
+export class CustomError extends Error {
+  /**
+   * Creates a new CustomError instance.
+   * 
+   * @param {string} message - The error message.
+   * @param {Object} [details={}] - Additional details about the error.
+   */
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'CustomError';
+    this.details = details;
+    this.timestamp = new Date().toISOString();
+  }
+}

package/src/event.js

@@ -0,0 +1,15 @@
+/**
+ * Event types for buzzer interactions.
+ * 
+ * @module event
+ */
+export const EVENTS = {
+  /** Event emitted when a button is pressed */
+  PRESS: 'press',
+  /** Event emitted when a button is released */
+  RELEASE: 'release',
+  /** Event emitted when the buzzer system is ready */
+  READY: 'ready',
+  /** Event emitted when an error occurs */
+  ERROR: 'error'
+};

package/src/utils.js

@@ -0,0 +1,20 @@
+import { EVENTS } from "./event.js";
+
+/**
+ * Formats the original button event object into a simplified structure.
+ * 
+ * @param {Object} original - The original event object from the endpoint data.
+ * @param {string} eventType - The type of event (PRESS or RELEASE).
+ * @returns {Object} Formatted event object with controller, button, name, color, pressed, and state.
+ */
+export function formatEvent(original, eventType) {
+  const isPressed = eventType === EVENTS.PRESS;
+  return {
+    controller: original.controller,
+    button: original.button,
+    Name: original.name,
+    color: original.color,
+    pressed: isPressed,
+    state: isPressed ? 'pressed' : 'released'
+  };
+}