**English** | [简体中文](DEVICE-API.zh-cn.md)

# esp-emu-peris peripheral interface spec (v1)

A peripheral = one ES module under `peris/devices/` + one line in
`manifest.json`. Nothing else in the project needs to change.

> **Language**: plugins are **plain JavaScript** (drop-in, no build). The
> framework is compiled TypeScript; the full contract types live in
> `peris/core/types.d.ts` (`DeviceMeta`/`DeviceLike`/`DeviceCtx`/`PinState`
> etc.) and can be referenced from JSDoc for editor hints. The registry
> **validates metadata at load time** (a missing `typeId`/`title`/`pins()`/
> `defaultConfig` errors immediately); the unit tests in
> `tests/unit/devices.test.mjs` are the reference for electrical semantics.

## Module exports

```js
export class Device {          // runs in the worker, talks to the emulator
    static typeId      = 'led';       // unique, stable, kebab-case
    static version     = '1.0.0';     // plugin's own version (row header; logged in docs/CHANGELOG.md)
    static title       = 'LED';       // UI display name
    static category    = 'basic';     // Add-menu grouping
    static description = '...';       // one-line explanation (tooltip)
    static defaultConfig = {...};     // defaults for new instances
    static sharedBus = true;          // optional (M4): pins may overlap with
                                      //   OTHER sharedBus devices (bus wiring)
    static passive = true;            // optional (0.11): pure listener — never
                                      //   drives an input, claims no pad; may
                                      //   overlap with ANY device, and other
                                      //   devices' pin pickers ignore its pads
    static configSchema = [           // generic config editor fields (in the
                                  // expanded details, one per line)
        { key: 'pin',    label: 'GPIO pin', type: 'pin' },
        { key: 'color',  label: 'Colour',   type: 'color' },
        { key: 'name',   label: 'Label',    type: 'text' },
        // also supported: number(min/max/step), select(options:[{value,label}]), checkbox
        // a checkbox may add chip:'pull' + pullWhenChecked:'high'|'low'
        //   → the device row shows a V/G idle-pull badge (click to flip),
        //     see "Row UI conventions" below
    ];
    static pins(cfg) { return [cfg.pin]; }   // claimed GPIOs (conflict detection)

    constructor(ctx, cfg) {}          // cfg = { id, type, ...device settings }
    onPinState(pin, s) {}             // pin-output change callback s={out, oe, cycles}
    onBatch() {}                      // tick after every run_batch (MMIO polling,
                                      //   register-level devices — see below)
    onCommand(cmd, params) {}         // user action sent from the page View
    onEmuReady() {}                   // emulator (re)loaded: re-drive input levels /
                                      //   reset cached register state
    getState() { return {...}; }      // serialisable state pushed to the View (~30fps)
    destroy() {}                      // release / restore pins
}

export class View {             // runs on the page, renders the device view
    constructor(el, sendCmd, host) {}  // el = details body container;
                                       // sendCmd(cmd, params);
                                       // host.updateConfig(patch) requests a config change;
                                       // host.pinInfo?() → { valid, used } pins for multi-pin pickers
    rowIcon(el) {}               // optional: compact interactive row icon (~24px), see below
    render(state) {}             // state comes from Device.getState(); drives icon and body together
    setConfig(cfg) {}            // optional: called after config edits (e.g. LED colour)
    destroy() {}                 // optional: row removed / list rebuilt — Views owning DOM
                                       //   outside their row (floating windows) must clean it up
}
```

## Row UI conventions (0.3.0+)

The peripherals pane is its own column in the three-pane layout
(console | peripherals | debug); each device occupies one row:

```
[icon] [name] [GPIO#] [V/G]                    [▸ expand] [× remove] [⠿ drag]
```

- **Interactive icon** (`View.rowIcon(el)`): a clickable mini widget whose
  semantics the plugin defines — LED opens a colour picker on click (writes
  back via `host.updateConfig({color})`), buttons send press/release while
  held, the toggle switch flips on click. `render(state)` refreshes the icon
  state (lit / pressed / ON) as well. Without rowIcon a placeholder letter
  chip is shown.
  **Call order**: the panel always calls `rowIcon` before `setConfig`, so
  config-driven styling covers the icon; the icon and the details body are two
  visuals of the same state — plugins must share one setter/render
  (see led.js `setColour()`), never a separate styling path for the icon.
