# serialservo

> Drive a serial servo controller using the 3-byte Mini-SSC2 protocol

Latest version **1.0.1** (published 2026-07-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install serialservo
pnpm add serialservo
yarn add serialservo
bun add serialservo
```

Provides the command `serialservo`.

## Health

**Score 45/100 (D)** — status: active.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2026-07-05 |
| First published | 2014-10-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=20 |
| Dependencies | 1 |
| Unpacked size | 16.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Scott Preston |
| Maintainers | scottpreston, prestonresearch |
| Keywords | serial servo controller, ssc, servo, serialport, mini-ssc2 |

## Links

- npm: https://www.npmjs.com/package/serialservo
- Repository: https://github.com/scottpreston/serialservo
- Homepage: https://github.com/scottpreston/serialservo#readme
- Issues: https://github.com/scottpreston/serialservo/issues
- npm.io page: https://npm.io/package/serialservo

## Dependencies (1)

- [serialport](https://npm.io/package/serialport.md) ^13.0.0

## Recent versions

- 1.0.1 (latest) — 2026-07-05
- 1.0.0 — 2026-07-05
- 0.1.5 — 2016-10-04
- 0.1.4 — 2016-06-02
- 0.1.3 — 2016-06-01
- 0.1.2 — 2016-05-31
- 0.1.1 — 2016-05-23
- 0.1.0 — 2014-10-10

## README

# 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`](https://www.npmjs.com/package/serialport).

## Install

```bash
npm install serialservo
```

Requires Node.js 20 or newer.

## Typical Usage

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

```javascript
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

```javascript
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:

```bash
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).

```bash
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.

---
_Source: https://npm.io/package/serialservo · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._