@sim86/sdk

Provision simulated hardware the way you provision cloud infrastructure — from TypeScript. Build a board, flash the exact firmware you'd put on real hardware, run it on the Simulator86 cloud, and stream what it does live.

import { createClient, Components } from "@sim86/sdk";

const client = createClient(process.env.SIM86_API_KEY!);
const project = await client.getProject("your-project-id");

const mcu = project.graph.addComponent(Components.STM32F405_EXPRESS);
const led = project.graph.addComponent(Components.LED);
project.graph.connect(mcu.pin("13"), led.pin("+"));
project.graph.connect(mcu.pin("GND"), led.pin("-"));
await mcu.setFlash("./firmware.bin"); // the real binary — path or Uint8Array

const run = await project.graph.run({ duration: 30_000 });

run.stream("led1").subscribe(({ t, value }) => {
  console.log(`${t}ms`, value); // { intensity: 100 } … blinking
});

const { status, reason } = await run.done; // always ends with a truthful reason

Install

npm i @sim86/sdk        # zero runtime dependencies

Node ≥ 22, browsers, Bun, and Deno work out of the box. On Node 18/20, hand in a WebSocket implementation:

const client = createClient(key, { WebSocket: (await import("ws")).default });

Get an API key in the editor: Cloud → API keys (sim86_live_…). Set it as SIM86_API_KEY locally and as a secret in CI.

Runs are detached

A run lives on the Simulator86 cloud, not in your process. Close your laptop, kill the CI job — the simulation keeps going until it hits one of your limits, the firmware exits, or you stop it. No limits means it runs until stopped (soak tests measured in days are the point, not an accident).

const run = await graph.run();          // unbounded
run.detach();                            // your process can exit

// later, anywhere:
const again = await client.attach(runId);
for await (const line of again.logs({ follow: true })) console.log(line.line);
await again.stop();

• run({ duration }) — simulated-time limit (ms). "duration" always means simulated time in this SDK.
• run({ realtimeDuration }) — wall-clock limit (ms).
• client.runs() / project.runs() — everything you have, running or recent.
• run.done — resolves with the terminal status and why: duration, sim-exception: …, node-down, user-stop. A run can never end silently.

Watching and poking

// per-channel, throttled (ms of simulated time between samples)
imu.id; // component ids are stream channels
run.stream("imu1", "gyro", { throttle: 10 }).subscribe(({ value }) => {});

// or the whole board at once (what the editor renders)
for await (const state of run.states({ throttle: 100 })) {
  console.log(state.t, state.ui);
}

// inject events; atMs schedules inside the simulation loop (server-side)
await run.sendEvent(button, "pressed");
await run.at(5_000).press(button);
await run.at(10_000).do(() => console.log("10 simulated seconds in"));

// logs: fetch or follow
const lines = await run.logs();
for await (const line of run.logs({ follow: true })) console.log(line.line);

Streams are telemetry: a slow consumer skips samples (each sample carries a dropped count) and never slows the simulation.

Errors you can catch

AuthError (bad/revoked key) · PaywallError (plan/credits) · NotFoundError (not yours / gone) · SimulationError (refused/failed run) · ApiError (transport). All extend Sim86Error.

Early access notes

• Full component catalog, pin names, and API reference: https://docs.sim86.com
• Logs currently carry run lifecycle lines; firmware UART/RTT and CPU-register channels (record(), stream("pc")) are on the roadmap and will slot into the same APIs.
• Finished runs stay queryable for 7 days; live log tail survives a run by ~15 minutes.
• Surface may move while we're in early access.

Questions: [email protected] · https://sim86.com