JS Driver SDK (Tier 1)
JavaScript drivers are .driver.js files in workspace/drivers/. They run in a sandboxed V8 engine with access to transport APIs for communicating with hardware.
Structure
export default {
meta: {
name: "MyDriver",
version: "1.0.0",
description: "Short description of what this driver does.",
group: "instruments", // DriverGroup: "instruments", "motion", "communication", "utilities"
// Note: JS drivers always run behind the safety gate — a
// requiresSafetyGates: false declaration is ignored (gates forced on).
// access is exactly "R", "W" or "R/W" — only "R" and "R/W" properties are polled.
properties: { voltage: { type: "number", access: "R/W", unit: "V", description: "Output voltage" } },
actions: { reset: { description: "Reset device" } },
streams: ["output"],
},
async init(config) { /* set up transport, initialize device */ },
async get(property) { /* return property value */ },
async set(property, value) { /* set property value */ },
async execute(action, args) { /* execute action, return result */ },
async shutdown() { /* clean up */ },
};Connector starter template
Ship a template.js file next to your .driver.js. It is the starter connector content users see when creating a connector for your driver. The packager copies it into the .muxdriver at the package root; the server reads it at scan time. This file is required — node drivers.js build refuses to package a driver without it.
drivers/js/mydriver/
├── mydriver.driver.js
├── manifest.json
└── template.js ← starter connector content (required)Property and action descriptions
Every property and action entry supports two doc fields:
| Field | When it shows | Use it for |
|---|---|---|
description | Always — AI system prompt summary, IntelliSense hover, driver doc page | One-line summary. Keep it tight. |
details | On-demand — driver doc page ("Show details" toggle), IntelliSense hover, fetched via get_connector_schema / get_driver_schema | Short markdown: parameter enums, side effects, failure modes, truncation caps, non-obvious invariants. |
details is never included in the upfront AI system prompt — the LLM only pays for it when it explicitly fetches the full schema. Treat details as the place for everything that would take a user (or an AI agent) two round trips of trial and error to discover from the one-liner.
actions: {
scanBaud: {
description: "Close port, probe candidate baud rates, reopen at a chosen baud",
args: { portPath: "string?", candidates: "array?", durationMs: "number?", reopenAt: "string?" },
details: `\`reopenAt\` accepts \`"original"\` (default), \`"recommended"\`, or a numeric baud.
Results are ranked by printable-ratio descending, \`bytes\` as the tiebreaker.
If every candidate errors, \`recommended\` falls back to the original baud.`
},
},Markdown support: paragraphs, - bullet lists, fenced code blocks, inline bold, italic, and `code`.
Safety gate
JS drivers cannot opt out of the safety gate. Declaring meta.requiresSafetyGates: false has no effect — the loader logs a security warning and forces gates back on. Only built-in drivers and officially-signed C# DLL drivers can opt out. See Safety & access levels.
Available APIs
| API | Description |
|---|---|
createTcpTransport(host, port, opts) | Create TCP transport ({ delimiter, timeout }) |
createSerialTransport(path, opts) | Create serial transport ({ baudRate, delimiter, timeout }) |
__emitStream(stream, data) | Emit streaming data |
__emitEvent(name, data) | Publish event connector:<connector>.<name> (any JSON-serialisable data) for scripts' on() / waitFor(). Use it for occurrences such as a scan or a button press, which a property can't signal when the value repeats |
log.debug/info/warn/error(...) | Logging |
timestamp() | ISO timestamp string |
Sending text vs. bytes
A transport's write(string) sends text encoded as UTF-8, so any character from \x80 to \xFF goes out as two bytes. For binary protocols use writeRaw(data), which sends exactly the bytes you give it:
transport.writeRaw([0xFE, 0x01, 0xC3, 0xFF]); // byte array (or Uint8Array / ArrayBuffer)
transport.writeRaw(0x18); // a single byte
transport.writeRaw("?"); // string: one byte per char, char codes must be ≤ 0xFFA value outside 0–255 (or a char code above 0xFF) throws a RangeError instead of being truncated. To receive bytes, call transport.setRawMode(true) (serial only) and set transport.onRawData = (hex, ts) => …; each chunk arrives as an uppercase hex string.
Security Sandbox
JS drivers run in an isolated ClearScript V8 engine with these restrictions:
require(),import()— blockedprocess,global— deleted fromglobalThis- No access to
fs,net,child_process, or any Node.js APIs - Path traversal —
.driver.jsfiles must reside withinworkspace/drivers/ - Name collision — JS drivers cannot shadow built-in (Tier 0) driver names