- **Name / GPIO box / V·G badge**: rendered generically by the panel, edited
  in place on click (name and GPIO via inline editors, the V/G badge flips
  directly). The GPIO box maps to the schema's first `type:'pin'` field; the
  V/G badge maps to the checkbox marked `chip:'pull'` — when checked it shows
  V (pull-up to VCC) for `pullWhenChecked:'high'` (the default), otherwise G;
  unchecked is the opposite.
- **Expanded details**: the device widget body (`el`, the constructor's first
  argument) + the full config editor (one property per line). Advanced
  features that do not fit in the row live here.
- **Drag sorting** ⠿: dragging is armed only while the grip is held; on
  release the devices order is written back (no worker rebuild).

## ctx (worker-side device context)

| member | description |
|---|---|
| `ctx.id` / `ctx.chip` / `ctx.gpioCount` | device id, chip model, GPIO count |
| `ctx.mmio` | register address tables for `ctx.chip` (LEDC/RMT/GPIO matrix), or `null` when the chip has no table yet — register-level devices must idle then |
| `ctx.setPinInput(pin, high)` | drive a pin's input level (firmware reads it; raises GPIO interrupts) |
| `ctx.subscribe(pins)` / `ctx.unsubscribe()` | subscribe to pin-output changes (onPinState) |
| `ctx.readMem(addr, len)` / `ctx.readU32(addr)` | bus/MMIO reads (LEDC duty, RMT RAM, …) |
| `ctx.pinLevel(pin)` | current driven level straight from `gpio_state()` — true/false while the guest drives the pad (oe), null when released. One wasm read: snapshot channels sparingly (the logic analyzer samples at capture start), never per batch |
| `ctx.cycles()` | emulator cycle counter |
| `ctx.cyclesPerUs` | emulator clock in cycles per µs (edge timing → time units) |
| `ctx.armSampling(batch)` | M4 scheduler: standing run_batch size while this device watches an idle bus |
| `ctx.fineSampling(batch, forCycles)` | M4 scheduler: fine batches for the next `forCycles` cycles (renew while a transfer is in flight); auto-expires on CPU-sleep fast-forward |
| `ctx.releaseSampling()` | drop this device's scheduler leases (destroy) |
| `ctx.markDirty()` | request getState() to be pushed to the page soon |
| `ctx.log(text, level?)` | print a `[Peris]` line on the UART console |

## Register-level devices (M2+)

Signals routed through the **GPIO matrix (LEDC, RMT) never appear in
`onPinState`** (M0 Q2a/Q3a) — a device for such a peripheral polls MMIO
instead:

- implement `onBatch()` (called after every `run_batch`, after the pin
  sample): read registers via `ctx.readU32` + `ctx.mmio` addresses, and
  `ctx.markDirty()` only when the derived state actually changed (duties
  are quantised to 1/1000 in ledc-lib so sub-visible changes stay quiet);
- reset any cached register/wiring state in `onEmuReady()` — a fresh
  emulator instance reads all zeros;
- `static pins(cfg)` returns `[]` when the wiring is firmware-side routing
  (LEDC devices claim no GPIO; two devices on one channel merely mirror).

The M2 plugins keep every shared semantic in **`peris/devices/ledc-lib.js`**
(channel parsing, `GPIO_FUNCn_OUT_SEL_CFG` wiring scan, DUTY_R/timer-DUTY_RES
duty decode, canvas bulb painter + level animator): helper modules like it
live in `peris/devices/` **outside the manifest** (only manifest-listed
modules load as devices) and are imported relatively by the plugins and the
unit tests — never fork a second duty decode or wiring scan.

Two pitfalls the helpers already handle: the generic editor's `<select>`
hands values back as **strings** (`parseChannel` accepts `'3'` and
`Number(null) === 0` is guarded), and `idf.py merge-bin`'s `-o` is relative
to the build dir (`tests/firmware/merge.ps1`).

The M3 WS2812 plugin follows the same pattern with
**`peris/devices/ws2812-lib.js`** (RMT channel-RAM read, `CHnSTATUS` TX-busy
gate, wiring scan, frame decode with reset resync + leading-zero
realignment, LED-grid geometry/painters; channel parsing and the animator
are imported from ledc-lib — same semantics, one implementation). Its
measured constraint, surfaced in the UI: a 48-word channel RAM retains only
the last 46 bits of a frame, so long strips decode only their tail LEDs
(see FEASIBILITY.md §"Key technical details" 3–4).

## Bit-bang protocol devices (M4)

CPU-driven (bit-banged) waveforms ARE visible in `onPinState` — but
`gpio_state()` is sampled once per `run_batch`, so every edge only survives
when the batch is small compared with the signal's half period. Devices
lease batch sizes through the scheduler (`src/core/scheduler.ts`):

