serialservo

serialservo

Drive a serial servo controller from Node.js using the classic 3-byte Mini-SSC2 protocol [255, pin, pos]. Its only dependency is serialport.

Install

npm install serialservo

Requires Node.js 20 or newer.

Typical Usage

Defaults are path = /dev/ttyUSB0, baudRate = 9600, loggingEnabled = true.

const SerialServo = require("serialservo");
const ssc = new SerialServo();      // default
ssc.move(0, 100);                   // move pin 0 to position 100
ssc.nav(100, 100);                  // move pins 0 and 1 to position 100
ssc.timedMove(0, 100, 100);         // move pin 0 to 100 for 100ms, then back to 127
ssc.timedNav(100, 100, 100);        // move pins 0 and 1 to 100 for 100ms, then back to 127

Positions (and pins) must be integers in the range 0-254 — 255 is the protocol's sync byte. Out-of-range values throw a RangeError rather than being silently clamped.

Customized Usage

const SerialServo = require("serialservo");
const ssc = new SerialServo({
    path: "/dev/ttyUSB0",
    baudRate: 19200,
    loggingEnabled: false,
    leftMotor: 0,   // pin used as "left" by nav / timedNav
    rightMotor: 1   // pin used as "right" by nav / timedNav
});
ssc.move(0, 100);

If the serial device cannot be opened, the underlying serialport emits an error — serialservo does not fall back to a fake device, so failures surface loudly.

CLI

Once the package is installed in a project (npm install serialservo), run the interactive prompt with npx — no global install needed:

npx serialservo --port /dev/ttyUSB0 --baud 9600

Flags: --port/-p (default /dev/ttyUSB0), --baud/-b (default 9600), --step/-s (default 1), --help/-h.

At the serialservo> prompt:

Command	Effect
<pin> <pos>	Move a pin to a position and make it the active pin
+ / -	Nudge the active pin up/down by the current step
++ / --	Nudge by 2 steps (repeat the sign to multiply)
+N / -N	Nudge by exactly N, e.g. +5, -10
nav <l> <r>	Move the left/right motor pins together
step <n>	Set the +/- increment
help / ?	Show help
exit / quit	Close the port and leave

Example session:

serialservo> 0 127     # pin 0 to 127, now the active pin
serialservo> +         # pin 0 -> 128
serialservo> +5        # pin 0 -> 133
serialservo> 1 200     # pin 1 to 200, now the active pin
serialservo> -         # pin 1 -> 199
serialservo> exit

Serial Servo Controller Protocol

This module uses the 3-byte protocol popularized by the Scott Edwards Mini-SSC2, supported by many serial servo controllers. Every command is exactly three bytes:

[ 255 , pin , pos ]
   |      |     |
   |      |     └─ position, 0-254 (see below)
   |      └─────── servo/pin number, 0-254
   └────────────── sync marker — always 255, never used as a pin or position

• Sync byte (255) — a fixed marker that tells the controller a new command is starting. Because 255 is reserved, pin and pos are only valid in 0-254; serialservo throws a RangeError on anything outside that range rather than silently clamping.
• pin — the servo channel, generally 0-7 or 0-31 depending on the size of your controller.
• pos — the target position, 0-254. 0 is one extreme of travel and 254 the other (≈0–180° on a 0–180° servo). 127 is centered — it's the neutral value timedMove/timedNav return to.

Serial settings are typically 9600 baud, 8 data bits, no parity, 1 stop bit (8N1), which is the default. Some controllers support other baud rates — set baudRate in the constructor to match.

Example Servo Controllers

Search "serial servo controller" and you'll find plenty. A few vendors:

• https://www.pololu.com/
• http://www.lynxmotion.com/
• https://www.sparkfun.com

Testing

Tests use Node's built-in test runner — no test framework to install, and no serial hardware required (a fake port is injected).

npm test
npm run coverage

License

The MIT License (MIT)

Copyright (c) 2014-2026 Scott Preston

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.