serialpilot-drivers

Ready-to-use device drivers for GPS, CNC, ESP, AT modems, Modbus RTU, and PM sensors.

Higher-level drivers built on SerialPilot — Linux, macOS, and Windows.

npm · SerialPilot · Protocols · Contributing · MIT

---

Quick start

npm install serialpilot @serialpilot/driver-plantower

import { SerialPilot } from 'serialpilot'
import { Plantower } from '@serialpilot/driver-plantower'

const port = new SerialPilot({ path: '/dev/ttyUSB0', baudRate: 9600 })
const sensor = new Plantower({ transport: port })

sensor.on('reading', r => console.log(`PM2.5: ${r.pm2_5} μg/m³  PM10: ${r.pm10} μg/m³`))

await sensor.open()
await sensor.start()

Every driver follows the same pattern: import the class → construct with a transport → listen for events → await open(). Swap Plantower for any other driver and you're off.

Packages

This monorepo ships seven packages:

Package	npm	Purpose
@serialpilot/driver-kit		Shared building blocks: Device base, Transport, MockTransport, RequestQueue, LineBuffer, createLogger
@serialpilot/driver-at		Generic AT-command framework — cellular/LoRa/WiFi-via-AT modems
@serialpilot/driver-gps		NMEA 0183 GPS receiver — GGA/RMC/GSA/GSV, typed Fix events
@serialpilot/driver-grbl		GRBL 1.1 CNC controller — typed status, command-queued G-code, real-time control
@serialpilot/driver-esp-flasher		ESP32/ESP8266 ROM-bootloader flasher — SLIP framing, chip detect, flash with progress
@serialpilot/driver-modbus-rtu		Modbus RTU master — FC 03/04/06/10, CRC-16, typed exception handling
@serialpilot/driver-plantower		Plantower PM sensor — PMS5003/PMS1003/PMS3003, active-mode particulate matter readings

All drivers consume the published serialpilot core toolkit from npm. Each driver's own README has install + quickstart + API reference.

Driver details

@serialpilot/driver-kit

Tiny shared building blocks that every driver depends on: the Device state machine (closed → opening → open → closing → closed), the Transport interface drivers expect from a port, MockTransport for testing, RequestQueue<TResp> for command-response protocols, LineBuffer for text protocols, and createLogger.

@serialpilot/driver-at

Drives any device speaking the AT command protocol — cellular modems (SIMCom, Quectel, u-blox), LoRa modems (RN2483), WiFi-via-AT firmware (ESP-AT). Ships sendCommand(), multi-line response handling, automatic URC dispatch, and 5 standard 3GPP helpers: getIdentity(), getImei(), getIccid(), getSignalStrength(), getNetworkRegistration().

@serialpilot/driver-gps

NMEA 0183 GPS receiver driver. Parses GGA, RMC, GSA, and GSV sentences, merges GGA + RMC within a 1-second window into a typed Fix event with lat/lon/alt/sats/hdop. Supports GSA satellite geometry and GSV satellite visibility.

@serialpilot/driver-grbl

GRBL 1.1 CNC controller driver. Typed status reports (<Idle|WPos:...>), queued G-code streaming with per-line ok acknowledgment, jog/homing/soft-reset, and pollStatus(intervalMs) for live position updates.

@serialpilot/driver-esp-flasher

ESP32 and ESP8266 ROM-bootloader flasher. Handles SLIP framing, auto-reset bootloader entry via DTR/RTS, chip detection by magic register read, and flash download with progress events. Supports ESP32, ESP32-S2, S3, C3, C6, and ESP8266.

@serialpilot/driver-modbus-rtu

Modbus RTU master driver for industrial automation, building management, and energy/utility metering. Reads holding/input registers (FC 03/04), writes single/multiple registers (FC 06/10), with CRC-16 verification, typed exception handling, and per-call timeouts.

@serialpilot/driver-plantower

Plantower PM sensor driver for PMS5003, PMS1003, and PMS3003. Active mode only — the sensor sends readings automatically every ~1 s; the driver listens, frames, parses, and emits typed reading (PMS5003/1003 13-field) and reading-compact (PMS3003 7-field) events.

Architecture

Your code
  ↓
@serialpilot/driver-*   (Device subclasses, typed events, protocol parsing)
  ↓
@serialpilot/driver-kit  (Device base, Transport interface, RequestQueue, LineBuffer)
  ↓
serialpilot               (SerialPilot port — callback-style serial I/O)
  ↓
Node.js / OS serial port

Each driver accepts an injected Transport — you pass a SerialPilot port wrapped in a thin adapter (see any examples/*/src/serialPilotTransport.ts). In tests, swap the port for MockTransport and drive events with .inject().

Examples

Runnable examples live under examples/:

• at-modem-chat — query an AT modem for identity, signal, and registration
• gps-live-fix — print live NMEA fixes
• grbl-jog-cli — interactive CNC jog control
• esp-flash-blink — flash a .bin to an ESP chip
• modbus-read-holding — read holding registers from a Modbus RTU slave
• plantower-read — stream particulate matter readings from a Plantower PM sensor

Each example includes a small serialPilotTransport.ts adapter that wraps SerialPilot's callback-style API in the promise-based Transport interface that drivers expect.

Status

v0.1.0 — initial release. Lint/typecheck/build clean across all workspaces, ≥ 90% line coverage on every driver source file. CI matrix: Node 20/22/24 × ubuntu/macos/windows.

Developing

git clone git@github.com:serialpilot/serialpilot-drivers.git
cd serialpilot-drivers
npm install
npm run lint
npm run typecheck
npm run build
npm test

All four must pass before opening a PR. See CONTRIBUTING.md.

Workspace layout

serialpilot-drivers/
├── packages/driver-kit/   # shared building blocks
├── drivers/               # one dir per driver
│   ├── at/
│   ├── gps/
│   ├── grbl/
│   ├── esp-flasher/
│   ├── modbus-rtu/
│   └── plantower/
├── examples/              # runnable example per driver
│   ├── at-modem-chat/
│   ├── gps-live-fix/
│   ├── grbl-jog-cli/
│   ├── esp-flash-blink/
│   ├── modbus-read-holding/
│   └── plantower-read/
└── …

Adding a driver

Drivers live in drivers/<name>/ and are published as @serialpilot/driver-<name>. Each driver:

1. Has a src/protocol.ts that is I/O-free — protocol encoding/decoding only.
2. Extends Device from @serialpilot/driver-kit and accepts an injected transport.
3. Tests against MockTransport from @serialpilot/driver-kit — never against a real port in CI.
4. Ships a README.md with a working ≤ 30-line quickstart and an example under examples/.
5. Targets ≥ 90% line coverage.

See CONTRIBUTING.md for the full checklist.

Sister repos

• serialpilot — cross-platform serial-port toolkit for Node.js. Bindings, streams, parsers, CLI tools.
• serialpilot-protocols — pure-function protocol codecs and matching Transform-stream parsers (CRC kit, COBS, HDLC, Modbus RTU framing). Browser-clean.

License

MIT — see LICENSE.

Author

Ritesh Rana — contact@riteshrana.engineer

If SerialPilot saves you a weekend, consider buying me a coffee ☕.