@danidoble/serial-node-hoppers

A robust Node.js library for controlling Hopper devices via serial port communication. Built with TypeScript for type safety and reliability.

Features

• Strict Typing: Fully typed request and response objects.
• Promise-based API: easy-to-use async/await methods.
• Event-driven: Listen for real-time status updates, connection events, and errors.
• Hopper Management:
  • Read/Write individual hopper levels.
  • Dispense coins from specific hoppers.
  • Smart change dispensing logic.
• Balance Management: Read and clear total balance.
• Validator Control: Enable/Disable coin validator.

Installation

npm install @danidoble/serial-node-hoppers

Usage

Basic Connection

import { Hoppers } from '@danidoble/serial-node-hoppers';

const hoppers = new Hoppers({
  path: '/dev/ttyUSB0', // Your device path
  baudRate: 9600,
  autoConnect: true
});

hoppers.on('serial:connected', () => {
  console.log('Connected to Hoppers!');
  // Device keeps a handshake, so it's ready to use.
});

hoppers.on('serial:error', err => {
  console.error('Serial Error:', err);
});

hoppers.start();

Controlling Hoppers

// Read level of Hopper 1
const response = await hoppers.readHopper({ hopper: 1 });
console.log('Hopper 1 Level:', hoppers.getHopperLevel(1).amount);

// Dispense 1 coin from Hopper 2
await hoppers.dispenseHopper({ hopper: 2 });

// Dispense 50 units of change (smart dispense)
await hoppers.dispenseChange({ change: 50 });

Validator Configuration

// Enable the coin validator
await hoppers.enableValidator();

// Listen for validator status
hoppers.on('validator:status', status => {
  console.log('Validator enabled:', status.enabled);
});

API

Class: Hoppers

Events

• serial:connected: Emitted when connection is established.
• serial:disconnected: Emitted when disconnected.
• serial:error: Emitted on serial port errors.
• serial:status: Emitted with low-level status updates.
• hopper:updated: Emitted when a hopper level changes.
• balance:updated: Emitted when balance is read or cleared.

Methods

• start(): Opens serial connection.
• stop(): Closes connection.
• readHopper(options): Reads specific hopper level.
• writeHopper(options): Sets specific hopper level.
• dispenseHopper(options): Dispenses one unit from specific hopper.
• dispenseChange(options): Dispenses total change amount.
• readBalance(): Reads current credit balance.
• clearBalance(): Clears current credit balance.
• enableValidator() / disableValidator(): Controls coin acceptance.

Requirements

• Node.js: >= 18.0.0
• serial-core: ^0.2.0
• serialport: ^13.0.0

License

GPL-3.0 © Danidoble

Contributing

Contributions are welcome! Please read our CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.