Install and start using JSD

Install the public compiled package in your own Node.js application. The library's source repository is private; using the package does not require access to it. No library build, registry login or publishing permission is needed.

Use Node.js 20+ for hardware, or 20.6+ to run the included simulator.

1. Install in your application

If you already have a Node project, use its directory. Otherwise create one:

mkdir my-jsd-app
cd my-jsd-app
npm init -y

Install the client and its runtime peers with your preferred package manager:

npm

npm install @danidoble/serial-node-jsd "serial-core@^0.3.0" "serialport@^13.0.0"

pnpm

pnpm add @danidoble/serial-node-jsd "serial-core@^0.3.0" "serialport@^13.0.0"

Bun

bun add @danidoble/serial-node-jsd "serial-core@^0.3.0" "serialport@^13.0.0"

Yarn

yarn add @danidoble/serial-node-jsd "serial-core@^0.3.0" "serialport@^13.0.0"

Bun can manage the dependencies; these examples execute Node, not the Bun runtime.

2. Try it without a machine

The installed package includes a complete runnable example and a virtual device. Run it from your application directory, without cloning anything:

npm

npx --no-install jsd-example simulate

pnpm

pnpm exec jsd-example simulate

Bun

bun run jsd-example simulate

Yarn

yarn jsd-example simulate

It connects to a virtual port, prints real JSD events, queries the machine, reads logs, simulates a dispense and closes automatically. It never opens a physical port.

Next, follow the complete example to explore its commands, failure scenario and full copyable script.

3. Use a real machine

List the available ports:

npx --no-install jsd-example ports

Then provide the actual path and baud rate:

Linux / macOS

JSD_PORT=/dev/ttyUSB0 JSD_BAUD_RATE=9600 npx --no-install jsd-example connect

Windows PowerShell

$env:JSD_PORT = "COM3"
$env:JSD_BAUD_RATE = "9600"
npx --no-install jsd-example connect

On macOS use your actual /dev/cu.usbserial-... path instead of /dev/ttyUSB0. For pnpm, Bun or Yarn, use the command runner shown in step 2 and replace simulate with ports or connect.

Type help, status, version, id or temperature. This example keeps real dispensing disabled by default. Type quit or press Ctrl+C to disconnect.

4. Write your own application

Import from the package root. Register listeners before starting:

import { JSD } from '@danidoble/serial-node-jsd';

const jsd = new JSD({
  path: '/dev/ttyUSB0', // Replace with the actual path.
  baudRate: 9600,
  autoConnect: false,
  maxReconnectAttempts: 3
});

jsd.on('serial:error', error => console.error(error.message));
jsd.on('serial:jsd-error', message => console.error(message));
jsd.on('serial:connected', info => {
  console.log('Ready:', info.path);
  void jsd.vision.requestMachineIdentification({ machine: 1 })
    .catch(error => console.error(error));
});
jsd.on('vision:machine-id', data => console.log(data));
jsd.on('vision:machine-status', data => {
  console.log(data.machine, data.availabilityToDispense);
});

const shutdown = () => {
  void jsd.stop().catch(error => {
    console.error(error);
    process.exitCode = 1;
  });
};
process.once('SIGINT', shutdown);
process.once('SIGTERM', shutdown);

jsd.start();

This code is also valid JavaScript after saving it as connect.mjs; run it with node connect.mjs. The ts fence enables TypeScript highlighting and editor checking; it does not require compiling the library.

start() returns void. Readiness arrives through serial:connected, and machine availability arrives separately. JSD automatically queries machines 1–4 after connection. Await stop() in your application's shutdown workflow.

For deadlines, command handling, simulation and complete cleanup, copy the full application script.

CommonJS

const { JSD, SerialStatus } = require('@danidoble/serial-node-jsd');

ESM and CommonJS declarations are included. Continue with connection settings, typed events and errors and recovery.