@danidoble/serial-node-lockers

Node.js library to control serial lockers through serial port communication. This library provides a robust interface to manage locker systems with support for multiple cells, dispensing operations, and real-time status monitoring.

Features

• Serial Locker Control: Full control over locker cells via serial port communication
• Event-Driven Architecture: Real-time events for connection status, dispensing, and cell operations
• Cell Management: Open, enable, disable individual cells or perform bulk operations
• Progress Tracking: Real-time progress updates for long-running operations
• Automatic Handshake: Built-in connection handshake protocol
• TypeScript Support: Full TypeScript support with type definitions
• Queue Management: Built-in command queue to prevent conflicts
• Light Scan: Support for light scanning operations

Installation

npm install @danidoble/serial-node-lockers

Peer Dependencies

This library requires the following peer dependencies:

npm install serialport serial-core

Quick Start

import { Locker } from '@danidoble/serial-node-lockers';

// Create a locker instance
const locker = new Locker(
  {
    portPath: '/dev/ttyUSB0',
    baudRate: 9600,
    autoConnect: true
  },
  1
); // channel 1

// Listen for connection events
locker.on('serial:connected', info => {
  console.log('Locker connected:', info);
});

// Listen for dispensing events
locker.on('dispensed', data => {
  console.log('Cell dispensed successfully:', data);
});

// Open a specific cell
await locker.dispense({ cell: 5 });

// Get cell status
await locker.status({ cell: 5 });

API Reference

Class: Locker

The main class for controlling serial lockers.

Constructor

new Locker(config: SerialConfig, channel?: number)

• config: Serial configuration object (from serial-core)
  • portPath: Serial port path
  • baudRate: Communication speed (default: 9600)
  • autoConnect: Auto-connect on initialization
  • handshake: Optional handshake configuration (auto-configured if not provided)
  • parser: Optional parser (defaults to InterByteTimeoutParser with 40ms interval)
• channel: Locker channel ID (default: 1)

Methods

dispense(options?: LockerDispenseOptions): Promise<DispenserDispenseResponse>

Dispenses an item from a specific cell.

const result = await locker.dispense({ cell: 10 });
console.log(result.dispensed); // true if successful

status(options?: OpenCellOptions): Promise<void>

Gets the status of a specific cell.

await locker.status({ cell: 5 });

lightScan(options?: LightScanOptions): Promise<void>

Performs a light scan on a range of cells.

await locker.lightScan({ since: 0, until: 10 });

enable(options?: OpenCellOptions): Promise<void>

Enables a specific cell.

await locker.enable({ cell: 3 });

disable(options?: OpenCellOptions): Promise<void>

Disables a specific cell.

await locker.disable({ cell: 3 });

openAll(): Promise<void>

Opens all cells sequentially (1-80). Warning: This is a long-running process.

locker.on('percentage:open', ({ percentage }) => {
  console.log(`Progress: ${percentage}%`);
});

await locker.openAll();

enableAll(): Promise<void>

Enables all cells sequentially (1-80). Warning: This is a long-running process.

locker.on('percentage:enable', ({ percentage }) => {
  console.log(`Progress: ${percentage}%`);
});

await locker.enableAll();

disableAll(): Promise<void>

Disables all cells sequentially (1-80). Warning: This is a long-running process.

locker.on('percentage:disable', ({ percentage }) => {
  console.log(`Progress: ${percentage}%`);
});

await locker.disableAll();

Events

The Locker class extends EventEmitter and emits the following events:

Connection Events

• serial:status: Serial connection status changes
• serial:connected: Serial connection established
• serial:disconnected: Serial connection closed
• serial:error: Serial error occurred

Dispensing Events

• dispensed: Cell dispensed successfully
• not-dispensed: Cell dispensing failed

Progress Events

• percentage:open: Progress during openAll() operation
• percentage:enable: Progress during enableAll() operation
• percentage:disable: Progress during disableAll() operation

Message Events

• serial:message: Parsed message received from device

Class: Commands

Static class for generating command byte arrays.

import { Commands } from '@danidoble/serial-node-lockers/Commands';

const openCmd = Commands.openCell({ cell: 5, channel: 1 });
const statusCmd = Commands.statusCell({ cell: 5, channel: 1 });
const enableCmd = Commands.enableCell({ cell: 5, channel: 1 });
const disableCmd = Commands.disableCell({ cell: 5, channel: 1 });

Advanced Usage

Custom Handshake Configuration

const locker = new Locker({
  portPath: '/dev/ttyUSB0',
  baudRate: 9600,
  handshake: {
    command: Buffer.from([
      /* custom bytes */
    ]),
    pattern: 'expected-response-pattern',
    timeout: 2000,
    hexPattern: true
  }
});

Handling Dispensing Progress

locker.on('dispenser:progress', progress => {
  console.log(`Started at: ${progress.startedAt}`);
  console.log(`Elapsed: ${progress.secondsElapsed}s`);
  console.log(`Limit: ${progress.secondsLimit}s`);
  if (progress.finishedAt) {
    console.log(`Finished at: ${progress.finishedAt}`);
  }
});

const result = await locker.dispense({ cell: 1 });

Custom Dispensing Timeout

// Access the underlying service to configure timeouts
locker.service.dispensingLimitSeconds = 5; // 5 seconds timeout

Types

LockerDispenseOptions

interface LockerDispenseOptions {
  cell?: number; // Cell number (1-80)
  status?: boolean; // Expected status (default: true)
}

DispenserDispenseResponse

interface DispenserDispenseResponse {
  dispensed: boolean;
  error: boolean;
  reason: string | null;
}

DispenseStatus

type DispenseStatus = 'idle' | 'in_progress' | 'completed' | 'failed' | 'error' | 'no_response';

Development

Install Dependencies

npm install

Run Tests

npm run test

Build the Library

npm run build

Format Code

npm run format

Lint Code

npm run lint

Requirements

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

Contributing

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

License

This project is licensed under the GPL-3.0 License - see the LICENSE.md file for details.

Author

Danidoble - [email protected]

Links

• GitHub Repository
• Issue Tracker
• NPM Package

Changelog

See GitHub Releases for version history