- `ctx.armSampling(~1000)` once — a standing watch batch while the bus is
  idle (cheap, resolves a START on buses down to ~20 kHz);
- `ctx.fineSampling(~300, forCycles)` on every edge — renews a fine window
  for the rest of the transfer; it expires on its cycle deadline or when
  the emulator fast-forwards through a CPU sleep (nothing sampleable there).

Timings inside the guest are NOT wall-accurate (`esp_rom_delay_us` runs at
~50% of nominal — FEASIBILITY.md §"M4 measurements"), so decoders must be
level- or ratio-based, never absolute-µs. The M4 plugins follow both rules:

- `peris/devices/bitbang-i2c-slave.js` — 24C02 EEPROM / BME280 models on
  two bit-banged GPIOs (SCL/SDA; `sharedBus` lets several slaves share the
  pair, and the runtime wired-ANDs shared pads' input drives). Engine,
  register models and bit-exact Bosch compensation live in
  `peris/devices/i2c-lib.js`. The slave answers via the SDA input path —
  visible to the master exactly while it releases the pad (open-drain
  idiom); push-pull masters that never release cannot be answered, and
  clock stretching is not modelled.
- `peris/devices/ir-nec.js` — NEC capture from a bit-banged GPIO (edges →
  burst envelope in fine windows, flush after ~25 ms quiet) or from an RMT
  TX channel (34-word frames fit the post-TX channel RAM; the emulator
  leaves `APB_MEM_WADDR` at 0 so mid-TX stitching is impossible). Ratio-
  based decode; `source: auto` prefers RMT routing. Envelope + decode in
  `peris/devices/nec-lib.js`.
- `peris/devices/max7219.js` — MAX7219 display driver on a bit-banged
  DIN/CLK/LOAD bus (write-only: no input path needed). The shift engine
  samples DIN on CLK rising edges, latches 16-bit words on the LOAD rising
  edge, and drops misaligned frames (counted in `dropped`) instead of
  garbling the display. Register model + Code B font + painters in
  `peris/devices/max7219-lib.js`; daisy chains share the pads
  (`sharedBus`, `chain`/`pos` pick each part's word). Lease sizing is at
  the scheduler floor (fine 20 / arm 60): measured against delay-free
  back-to-back `gpio_set_level` pulses (edges ~20 instructions apart), the
  tightest real firmware found — delay-paced bit-bang is covered with
  much wider margins.

## Instrument devices (0.10.0)

- `peris/devices/logic-analyzer.js` — multi-channel GPIO waveform capture
  (up to 8 pads, one trigger: ANY GPIO + rising/falling/any edge or
  Immediate, guest-time window up to 1 h, auto re-arm). Readout math, the
  waveform painter and the floating window live in `peris/devices/la-lib.js`; the
  painter is one implementation shared by the popup, the details
  mini-preview and the row icon. Sampling rides the M4 scheduler like the
  bit-bang devices (arm lease while waiting for the trigger, fine lease
  renewed per edge while recording — the `resolution` config picks the
  fine batch: 20/100/300 instructions). Levels are 1/0 driven and -1 (Z)
  when the guest releases the pad; the analyzer never drives anything, so
  it declares `passive` and legally taps pads ANY device owns (the trigger
  pad gets its own subscription and need not be a channel; it fires only
  when the firmware drives the pad — gpio_state never shows pure-input
  pads). Capture data is pushed in full only when the buffer freezes
  (`done`); run pushes carry progress + live per-channel edge counts.
- **Floating windows** (`la-lib.makeFloatingWindow`): big UIs open a
  draggable, resizable, **non-modal** popup — `position: fixed`, no
  backdrop, so the page underneath keeps every pointer event. Geometry is
  clamped to the viewport and persisted to localStorage. Because such a
  window lives on `document.body` (outside the device row), its View must
  implement `destroy()` to remove it when the row goes away — the panel
  calls `destroy()` on row removal and on list rebuilds. Multi-pin pickers
  inside a View grey out occupied GPIOs through `host.pinInfo()` (the same
  candidate-aware set the generic editor uses).
- **Saleae-style plot model** (also in `la-lib`): a zoomable view
  `{t0, spanUs}` with `viewXform`/`clampView`/`zoomAt` (wheel zoom anchored
  at the cursor, drag pan, fit on double-click), hover measurement
  (`pulseAround` for the pulse under the cursor, `pwmOf` for
  period/frequency/duty from consecutive rising edges), A/B cursors with
  Δt + 1/Δt and edge jumping (`levelAt`, `fmtHz`). The device bumps `capId`
  on every capture start so Views reset zoom/cursors when fresh data
  arrives.

## Message protocol (page ↔ worker)

Added on top of the stock worker protocol (see `peris/protocol.js`):

- page→worker: `peris_config {config}` (apply a config in full),
  `peris_command {id, cmd, params}`
- worker→page: `peris_ready {ok, errors, devices}`, `peris_state {id, state}`,
  `peris_log {level, text}`

## Config files

```json
{
  "perisVersion": 1,
  "chip": "esp32c3",
  "firmware": { "name": "merged-binary.bin", "size": 250048 },
  "devices": [ { "id": "led-1", "type": "led", "pin": 8, "color": "#ff4d4d", "name": "Red" } ]
}
```

- Autosaved to localStorage (`peris.config.v1`, including `chip`, which is
  auto-selected when the page loads); the save/open icons in the panel head
  export/import `.json`.
- **Export file name**: set in the panel-head input (it doubles as the project
  name; empty = auto name `peris-{chip}-{date}.json`), remembered in
  localStorage; naming logic in `peris-panel.ts exportFileName()`.
- **`firmware` is an informational field**: records the name/size(/disk path)
  of the most recently loaded firmware at export time (the path exists only
  when the host exposes the non-standard `File.path` — the browser security
  model provides no full path). Import ignores it and never auto-loads
  firmware; `chip` selects the matching chip when the localStorage config is
  saved/restored, but in an imported JSON it is informational only (it does
  not change the current selection).
- v1 rule: each GPIO can be claimed by at most one device (either direction);
  conflicts surface in the yellow bar at the top of the pane.

## Device development notes (from M0 measurements; see FEASIBILITY.md)

1. **Pin outputs**: firmware GPIO writes are visible in `onPinState`
   (out+oe); **signals routed through the GPIO matrix (LEDC/RMT) never appear
   in the pin registers** — you must read MMIO (LEDC duty registers, RMT
   channel RAM) on `onBatch()`; the address tables arrive via `ctx.mmio`
   (sources: `src/core/mmio/`).
2. **Pin inputs**: `ctx.setPinInput` genuinely reaches the firmware (reads +
   interrupts); button-type devices must re-drive their level in
   `onEmuReady` (levels reset when the emulator reloads).
3. **Time**: emulator time fast-forwards during `vTaskDelay`; do not attempt
   pin-level waveform capture inside CPU sleep windows. Bit-banged waveforms
   while the CPU is active can be sampled between run_batch calls, but keep
   it modest (~99 MIPS with fine batches, 5000+ MIPS with coarse ones).
4. State pushes are throttled to ~30fps; the object returned by `getState()`
   is postMessaged — keep it small and serialisable.
5. **Device actions** from the View always go through `sendCmd(cmd, params)`;
   **config changes** (e.g. picking a colour from the row icon) go through
   `host.updateConfig(patch)` — the single source of truth for config is the
   page's PerisPanel; the worker side must never cache/mutate it. Never touch
   the emulator from the page side.

## Examples

- `peris/devices/led.js` — output device (sigbus subscription)
- `peris/devices/button.js` — input device (setPinInput + onEmuReady)
- `peris/devices/touch-button.js` — inherits button's Device, different View
- `peris/devices/toggle-switch.js` — latching input device
- `peris/devices/pwm-led.js` / `rgb-led.js` — register-level devices
  (onBatch + ctx.mmio + ledc-lib wiring scan/duty decode, canvas
  interpolation View)
- `peris/devices/ws2812.js` — register-level device on the RMT channel RAM
  (onBatch + ctx.mmio + ws2812-lib frame decode, strip/ring/matrix Views)
- `peris/devices/ledc-lib.js` — shared helper module (not a device)
- `peris/devices/ws2812-lib.js` — shared helper module (not a device)
- `peris/devices/bitbang-i2c-slave.js` — bit-bang I2C slave (i2c-lib.js engine)
- `peris/devices/ir-nec.js` — NEC receiver, gpio + RMT capture (nec-lib.js)
- `peris/devices/max7219.js` — MAX7219 display on a bit-banged 3-wire bus
  (max7219-lib.js engine, Code B font, matrix/7-seg painters)
- `peris/devices/logic-analyzer.js` — multi-GPIO waveform capture with a
  floating analyzer window (la-lib.js readout math + painter + window)
- `peris/devices/i2c-lib.js` / `peris/devices/nec-lib.js` /
  `peris/devices/max7219-lib.js` / `peris/devices/la-lib.js` — shared
  helper modules (not devices)