---
url: /guide/getting-started.md
---
# Getting Started

## Requirements

| Requirement | Version                            |
| ----------- | ---------------------------------- |
| Node.js     | ≥ 18                               |
| TypeScript  | ≥ 5.0                              |
| Browser     | Chrome 89+ / Edge 89+ (Web Serial) |

> **Note:** Web Serial requires a secure context (HTTPS or `localhost`) and
> a Chromium-based browser. WebUSB and Web Bluetooth have similar requirements.

## Installation

```bash
npm install webserial-core
```

## Quick example — Web Serial

```ts
import { AbstractSerialDevice, delimiter } from "webserial-core";

class MyDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: true,
    });
  }

  protected async handshake(): Promise<boolean> {
    // Optional: send a command and wait for confirmation.
    // Return true to accept any port.
    return true;
  }
}

const device = new MyDevice();

device.on("serial:connected", () => console.log("Connected!"));
device.on("serial:data", (line) => console.log("Received:", line));
device.on("serial:error", (err) => console.error("Error:", err.message));

// Opens the browser port picker and connects
await device.connect();

// Send data
await device.send("LED_ON\n");

// Disconnect
await device.disconnect();
```

## Switching transport providers

All four adapters implement the same `SerialProvider` interface. Inject your
chosen provider once before constructing any device:

```ts
import { AbstractSerialDevice } from "webserial-core";
import { WebUsbProvider } from "webserial-core/adapters/web-usb";
// or:
import { createBluetoothProvider } from "webserial-core/adapters/web-bluetooth";
// or:
import { createWebSocketProvider } from "webserial-core/adapters/websocket";

// WebUSB polyfill (useful on Android Chrome)
AbstractSerialDevice.setProvider(new WebUsbProvider());

// Web Bluetooth NUS
AbstractSerialDevice.setProvider(createBluetoothProvider());

// WebSocket bridge (Node.js server required — see demos/websocket/README.md)
AbstractSerialDevice.setProvider(
  createWebSocketProvider("ws://127.0.0.1:8080/?token=TOKEN"),
);
```

After calling `setProvider`, every `AbstractSerialDevice` subclass instance
will use that transport automatically.

## Configuration options

All options are passed to the `super()` call in your device constructor:

```ts
super({
  baudRate: 9600, // Serial baud rate
  dataBits: 8, // 7 or 8
  stopBits: 1, // 1 or 2
  parity: "none", // "none" | "even" | "odd"
  flowControl: "none", // "none" | "hardware"
  bufferSize: 255, // Internal read buffer size (bytes)
  parser: delimiter("\n"), // How to split incoming bytes into messages
  commandTimeout: 3000, // ms before a queued command times out
  autoReconnect: true, // Automatically reconnect on disconnect
  autoReconnectInterval: 1500, // ms between reconnect attempts
  handshakeTimeout: 2000, // ms allowed for handshake() to complete
  filters: [], // USB vendor/product ID filters
});
```

## Next steps

* Read the [Architecture guide](./architecture.md) to understand how the pieces
  fit together.
* Browse the [API reference](/api/abstract-serial-device) for full method and
  event documentation.
* Check the [examples](/examples/web-serial) for copy-paste demos.
* If you are upgrading from v1, see the [Migration guide](./migration-v1-v2.md).

---

---
url: /guide/architecture.md
---
# Architecture

## Overview

```
┌──────────────────────────────────────────────────────────┐
│                    Your device class                     │
│              (extends AbstractSerialDevice<T>)           │
└───────────────────────┬──────────────────────────────────┘
                        │ inherits
                        ▼
┌──────────────────────────────────────────────────────────┐
│              AbstractSerialDevice<T>                     │
│  ┌─────────────────┐  ┌──────────┐  ┌────────────────┐  │
│  │  SerialRegistry │  │ CmdQueue │  │ SerialEventEmit│  │
│  │  (port locks)   │  │ (FIFO)   │  │  ter<EventMap> │  │
│  └─────────────────┘  └──────────┘  └────────────────┘  │
│                                                          │
│  connect() / disconnect() / send() / handshake()         │
└───────────────────────┬──────────────────────────────────┘
                        │ delegates to
                        ▼
┌──────────────────────────────────────────────────────────┐
│                   SerialProvider                         │
│  (requestPort, getPorts — returns SerialPort objects)    │
├──────────────────────────────────────────────────────────┤
│  ┌────────────────┐ ┌──────────────────┐ ┌───────────┐  │
│  │ Navigator      │ │  WebUsbProvider  │ │ WebBT/WS  │  │
│  │ (native Web    │ │  (USB polyfill)  │ │ providers │  │
│  │  Serial API)   │ │                  │ │           │  │
│  └────────────────┘ └──────────────────┘ └───────────┘  │
└──────────────────────────────────────────────────────────┘
```

## Core components

### `AbstractSerialDevice<T>`

The base class your device inherits from. It manages the full connection
lifecycle:

1. **`connect()`** — calls `provider.requestPort()`, opens the port, runs
   `handshake()`, then starts the read loop.
2. **Read loop** — continuously reads `Uint8Array` chunks from the port's
   `ReadableStream` and feeds them through the configured `SerialParser<T>`.
   Every time the parser emits a value, a `serial:data` event fires.
3. **`send(data)`** — encodes strings/bytes, enqueues the write in
   `CommandQueue`, and flushes to the port's `WritableStream`.
4. **`disconnect()`** — cancels the read loop, drains the queue, closes the
   port, and fires `serial:disconnected`.
5. **Auto-reconnect** — if `autoReconnect: true` and the connection drops,
   the device waits `autoReconnectInterval` ms and calls `connect()` again.

### `SerialProvider`

```ts
interface SerialProvider {
  requestPort(options?: { filters?: SerialPortFilter[] }): Promise<SerialPort>;
  getPorts(): Promise<SerialPort[]>;
}
```

The default provider uses `navigator.serial` (native Web Serial API). Inject
a custom provider for WebUSB, Web Bluetooth, or WebSocket.

### `SerialParser<T>`

```ts
interface SerialParser<T> {
  transform(chunk: Uint8Array, push: (value: T) => void): void;
  flush?(push: (value: T) => void): void;
}
```

Receives raw bytes and calls `push()` for each complete message. Three
built-in parsers are included:

| Parser       | Factory          | Description                                 |
| ------------ | ---------------- | ------------------------------------------- |
| Delimiter    | `delimiter(sep)` | Splits on a byte sequence (e.g. `"\n"`)     |
| Fixed length | `fixedLength(n)` | Emits every N bytes                         |
| Raw          | `raw()`          | Passes each chunk unchanged as `Uint8Array` |

### `CommandQueue`

A FIFO queue that serialises writes to the port. Each `send()` call enqueues
a write. If a command does not complete within `commandTimeout` ms, a
`serial:timeout` event fires and the next command proceeds.

### `SerialRegistry`

A global singleton that tracks which ports are currently open. Prevents two
`AbstractSerialDevice` instances from opening the same port simultaneously.

### `SerialEventEmitter<EventMap>`

A minimal typed event emitter. `on`, `off`, and `emit` are all fully typed
using the `SerialEventMap<T>` generic, so TypeScript knows the exact payload
type for every event.

## Data flow

```
SerialPort.readable (ReadableStream<Uint8Array>)
        │
        ▼
   Read loop (pump)
        │  Uint8Array chunks
        ▼
   SerialParser<T>.transform(chunk, push)
        │  Parsed values of type T
        ▼
   emit("serial:data", value)
        │
        ▼
   Your event handler
```

## Provider injection

```ts
// Global — affects all AbstractSerialDevice instances
AbstractSerialDevice.setProvider(myProvider);

// Or pass it directly to the constructor (per-instance)
super({ ...options, provider: myProvider });
```

---

---
url: /guide/migration-v1-v2.md
---
# Migrating from v1

> **v2 is a complete rewrite of webserial-core and is not backwards compatible with v1.**

Version 2 introduces a new architecture, new adapter system, new folder structure, new build
output format, and changes to every public API. There is no incremental upgrade path.

***

## Recommended approach

The cleanest way to migrate is to **start fresh** with v2:

1. Uninstall v1 and install v2:

   ```bash
   npm remove webserial-core
   npm install webserial-core@latest
   ```

2. Delete any existing extension of the old `SerialDevice` class.

3. Create a new class extending `AbstractSerialDevice<T>` following the
   [Getting started](./getting-started.md) guide.

***

## Why a full rewrite?

Version 1 was a prototype that proved the concept. Version 2 was designed from scratch with
the following goals that required breaking changes at every layer:

* **Strict TypeScript** — no `any`, full JSDoc, named interfaces for every option
* **Modular adapter system** — WebUSB, Web Bluetooth, and WebSocket are first-class transports
* **Dual ESM + CJS output** — proper `.mjs` / `.cjs` / `.umd.cjs` build via Vite
* **Isolated responsibilities** — parsers, queue, events, registry, and adapters are all
  separate modules that can be tested independently
* **English-only source** — all source code, JSDoc, and error messages are in English

***

## Reference

:::tip Start here
Read the [Getting started](./getting-started.md) guide for the full v2 API.
:::

* [API — AbstractSerialDevice](../api/abstract-serial-device.md)
* [API — Events](../api/events.md)
* [API — Parsers](../api/parsers.md)
* [Examples](../examples/web-serial.md)

---

---
url: /guide/contributing.md
---
# Contributing

Thank you for your interest in contributing to **webserial-core**!

## Development setup

```bash
git clone https://github.com/danidoble/webserial-core.git
cd webserial-core
npm install
```

Start the Vite dev server to test the demos interactively:

```bash
npm run dev
```

Then open any of the demo pages in your browser:

* `http://localhost:5173/` — Web Serial (native)
* `http://localhost:5173/demos/web-usb/` — WebUSB Polyfill
* `http://localhost:5173/demos/web-bluetooth/` — Web Bluetooth
* `http://localhost:5173/demos/websocket/` — WebSocket Bridge

## Code style

* **TypeScript strict mode** — no `any`, all public APIs fully typed.
* **ESM imports** — use `.js` extension on relative imports (e.g.
  `import x from "./foo.js"`). Vite resolves these to the `.ts` source files.
* **English only** — all comments, JSDoc, variable names, and string literals
  must be in English.
* **JSDoc** — all exported symbols must have JSDoc with `@param`, `@returns`,
  and `@throws` where applicable.

Run lint and format checks before pushing:

```bash
npm run lint
npm run format
```

## Building

```bash
npm run build
```

Produces:

```
dist/
  webserial-core.mjs      ← ESM (tree-shakeable, for bundlers)
  webserial-core.cjs      ← CommonJS (Node.js / legacy bundlers)
  webserial-core.umd.cjs  ← UMD (standalone <script> tag / CDN)
  index.d.ts              ← Bundled TypeScript declarations
```

## Building the docs

```bash
npm run docs:dev   # Live preview
npm run docs:build # Static output → docs/.vitepress/dist
```

## Submitting a pull request

1. Fork the repository and create a branch: `git checkout -b feat/my-feature`
2. Make your changes and add JSDoc to any new public symbols.
3. Run `npm run lint` and `npm run format`.
4. Verify the build: `npm run build`.
5. Push and open a PR against `main`.

## Adding a new adapter

Place adapter code under `src/adapters/<name>/`:

```
src/adapters/my-adapter/
  MyAdapter.ts   ← implements SerialProvider
  index.ts       ← re-exports
```

Then re-export from `src/index.ts`:

```ts
export * from "./adapters/my-adapter/index.js";
```

Add a demo under `demos/my-adapter/` following the existing demo structure.

---

---
url: /api/abstract-serial-device.md
---
# AbstractSerialDevice\<T>

`AbstractSerialDevice<T>` is the heart of the library. Extend it to create
a device driver for any serial-connected device.

## Type parameter

| Parameter | Description                                                                                           |
| --------- | ----------------------------------------------------------------------------------------------------- |
| `T`       | The type of data emitted by `serial:data` events (e.g. `string`, `Uint8Array`, your own message type) |

## Constructor

```ts
protected constructor(options: SerialDeviceOptions<T>)
```

Called from your subclass via `super(options)`.

See [`SerialDeviceOptions<T>`](/api/types#serialdeviceoptions) for all fields.

## Static methods

### `setProvider(provider)`

```ts
static setProvider(provider: SerialProvider): void
```

Injects a global `SerialProvider` that all device instances will use.
Call this once before constructing any device.

```ts
AbstractSerialDevice.setProvider(new WebUsbProvider());
```

### Per-instance provider

You can also set a provider for a **single device instance** by passing
`provider` in the constructor options. This takes precedence over the
global provider and does not affect other instances.

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createBluetoothProvider,
  createWebSocketProvider,
} from "webserial-core";
import { WebUsbProvider } from "webserial-core";

// One instance using Web Bluetooth
class BleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      provider: createBluetoothProvider(),
    });
  }
  protected async handshake(): Promise<boolean> { return true; }
}

// Another instance using WebUSB in the same app
class UsbDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 115200,
      parser: delimiter("\n"),
      provider: new WebUsbProvider(),
    });
  }
  protected async handshake(): Promise<boolean> { return true; }
}

// Yet another instance tunnelled over WebSocket
class WsDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      provider: createWebSocketProvider("ws://127.0.0.1:8080/?token=TOKEN"),
    });
  }
  protected async handshake(): Promise<boolean> { return true; }
}

// All three co-exist; no global provider is touched
const ble = new BleDevice();
const usb = new UsbDevice();
const ws  = new WsDevice();
```

Provider resolution order per instance:

| Priority | Source |
| -------- | ------ |
| 1 (highest) | `options.provider` passed to the constructor |
| 2 | `AbstractSerialDevice.setProvider(...)` global static |
| 3 (lowest) | `navigator.serial` native Web Serial API |

## Instance methods

### `connect()`

```ts
connect(): Promise<void>
```

Opens the port picker (or auto-selects a previously authorized port), runs the
`handshake()`, and starts the read loop. Emits `serial:connecting` at the
start and `serial:connected` on success.

Throws `SerialPortConflictError` if another device instance already holds the
port. Throws `SerialPermissionError` if the user denies access.

### `disconnect()`

```ts
disconnect(): Promise<void>
```

Cancels the read loop, drains the command queue, closes the port, and emits
`serial:disconnected`. Disables auto-reconnect for this session.

### `isConnected()`

```ts
isConnected(): boolean
```

Returns `true` if the port is currently open. `false` if disconnected or in the process of connecting.

### `isDisconnected()`

```ts
isDisconnected(): boolean
```

Returns `true` if the port is currently closed. `false` if connected or in the process of disconnecting.

### `send(data)`

```ts
send(data: string | Uint8Array): Promise<void>
```

Encodes `data` (UTF-8 if string) and enqueues the write. Returns when the
bytes have been flushed to the port. Emits `serial:sent` with the raw bytes.

### `on(event, handler)` / `off(event, handler)`

```ts
on<K extends keyof SerialEventMap<T>>(event: K, handler: SerialEventMap<T>[K]): this
off<K extends keyof SerialEventMap<T>>(event: K, handler: SerialEventMap<T>[K]): this
```

Subscribe to or unsubscribe from a typed event. See the [Events reference](/api/events).

## Abstract methods

### `handshake()`

```ts
protected abstract handshake(): Promise<boolean>
```

Called after the port opens, before the first `serial:data` event. Return
`true` to accept the connection or `false` to reject it (which triggers a
disconnect). Use this for device identification or initial configuration.

```ts
protected async handshake(): Promise<boolean> {
  await this.send("PING\n");
  return new Promise((resolve) => {
    const handler = (data: string) => {
      this.off("serial:data", handler);
      resolve(data.trim() === "PONG");
    };
    this.on("serial:data", handler);
  });
}
```

Return `true` immediately to skip the handshake and accept any port:

```ts
protected async handshake(): Promise<boolean> {
  return true;
}
```

## Protected properties

| Property      | Type                 | Description                                             |
| ------------- | -------------------- | ------------------------------------------------------- |
| `isConnected` | `boolean`            | Whether the port is currently open                      |
| `port`        | `SerialPort \| null` | The underlying port object, or `null` when disconnected |

---

---
url: /api/web-usb-provider.md
---
# WebUsbProvider

`WebUsbProvider` implements `SerialProvider` using the
[WebUSB API](https://developer.mozilla.org/en-US/docs/Web/API/WebUSB_API)
as a polyfill for the native Web Serial API.

## When to use

* **Android Chrome** — Web Serial is not available; WebUSB is the only way to
  talk to USB serial adapters.
* **Desktop testing** — Force the WebUSB code path to verify behaviour before
  deploying to Android.
* **Custom USB devices** — Devices not exposed via Web Serial (e.g. custom
  vendor-class USB).

## Supported protocols

| Protocol       | USB class       | Notes                         |
| -------------- | --------------- | ----------------------------- |
| CDC ACM        | Class 0x02      | Standard Arduino, ST-LINK     |
| CP210x / CH340 | Vendor-specific | Common USB-UART bridges       |
| Raw bulk       | Any class       | Generic bulk-transfer devices |

## Import

```ts
import { WebUsbProvider } from "webserial-core";
```

## Constructor

```ts
new WebUsbProvider(options?: SerialPolyfillOptions)
```

| Option                      | Type     | Default | Description                               |
| --------------------------- | -------- | ------- | ----------------------------------------- |
| `usbControlInterfaceClass`  | `number` | `10`    | USB interface class for control transfers |
| `usbTransferInterfaceClass` | `number` | `10`    | USB interface class for bulk transfers    |

For devices using vendor-class interfaces (CP210x, CH340):

```ts
new WebUsbProvider({
  usbControlInterfaceClass: 255,
  usbTransferInterfaceClass: 255,
});
```

## Usage

```ts
import { AbstractSerialDevice, delimiter } from "webserial-core";
import { WebUsbProvider } from "webserial-core";

AbstractSerialDevice.setProvider(
  new WebUsbProvider({
    usbControlInterfaceClass: 255,
    usbTransferInterfaceClass: 255,
  }),
);

class MyDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      filters: [{ usbVendorId: 0x10c4, usbProductId: 0xea60 }], // CP2102
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyDevice();
await device.connect(); // Opens WebUSB device picker
```

## Per-instance usage

Pass `provider` (and optionally `polyfillOptions`) in the constructor options
to bind `WebUsbProvider` to a single device instance without touching the
global provider.

```ts
import { AbstractSerialDevice, delimiter, WebUsbProvider } from "webserial-core";

class MyUsbDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      filters: [{ usbVendorId: 0x10c4, usbProductId: 0xea60 }],
      provider: new WebUsbProvider({
        usbControlInterfaceClass: 255,
        usbTransferInterfaceClass: 255,
      }),
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyUsbDevice();
await device.connect();
```

Alternatively, pass `polyfillOptions` separately and let the library forward
them to whichever provider resolves for that instance:

```ts
class MyUsbDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      provider: new WebUsbProvider(),
      polyfillOptions: { usbControlInterfaceClass: 255 },
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}
```

## Browser support

Requires a Chromium-based browser with WebUSB enabled. Not available in Firefox
or Safari. Requires HTTPS or `localhost`.

---

---
url: /api/web-bluetooth-provider.md
---
# WebBluetoothProvider

`createBluetoothProvider()` returns a `SerialProvider` that uses the
[Web Bluetooth API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API)
over GATT to emulate a serial connection.

## Supported service

Implements the **Nordic UART Service (NUS)** over BLE:

| UUID                                   | Role                                                |
| -------------------------------------- | --------------------------------------------------- |
| `6e400001-b5a3-f393-e0a9-e50e24dcca9e` | Primary service                                     |
| `6e400002-b5a3-f393-e0a9-e50e24dcca9e` | TX characteristic (browser writes)                  |
| `6e400003-b5a3-f393-e0a9-e50e24dcca9e` | RX characteristic (browser reads via notifications) |

Compatible hardware: nRF52 series, ESP32 BLE UART, HC-08 / AT-09 BLE modules,
or any firmware advertising the NUS service.

## Import

```ts
import { createBluetoothProvider } from "webserial-core";
```

## Factory function

```ts
createBluetoothProvider(): SerialProvider
```

Returns a new `SerialProvider` instance. No options — the BLE MTU and
inter-chunk delay are fixed at safe defaults (20-byte MTU, 10 ms delay).

## Usage

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createBluetoothProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(createBluetoothProvider());

class MyBleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600, // Ignored over BLE, kept for interface compatibility
      parser: delimiter("\n"),
      autoReconnect: false, // BLE reconnect requires re-pairing; handle manually
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyBleDevice();
await device.connect(); // Opens Web Bluetooth device picker
```

## Per-instance usage

Pass `provider` directly in the constructor options to scope the BLE provider
to a single device instance. The global provider set via
`AbstractSerialDevice.setProvider()` is not touched, so other devices in the
same app continue using their own providers.

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createBluetoothProvider,
} from "webserial-core";

class MyBleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: false,
      provider: createBluetoothProvider(), // BLE only for this instance
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyBleDevice();
await device.connect();
```

This is especially useful when an app manages multiple device types
simultaneously — for example, one BLE device alongside a USB or WebSocket
device.

## MTU and chunking

BLE has a default MTU of **20 bytes** for `writeValueWithoutResponse`. The
provider automatically splits writes into 20-byte chunks with a 10 ms inter-
chunk delay to avoid overflowing the BLE stack.

## Browser support

Requires Chrome 56+ on desktop (macOS, Windows, Linux with BlueZ), Chrome on
Android, or Edge. Not available in Firefox or Safari. Requires HTTPS or
`localhost`.

## Notes

* `baudRate` in `SerialDeviceOptions` is ignored over BLE. The physical link
  speed is determined by the BLE connection parameters.
* `autoReconnect: false` is recommended — BLE reconnection requires the user
  to re-pair the device through the browser picker.

---

---
url: /api/websocket-provider.md
---
# WebSocketProvider

`createWebSocketProvider(serverUrl)` returns a `SerialProvider` that relays
serial I/O to a Node.js bridge server over a WebSocket connection.

## When to use

* Access serial ports on a remote machine (e.g. a Raspberry Pi) from a browser.
* Build web UIs for devices connected to a server behind a firewall.
* Test serial code in an environment where Web Serial is unavailable.

## Import

```ts
import { createWebSocketProvider } from "webserial-core";
```

## Factory function

```ts
createWebSocketProvider(serverUrl: string): SerialProvider
```

| Parameter   | Type     | Description                                                       |
| ----------- | -------- | ----------------------------------------------------------------- |
| `serverUrl` | `string` | WebSocket URL of the bridge server (e.g. `"ws://127.0.0.1:8080/?token=TOKEN"`) |

## Usage

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createWebSocketProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(
  createWebSocketProvider("ws://127.0.0.1:8080/?token=TOKEN"),
);

class MyDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: true,
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyDevice();
await device.connect(); // Connects to the first port listed by the bridge
```

## Per-instance usage

Pass `provider` in the constructor options to scope the WebSocket provider to
a single device instance. This is useful when different devices connect to
different bridge servers, or when one device uses WebSocket while another uses
a different provider in the same app.

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createWebSocketProvider,
} from "webserial-core";

class RemoteDevice extends AbstractSerialDevice<string> {
  constructor(bridgeUrl: string) {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: true,
      provider: createWebSocketProvider(bridgeUrl), // WS only for this instance
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

// Two independent instances, each with its own bridge URL
const deviceA = new RemoteDevice("ws://pi-sensor.local:8080");
const deviceB = new RemoteDevice("ws://pi-actuator.local:8080");

await deviceA.connect();
await deviceB.connect();
```

## Bridge server

A ready-to-use Node.js bridge server is included at
`demos/websocket/server.js`. See the
[WebSocket Bridge demo README](https://github.com/danidoble/webserial-core/tree/main/demos/websocket)
for setup instructions.

## Wire protocol

All messages are JSON objects sent over the WebSocket connection.

| Direction        | Type         | Payload description                                      |
| ---------------- | ------------ | -------------------------------------------------------- |
| Browser → Server | `list-ports` | `{ filters: SerialPortFilter[] }`                        |
| Server → Browser | `port-list`  | `{ payload: PortInfo[] }`                                |
| Browser → Server | `open`       | `{ path, baudRate, dataBits, stopBits, parity, parser }` |
| Server → Browser | `opened`     | acknowledge                                              |
| Browser → Server | `write`      | `{ bytes: number[] }`                                    |
| Server → Browser | `data`       | `{ bytes: number[] }`                                    |
| Browser → Server | `close`      | —                                                        |
| Server → Browser | `closed`     | —                                                        |
| Server → Browser | `error`      | `{ payload: { message: string } }`                       |

## Port selection

`requestPort()` opens a new WebSocket connection, requests the port list, and
**auto-selects the first available port**. For production apps, display a UI
picker over the returned port list before calling `open`.

## Security note

The bridge server has raw access to serial ports. Deploy it only on trusted
networks and add authentication for any internet-facing setup.

---

---
url: /api/parsers.md
---
# Parsers

Parsers transform a stream of raw `Uint8Array` chunks into structured values
of type `T`. Pass a parser to `SerialDeviceOptions.parser`.

## Built-in parsers

### `delimiter(separator, options?)`

Accumulates bytes until the delimiter sequence is found, then emits the frame
with the delimiter stripped (unless `includeDelimiter` is `true`).

* When `separator` is a **string**, bytes are decoded as UTF-8 and a `string` is emitted.
* When `separator` is a **`Uint8Array`** or **`number[]`**, raw bytes are emitted as `Uint8Array`.

```ts
import { delimiter } from "webserial-core";

// Split on newline — good for Arduino Serial.println()
parser: delimiter("\n");

// Split on carriage-return + newline
parser: delimiter("\r\n");

// Include the delimiter in the emitted value
parser: delimiter("\n", { includeDelimiter: true });

// Split on a binary sequence — emits Uint8Array
parser: delimiter(new Uint8Array([0x0d, 0x0a]));

// Split using a number array — emits Uint8Array
parser: delimiter([0xaa, 0xff]);
```

| Parameter          | Type                                | Description                                               |
| ------------------ | ----------------------------------- | --------------------------------------------------------- |
| `separator`        | `string \| Uint8Array \| number[]`  | Byte sequence that marks the end of a frame               |
| `options.includeDelimiter` | `boolean`                  | Append the delimiter to each emitted value. Default: `false` |

**Emits:** `string` (when separator is `string`) · `Uint8Array` (when separator is binary)

***

### `readline(options?)`

Splits the byte stream on a configurable line delimiter and emits each line as
a decoded string. Equivalent to `@serialport/parser-readline`.

```ts
import { readline } from "webserial-core";

// Default — split on '\n', UTF-8
parser: readline();

// Custom delimiter and encoding
parser: readline({ delimiter: "\r\n", encoding: "ascii" });

// Include the delimiter
parser: readline({ delimiter: "\n", includeDelimiter: true });
```

| Option             | Type                               | Default  | Description                                     |
| ------------------ | ---------------------------------- | -------- | ----------------------------------------------- |
| `delimiter`        | `string \| Uint8Array \| number[]` | `'\n'`   | Line terminator sequence                        |
| `includeDelimiter` | `boolean`                          | `false`  | Append the delimiter to each emitted string     |
| `encoding`         | `string`                           | `'utf-8'`| Text encoding used to decode bytes              |

**Emits:** `string`

***

### `fixedLength(length)`

Emits every N bytes as a raw `Uint8Array`. Useful for binary protocols with
fixed-size packets.

```ts
import { fixedLength } from "webserial-core";

// Emit every 16 bytes
parser: fixedLength(16);
```

| Parameter | Type     | Description               |
| --------- | -------- | ------------------------- |
| `length`  | `number` | Number of bytes per frame |

**Emits:** `Uint8Array`

***

### `raw()`

Passes each chunk from the port unchanged. Use this when you want to handle
framing yourself.

```ts
import { raw } from "webserial-core";

parser: raw();
```

**Emits:** `Uint8Array`

***

### `interByteTimeout(options)`

Buffers incoming bytes and emits them after a period of silence (`interval` ms
with no new bytes), or when the buffer reaches `maxBufferSize`. Equivalent to
`@serialport/parser-inter-byte-timeout`.

```ts
import { interByteTimeout } from "webserial-core";

// Emit buffered data after 30 ms of silence
parser: interByteTimeout({ interval: 30 });

// With a max buffer cap
parser: interByteTimeout({ interval: 30, maxBufferSize: 1024 });
```

| Option          | Type     | Default  | Description                                                    |
| --------------- | -------- | -------- | -------------------------------------------------------------- |
| `interval`      | `number` | —        | Silence period in milliseconds before emitting (**required**)  |
| `maxBufferSize` | `number` | `65536`  | Maximum bytes to buffer before forcing an emit                 |

**Emits:** `Uint8Array`

***

### `packetLength(options?)`

Frames packets using a leading delimiter byte and an embedded length field.
Equivalent to `@serialport/parser-packet-length`.

Default packet layout: `[0xAA][0x00][len][payload...][footer]`

```ts
import { packetLength } from "webserial-core";

// Default options
parser: packetLength();

// Custom packet structure: [0xBC][0x00][lenHi][lenLo][cargo...][footer0][footer1]
parser: packetLength({ delimiter: 0xbc, packetOverhead: 5, lengthBytes: 2, lengthOffset: 2 });
```

| Option          | Type     | Default | Description                                                           |
| --------------- | -------- | ------- | --------------------------------------------------------------------- |
| `delimiter`     | `number` | `0xAA`  | Byte value that marks the start of each packet                        |
| `packetOverhead`| `number` | `2`     | Total fixed overhead bytes (delimiter + length field(s) + any footer) |
| `lengthBytes`   | `number` | `1`     | Number of bytes that encode the payload length                        |
| `lengthOffset`  | `number` | `1`     | Byte offset from the delimiter to the first length byte               |
| `maxLen`        | `number` | `0xFF`  | Maximum allowed payload length; packets exceeding this are discarded  |

**Emits:** `Uint8Array`

***

### `regexParser(options)`

Decodes incoming bytes and splits the resulting string on a regular expression,
emitting each segment. Equivalent to `@serialport/parser-regex`.

```ts
import { regexParser } from "webserial-core";

// Split on any combination of \r and \n
parser: regexParser({ regex: /[\r\n]+/ });

// Split on semicolons, case-insensitive
parser: regexParser({ regex: /;+/ });
```

| Option     | Type               | Default   | Description                              |
| ---------- | ------------------ | --------- | ---------------------------------------- |
| `regex`    | `RegExp \| string` | —         | Pattern used to split the incoming text  |
| `encoding` | `string`           | `'utf-8'` | Text encoding used to decode bytes       |

**Emits:** `string`

***

### `readyParser(options)`

Discards all incoming bytes until a configurable "ready" sequence is detected.
After that, every subsequent byte chunk is emitted as-is. Fires an optional
`onReady` callback when the sequence is found. Equivalent to
`@serialport/parser-ready`.

```ts
import { readyParser } from "webserial-core";

parser: readyParser({
  delimiter: "READY\n",
  onReady: () => console.log("device is ready"),
});
```

| Option      | Type                               | Description                                              |
| ----------- | ---------------------------------- | -------------------------------------------------------- |
| `delimiter` | `string \| Uint8Array \| number[]` | Byte sequence that signals the device is ready (**required**) |
| `onReady`   | `() => void`                       | Called once when the ready sequence is detected          |

**Emits:** `Uint8Array` (all data received after the ready sequence)

***

### `ccTalk(maxDelayBetweenBytesMs?)`

Parses [ccTalk](https://en.wikipedia.org/wiki/CcTalk) bus packets. Each packet
is `N + 5` bytes where `N` is the data length in byte 1. The internal buffer is
discarded if no byte arrives within `maxDelayBetweenBytesMs`. Equivalent to
`@serialport/parser-cctalk`.

```ts
import { ccTalk } from "webserial-core";

// Default 50 ms inter-byte timeout
parser: ccTalk();

// Custom timeout
parser: ccTalk(100);
```

| Parameter                | Type     | Default | Description                                             |
| ------------------------ | -------- | ------- | ------------------------------------------------------- |
| `maxDelayBetweenBytesMs` | `number` | `50`    | Maximum silence between bytes before the buffer is reset|

**Emits:** `Uint8Array`

***

### `slipDecoder(options?)`

Decodes a SLIP-framed byte stream (RFC 1055) and emits each packet. Optional
custom escape / end bytes are supported. Equivalent to `SlipDecoder` from
`@serialport/parser-slip-encoder`.

```ts
import { slipDecoder } from "webserial-core";

// Standard SLIP
parser: slipDecoder();

// Custom framing bytes
parser: slipDecoder({ END: 0xc0, ESC: 0xdb, ESC_END: 0xdc, ESC_ESC: 0xdd });

// Bluetooth quirk — expects a START byte before each packet
parser: slipDecoder({ START: 0xc0 });
```

| Option      | Type     | Default | Description                                     |
| ----------- | -------- | ------- | ----------------------------------------------- |
| `END`       | `number` | `0xC0`  | Packet end byte                                 |
| `ESC`       | `number` | `0xDB`  | Escape byte                                     |
| `ESC_END`   | `number` | `0xDC`  | ESC sequence for the END byte                   |
| `ESC_ESC`   | `number` | `0xDD`  | ESC sequence for the ESC byte                   |
| `START`     | `number` | —       | Optional packet start byte                      |
| `ESC_START` | `number` | `ESC`   | ESC sequence for the START byte                 |

**Emits:** `Uint8Array`

#### `slipEncode(data, options?)`

Utility function (not a parser) that SLIP-encodes an outgoing packet before
writing it to the serial port.

```ts
import { slipEncode } from "webserial-core";

const frame = slipEncode(new Uint8Array([0x01, 0xc0, 0x02]));
await device.send(frame);

// Bluetooth quirk — prepends an extra END byte
const frame = slipEncode(payload, { bluetoothQuirk: true });
```

| Option           | Type      | Default | Description                                             |
| ---------------- | --------- | ------- | ------------------------------------------------------- |
| `bluetoothQuirk` | `boolean` | `false` | Prepend an END byte at the beginning of each packet     |
| *(+ all SLIP bytes from above)* | | | |

**Returns:** `Uint8Array`

***

### `spacePacket(options?)`

Parses [CCSDS Space Packet Protocol](https://ccsds.org/Pubs/133x0b2e2.pdf)
frames and emits a structured `SpacePacket` object for each complete packet.
Equivalent to `@serialport/parser-spacepacket`.

```ts
import { spacePacket } from "webserial-core";

// No secondary header
parser: spacePacket();

// With a time code field in the secondary header
parser: spacePacket({ timeCodeFieldLength: 8 });

// With both time code and ancillary data fields
parser: spacePacket({ timeCodeFieldLength: 4, ancillaryDataFieldLength: 2 });
```

| Option                     | Type     | Default | Description                                         |
| -------------------------- | -------- | ------- | --------------------------------------------------- |
| `timeCodeFieldLength`      | `number` | `0`     | Length in bytes of the Time Code Field              |
| `ancillaryDataFieldLength` | `number` | `0`     | Length in bytes of the Ancillary Data Field         |

**Emits:** `SpacePacket`

```ts
interface SpacePacket {
  header: {
    versionNumber: number;
    identification: { apid: number; secondaryHeader: number; type: number };
    sequenceControl: { packetName: number; sequenceFlags: number };
    dataLength: number;
  };
  secondaryHeader?: {
    timeCode?: string;
    ancillaryData?: string;
  };
  data: string;
}
```

***

## Custom parsers

Implement `SerialParser<T>` to handle any custom protocol:

```ts
import type { SerialParser } from "webserial-core";

interface MyPacket {
  command: number;
  payload: Uint8Array;
}

function myProtocolParser(): SerialParser<MyPacket> {
  const buffer: number[] = [];

  return {
    parse(chunk, emit) {
      for (const byte of chunk) {
        buffer.push(byte);

        // Simple framing: packets start with 0xAA and are 5 bytes long
        if (buffer[0] !== 0xaa) {
          buffer.shift();
          continue;
        }
        if (buffer.length < 5) continue;

        emit({
          command: buffer[1],
          payload: new Uint8Array(buffer.splice(0, 5).slice(2)),
        });
      }
    },

    reset() {
      buffer.length = 0;
    },
  };
}
```

Then use it in your device:

```ts
super({
  baudRate: 115200,
  parser: myProtocolParser(),
});
```

The `T` type parameter on `AbstractSerialDevice<T>` and `SerialEventMap<T>`
will automatically match the type your parser emits.

## Parser interface

```ts
interface SerialParser<T> {
  /** Called for each raw chunk received from the port. */
  parse(chunk: Uint8Array, emit: (value: T) => void): void;

  /** Optional — resets internal buffer state (e.g. on reconnect). */
  reset?(): void;
}
```

---

---
url: /api/types.md
---
# Types & Interfaces

All types are exported from the main `webserial-core` entry point.

## `SerialDeviceOptions<T>`

Passed to `super()` in your `AbstractSerialDevice` subclass.

```ts
interface SerialDeviceOptions<T> {
  /** Serial baud rate (e.g. 9600, 115200). */
  baudRate: number;

  /** Data bits per byte. Default: 8 */
  dataBits?: 7 | 8;

  /** Stop bits. Default: 1 */
  stopBits?: 1 | 2;

  /** Parity mode. Default: "none" */
  parity?: "none" | "even" | "odd";

  /** Hardware flow control. Default: "none" */
  flowControl?: "none" | "hardware";

  /** Internal read buffer size in bytes. Default: 255 */
  bufferSize?: number;

  /** Parser that transforms raw bytes into values of type T. */
  parser: SerialParser<T>;

  /** Timeout (ms) before a queued command is considered failed. Default: 0 (disabled) */
  commandTimeout?: number;

  /** Automatically reconnect on unexpected disconnect. Default: false */
  autoReconnect?: boolean;

  /** Delay (ms) between auto-reconnect attempts. Default: 1000 */
  autoReconnectInterval?: number;

  /** Timeout (ms) allowed for handshake() to complete. Default: 5000 */
  handshakeTimeout?: number;

  /** USB vendor/product ID filters shown in the port picker. Default: [] */
  filters?: SerialPortFilter[];

  /**
   * Custom serial provider for THIS instance only (e.g. `WebUsbProvider`,
   * `createBluetoothProvider()`, `createWebSocketProvider(...)`).
   * Takes precedence over the global provider set via
   * `AbstractSerialDevice.setProvider()`.
   */
  provider?: SerialProvider;

  /**
   * Polyfill options forwarded to `provider` when requesting or listing
   * ports for THIS instance. Only used when `provider` is set.
   */
  polyfillOptions?: SerialPolyfillOptions;
}
```

***

## `SerialProvider`

```ts
interface SerialProvider {
  /**
   * Opens the browser port picker (or equivalent) and returns the selected
   * SerialPort-compatible object.
   */
  requestPort(options?: { filters?: SerialPortFilter[] }): Promise<SerialPort>;

  /** Returns all previously authorized (already-paired) ports. */
  getPorts(): Promise<SerialPort[]>;
}
```

***

## `SerialParser<T>`

```ts
interface SerialParser<T> {
  transform(chunk: Uint8Array, push: (value: T) => void): void;
  flush?(push: (value: T) => void): void;
}
```

***

## `SerialEventMap<T>`

```ts
interface SerialEventMap<T> {
  "serial:connecting": () => void;
  "serial:connected": () => void;
  "serial:disconnected": () => void;
  "serial:data": (value: T) => void;
  "serial:sent": (data: Uint8Array) => void;
  "serial:error": (error: Error) => void;
  "serial:need-permission": () => void;
  "serial:timeout": (command: Uint8Array) => void;
  "serial:queue-empty": () => void;
  "serial:reconnecting": () => void;
}
```

***

## `SerialPortFilter`

```ts
interface SerialPortFilter {
  usbVendorId?: number;
  usbProductId?: number;
}
```

***

## `SerialPolyfillOptions`

Options for `WebUsbProvider`. Controls which USB interface classes are used
for control and bulk transfer.

```ts
interface SerialPolyfillOptions {
  /** USB interface class used for control messages. Default: 10 (CDC) */
  usbControlInterfaceClass?: number;

  /** USB interface class used for bulk data transfer. Default: 10 (CDC) */
  usbTransferInterfaceClass?: number;
}
```

***

## `CommandQueueOptions`

Options accepted by the `CommandQueue` constructor.

```ts
interface CommandQueueOptions {
  /** Timeout (ms) per command. 0 = no timeout. Default: 0 */
  timeout?: number;
}
```

***

## Error classes

| Class                     | When thrown                                    |
| ------------------------- | ---------------------------------------------- |
| `SerialPortConflictError` | Two devices attempt to open the same port      |
| `SerialPermissionError`   | User denies port access                        |
| `SerialTimeoutError`      | `commandTimeout` exceeded for a queued command |
| `SerialReadError`         | Error reading from the port's `ReadableStream` |
| `SerialWriteError`        | Error writing to the port's `WritableStream`   |

All extend the built-in `Error` class and include `name` and `message`.

---

---
url: /api/events.md
---
# Events

`AbstractSerialDevice<T>` emits the following typed events. All are prefixed
with `serial:` to avoid collisions with DOM events.

## Event reference

### `serial:connecting`

Fired immediately when `connect()` is called, before the port picker appears.

```ts
device.on("serial:connecting", () => {
  connectButton.disabled = true;
});
```

**Payload:** none

***

### `serial:connected`

Fired after the port is open **and** `handshake()` returns `true`.

```ts
device.on("serial:connected", () => {
  console.log("Ready to communicate!");
});
```

**Payload:** none

***

### `serial:disconnected`

Fired after the port closes, for any reason (manual disconnect, error, device
unplugged). If `autoReconnect` is enabled, a reconnect attempt follows.

```ts
device.on("serial:disconnected", () => {
  console.log("Connection lost.");
});
```

**Payload:** none

***

### `serial:data`

Fired every time the parser emits a complete message.

```ts
device.on("serial:data", (value) => {
  // `value` is typed as T (e.g. string when using delimiter())
  console.log("Received:", value);
});
```

**Payload:** `T` — the parsed value

***

### `serial:sent`

Fired after bytes are written to the port.

```ts
device.on("serial:sent", (bytes) => {
  console.log("Sent:", bytes);
});
```

**Payload:** `Uint8Array` — the exact bytes written

***

### `serial:error`

Fired when an unrecoverable error occurs (port error, write failure, etc.).

```ts
device.on("serial:error", (error) => {
  console.error("Serial error:", error.message);
});
```

**Payload:** `Error`

***

### `serial:need-permission`

Fired when the user denies port access or no authorized ports are available.
This is the right place to re-enable your "Connect" button.

```ts
device.on("serial:need-permission", () => {
  connectButton.disabled = false;
});
```

**Payload:** none

***

### `serial:timeout`

Fired when a queued command does not complete within `commandTimeout` ms.

```ts
device.on("serial:timeout", (command) => {
  console.warn("Command timed out:", command);
});
```

**Payload:** `Uint8Array` — the bytes of the command that timed out

***

### `serial:queue-empty`

Fired when the last command in the queue finishes and the queue becomes idle.

```ts
device.on("serial:queue-empty", () => {
  console.log("All commands sent.");
});
```

**Payload:** none

***

### `serial:reconnecting`

Fired at the start of each auto-reconnect attempt.

```ts
device.on("serial:reconnecting", () => {
  statusLabel.textContent = "Reconnecting...";
});
```

**Payload:** none

***

## TypeScript: full event map

```ts
import type { SerialEventMap } from "webserial-core";

// SerialEventMap<T> is:
interface SerialEventMap<T> {
  "serial:connecting": () => void;
  "serial:connected": () => void;
  "serial:disconnected": () => void;
  "serial:data": (value: T) => void;
  "serial:sent": (data: Uint8Array) => void;
  "serial:error": (error: Error) => void;
  "serial:need-permission": () => void;
  "serial:timeout": (command: Uint8Array) => void;
  "serial:queue-empty": () => void;
  "serial:reconnecting": () => void;
}
```

---

---
url: /examples/web-serial.md
---
# Web Serial example

Uses the native **Web Serial API** — no polyfill, no extra setup.

## Full example

```ts
import { AbstractSerialDevice, delimiter } from "webserial-core";
import type { SerialPortFilter } from "webserial-core";

class ArduinoDevice extends AbstractSerialDevice<string> {
  constructor(baudRate = 9600, filters?: SerialPortFilter[]) {
    super({
      baudRate,
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      flowControl: "none",
      bufferSize: 255,
      commandTimeout: 3000,
      parser: delimiter("\n"),
      autoReconnect: true,
      autoReconnectInterval: 1500,
      handshakeTimeout: 2000,
      filters: filters ?? [],
    });
  }

  protected async handshake(): Promise<boolean> {
    // Send identification command and wait for response
    await this.send("CONNECT\n");
    return new Promise((resolve) => {
      const handler = (data: string) => {
        this.off("serial:data", handler);
        resolve(data.trim() === "connected");
      };
      this.on("serial:data", handler);
    });
  }
}

// ─── Create device ────────────────────────────────────────────

const device = new ArduinoDevice(9600, [
  { usbVendorId: 0x2341 }, // Arduino vendor ID
]);

// ─── Listen to events ─────────────────────────────────────────

device.on("serial:connected", () => console.log("Connected!"));
device.on("serial:disconnected", () => console.log("Disconnected."));
device.on("serial:reconnecting", () => console.log("Reconnecting..."));
device.on("serial:data", (line) => console.log("←", line));
device.on("serial:sent", (bytes) => console.log("→", bytes));
device.on("serial:error", (err) => console.error("Error:", err.message));
device.on("serial:need-permission", () => console.warn("Permission denied"));
device.on("serial:timeout", (cmd) => console.warn("Timeout:", cmd));

// ─── Connect ──────────────────────────────────────────────────

await device.connect(); // opens the port picker

// ─── Send data ────────────────────────────────────────────────

await device.send("LED_ON\n");
await device.send(new Uint8Array([0xaa, 0x01, 0xff])); // binary

// ─── Disconnect ───────────────────────────────────────────────

await device.disconnect();
```

## Minimal example (no handshake)

```ts
import { AbstractSerialDevice, delimiter } from "webserial-core";

class SimpleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({ baudRate: 9600, parser: delimiter("\n") });
  }

  protected async handshake(): Promise<boolean> {
    return true; // accept any port
  }
}

const device = new SimpleDevice();
device.on("serial:data", (line) => console.log(line));
await device.connect();
```

## Live demo

👉 **[Open interactive demo](/demos/web-serial.html)** — runs directly in your browser

Or run locally:

```bash
npm run dev
# Then open http://localhost:5173/demos/web-serial/
```

Source: [`demos/web-serial/`](https://github.com/danidoble/webserial-core/tree/main/demos/web-serial)

---

---
url: /examples/web-usb.md
---
# WebUSB example

Uses **WebUsbProvider** as a polyfill for the native Web Serial API.
Ideal for Android Chrome where Web Serial is unavailable.

## Setup

```ts
import {
  AbstractSerialDevice,
  delimiter,
  WebUsbProvider,
} from "webserial-core";

// Inject the WebUSB provider once, before constructing any device.
// usbControlInterfaceClass / usbTransferInterfaceClass = 255 covers
// CP210x, CH340, and other vendor-class USB-UART bridges.
AbstractSerialDevice.setProvider(
  new WebUsbProvider({
    usbControlInterfaceClass: 255,
    usbTransferInterfaceClass: 255,
  }),
);
```

## Full example

```ts
import {
  AbstractSerialDevice,
  delimiter,
  WebUsbProvider,
} from "webserial-core";
import type { SerialPortFilter } from "webserial-core";

AbstractSerialDevice.setProvider(
  new WebUsbProvider({
    usbControlInterfaceClass: 255,
    usbTransferInterfaceClass: 255,
  }),
);

class UsbDevice extends AbstractSerialDevice<string> {
  constructor(filters?: SerialPortFilter[]) {
    super({
      baudRate: 9600,
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      flowControl: "none",
      bufferSize: 255,
      commandTimeout: 3000,
      parser: delimiter("\n"),
      autoReconnect: true,
      autoReconnectInterval: 1500,
      handshakeTimeout: 2000,
      filters: filters ?? [],
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

// Filter to CP2102 (ESP32 / NodeMCU)
const device = new UsbDevice([{ usbVendorId: 0x10c4, usbProductId: 0xea60 }]);

device.on("serial:connected", () => console.log("Connected via WebUSB!"));
device.on("serial:data", (line) => console.log("←", line));
device.on("serial:error", (err) => console.error(err.message));

await device.connect();
await device.send("LED_ON\n");
```

## Common USB vendor IDs

| Device                   | Vendor ID | Product ID |
| ------------------------ | --------- | ---------- |
| ESP32 / NodeMCU (CP2102) | `0x10c4`  | `0xea60`   |
| ESP32 / NodeMCU (CH340)  | `0x1a86`  | `0x7523`   |
| Arduino Uno              | `0x2341`  | `0x0043`   |
| Arduino Nano             | `0x0403`  | `0x6001`   |

## Live demo

👉 **[Open interactive demo](/demos/web-usb.html)** — runs directly in your browser

Or run locally:

```bash
npm run dev
# Then open http://localhost:5173/demos/web-usb/
```

Source: [`demos/web-usb/`](https://github.com/danidoble/webserial-core/tree/main/demos/web-usb)

---

---
url: /examples/web-bluetooth.md
---
# Web Bluetooth example

Uses **WebBluetoothProvider** to communicate with BLE UART modules via the
Nordic UART Service (NUS) over GATT.

## Compatible hardware

Any device advertising the NUS service UUID `6e400001-b5a3-f393-e0a9-e50e24dcca9e`:

* nRF52840 / nRF52832 running NUS firmware
* ESP32 with Arduino BLE UART sketch
* HC-08, AT-09, HM-10 BLE-to-UART modules

## Setup

```ts
import { AbstractSerialDevice, createBluetoothProvider } from "webserial-core";

AbstractSerialDevice.setProvider(createBluetoothProvider());
```

## Full example

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createBluetoothProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(createBluetoothProvider());

class BleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600, // Ignored over BLE — kept for interface compatibility
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      flowControl: "none",
      bufferSize: 255,
      commandTimeout: 3000,
      parser: delimiter("\n"),
      autoReconnect: false, // BLE reconnect requires user interaction
      handshakeTimeout: 2000,
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new BleDevice();

device.on("serial:connecting", () => console.log("Opening BLE picker..."));
device.on("serial:connected", () => console.log("Connected via BLE!"));
device.on("serial:disconnected", () => console.log("BLE disconnected."));
device.on("serial:data", (line) => console.log("←", line));
device.on("serial:error", (err) => console.error(err.message));

// Opens the Web Bluetooth device picker
await device.connect();

// Sends are automatically chunked at 20-byte BLE MTU
await device.send("HELLO\n");
```

## Chunking note

The BLE MTU for `writeValueWithoutResponse` is typically **20 bytes**. The
provider splits every `send()` call into 20-byte chunks automatically, with a
10 ms delay between chunks to avoid overflowing the BLE stack.

For messages shorter than 20 bytes, there is no split and no delay.

## Browser support

| Browser            | Platform                      | Support |
| ------------------ | ----------------------------- | ------- |
| Chrome 56+         | macOS, Windows, Linux (BlueZ) | ✅      |
| Chrome for Android | Android 6.0+                  | ✅      |
| Edge 79+           | Windows                       | ✅      |
| Firefox            | All                           | ❌      |
| Safari             | All                           | ❌      |

## Live demo

👉 **[Open interactive demo](/demos/web-bluetooth.html)** — runs directly in your browser

Or run locally:

```bash
npm run dev
# Then open http://localhost:5173/demos/web-bluetooth/
```

Source: [`demos/web-bluetooth/`](https://github.com/danidoble/webserial-core/tree/main/demos/web-bluetooth)

---

---
url: /examples/websocket.md
---
# WebSocket Bridge example

Uses **WebSocketProvider** to route serial I/O through a Node.js bridge
server over WebSocket. The browser never touches the serial port directly —
all I/O happens server-side and is relayed via JSON messages.

## Architecture

```
Browser (webserial-core)
        │  ws://127.0.0.1:8080/?token=TOKEN  JSON messages
        ▼
Node.js bridge (demos/websocket/server.js)
        │  serialport
        ▼
Physical device
```

## 1. Start the bridge server

```bash
cd demos/websocket
npm install
node server.js
# Copy the token printed by the bridge into the URL below.
```

## 2. Browser code

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createWebSocketProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(
  createWebSocketProvider("ws://127.0.0.1:8080/?token=TOKEN"),
);

class BridgedDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      flowControl: "none",
      bufferSize: 255,
      commandTimeout: 3000,
      parser: delimiter("\n"),
      autoReconnect: true,
      autoReconnectInterval: 1500,
      handshakeTimeout: 2000,
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new BridgedDevice();

device.on("serial:connected", () => console.log("Connected via WebSocket!"));
device.on("serial:data", (line) => console.log("←", line));
device.on("serial:reconnecting", () => console.log("Reconnecting..."));
device.on("serial:error", (err) => console.error(err.message));

await device.connect();
await device.send("LED_ON\n");
```

## Wire protocol reference

| Browser → Server                        | Description             |
| --------------------------------------- | ----------------------- |
| `{ type: "list-ports", filters: [] }`   | Request available ports |
| `{ type: "open", path, baudRate, ... }` | Open a port             |
| `{ type: "write", bytes: number[] }`    | Send bytes              |
| `{ type: "close" }`                     | Close the port          |

| Server → Browser                             | Description              |
| -------------------------------------------- | ------------------------ |
| `{ type: "port-list", payload: PortInfo[] }` | Available ports          |
| `{ type: "opened" }`                         | Port opened successfully |
| `{ type: "data", bytes: number[] }`          | Incoming serial bytes    |
| `{ type: "closed" }`                         | Port closed              |
| `{ type: "error", payload: { message } }`    | Error                    |

## Connecting to a remote machine

Change the server URL to point at your remote host:

```ts
createWebSocketProvider("ws://my-raspberry-pi.local:8080");
```

> **Security:** The bridge has raw access to serial ports. Add authentication
> middleware before exposing it outside `localhost`.

## Live demo

The WebSocket demo requires a local bridge server — run it locally:

```bash
# Terminal 1: bridge server
cd demos/websocket && npm install && node server.js

# Terminal 2: Vite dev server
npm run dev

# Open http://localhost:5173/demos/websocket/
```

Source: [`demos/websocket/`](https://github.com/danidoble/webserial-core/tree/main/demos/websocket)

---

---
url: /demos.md
---
# Interactive Demos

Try **webserial-core** directly in your browser — no installation, no build
step required. The demos use the UMD bundle to run as static HTML pages.

> **Requirement:** The demos use browser-exclusive APIs (Web Serial, WebUSB,
> Web Bluetooth). You need **Chrome 89+** or **Edge 89+** for most demos.
> Safari and Firefox are not supported.

## Available demos

### ⚡ Web Serial

Connect using the **native Web Serial API** in Chrome/Edge.

* Send TXT or HEX data
* Real-time connection/disconnection events
* Configurable auto-reconnect

👉 **[Open Web Serial demo](/demos/web-serial.html)**

***

### 🔌 WebUSB

Connect USB serial devices on Android Chrome or Desktop using the
**WebUSB polyfill** (no Web Serial API required).

* Compatible with CP210x, CH340, Arduino (CDC-ACM)
* Useful for testing Android behavior from desktop

👉 **[Open WebUSB demo](/demos/web-usb.html)**

***

### 📶 Web Bluetooth (BLE UART)

Communicate with BLE UART devices using the
**Nordic UART Service (NUS)** over GATT.

* Compatible with ESP32 BLE, nRF52, HC-08, AT-09
* Auto-chunked writes at 20-byte BLE MTU

👉 **[Open Web Bluetooth demo](/demos/web-bluetooth.html)**

***

## Using in production

The demos use the UMD bundle (`webserial-core.umd.js`) via a `<script>` tag.
For real projects, import via ESM to take advantage of tree-shaking:

```ts
import { AbstractSerialDevice, delimiter } from "webserial-core";
```

## Development demo source

The full TypeScript development demos live in
[`demos/`](https://github.com/danidoble/webserial-core/tree/main/demos) in the
repository. They include auto-reconnect examples, HEX mode, and the WebSocket bridge.

---

---
url: /es/guide/getting-started.md
---
# Primeros pasos

## Requisitos

| Requisito  | Versión                            |
| ---------- | ---------------------------------- |
| Node.js    | ≥ 18                               |
| TypeScript | ≥ 5.0                              |
| Navegador  | Chrome 89+ / Edge 89+ (Web Serial) |

> **Nota:** Web Serial requiere un contexto seguro (HTTPS o `localhost`) y
> un navegador basado en Chromium. WebUSB y Web Bluetooth tienen requisitos similares.

## Instalación

::: code-group

```bash [npm]
npm install webserial-core
```

```bash [pnpm]
pnpm add webserial-core
```

```bash [bun]
bun add webserial-core
```

:::

## Ejemplo rápido — Web Serial

```ts
import { AbstractSerialDevice, delimiter } from "webserial-core";

class MyDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: true,
    });
  }

  protected async handshake(): Promise<boolean> {
    // Opcional: enviar un comando y esperar confirmación.
    // Devuelve true para aceptar cualquier puerto.
    return true;
  }
}

const device = new MyDevice();

device.on("serial:connected", () => console.log("Conectado!"));
device.on("serial:data", (line) => console.log("Recibido:", line));
device.on("serial:error", (err) => console.error("Error:", err.message));

// Abre el selector de puertos del navegador y conecta
await device.connect();

// Enviar datos
await device.send("LED_ON\n");

// Desconectar
await device.disconnect();
```

## Cambiar el proveedor de transporte

Los cuatro adaptadores implementan la misma interfaz `SerialProvider`. Inyecta
el proveedor elegido una vez antes de construir cualquier dispositivo:

```ts
import { AbstractSerialDevice } from "webserial-core";
import { WebUsbProvider } from "webserial-core/adapters/web-usb";
// o:
import { createBluetoothProvider } from "webserial-core/adapters/web-bluetooth";
// o:
import { createWebSocketProvider } from "webserial-core/adapters/websocket";

// Polyfill WebUSB (útil en Android Chrome)
AbstractSerialDevice.setProvider(new WebUsbProvider());

// Web Bluetooth NUS
AbstractSerialDevice.setProvider(createBluetoothProvider());

// Puente WebSocket (requiere servidor Node.js — ver demos/websocket/README.md)
AbstractSerialDevice.setProvider(
  createWebSocketProvider("ws://127.0.0.1:8080/?token=TOKEN"),
);
```

Después de llamar a `setProvider`, todas las subclases de `AbstractSerialDevice`
usarán ese transporte automáticamente.

## Opciones de configuración

Todas las opciones se pasan en la llamada `super()` del constructor:

```ts
super({
  baudRate: 9600, // Velocidad en baudios
  dataBits: 8, // 7 u 8
  stopBits: 1, // 1 o 2
  parity: "none", // "none" | "even" | "odd"
  flowControl: "none", // "none" | "hardware"
  bufferSize: 255, // Tamaño del buffer de lectura (bytes)
  parser: delimiter("\n"), // Cómo dividir los bytes entrantes en mensajes
  commandTimeout: 3000, // ms antes de que un comando expire
  autoReconnect: true, // Reconectar automáticamente al desconectarse
  autoReconnectInterval: 1500, // ms entre intentos de reconexión
  handshakeTimeout: 2000, // ms permitidos para que handshake() termine
  filters: [], // Filtros de vendor/product ID USB
});
```

## Próximos pasos

* Lee la [guía de Arquitectura](./architecture.md) para entender cómo encajan las piezas.
* Consulta la [referencia de API](/es/api/abstract-serial-device) para la documentación completa de métodos y eventos.
* Revisa los [ejemplos](/es/examples/web-serial) con demos listos para usar.
* Prueba los [demos interactivos](/es/demos) directamente en el navegador.
* Si estás actualizando desde v1, consulta la [guía de migración](./migration-v1-v2.md).

---

---
url: /es/guide/architecture.md
---
# Arquitectura

## Visión general

```
┌──────────────────────────────────────────────────────────┐
│                    Tu clase de dispositivo               │
│              (extends AbstractSerialDevice<T>)           │
└───────────────────────┬──────────────────────────────────┘
                        │ hereda
                        ▼
┌──────────────────────────────────────────────────────────┐
│              AbstractSerialDevice<T>                     │
│  ┌─────────────────┐  ┌──────────┐  ┌────────────────┐  │
│  │  SerialRegistry │  │ CmdQueue │  │ SerialEventEmit│  │
│  │  (bloqueo port) │  │ (FIFO)   │  │  ter<EventMap> │  │
│  └─────────────────┘  └──────────┘  └────────────────┘  │
│                                                          │
│  connect() / disconnect() / send() / handshake()         │
└───────────────────────┬──────────────────────────────────┘
                        │ delega en
                        ▼
┌──────────────────────────────────────────────────────────┐
│                   SerialProvider                         │
│  (requestPort, getPorts — devuelve objetos SerialPort)   │
├──────────────────────────────────────────────────────────┤
│  ┌────────────────┐ ┌──────────────────┐ ┌───────────┐  │
│  │ Navigator      │ │  WebUsbProvider  │ │ WebBT/WS  │  │
│  │ (Web Serial    │ │  (polyfill USB)  │ │ providers │  │
│  │  API nativa)   │ │                  │ │           │  │
│  └────────────────┘ └──────────────────┘ └───────────┘  │
└──────────────────────────────────────────────────────────┘
```

## Componentes principales

### `AbstractSerialDevice<T>`

La clase base de la que hereda tu dispositivo. Gestiona el ciclo de vida completo de la conexión:

1. **`connect()`** — llama a `provider.requestPort()`, abre el puerto, ejecuta
   `handshake()` y luego inicia el bucle de lectura.
2. **Bucle de lectura** — lee continuamente chunks `Uint8Array` del `ReadableStream`
   del puerto y los procesa con el `SerialParser<T>` configurado.
   Cada vez que el parser emite un valor, se dispara el evento `serial:data`.
3. **`send(data)`** — codifica strings/bytes, encola la escritura en `CommandQueue`
   y la envía al `WritableStream` del puerto.
4. **`disconnect()`** — cancela el bucle de lectura, vacía la cola, cierra el puerto
   y emite `serial:disconnected`.
5. **Auto-reconexión** — si `autoReconnect: true` y la conexión se pierde,
   el dispositivo espera `autoReconnectInterval` ms y llama a `connect()` de nuevo.

### `SerialProvider`

```ts
interface SerialProvider {
  requestPort(options?: { filters?: SerialPortFilter[] }): Promise<SerialPort>;
  getPorts(): Promise<SerialPort[]>;
}
```

El proveedor predeterminado usa `navigator.serial` (Web Serial API nativa). Inyecta
un proveedor personalizado para WebUSB, Web Bluetooth o WebSocket.

### `SerialParser<T>`

```ts
interface SerialParser<T> {
  transform(chunk: Uint8Array, push: (value: T) => void): void;
  flush?(push: (value: T) => void): void;
}
```

Recibe bytes sin procesar y llama a `push()` por cada mensaje completo. Se incluyen
tres parsers integrados:

| Parser        | Fábrica          | Descripción                                   |
| ------------- | ---------------- | --------------------------------------------- |
| Delimitador   | `delimiter(sep)` | Divide en una secuencia de bytes (ej. `"\n"`) |
| Longitud fija | `fixedLength(n)` | Emite exactamente N bytes                     |
| Sin procesar  | `raw()`          | Pasa cada chunk sin cambios como `Uint8Array` |

### `CommandQueue`

Una cola FIFO que serializa las escrituras al puerto. Cada llamada a `send()` encola
una escritura. Si un comando no completa en `commandTimeout` ms, se dispara el evento
`serial:timeout` y el siguiente comando continúa.

### `SerialRegistry`

Un singleton global que registra qué puertos están abiertos. Evita que dos instancias
de `AbstractSerialDevice` abran el mismo puerto simultáneamente.

### `SerialEventEmitter<EventMap>`

Un emisor de eventos tipado mínimo. `on`, `off` y `emit` están totalmente tipados
usando el genérico `SerialEventMap<T>`, de modo que TypeScript conoce el tipo exacto
del payload para cada evento.

## Flujo de datos

```
SerialPort.readable (ReadableStream<Uint8Array>)
        │
        ▼
   Bucle de lectura (pump)
        │  Chunks de Uint8Array
        ▼
   SerialParser<T>.transform(chunk, push)
        │  Valores de tipo T
        ▼
   emit("serial:data", value)
        │
        ▼
   Tu manejador de eventos
```

## Inyección de proveedor

```ts
// Global — afecta a todas las instancias de AbstractSerialDevice
AbstractSerialDevice.setProvider(myProvider);

// O pásalo directamente al constructor (por instancia)
super({ ...options, provider: myProvider });
```

---

---
url: /es/guide/migration-v1-v2.md
---
# Migración desde v1

> **v2 es una reescritura completa de webserial-core y no es compatible con v1.**

La versión 2 introduce una nueva arquitectura, un nuevo sistema de adaptadores, nueva
estructura de carpetas, nuevo formato de salida de compilación y cambios en toda la API
pública. No existe una ruta de actualización incremental.

***

## Enfoque recomendado

La forma más limpia de migrar es **empezar desde cero** con v2:

1. Desinstala v1 e instala v2:

   ```bash
   npm remove webserial-core
   npm install webserial-core@latest
   ```

2. Elimina cualquier extensión existente de la antigua clase `SerialDevice`.

3. Crea una nueva clase que extienda `AbstractSerialDevice<T>` siguiendo la
   guía de [Primeros pasos](./getting-started.md).

***

## ¿Por qué una reescritura completa?

La versión 1 fue un prototipo que demostró el concepto. La versión 2 fue diseñada desde
cero con los siguientes objetivos que requirieron cambios incompatibles en cada capa:

* **TypeScript estricto** — sin `any`, JSDoc completo, interfaces con nombre para cada opción
* **Sistema de adaptadores modular** — WebUSB, Web Bluetooth y WebSocket son transportes de primera clase
* **Salida dual ESM + CJS** — compilación correcta con `.mjs` / `.cjs` / `.umd.js` vía Vite
* **Responsabilidades aisladas** — parsers, cola, eventos, registro y adaptadores son módulos
  separados que pueden testearse independientemente
* **Código fuente solo en inglés** — todo el código fuente, JSDoc y mensajes de error están en inglés

***

## Referencia

:::tip Empieza aquí
Lee la guía de [Primeros pasos](./getting-started.md) para la API completa de v2.
:::

* [API — AbstractSerialDevice](../api/abstract-serial-device.md)
* [API — Eventos](../api/events.md)
* [API — Parsers](../api/parsers.md)
* [Ejemplos](../examples/web-serial.md)

---

---
url: /es/guide/contributing.md
---
# Contribuir

¡Gracias por tu interés en contribuir a **webserial-core**!

## Configuración del entorno de desarrollo

```bash
git clone https://github.com/danidoble/webserial-core.git
cd webserial-core
npm install
```

Inicia el servidor de desarrollo Vite para probar los demos de forma interactiva:

```bash
npm run dev
```

Luego abre cualquiera de las páginas de demo en tu navegador:

* `http://localhost:5173/` — Web Serial (nativo)
* `http://localhost:5173/demos/web-usb/` — Polyfill WebUSB
* `http://localhost:5173/demos/web-bluetooth/` — Web Bluetooth
* `http://localhost:5173/demos/websocket/` — Puente WebSocket

## Estilo de código

* **TypeScript en modo estricto** — sin `any`, todas las APIs públicas totalmente tipadas.
* **Importaciones ESM** — usa extensión `.js` en importaciones relativas (ej.
  `import x from "./foo.js"`). Vite las resuelve a los archivos fuente `.ts`.
* **Solo en inglés** — todos los comentarios, JSDoc, nombres de variables y literales
  de cadena deben estar en inglés.
* **JSDoc** — todos los símbolos exportados deben tener JSDoc con `@param`, `@returns`
  y `@throws` donde corresponda.

Ejecuta las comprobaciones de lint y formato antes de hacer push:

```bash
npm run lint
npm run format
```

## Compilar

```bash
npm run build
```

Produce:

```
dist/
  webserial-core.mjs      ← ESM (tree-shakeable, para bundlers)
  webserial-core.cjs      ← CommonJS (Node.js / bundlers legacy)
  webserial-core.umd.js   ← UMD (tag <script> independiente / CDN)
  index.d.ts              ← Declaraciones TypeScript agrupadas
```

## Compilar la documentación

```bash
npm run docs:dev   # Vista previa en vivo
npm run docs:build # Salida estática → docs/.vitepress/dist
```

## Enviar un pull request

1. Haz fork del repositorio y crea una rama: `git checkout -b feat/mi-funcionalidad`
2. Realiza tus cambios y añade JSDoc a cualquier símbolo público nuevo.
3. Ejecuta `npm run lint` y `npm run format`.
4. Verifica la compilación: `npm run build`.
5. Haz push y abre un PR contra `main`.

## Añadir un nuevo adaptador

Coloca el código del adaptador en `src/adapters/<nombre>/`:

```
src/adapters/my-adapter/
  MyAdapter.ts   ← implementa SerialProvider
  index.ts       ← re-exportaciones
```

Luego re-expórtalo desde `src/index.ts`:

```ts
export * from "./adapters/my-adapter/index.js";
```

Añade un demo en `demos/my-adapter/` siguiendo la estructura de demos existente.

---

---
url: /es/api/abstract-serial-device.md
---
# AbstractSerialDevice\<T>

`AbstractSerialDevice<T>` es el núcleo de la librería. Extiéndela para crear
un driver de dispositivo para cualquier dispositivo conectado por serial.

## Parámetro de tipo

| Parámetro | Descripción                                                                                          |
| --------- | ---------------------------------------------------------------------------------------------------- |
| `T`       | El tipo de datos emitidos por los eventos `serial:data` (ej. `string`, `Uint8Array`, tu propio tipo) |

## Constructor

```ts
protected constructor(options: SerialDeviceOptions<T>)
```

Llamado desde tu subclase mediante `super(options)`.

Ve [`SerialDeviceOptions<T>`](/es/api/types#serialdeviceoptions) para todos los campos.

## Métodos estáticos

### `setProvider(provider)`

```ts
static setProvider(provider: SerialProvider): void
```

Inyecta un `SerialProvider` global que usarán todas las instancias de dispositivos.
Llámalo una vez antes de construir cualquier dispositivo.

```ts
AbstractSerialDevice.setProvider(new WebUsbProvider());
```

### Proveedor por instancia

También puedes establecer un proveedor para una **única instancia** pasando
`provider` en las opciones del constructor. Tiene precedencia sobre el
proveedor global y no afecta a otras instancias.

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createBluetoothProvider,
  createWebSocketProvider,
} from "webserial-core";
import { WebUsbProvider } from "webserial-core";

// Una instancia usando Web Bluetooth
class BleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      provider: createBluetoothProvider(),
    });
  }
  protected async handshake(): Promise<boolean> { return true; }
}

// Otra instancia usando WebUSB en la misma app
class UsbDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 115200,
      parser: delimiter("\n"),
      provider: new WebUsbProvider(),
    });
  }
  protected async handshake(): Promise<boolean> { return true; }
}

// Otra instancia tunelizada sobre WebSocket
class WsDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      provider: createWebSocketProvider("ws://127.0.0.1:8080/?token=TOKEN"),
    });
  }
  protected async handshake(): Promise<boolean> { return true; }
}

// Las tres coexisten; no se toca ningún proveedor global
const ble = new BleDevice();
const usb = new UsbDevice();
const ws  = new WsDevice();
```

Orden de resolución del proveedor por instancia:

| Prioridad | Fuente |
| --------- | ------ |
| 1 (más alta) | `options.provider` pasado al constructor |
| 2 | `AbstractSerialDevice.setProvider(...)` estático global |
| 3 (más baja) | `navigator.serial` Web Serial API nativa |

## Métodos de instancia

### `connect()`

```ts
connect(): Promise<void>
```

Abre el selector de puertos (o selecciona automáticamente un puerto ya autorizado),
ejecuta el `handshake()` e inicia el bucle de lectura. Emite `serial:connecting` al
inicio y `serial:connected` al completar.

Lanza `SerialPortConflictError` si otra instancia ya tiene el puerto. Lanza
`SerialPermissionError` si el usuario deniega el acceso.

### `disconnect()`

```ts
disconnect(): Promise<void>
```

Cancela el bucle de lectura, vacía la cola de comandos, cierra el puerto y
emite `serial:disconnected`. Deshabilita la auto-reconexión para esta sesión.

### `isConnected()`

```ts
isConnected(): boolean
```

Regresa `true` si el puerto está actualmente abierto. `false` si está desconectado o en proceso de conexión.

### `isDisconnected()`

```ts
isDisconnected(): boolean
```

Regresa `true` si el puerto está actualmente cerrado. `false` si está conectado o en proceso de desconexión.

### `send(data)`

```ts
send(data: string | Uint8Array): Promise<void>
```

Codifica `data` (UTF-8 si es string) y encola la escritura. Devuelve cuando los
bytes han sido enviados al puerto. Emite `serial:sent` con los bytes sin procesar.

### `on(event, handler)` / `off(event, handler)`

```ts
on<K extends keyof SerialEventMap<T>>(event: K, handler: SerialEventMap<T>[K]): this
off<K extends keyof SerialEventMap<T>>(event: K, handler: SerialEventMap<T>[K]): this
```

Suscribirse o cancelar la suscripción a un evento tipado. Ver la [referencia de eventos](/es/api/events).

## Métodos abstractos

### `handshake()`

```ts
protected abstract handshake(): Promise<boolean>
```

Llamado después de que el puerto se abre, antes del primer evento `serial:data`.
Devuelve `true` para aceptar la conexión o `false` para rechazarla (lo que dispara
una desconexión). Úsalo para identificación del dispositivo o configuración inicial.

```ts
protected async handshake(): Promise<boolean> {
  await this.send("PING\n");
  return new Promise((resolve) => {
    const handler = (data: string) => {
      this.off("serial:data", handler);
      resolve(data.trim() === "PONG");
    };
    this.on("serial:data", handler);
  });
}
```

Devuelve `true` inmediatamente para saltar el handshake y aceptar cualquier puerto:

```ts
protected async handshake(): Promise<boolean> {
  return true;
}
```

## Propiedades protegidas

| Propiedad     | Tipo                 | Descripción                                              |
| ------------- | -------------------- | -------------------------------------------------------- |
| `isConnected` | `boolean`            | Si el puerto está actualmente abierto                    |
| `port`        | `SerialPort \| null` | El objeto de puerto subyacente, o `null` al desconectado |

---

---
url: /es/api/web-usb-provider.md
---
# WebUsbProvider

`WebUsbProvider` implementa `SerialProvider` usando la
[API WebUSB](https://developer.mozilla.org/es/docs/Web/API/WebUSB_API)
como polyfill para la Web Serial API nativa.

## Cuándo usarlo

* **Android Chrome** — Web Serial no está disponible; WebUSB es la única forma de
  comunicarse con adaptadores USB-serial.
* **Pruebas en escritorio** — Forzar la ruta de código WebUSB para verificar el
  comportamiento antes de desplegar en Android.
* **Dispositivos USB personalizados** — Dispositivos no expuestos vía Web Serial (ej.
  USB de clase vendor personalizada).

## Protocolos soportados

| Protocolo      | Clase USB         | Notas                              |
| -------------- | ----------------- | ---------------------------------- |
| CDC ACM        | Clase 0x02        | Arduino estándar, ST-LINK          |
| CP210x / CH340 | Vendor específico | Puentes USB-UART comunes           |
| Bulk genérico  | Cualquier clase   | Dispositivos de transferencia bulk |

## Importación

```ts
import { WebUsbProvider } from "webserial-core";
```

## Constructor

```ts
new WebUsbProvider(options?: SerialPolyfillOptions)
```

| Opción                      | Tipo     | Por defecto | Descripción                                          |
| --------------------------- | -------- | ----------- | ---------------------------------------------------- |
| `usbControlInterfaceClass`  | `number` | `10`        | Clase de interfaz USB para transferencias de control |
| `usbTransferInterfaceClass` | `number` | `10`        | Clase de interfaz USB para transferencias bulk       |

Para dispositivos con interfaces de clase vendor (CP210x, CH340):

```ts
new WebUsbProvider({
  usbControlInterfaceClass: 255,
  usbTransferInterfaceClass: 255,
});
```

## Uso

```ts
import {
  AbstractSerialDevice,
  delimiter,
  WebUsbProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(
  new WebUsbProvider({
    usbControlInterfaceClass: 255,
    usbTransferInterfaceClass: 255,
  }),
);

class MyDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      filters: [{ usbVendorId: 0x10c4, usbProductId: 0xea60 }], // CP2102
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyDevice();
await device.connect(); // Abre el selector de dispositivos WebUSB
```

## Uso por instancia

Pasa `provider` (y opcionalmente `polyfillOptions`) en las opciones del
constructor para vincular `WebUsbProvider` a una sola instancia sin modificar
el proveedor global.

```ts
import { AbstractSerialDevice, delimiter, WebUsbProvider } from "webserial-core";

class MyUsbDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      filters: [{ usbVendorId: 0x10c4, usbProductId: 0xea60 }],
      provider: new WebUsbProvider({
        usbControlInterfaceClass: 255,
        usbTransferInterfaceClass: 255,
      }),
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyUsbDevice();
await device.connect();
```

También puedes pasar `polyfillOptions` por separado y dejar que la librería
los reenvíe al proveedor que resuelva para esa instancia:

```ts
class MyUsbDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      provider: new WebUsbProvider(),
      polyfillOptions: { usbControlInterfaceClass: 255 },
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}
```

## Soporte de navegadores

Requiere un navegador basado en Chromium con WebUSB habilitado. No disponible en
Firefox ni Safari. Requiere HTTPS o `localhost`.

---

---
url: /es/api/web-bluetooth-provider.md
---
# WebBluetoothProvider

`createBluetoothProvider()` devuelve un `SerialProvider` que usa la
[API Web Bluetooth](https://developer.mozilla.org/es/docs/Web/API/Web_Bluetooth_API)
sobre GATT para emular una conexión serial.

## Servicio compatible

Implementa el **Nordic UART Service (NUS)** sobre BLE:

| UUID                                   | Rol                                                     |
| -------------------------------------- | ------------------------------------------------------- |
| `6e400001-b5a3-f393-e0a9-e50e24dcca9e` | Servicio primario                                       |
| `6e400002-b5a3-f393-e0a9-e50e24dcca9e` | Característica TX (el navegador escribe)                |
| `6e400003-b5a3-f393-e0a9-e50e24dcca9e` | Característica RX (el navegador lee vía notificaciones) |

Hardware compatible: serie nRF52, ESP32 BLE UART, módulos HC-08 / AT-09 BLE,
o cualquier firmware que anuncie el servicio NUS.

## Importación

```ts
import { createBluetoothProvider } from "webserial-core";
```

## Función de fábrica

```ts
createBluetoothProvider(): SerialProvider
```

Devuelve una nueva instancia de `SerialProvider`. Sin opciones — el MTU BLE y
el retardo entre chunks están fijados a valores seguros (MTU 20 bytes, 10 ms de retardo).

## Uso

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createBluetoothProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(createBluetoothProvider());

class MyBleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600, // Ignorado sobre BLE, mantenido por compatibilidad de interfaz
      parser: delimiter("\n"),
      autoReconnect: false, // La reconexión BLE requiere re-emparejamiento; manejar manualmente
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyBleDevice();
await device.connect(); // Abre el selector de dispositivos Web Bluetooth
```

## Uso por instancia

Pasa `provider` directamente en las opciones del constructor para limitar el
proveedor BLE a una sola instancia. El proveedor global establecido mediante
`AbstractSerialDevice.setProvider()` no se modifica, por lo que otros
dispositivos en la misma app siguen usando sus propios proveedores.

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createBluetoothProvider,
} from "webserial-core";

class MyBleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: false,
      provider: createBluetoothProvider(), // BLE solo para esta instancia
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyBleDevice();
await device.connect();
```

Esto es especialmente útil cuando una app gestiona múltiples tipos de
dispositivos simultáneamente — por ejemplo, un dispositivo BLE junto a uno
USB o WebSocket.

## MTU y fragmentación

BLE tiene un MTU predeterminado de **20 bytes** para `writeValueWithoutResponse`. El
proveedor divide automáticamente las escrituras en chunks de 20 bytes con un retardo de
10 ms entre chunks para evitar saturar el stack BLE.

## Soporte de navegadores

Requiere Chrome 56+ en escritorio (macOS, Windows, Linux con BlueZ), Chrome en Android,
o Edge. No disponible en Firefox ni Safari. Requiere HTTPS o `localhost`.

## Notas

* `baudRate` en `SerialDeviceOptions` es ignorado sobre BLE. La velocidad del enlace
  físico la determinan los parámetros de conexión BLE.
* Se recomienda `autoReconnect: false` — la reconexión BLE requiere que el usuario
  empareje el dispositivo nuevamente mediante el selector del navegador.

---

---
url: /es/api/websocket-provider.md
---
# WebSocketProvider

`createWebSocketProvider(serverUrl)` devuelve un `SerialProvider` que retransmite
I/O serial a un servidor puente Node.js a través de una conexión WebSocket.

## Cuándo usarlo

* Acceder a puertos seriales en una máquina remota (ej. una Raspberry Pi) desde un navegador.
* Construir interfaces web para dispositivos conectados a un servidor detrás de un firewall.
* Probar código serial en un entorno donde Web Serial no está disponible.

## Importación

```ts
import { createWebSocketProvider } from "webserial-core";
```

## Función de fábrica

```ts
createWebSocketProvider(serverUrl: string): SerialProvider
```

| Parámetro   | Tipo     | Descripción                                                     |
| ----------- | -------- | --------------------------------------------------------------- |
| `serverUrl` | `string` | URL WebSocket del servidor puente (ej. `"ws://127.0.0.1:8080/?token=TOKEN"`) |

## Uso

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createWebSocketProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(
  createWebSocketProvider("ws://127.0.0.1:8080/?token=TOKEN"),
);

class MyDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: true,
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyDevice();
await device.connect(); // Conecta al primer puerto listado por el puente
```

## Uso por instancia

Pasa `provider` en las opciones del constructor para limitar el proveedor
WebSocket a una sola instancia. Útil cuando diferentes dispositivos se
conectan a distintos servidores puente, o cuando un dispositivo usa WebSocket
y otro un proveedor diferente en la misma app.

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createWebSocketProvider,
} from "webserial-core";

class RemoteDevice extends AbstractSerialDevice<string> {
  constructor(bridgeUrl: string) {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: true,
      provider: createWebSocketProvider(bridgeUrl), // WS solo para esta instancia
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

// Dos instancias independientes, cada una con su propia URL de puente
const deviceA = new RemoteDevice("ws://pi-sensor.local:8080");
const deviceB = new RemoteDevice("ws://pi-actuador.local:8080");

await deviceA.connect();
await deviceB.connect();
```

## Servidor puente

Se incluye un servidor puente Node.js listo para usar en
`demos/websocket/server.js`. Ve el
[README del demo del puente WebSocket](https://github.com/danidoble/webserial-core/tree/main/demos/websocket)
para las instrucciones de configuración.

## Protocolo de comunicación

Todos los mensajes son objetos JSON enviados sobre la conexión WebSocket.

| Dirección          | Tipo         | Descripción del payload                                  |
| ------------------ | ------------ | -------------------------------------------------------- |
| Navegador → Server | `list-ports` | `{ filters: SerialPortFilter[] }`                        |
| Server → Navegador | `port-list`  | `{ payload: PortInfo[] }`                                |
| Navegador → Server | `open`       | `{ path, baudRate, dataBits, stopBits, parity, parser }` |
| Server → Navegador | `opened`     | confirmación                                             |
| Navegador → Server | `write`      | `{ bytes: number[] }`                                    |
| Server → Navegador | `data`       | `{ bytes: number[] }`                                    |
| Navegador → Server | `close`      | —                                                        |
| Server → Navegador | `closed`     | —                                                        |
| Server → Navegador | `error`      | `{ payload: { message: string } }`                       |

## Selección de puerto

`requestPort()` abre una nueva conexión WebSocket, solicita la lista de puertos y
**selecciona automáticamente el primer puerto disponible**. Para aplicaciones en
producción, muestra un selector de UI sobre la lista de puertos devuelta antes de
llamar a `open`.

## Nota de seguridad

El servidor puente tiene acceso directo a los puertos seriales. Despliégalo
solo en redes de confianza y añade autenticación para cualquier configuración
expuesta a internet.

---

---
url: /es/api/parsers.md
---
# Parsers

Los parsers transforman un flujo de chunks `Uint8Array` sin procesar en valores
estructurados de tipo `T`. Pasa un parser a `SerialDeviceOptions.parser`.

## Parsers integrados

### `delimiter(separator, options?)`

Acumula bytes hasta encontrar la secuencia delimitadora y emite el frame sin el
delimitador (a menos que `includeDelimiter` sea `true`).

* Cuando `separator` es un **string**, los bytes se decodifican como UTF-8 y se
  emite un `string`.
* Cuando `separator` es **`Uint8Array`** o **`number[]`**, se emiten los bytes
  crudos como `Uint8Array`.

```ts
import { delimiter } from "webserial-core";

// Dividir en nueva línea — ideal para Arduino Serial.println()
parser: delimiter("\n");

// Dividir en retorno de carro + nueva línea
parser: delimiter("\r\n");

// Incluir el delimitador en el valor emitido
parser: delimiter("\n", { includeDelimiter: true });

// Dividir en secuencia binaria — emite Uint8Array
parser: delimiter(new Uint8Array([0x0d, 0x0a]));

// Dividir con un array de números — emite Uint8Array
parser: delimiter([0xaa, 0xff]);
```

| Parámetro                     | Tipo                               | Descripción                                                      |
| ----------------------------- | ---------------------------------- | ---------------------------------------------------------------- |
| `separator`                   | `string \| Uint8Array \| number[]` | Secuencia de bytes que marca el fin de un frame                  |
| `options.includeDelimiter`    | `boolean`                          | Incluir el delimitador al final de cada valor emitido. Por defecto: `false` |

**Emite:** `string` (cuando separator es `string`) · `Uint8Array` (cuando es binario)

***

### `readline(options?)`

Divide el flujo de bytes en líneas usando un delimitador configurable y emite
cada línea como string decodificado. Equivalente a `@serialport/parser-readline`.

```ts
import { readline } from "webserial-core";

// Por defecto — divide en '\n', UTF-8
parser: readline();

// Delimitador y codificación personalizados
parser: readline({ delimiter: "\r\n", encoding: "ascii" });

// Incluir el delimitador
parser: readline({ delimiter: "\n", includeDelimiter: true });
```

| Opción             | Tipo                               | Por defecto | Descripción                                          |
| ------------------ | ---------------------------------- | ----------- | ---------------------------------------------------- |
| `delimiter`        | `string \| Uint8Array \| number[]` | `'\n'`      | Secuencia de fin de línea                            |
| `includeDelimiter` | `boolean`                          | `false`     | Incluir el delimitador al final de cada string       |
| `encoding`         | `string`                           | `'utf-8'`   | Codificación de texto utilizada para decodificar     |

**Emite:** `string`

***

### `fixedLength(length)`

Emite exactamente N bytes como un `Uint8Array` sin procesar. Útil para protocolos
binarios con paquetes de tamaño fijo.

```ts
import { fixedLength } from "webserial-core";

// Emitir cada 16 bytes
parser: fixedLength(16);
```

| Parámetro | Tipo     | Descripción               |
| --------- | -------- | ------------------------- |
| `length`  | `number` | Número de bytes por frame |

**Emite:** `Uint8Array`

***

### `raw()`

Pasa cada chunk del puerto sin cambios. Úsalo cuando quieras manejar el
encuadre por tu cuenta.

```ts
import { raw } from "webserial-core";

parser: raw();
```

**Emite:** `Uint8Array`

***

### `interByteTimeout(options)`

Acumula bytes y los emite tras un período de silencio (`interval` ms sin bytes
nuevos), o cuando el buffer alcanza `maxBufferSize`. Equivalente a
`@serialport/parser-inter-byte-timeout`.

```ts
import { interByteTimeout } from "webserial-core";

// Emitir datos después de 30 ms de silencio
parser: interByteTimeout({ interval: 30 });

// Con límite máximo de buffer
parser: interByteTimeout({ interval: 30, maxBufferSize: 1024 });
```

| Opción          | Tipo     | Por defecto | Descripción                                                         |
| --------------- | -------- | ----------- | ------------------------------------------------------------------- |
| `interval`      | `number` | —           | Período de silencio en milisegundos antes de emitir (**requerido**) |
| `maxBufferSize` | `number` | `65536`     | Máximo de bytes a acumular antes de forzar la emisión               |

**Emite:** `Uint8Array`

***

### `packetLength(options?)`

Enmarca paquetes usando un byte delimitador inicial y un campo de longitud
embebido. Equivalente a `@serialport/parser-packet-length`.

Estructura de paquete por defecto: `[0xAA][0x00][len][payload...][footer]`

```ts
import { packetLength } from "webserial-core";

// Opciones por defecto
parser: packetLength();

// Estructura personalizada: [0xBC][0x00][lenHi][lenLo][cargo...][footer0][footer1]
parser: packetLength({ delimiter: 0xbc, packetOverhead: 5, lengthBytes: 2, lengthOffset: 2 });
```

| Opción           | Tipo     | Por defecto | Descripción                                                                     |
| ---------------- | -------- | ----------- | ------------------------------------------------------------------------------- |
| `delimiter`      | `number` | `0xAA`      | Byte que marca el inicio de cada paquete                                        |
| `packetOverhead` | `number` | `2`         | Bytes fijos de overhead (delimitador + campo(s) de longitud + footer)           |
| `lengthBytes`    | `number` | `1`         | Número de bytes que codifican la longitud del payload                           |
| `lengthOffset`   | `number` | `1`         | Desplazamiento en bytes desde el delimitador hasta el primer byte de longitud   |
| `maxLen`         | `number` | `0xFF`      | Longitud máxima de payload permitida; paquetes que la superen se descartan      |

**Emite:** `Uint8Array`

***

### `regexParser(options)`

Decodifica los bytes entrantes y divide el texto resultante por una expresión
regular, emitiendo cada segmento. Equivalente a `@serialport/parser-regex`.

```ts
import { regexParser } from "webserial-core";

// Dividir en cualquier combinación de \r y \n
parser: regexParser({ regex: /[\r\n]+/ });

// Dividir en punto y coma
parser: regexParser({ regex: /;+/ });
```

| Opción     | Tipo               | Por defecto | Descripción                                 |
| ---------- | ------------------ | ----------- | ------------------------------------------- |
| `regex`    | `RegExp \| string` | —           | Patrón para dividir el texto entrante       |
| `encoding` | `string`           | `'utf-8'`   | Codificación de texto para decodificar bytes|

**Emite:** `string`

***

### `readyParser(options)`

Descarta todos los bytes hasta detectar una secuencia de "listo" configurable.
A partir de ahí, cada chunk recibido se emite tal cual. Dispara un callback
opcional `onReady` al encontrar la secuencia. Equivalente a
`@serialport/parser-ready`.

```ts
import { readyParser } from "webserial-core";

parser: readyParser({
  delimiter: "READY\n",
  onReady: () => console.log("dispositivo listo"),
});
```

| Opción      | Tipo                               | Descripción                                                        |
| ----------- | ---------------------------------- | ------------------------------------------------------------------ |
| `delimiter` | `string \| Uint8Array \| number[]` | Secuencia que indica que el dispositivo está listo (**requerido**) |
| `onReady`   | `() => void`                       | Llamado una vez cuando se detecta la secuencia de listo            |

**Emite:** `Uint8Array` (todos los datos recibidos después de la secuencia de listo)

***

### `ccTalk(maxDelayBetweenBytesMs?)`

Parsea paquetes del protocolo de bus [ccTalk](https://en.wikipedia.org/wiki/CcTalk).
Cada paquete tiene `N + 5` bytes, donde `N` es la longitud de datos en el byte 1.
El buffer interno se descarta si no llegan bytes dentro de `maxDelayBetweenBytesMs`.
Equivalente a `@serialport/parser-cctalk`.

```ts
import { ccTalk } from "webserial-core";

// Timeout entre bytes por defecto de 50 ms
parser: ccTalk();

// Timeout personalizado
parser: ccTalk(100);
```

| Parámetro                | Tipo     | Por defecto | Descripción                                                  |
| ------------------------ | -------- | ----------- | ------------------------------------------------------------ |
| `maxDelayBetweenBytesMs` | `number` | `50`        | Silencio máximo entre bytes antes de reiniciar el buffer     |

**Emite:** `Uint8Array`

***

### `slipDecoder(options?)`

Decodifica un flujo de bytes con encuadre SLIP (RFC 1055) y emite cada paquete.
Se admiten bytes de escape y fin personalizados. Equivalente a `SlipDecoder` de
`@serialport/parser-slip-encoder`.

```ts
import { slipDecoder } from "webserial-core";

// SLIP estándar
parser: slipDecoder();

// Bytes de encuadre personalizados
parser: slipDecoder({ END: 0xc0, ESC: 0xdb, ESC_END: 0xdc, ESC_ESC: 0xdd });

// Quirk Bluetooth — espera un byte START antes de cada paquete
parser: slipDecoder({ START: 0xc0 });
```

| Opción      | Tipo     | Por defecto | Descripción                                  |
| ----------- | -------- | ----------- | -------------------------------------------- |
| `END`       | `number` | `0xC0`      | Byte de fin de paquete                       |
| `ESC`       | `number` | `0xDB`      | Byte de escape                               |
| `ESC_END`   | `number` | `0xDC`      | Secuencia ESC para el byte END               |
| `ESC_ESC`   | `number` | `0xDD`      | Secuencia ESC para el byte ESC               |
| `START`     | `number` | —           | Byte de inicio de paquete (opcional)         |
| `ESC_START` | `number` | `ESC`       | Secuencia ESC para el byte START             |

**Emite:** `Uint8Array`

#### `slipEncode(data, options?)`

Función utilitaria (no es un parser) que codifica un paquete saliente con SLIP
antes de enviarlo al puerto serie.

```ts
import { slipEncode } from "webserial-core";

const frame = slipEncode(new Uint8Array([0x01, 0xc0, 0x02]));
await device.send(frame);

// Quirk Bluetooth — antepone un byte END extra
const frame = slipEncode(payload, { bluetoothQuirk: true });
```

| Opción           | Tipo      | Por defecto | Descripción                                              |
| ---------------- | --------- | ----------- | -------------------------------------------------------- |
| `bluetoothQuirk` | `boolean` | `false`     | Anteponer un byte END al inicio de cada paquete          |
| *(+ todos los bytes SLIP descritos arriba)* | | | |

**Retorna:** `Uint8Array`

***

### `spacePacket(options?)`

Parsea tramas del [Protocolo de Paquete Espacial CCSDS](https://public.ccsds.org/Pubs/133x0b2e1.pdf)
y emite un objeto `SpacePacket` estructurado por cada paquete completo recibido.
Equivalente a `@serialport/parser-spacepacket`.

```ts
import { spacePacket } from "webserial-core";

// Sin cabecera secundaria
parser: spacePacket();

// Con campo de código de tiempo en la cabecera secundaria
parser: spacePacket({ timeCodeFieldLength: 8 });

// Con campo de código de tiempo y datos auxiliares
parser: spacePacket({ timeCodeFieldLength: 4, ancillaryDataFieldLength: 2 });
```

| Opción                     | Tipo     | Por defecto | Descripción                                            |
| -------------------------- | -------- | ----------- | ------------------------------------------------------ |
| `timeCodeFieldLength`      | `number` | `0`         | Longitud en bytes del campo Time Code                  |
| `ancillaryDataFieldLength` | `number` | `0`         | Longitud en bytes del campo Ancillary Data             |

**Emite:** `SpacePacket`

```ts
interface SpacePacket {
  header: {
    versionNumber: number;
    identification: { apid: number; secondaryHeader: number; type: number };
    sequenceControl: { packetName: number; sequenceFlags: number };
    dataLength: number;
  };
  secondaryHeader?: {
    timeCode?: string;
    ancillaryData?: string;
  };
  data: string;
}
```

***

## Parsers personalizados

Implementa `SerialParser<T>` para manejar cualquier protocolo personalizado:

```ts
import type { SerialParser } from "webserial-core";

interface MyPacket {
  command: number;
  payload: Uint8Array;
}

function myProtocolParser(): SerialParser<MyPacket> {
  const buffer: number[] = [];

  return {
    parse(chunk, emit) {
      for (const byte of chunk) {
        buffer.push(byte);

        // Encuadre simple: los paquetes empiezan con 0xAA y miden 5 bytes
        if (buffer[0] !== 0xaa) {
          buffer.shift();
          continue;
        }
        if (buffer.length < 5) continue;

        emit({
          command: buffer[1],
          payload: new Uint8Array(buffer.splice(0, 5).slice(2)),
        });
      }
    },

    reset() {
      buffer.length = 0;
    },
  };
}
```

Luego úsalo en tu dispositivo:

```ts
super({
  baudRate: 115200,
  parser: myProtocolParser(),
});
```

El parámetro de tipo `T` en `AbstractSerialDevice<T>` y `SerialEventMap<T>`
coincidirá automáticamente con el tipo que emite tu parser.

## Interfaz del parser

```ts
interface SerialParser<T> {
  /** Llamado para cada chunk recibido del puerto. */
  parse(chunk: Uint8Array, emit: (value: T) => void): void;

  /** Opcional — reinicia el estado interno del buffer (por ejemplo, al reconectar). */
  reset?(): void;
}
```

---

---
url: /es/api/types.md
---
# Tipos e Interfaces

Todos los tipos se exportan desde el punto de entrada principal de `webserial-core`.

## `SerialDeviceOptions<T>`

Pasado a `super()` en tu subclase de `AbstractSerialDevice`.

```ts
interface SerialDeviceOptions<T> {
  /** Velocidad en baudios (ej. 9600, 115200). */
  baudRate: number;

  /** Bits de datos por byte. Por defecto: 8 */
  dataBits?: 7 | 8;

  /** Bits de parada. Por defecto: 1 */
  stopBits?: 1 | 2;

  /** Modo de paridad. Por defecto: "none" */
  parity?: "none" | "even" | "odd";

  /** Control de flujo por hardware. Por defecto: "none" */
  flowControl?: "none" | "hardware";

  /** Tamaño del buffer de lectura interno en bytes. Por defecto: 255 */
  bufferSize?: number;

  /** Parser que transforma bytes sin procesar en valores de tipo T. */
  parser: SerialParser<T>;

  /** Timeout (ms) antes de que un comando en cola sea considerado fallido. Por defecto: 0 (deshabilitado) */
  commandTimeout?: number;

  /** Reconectar automáticamente en desconexión inesperada. Por defecto: false */
  autoReconnect?: boolean;

  /** Retardo (ms) entre intentos de auto-reconexión. Por defecto: 1000 */
  autoReconnectInterval?: number;

  /** Timeout (ms) permitido para que handshake() complete. Por defecto: 5000 */
  handshakeTimeout?: number;

  /** Filtros de vendor/product ID USB mostrados en el selector de puerto. Por defecto: [] */
  filters?: SerialPortFilter[];

  /**
   * Proveedor serial personalizado solo para ESTA instancia (ej. `WebUsbProvider`,
   * `createBluetoothProvider()`, `createWebSocketProvider(...)`).
   * Tiene precedencia sobre el proveedor global establecido mediante
   * `AbstractSerialDevice.setProvider()`.
   */
  provider?: SerialProvider;

  /**
   * Opciones de polyfill reenviadas al `provider` al solicitar o listar
   * puertos para ESTA instancia. Solo se usa cuando `provider` está definido.
   */
  polyfillOptions?: SerialPolyfillOptions;
}
```

***

## `SerialProvider`

```ts
interface SerialProvider {
  /**
   * Abre el selector de puerto del navegador (o equivalente) y devuelve el
   * objeto SerialPort compatible seleccionado.
   */
  requestPort(options?: { filters?: SerialPortFilter[] }): Promise<SerialPort>;

  /** Devuelve todos los puertos previamente autorizados (ya emparejados). */
  getPorts(): Promise<SerialPort[]>;
}
```

***

## `SerialParser<T>`

```ts
interface SerialParser<T> {
  transform(chunk: Uint8Array, push: (value: T) => void): void;
  flush?(push: (value: T) => void): void;
}
```

***

## `SerialEventMap<T>`

```ts
interface SerialEventMap<T> {
  "serial:connecting": () => void;
  "serial:connected": () => void;
  "serial:disconnected": () => void;
  "serial:data": (value: T) => void;
  "serial:sent": (data: Uint8Array) => void;
  "serial:error": (error: Error) => void;
  "serial:need-permission": () => void;
  "serial:timeout": (command: Uint8Array) => void;
  "serial:queue-empty": () => void;
  "serial:reconnecting": () => void;
}
```

***

## `SerialPortFilter`

```ts
interface SerialPortFilter {
  usbVendorId?: number;
  usbProductId?: number;
}
```

***

## `SerialPolyfillOptions`

Opciones para `WebUsbProvider`. Controla qué clases de interfaz USB se usan
para control y transferencia masiva.

```ts
interface SerialPolyfillOptions {
  /** Clase de interfaz USB para mensajes de control. Por defecto: 10 (CDC) */
  usbControlInterfaceClass?: number;

  /** Clase de interfaz USB para transferencia masiva. Por defecto: 10 (CDC) */
  usbTransferInterfaceClass?: number;
}
```

***

## `CommandQueueOptions`

Opciones aceptadas por el constructor de `CommandQueue`.

```ts
interface CommandQueueOptions {
  /** Timeout (ms) por comando. 0 = sin timeout. Por defecto: 0 */
  timeout?: number;
}
```

***

## Clases de error

| Clase                     | Cuándo se lanza                                     |
| ------------------------- | --------------------------------------------------- |
| `SerialPortConflictError` | Dos dispositivos intentan abrir el mismo puerto     |
| `SerialPermissionError`   | El usuario deniega el acceso al puerto              |
| `SerialTimeoutError`      | Se superó `commandTimeout` para un comando en cola  |
| `SerialReadError`         | Error al leer del `ReadableStream` del puerto       |
| `SerialWriteError`        | Error al escribir en el `WritableStream` del puerto |

Todas extienden la clase `Error` integrada e incluyen `name` y `message`.

---

---
url: /es/api/events.md
---
# Eventos

`AbstractSerialDevice<T>` emite los siguientes eventos tipados. Todos tienen el prefijo
`serial:` para evitar colisiones con eventos del DOM.

## Referencia de eventos

### `serial:connecting`

Se dispara inmediatamente cuando se llama a `connect()`, antes de que aparezca el selector de puerto.

```ts
device.on("serial:connecting", () => {
  connectButton.disabled = true;
});
```

**Payload:** ninguno

***

### `serial:connected`

Se dispara después de que el puerto está abierto **y** `handshake()` devuelve `true`.

```ts
device.on("serial:connected", () => {
  console.log("Listo para comunicarse!");
});
```

**Payload:** ninguno

***

### `serial:disconnected`

Se dispara después de que el puerto se cierra, por cualquier motivo (desconexión manual,
error, dispositivo desenchufado). Si `autoReconnect` está habilitado, sigue un intento
de reconexión.

```ts
device.on("serial:disconnected", () => {
  console.log("Conexión perdida.");
});
```

**Payload:** ninguno

***

### `serial:data`

Se dispara cada vez que el parser emite un mensaje completo.

```ts
device.on("serial:data", (value) => {
  // `value` está tipado como T (ej. string cuando se usa delimiter())
  console.log("Recibido:", value);
});
```

**Payload:** `T` — el valor parseado

***

### `serial:sent`

Se dispara después de que los bytes son escritos en el puerto.

```ts
device.on("serial:sent", (bytes) => {
  console.log("Enviado:", bytes);
});
```

**Payload:** `Uint8Array` — los bytes exactos escritos

***

### `serial:error`

Se dispara cuando ocurre un error irrecuperable (error de puerto, fallo de escritura, etc.).

```ts
device.on("serial:error", (error) => {
  console.error("Error serial:", error.message);
});
```

**Payload:** `Error`

***

### `serial:need-permission`

Se dispara cuando el usuario deniega el acceso al puerto o no hay puertos autorizados disponibles.
Es el lugar correcto para volver a habilitar tu botón "Conectar".

```ts
device.on("serial:need-permission", () => {
  connectButton.disabled = false;
});
```

**Payload:** ninguno

***

### `serial:timeout`

Se dispara cuando un comando en cola no completa dentro de `commandTimeout` ms.

```ts
device.on("serial:timeout", (command) => {
  console.warn("Comando expiró:", command);
});
```

**Payload:** `Uint8Array` — los bytes del comando que expiró

***

### `serial:queue-empty`

Se dispara cuando el último comando de la cola termina y la cola queda vacía.

```ts
device.on("serial:queue-empty", () => {
  console.log("Todos los comandos enviados.");
});
```

**Payload:** ninguno

***

### `serial:reconnecting`

Se dispara al inicio de cada intento de auto-reconexión.

```ts
device.on("serial:reconnecting", () => {
  statusLabel.textContent = "Reconectando...";
});
```

**Payload:** ninguno

***

## TypeScript: mapa completo de eventos

```ts
import type { SerialEventMap } from "webserial-core";

// SerialEventMap<T> es:
interface SerialEventMap<T> {
  "serial:connecting": () => void;
  "serial:connected": () => void;
  "serial:disconnected": () => void;
  "serial:data": (value: T) => void;
  "serial:sent": (data: Uint8Array) => void;
  "serial:error": (error: Error) => void;
  "serial:need-permission": () => void;
  "serial:timeout": (command: Uint8Array) => void;
  "serial:queue-empty": () => void;
  "serial:reconnecting": () => void;
}
```

---

---
url: /es/examples/web-serial.md
---
# Ejemplo de Web Serial

Usa la **Web Serial API** nativa — sin polyfill, sin configuración adicional.

## Ejemplo completo

```ts
import { AbstractSerialDevice, delimiter } from "webserial-core";
import type { SerialPortFilter } from "webserial-core";

class ArduinoDevice extends AbstractSerialDevice<string> {
  constructor(baudRate = 9600, filters?: SerialPortFilter[]) {
    super({
      baudRate,
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      flowControl: "none",
      bufferSize: 255,
      commandTimeout: 3000,
      parser: delimiter("\n"),
      autoReconnect: true,
      autoReconnectInterval: 1500,
      handshakeTimeout: 2000,
      filters: filters ?? [],
    });
  }

  protected async handshake(): Promise<boolean> {
    // Enviar comando de identificación y esperar respuesta
    await this.send("CONNECT\n");
    return new Promise((resolve) => {
      const handler = (data: string) => {
        this.off("serial:data", handler);
        resolve(data.trim() === "connected");
      };
      this.on("serial:data", handler);
    });
  }
}

// ─── Crear dispositivo ────────────────────────────────────────

const device = new ArduinoDevice(9600, [
  { usbVendorId: 0x2341 }, // Vendor ID de Arduino
]);

// ─── Escuchar eventos ─────────────────────────────────────────

device.on("serial:connected", () => console.log("Conectado!"));
device.on("serial:disconnected", () => console.log("Desconectado."));
device.on("serial:reconnecting", () => console.log("Reconectando..."));
device.on("serial:data", (line) => console.log("←", line));
device.on("serial:sent", (bytes) => console.log("→", bytes));
device.on("serial:error", (err) => console.error("Error:", err.message));
device.on("serial:need-permission", () => console.warn("Permiso denegado"));
device.on("serial:timeout", (cmd) => console.warn("Timeout:", cmd));

// ─── Conectar ─────────────────────────────────────────────────

await device.connect(); // abre el selector de puerto

// ─── Enviar datos ─────────────────────────────────────────────

await device.send("LED_ON\n");
await device.send(new Uint8Array([0xaa, 0x01, 0xff])); // binario

// ─── Desconectar ──────────────────────────────────────────────

await device.disconnect();
```

## Ejemplo mínimo (sin handshake)

```ts
import { AbstractSerialDevice, delimiter } from "webserial-core";

class SimpleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({ baudRate: 9600, parser: delimiter("\n") });
  }

  protected async handshake(): Promise<boolean> {
    return true; // aceptar cualquier puerto
  }
}

const device = new SimpleDevice();
device.on("serial:data", (line) => console.log(line));
await device.connect();
```

## Demo interactivo

Prueba este ejemplo directamente en tu navegador sin necesidad de compilar:

👉 **[Abrir demo Web Serial](/demos/web-serial.html)**

O ejecuta el demo localmente:

```bash
npm run dev
# Luego abre http://localhost:5173/demos/web-serial/
```

Código fuente: [`demos/web-serial/`](https://github.com/danidoble/webserial-core/tree/main/demos/web-serial)

---

---
url: /es/examples/web-usb.md
---
# Ejemplo de WebUSB

Usa **WebUsbProvider** como polyfill para la Web Serial API nativa.
Ideal para Android Chrome donde Web Serial no está disponible.

## Configuración

```ts
import {
  AbstractSerialDevice,
  delimiter,
  WebUsbProvider,
} from "webserial-core";

// Inyectar el proveedor WebUSB una vez, antes de construir cualquier dispositivo.
// usbControlInterfaceClass / usbTransferInterfaceClass = 255 cubre
// CP210x, CH340 y otros puentes USB-UART de clase vendor.
AbstractSerialDevice.setProvider(
  new WebUsbProvider({
    usbControlInterfaceClass: 255,
    usbTransferInterfaceClass: 255,
  }),
);
```

## Ejemplo completo

```ts
import {
  AbstractSerialDevice,
  delimiter,
  WebUsbProvider,
} from "webserial-core";
import type { SerialPortFilter } from "webserial-core";

AbstractSerialDevice.setProvider(
  new WebUsbProvider({
    usbControlInterfaceClass: 255,
    usbTransferInterfaceClass: 255,
  }),
);

class UsbDevice extends AbstractSerialDevice<string> {
  constructor(filters?: SerialPortFilter[]) {
    super({
      baudRate: 9600,
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      flowControl: "none",
      bufferSize: 255,
      commandTimeout: 3000,
      parser: delimiter("\n"),
      autoReconnect: true,
      autoReconnectInterval: 1500,
      handshakeTimeout: 2000,
      filters: filters ?? [],
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

// Filtrar por CP2102 (ESP32 / NodeMCU)
const device = new UsbDevice([{ usbVendorId: 0x10c4, usbProductId: 0xea60 }]);

device.on("serial:connected", () => console.log("Conectado via WebUSB!"));
device.on("serial:data", (line) => console.log("←", line));
device.on("serial:error", (err) => console.error(err.message));

await device.connect();
await device.send("LED_ON\n");
```

## Vendor IDs USB comunes

| Dispositivo              | Vendor ID | Product ID |
| ------------------------ | --------- | ---------- |
| ESP32 / NodeMCU (CP2102) | `0x10c4`  | `0xea60`   |
| ESP32 / NodeMCU (CH340)  | `0x1a86`  | `0x7523`   |
| Arduino Uno              | `0x2341`  | `0x0043`   |
| Arduino Nano             | `0x0403`  | `0x6001`   |

## Demo interactivo

Prueba este ejemplo directamente en tu navegador:

👉 **[Abrir demo WebUSB](/demos/web-usb.html)**

O ejecuta el demo localmente:

```bash
npm run dev
# Luego abre http://localhost:5173/demos/web-usb/
```

Código fuente: [`demos/web-usb/`](https://github.com/danidoble/webserial-core/tree/main/demos/web-usb)

---

---
url: /es/examples/web-bluetooth.md
---
# Ejemplo de Web Bluetooth

Usa **WebBluetoothProvider** para comunicarse con módulos BLE UART a través del
Nordic UART Service (NUS) sobre GATT.

## Hardware compatible

Cualquier dispositivo que anuncie el UUID del servicio NUS `6e400001-b5a3-f393-e0a9-e50e24dcca9e`:

* nRF52840 / nRF52832 con firmware NUS
* ESP32 con sketch Arduino BLE UART
* Módulos BLE-to-UART HC-08, AT-09, HM-10

## Configuración

```ts
import { AbstractSerialDevice, createBluetoothProvider } from "webserial-core";

AbstractSerialDevice.setProvider(createBluetoothProvider());
```

## Ejemplo completo

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createBluetoothProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(createBluetoothProvider());

class BleDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600, // Ignorado sobre BLE — mantenido por compatibilidad de interfaz
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      flowControl: "none",
      bufferSize: 255,
      commandTimeout: 3000,
      parser: delimiter("\n"),
      autoReconnect: false, // La reconexión BLE requiere interacción del usuario
      handshakeTimeout: 2000,
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new BleDevice();

device.on("serial:connecting", () => console.log("Abriendo selector BLE..."));
device.on("serial:connected", () => console.log("Conectado via BLE!"));
device.on("serial:disconnected", () => console.log("BLE desconectado."));
device.on("serial:data", (line) => console.log("←", line));
device.on("serial:error", (err) => console.error(err.message));

// Abre el selector de dispositivos Web Bluetooth
await device.connect();

// Los envíos se fragmentan automáticamente al MTU BLE de 20 bytes
await device.send("HELLO\n");
```

## Nota sobre fragmentación

El MTU BLE para `writeValueWithoutResponse` es típicamente **20 bytes**. El proveedor
divide automáticamente cada llamada a `send()` en chunks de 20 bytes, con un retardo de
10 ms entre chunks para evitar saturar el stack BLE.

Para mensajes de menos de 20 bytes, no hay división ni retardo.

## Soporte de navegadores

| Navegador          | Plataforma                    | Soporte |
| ------------------ | ----------------------------- | ------- |
| Chrome 56+         | macOS, Windows, Linux (BlueZ) | ✅      |
| Chrome for Android | Android 6.0+                  | ✅      |
| Edge 79+           | Windows                       | ✅      |
| Firefox            | Todos                         | ❌      |
| Safari             | Todos                         | ❌      |

## Demo interactivo

Prueba este ejemplo directamente en tu navegador:

👉 **[Abrir demo Web Bluetooth](/demos/web-bluetooth.html)**

O ejecuta el demo localmente:

```bash
npm run dev
# Luego abre http://localhost:5173/demos/web-bluetooth/
```

Código fuente: [`demos/web-bluetooth/`](https://github.com/danidoble/webserial-core/tree/main/demos/web-bluetooth)

---

---
url: /es/examples/websocket.md
---
# Ejemplo del Puente WebSocket

Usa **WebSocketProvider** para enrutar I/O serial a través de un servidor
puente Node.js sobre WebSocket. El navegador nunca toca el puerto serial
directamente — todo el I/O ocurre en el servidor y se retransmite vía mensajes JSON.

## Arquitectura

```
Navegador (webserial-core)
        │  ws://127.0.0.1:8080/?token=TOKEN  mensajes JSON
        ▼
Puente Node.js (demos/websocket/server.js)
        │  serialport
        ▼
Dispositivo físico
```

## 1. Iniciar el servidor puente

```bash
cd demos/websocket
npm install
node server.js
# Copia el token impreso por el puente en la URL de abajo.
```

## 2. Código del navegador

```ts
import {
  AbstractSerialDevice,
  delimiter,
  createWebSocketProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(
  createWebSocketProvider("ws://127.0.0.1:8080/?token=TOKEN"),
);

class BridgedDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      flowControl: "none",
      bufferSize: 255,
      commandTimeout: 3000,
      parser: delimiter("\n"),
      autoReconnect: true,
      autoReconnectInterval: 1500,
      handshakeTimeout: 2000,
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new BridgedDevice();

device.on("serial:connected", () => console.log("Conectado via WebSocket!"));
device.on("serial:data", (line) => console.log("←", line));
device.on("serial:reconnecting", () => console.log("Reconectando..."));
device.on("serial:error", (err) => console.error(err.message));

await device.connect();
await device.send("LED_ON\n");
```

## Referencia del protocolo

| Navegador → Servidor                    | Descripción       |
| --------------------------------------- | ----------------- |
| `{ type: "list-ports", filters: [] }`   | Solicitar puertos |
| `{ type: "open", path, baudRate, ... }` | Abrir un puerto   |
| `{ type: "write", bytes: number[] }`    | Enviar bytes      |
| `{ type: "close" }`                     | Cerrar el puerto  |

| Servidor → Navegador                         | Descripción              |
| -------------------------------------------- | ------------------------ |
| `{ type: "port-list", payload: PortInfo[] }` | Puertos disponibles      |
| `{ type: "opened" }`                         | Puerto abierto con éxito |
| `{ type: "data", bytes: number[] }`          | Bytes seriales entrantes |
| `{ type: "closed" }`                         | Puerto cerrado           |
| `{ type: "error", payload: { message } }`    | Error                    |

## Conectar a una máquina remota

Cambia la URL del servidor para apuntar a tu host remoto:

```ts
createWebSocketProvider("ws://mi-raspberry-pi.local:8080");
```

> **Seguridad:** El puente tiene acceso directo a los puertos seriales. Añade
> middleware de autenticación antes de exponerlo fuera de `localhost`.

## Demo local

```bash
# Terminal 1: servidor puente
cd demos/websocket && npm install && node server.js

# Terminal 2: servidor de desarrollo Vite
npm run dev

# Abrir http://localhost:5173/demos/websocket/
```

Código fuente: [`demos/websocket/`](https://github.com/danidoble/webserial-core/tree/main/demos/websocket)

---

---
url: /es/demos.md
---
# Demos interactivos

Prueba **webserial-core** directamente en tu navegador — sin instalación, sin
compilación. Los demos usan el bundle UMD para funcionar como páginas HTML estáticas.

> **Requisito:** Los demos usan APIs de navegador exclusivas (Web Serial, WebUSB,
> Web Bluetooth). Necesitas **Chrome 89+** o **Edge 89+** en la mayoría de demos.
> Safari y Firefox no están soportados.

## Demos disponibles

### ⚡ Web Serial

Conecta usando la **Web Serial API nativa** de Chrome/Edge.

* Enviar TXT o HEX
* Eventos de conexión/desconexión en tiempo real
* Auto-reconexión configurable

👉 **[Abrir demo Web Serial](/demos/web-serial.html)**

***

### 🔌 WebUSB

Conecta dispositivos serial USB en Android Chrome o Desktop usando el
**polyfill WebUSB** (sin necesitar la API Web Serial).

* Compatible con CP210x, CH340, Arduino (CDC-ACM)
* Útil para probar el comportamiento de Android desde el escritorio

👉 **[Abrir demo WebUSB](/demos/web-usb.html)**

***

### 📶 Web Bluetooth (BLE UART)

Comunícate con dispositivos BLE UART mediante el
**Nordic UART Service (NUS)** sobre GATT.

* Compatible con ESP32 BLE, nRF52, HC-08, AT-09
* Escrituras auto-fragmentadas al MTU BLE de 20 bytes

👉 **[Abrir demo Web Bluetooth](/demos/web-bluetooth.html)**

***

## Uso en producción

Los demos usan el bundle UMD (`webserial-core.umd.js`) vía tag `<script>`.
Para proyectos reales, importa con ESM para aprovechar el tree-shaking:

```ts
import { AbstractSerialDevice, delimiter } from "webserial-core";
```

## Código fuente de los demos de desarrollo

Los demos de desarrollo completos con TypeScript se encuentran en
[`demos/`](https://github.com/danidoble/webserial-core/tree/main/demos) en el repositorio.
Incluye ejemplos de auto-reconexión, modo HEX y bridge WebSocket.

---

---
url: /v1.md
---

::: warning Legacy version
You are viewing the **v1 (legacy) documentation**. v1 is now on security fixes only.

For new projects use [v2 (latest)](/guide/getting-started) which adds:

* Provider-agnostic adapters (WebUSB, Web Bluetooth, WebSocket)
* Full TypeScript generics and strict typings
* Improved parser system (delimiter, fixed-length, raw)
* Auto-reconnect with exponential back-off
  :::

---

---
url: /v1/guide/getting-started.md
---

# Getting Started — v1

::: warning You are viewing legacy v1 docs
v1 is on security fixes only. For new projects please use [v2 (latest)](/guide/getting-started).
:::

## Requirements

* A Chromium-based browser (Chrome 89+, Edge 89+) with the **Web Serial API** enabled.
* Linux users must add themselves to the `dialout` group:

```bash
sudo usermod -a -G dialout $USER
# Log out and back in for the change to take effect
```

## Installation

```bash
npm install webserial-core
```

> For a pinned v1.x.x release use `npm install webserial-core@^1.2.1`.

## Core concepts

In v1 the main entry point is the `Core` class. You **always subclass it** — you never instantiate `Core` directly. Inside the subclass you implement two abstract-like methods:

| Method                          | Purpose                                                                                         |
| ------------------------------- | ----------------------------------------------------------------------------------------------- |
| `serialSetConnectionConstant()` | Returns the bytes that are sent to the device on connect to identify this client                |
| `serialMessage(code)`           | Called each time the device sends a response; you parse it and `dispatch` the appropriate event |

## Step 1 — Write your device class

```javascript
// arduino.js
import { Core, Devices } from "webserial-core";

export class Arduino extends Core {
  constructor({
    filters = null,
    config_port = {
      baudRate: 9600,
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      bufferSize: 32768,
      flowControl: "none",
    },
    no_device = 1,
  } = {}) {
    super({ filters, config_port, no_device });

    // Give this device type a name and register it
    this.__internal__.device.type = "arduino";
    Devices.registerType(this.__internal__.device.type);

    if (Devices.getByNumber(this.typeDevice, no_device)) {
      throw new Error(`Device arduino #${no_device} already exists`);
    }

    // Tune timeouts (ms)
    this.__internal__.time.response_connection = 2000;
    this.__internal__.time.response_general = 2000;
    this.__internal__.serial.delay_first_connection = 1000;

    Devices.add(this);

    // Responses will be decoded as plain strings
    this.getResponseAsString();
  }

  // The bytes sent on connect to identify the device
  serialSetConnectionConstant() {
    return this.add0x(this.parseStringToBytes("CONNECT"));
  }

  // Called for every message received from the device
  serialMessage(codex) {
    const message = {
      code: codex,
      name: "unknown",
      description: "Unknown command",
      request: "unknown",
      no_code: 400,
    };

    switch (codex) {
      case "connected":
        message.name = "connected";
        message.description = "Connection established";
        message.request = "connect";
        message.no_code = 100;
        break;
      case "created by danidoble":
        message.name = "thanks";
        message.description = "Thanks for using this software";
        message.request = "credits";
        message.no_code = 101;
        break;
      case "hello there":
        message.name = "hello there";
        message.description = "Hi human";
        message.request = "hi";
        message.no_code = 102;
        break;
    }

    this.dispatch("serial:message", message);
  }

  // --- Public commands ---

  async sayCredits() {
    await this.appendToQueue(this.parseStringToBytes("CREDITS"), "credits");
  }

  async sayHi() {
    await this.appendToQueue(this.parseStringToBytes("HI"), "hi");
  }

  async sendCustomCode({ code = "" } = {}) {
    if (typeof code !== "string") throw new Error("code must be a string");
    await this.appendToQueue(this.parseStringToBytes(code), "custom");
  }
}
```

## Step 2 — Connect and listen to events

```javascript
// main.js
import { Arduino } from "./arduino.js";

const arduino = new Arduino();

arduino.on("serial:connected", () => {
  console.log("Connected!");
});

arduino.on("serial:disconnected", () => {
  console.log("Disconnected");
});

arduino.on("serial:message", (event) => {
  const msg = event.detail;
  console.log(`[${msg.no_code}] ${msg.name}: ${msg.description}`);
});

arduino.on("serial:timeout", (event) => {
  console.warn("Timeout:", event.detail);
});

arduino.on("serial:error", (event) => {
  console.error("Error:", event.detail.message);
});

// Opens the browser port-picker and connects
arduino.connect().catch(console.error);
```

## Step 3 — HTML

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>webserial-core v1 demo</title>
    <script src="./main.js" type="module"></script>
  </head>
  <body>
    <button id="connect">Connect</button>
    <button id="disconnect" hidden>Disconnect</button>
    <button id="hi">Say Hi</button>
    <pre id="log"></pre>

    <script type="module">
      import { arduino } from "./main.js";

      const log = (msg) =>
        (document.getElementById("log").textContent += msg + "\n");

      arduino.on("serial:connected", () => {
        log("Connected");
      });
      arduino.on("serial:disconnected", () => {
        log("Disconnected");
      });
      arduino.on("serial:message", (e) => log(JSON.stringify(e.detail)));
      arduino.on("serial:need-permission", () =>
        log("Permission required — click Connect"),
      );

      document
        .getElementById("connect")
        .addEventListener("click", () =>
          arduino.connect().catch(console.error),
        );
      document
        .getElementById("disconnect")
        .addEventListener("click", () =>
          arduino.disconnect().catch(console.error),
        );
      document
        .getElementById("hi")
        .addEventListener("click", () => arduino.sayHi().catch(console.error));
    </script>
  </body>
</html>
```

## Response format

By default v1 returns device data as **`Uint8Array`**. Call one of the helpers inside your constructor to change the format:

| Method                            | Returns                  |
| --------------------------------- | ------------------------ |
| `this.getResponseAsUint8Array()`  | `Uint8Array` *(default)* |
| `this.getResponseAsString()`      | decoded `string`         |
| `this.getResponseAsArrayHex()`    | `string[]` hex values    |
| `this.getResponseAsArrayBuffer()` | `ArrayBuffer`            |

## Differences from v2

| Feature                 | v1                        | v2                                       |
| ----------------------- | ------------------------- | ---------------------------------------- |
| Transports              | Web Serial only           | Web Serial, WebUSB, Bluetooth, WebSocket |
| TypeScript generics     | Partial                   | Full                                     |
| Parsers                 | Manual in `serialMessage` | Built-in (delimiter, fixed-length, raw)  |
| Provider injection      | No                        | Yes                                      |
| Auto-reconnect back-off | No                        | Yes                                      |
| Command queue           | ❌                        | ✅                                       |
| Auto-reconnect          | ❌                        | ✅                                       |
| Provider injection      | ❌                        | ✅                                       |
| Tree-shakeable          | ❌                        | ✅                                       |

## Migrating to v2

See the [Migration Guide](/guide/migration-v1-v2) for a step-by-step upgrade path.

---

---
url: /v1/api/core.md
---

# Core

::: warning Legacy v1 docs
v1 is on security fixes only. See [v2 docs](/api/abstract-serial-device) for the current release.
:::

`Core` is the base class for all v1 devices. You always **subclass** it — never instantiate it directly.

```typescript
import { Core, Devices } from "webserial-core";

class MyDevice extends Core {
  constructor() {
    super({ baudRate: 9600 });
    this.__internal__.device.type = "my-device";
    Devices.registerType("my-device");
    Devices.add(this);
    this.getResponseAsString();
  }

  serialSetConnectionConstant() {
    return this.add0x(this.parseStringToBytes("CONNECT"));
  }

  serialMessage(code) {
    this.dispatch("serial:message", { code });
  }
}
```

## Constructor

```typescript
new Core(options?: CoreConstructorParams)
```

| Parameter                     | Type                         | Default                                                                                                | Description                                                 |
| ----------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `filters`                     | `SerialPortFilter[] \| null` | `null`                                                                                                 | Filters passed to `navigator.serial.requestPort()`          |
| `config_port`                 | `SerialOptions`              | `{ baudRate: 9600, dataBits: 8, stopBits: 1, parity: "none", bufferSize: 32768, flowControl: "none" }` | Serial port configuration                                   |
| `no_device`                   | `number`                     | `1`                                                                                                    | Device instance number (used by the registry)               |
| `device_listen_on_channel`    | `number \| string`           | `1`                                                                                                    | Channel/port number passed to `serialSetConnectionConstant` |
| `bypassSerialBytesConnection` | `boolean`                    | `false`                                                                                                | Skip automatic connection-byte sending                      |
| `socket`                      | `boolean`                    | `false`                                                                                                | Use Socket.io bridge instead of direct Web Serial           |
| `transformStream`             | `false \| TransformStream`   | `false`                                                                                                | Custom transform stream to inject into the read pipeline    |

## Methods to implement in subclass

### `serialSetConnectionConstant(listenOnPort?)`

Called automatically during connection. Must return the bytes to send for device handshake.

```typescript
serialSetConnectionConstant(listenOnPort = 1): string | Uint8Array | string[] | number[] | null
```

**Example**

```javascript
serialSetConnectionConstant() {
  return this.add0x(this.parseStringToBytes("CONNECT"));
}
```

***

### `serialMessage(code)`

Called for every message received from the device. Parse and dispatch events here.

```typescript
serialMessage(code: string | Uint8Array | string[] | ArrayBuffer): void
```

**Example**

```javascript
serialMessage(codex) {
  if (codex === "connected") {
    this.dispatch("serial:message", { name: "connected", no_code: 100 });
  }
}
```

***

### `serialCorruptMessage(code)` *(optional)*

Called when a received message fails validation. Override to handle corrupt responses.

```typescript
serialCorruptMessage(code: Uint8Array | string[] | string | null): void
```

## Connection methods

### `connect()`

Opens the system port picker (if no port is already saved) and establishes the serial connection.

```typescript
connect(): Promise<boolean>
```

Returns `true` when connected.

***

### `disconnect(detail?)`

Closes the serial port and emits `serial:disconnected`.

```typescript
disconnect(detail?: object | null): Promise<void>
```

***

### `serialConnect()`

Low-level connect (no port picker). Reopens a previously granted port.

```typescript
serialConnect(): Promise<void>
```

***

### `serialDisconnect()`

Low-level close of the serial port streams.

```typescript
serialDisconnect(): Promise<void>
```

***

### `serialForget()`

Calls `port.forget()` to revoke the browser permission for the saved port.

```typescript
serialForget(): Promise<boolean>
```

## Queue methods

### `appendToQueue(arr, action)`

Enqueues bytes to be written to the device. Sends `internal:queue` to process the next item.

```typescript
appendToQueue(
  arr: string | Uint8Array | string[] | number[],
  action: string
): Promise<void>
```

***

### `sendConnect()`

Sends the connection-constant bytes through the queue.

```typescript
sendConnect(): Promise<void>
```

***

### `sendCustomCode({ code })`

Enqueues arbitrary bytes with action `"custom"`.

```typescript
sendCustomCode({ code }: { code: string | Uint8Array | string[] | number[] }): Promise<void>
```

***

### `clearSerialQueue()`

Empties the command queue immediately.

```typescript
clearSerialQueue(): void
```

***

### `softReload()`

Clears the last error state and emits `serial:soft-reload`.

```typescript
softReload(): void
```

## Response format helpers

Call exactly **one** of these in your constructor:

```javascript
this.getResponseAsUint8Array(); // default — Uint8Array
this.getResponseAsString(); // decoded string (TextDecoder)
this.getResponseAsArrayHex(); // string[] of hex values
this.getResponseAsArrayBuffer(); // ArrayBuffer
```

## Properties

### State

| Property         | Type             | Description                                          |
| ---------------- | ---------------- | ---------------------------------------------------- |
| `isConnected`    | `boolean`        | `true` when the port is open and readable/writable   |
| `isConnecting`   | `boolean`        | `true` while the connection handshake is in progress |
| `isDisconnected` | `boolean`        | `true` when not connected                            |
| `lastAction`     | `string \| null` | The `action` string of the last queued command       |

### Identity

| Property       | Type     | Description                                            |
| -------------- | -------- | ------------------------------------------------------ |
| `uuid`         | `string` | Auto-generated `crypto.randomUUID()`                   |
| `typeDevice`   | `string` | Device type string (e.g. `"arduino"`)                  |
| `deviceNumber` | `number` | Instance number set via `no_device` in the constructor |

### Queue

| Property | Type          | Description                             |
| -------- | ------------- | --------------------------------------- |
| `queue`  | `QueueData[]` | Current pending items in the send queue |

### Port configuration

| Property           | Type                       | Description                                |
| ------------------ | -------------------------- | ------------------------------------------ |
| `serialFilters`    | `SerialPortFilter[]`       | Get/set port filters (throws if connected) |
| `serialConfigPort` | `SerialOptions`            | Get/set port options (throws if connected) |
| `portPath`         | `string \| null`           | COM/tty path hint for socket mode          |
| `portVendorId`     | `string \| number \| null` | USB vendor ID hint for socket mode         |
| `portProductId`    | `string \| number \| null` | USB product ID hint for socket mode        |
| `useRTSCTS`        | `boolean`                  | Enable RTS/CTS hardware flow control       |

### Response parsing

| Property                      | Type                       | Description                                                                |
| ----------------------------- | -------------------------- | -------------------------------------------------------------------------- |
| `fixedBytesMessage`           | `number \| null`           | Expect exactly N bytes per message; `null` = variable                      |
| `timeoutBeforeResponseBytes`  | `number`                   | Inter-byte silence (ms) before declaring a response complete. Default `50` |
| `responseDelimited`           | `boolean`                  | Use `responseLimiter` to split messages                                    |
| `responseLimiter`             | `string \| RegExp \| null` | Delimiter for message boundaries                                           |
| `responsePrefixLimited`       | `boolean`                  | Limiter appears at the **start** of each message                           |
| `responseSufixLimited`        | `boolean`                  | Limiter appears at the **end** of each message (default `true`)            |
| `bypassSerialBytesConnection` | `boolean`                  | Skip connection-byte dispatch                                              |
| `connectionBytes`             | `Uint8Array`               | Read-only computed connection bytes                                        |

### Socket mode

| Property                   | Type                                    | Description                                  |
| -------------------------- | --------------------------------------- | -------------------------------------------- |
| `useSocket`                | `boolean`                               | Whether socket mode is active                |
| `socketPortParser`         | `"byte-length" \| "inter-byte-timeout"` | Parser type for the socket bridge            |
| `socketPortParserInterval` | `number`                                | Inter-byte timeout (ms) for socket parser    |
| `socketPortParserLength`   | `number`                                | Fixed byte length for socket parser          |
| `configDeviceSocket`       | `object`                                | Full config object sent to the socket bridge |

## Byte-conversion utilities

```typescript
parseStringToBytes(string: string, end?: string): string[]
parseStringToTextEncoder(string: string, end?: string): Uint8Array
parseUint8ToHex(array: Uint8Array): string[]
parseHexToUint8(array: string[]): Uint8Array
stringArrayToUint8Array(strings: string[]): Uint8Array
parseUint8ArrayToString(array: Uint8Array | string[]): string
stringToArrayHex(string: string): string[]
stringToArrayBuffer(string: string, end?: string): ArrayBufferLike
hexToAscii(hex: string | number): string
asciiToHex(asciiString: string): string
decToHex(dec: number | string): string
hexToDec(hex: string): number
hexMaker(val?: string, min?: number): string
add0x(bytes: string[]): string[]
bytesToHex(bytes: string[]): string[]
sumHex(arr: string[]): string
validateBytes(data: string | Uint8Array | string[] | number[]): Uint8Array
```

---

---
url: /v1/api/devices.md
---

# Devices

::: warning Legacy v1 docs
v1 is on security fixes only. See [v2 docs](/api/abstract-serial-device) for the current release.
:::

`Devices` is a **static registry** that keeps track of every device instance in your app. It is a `Dispatcher` subclass so you can listen to the `change` event globally.

```typescript
import { Devices } from "webserial-core";
```

## Static methods

### `registerType(type)`

Creates a slot in the registry for a new device type. Call this once inside your subclass constructor before calling `Devices.add()`.

```typescript
Devices.registerType(type: string): void
```

```javascript
Devices.registerType("arduino");
```

***

### `add(device)`

Registers a device instance. Typically called at the end of your subclass constructor.

```typescript
Devices.add(device: Core): number  // returns the index in the type bucket
```

Throws if a device with the same UUID is already registered.

***

### `get(type, id)`

Returns a device by type name and UUID.

```typescript
Devices.get(type: string, id: string): Core
```

***

### `getByNumber(type, deviceNumber)`

Returns the device with the given `deviceNumber` within a type bucket, or `null`.

```typescript
Devices.getByNumber(type: string, deviceNumber: number): Core | null
```

***

### `getCustom(type, deviceNumber?)`

Alias of `getByNumber`.

```typescript
Devices.getCustom(type: string, deviceNumber?: number): Core | null
```

***

### `getAll(type?)`

Returns all devices of a given type (or all devices grouped by type when `type` is `null`).

```typescript
Devices.getAll(type?: string | null): IDevice | IDevices
```

***

### `getList()`

Returns a flat array of every registered device regardless of type.

```typescript
Devices.getList(): Core[]
```

***

### `connectToAll()`

Calls `connect()` on every device that is currently disconnected.

```typescript
Devices.connectToAll(): Promise<boolean>
```

Returns `true` when every device is connected.

***

### `disconnectAll()`

Calls `disconnect()` on every device that is currently connected.

```typescript
Devices.disconnectAll(): Promise<boolean>
```

***

### `areAllConnected()`

Returns `true` when every registered device is connected.

```typescript
Devices.areAllConnected(): Promise<boolean>
```

***

### `areAllDisconnected()`

Returns `true` when every registered device is disconnected.

```typescript
Devices.areAllDisconnected(): Promise<boolean>
```

***

### `getAllConnected()`

Returns an array of all devices that are currently connected.

```typescript
Devices.getAllConnected(): Promise<Core[]>
```

***

### `getAllDisconnected()`

Returns an array of all devices that are currently disconnected.

```typescript
Devices.getAllDisconnected(): Promise<Core[]>
```

## Instance event

The singleton `Devices.instance` emits one event:

| Event    | Payload                   | Description                                                      |
| -------- | ------------------------- | ---------------------------------------------------------------- |
| `change` | `{ devices, dispatcher }` | Fired whenever a device is added or its connection state changes |

```javascript
Devices.instance.on("change", (event) => {
  const { devices, dispatcher } = event.detail;
  console.log("Registry changed:", Object.keys(devices));
});
```

## Usage example

```javascript
import { Arduino } from "./arduino.js";
import { Devices } from "webserial-core";

const a1 = new Arduino({ no_device: 1 });
const a2 = new Arduino({ no_device: 2 });

// Connect both at once
await Devices.connectToAll();

// Retrieve by number
const first = Devices.getByNumber("arduino", 1);
console.log(first.isConnected); // true

// Disconnect all
await Devices.disconnectAll();
```

---

---
url: /v1/api/dispatcher.md
---

# Dispatcher

::: warning Legacy v1 docs
v1 is on security fixes only. See [v2 docs](/api/abstract-serial-device) for the current release.
:::

`Dispatcher` extends the native `EventTarget` and adds helper methods for the event-driven communication system. Both `Core` and `Devices` extend this class.

```typescript
import { Dispatcher } from "webserial-core";
```

## Methods

### `on(type, callback)`

Registers an event listener and marks the event type as active.

```typescript
on(type: string, callback: EventListenerOrEventListenerObject): void
```

```javascript
device.on("serial:connected", (event) => {
  console.log("connected", event.detail);
});
```

***

### `off(type, callback)`

Removes a previously registered event listener.

```typescript
off(type: string, callback: EventListenerOrEventListenerObject): void
```

```javascript
const handler = (e) => console.log(e.detail);
device.on("serial:message", handler);
// later...
device.off("serial:message", handler);
```

***

### `dispatch(type, data?)`

Synchronously dispatches a `SerialEvent` (a `CustomEvent` subclass). The `data` value becomes `event.detail`.

```typescript
dispatch(type: string, data?: string | number | boolean | object | null): void
```

***

### `dispatchAsync(type, data?, ms?)`

Dispatches an event after `ms` milliseconds (default `100`).

```typescript
dispatchAsync(type: string, data?: any, ms?: number): void
```

***

### `serialRegisterAvailableListener(type)`

Registers a new event type so it appears in `availableListeners`. Called internally in the `Core` constructor — use it in your subclass to declare custom events.

```typescript
serialRegisterAvailableListener(type: string): void
```

```javascript
// inside your subclass constructor:
this.serialRegisterAvailableListener("my-custom-event");
```

***

### `removeAllListeners()`

Removes every listener except `internal:queue` and resets all listening flags to `false`. Useful for cleanup.

```typescript
removeAllListeners(): void
```

## Properties

### `availableListeners`

Read-only array of `{ type: string; listening: boolean }` objects representing all registered event types.

```typescript
get availableListeners(): { type: string; listening: boolean }[]
```

```javascript
console.table(device.availableListeners);
// [
//   { type: "serial:connected",    listening: true },
//   { type: "serial:disconnected", listening: false },
//   ...
// ]
```

---

---
url: /v1/api/socket.md
---

# Socket

::: warning Legacy v1 docs
v1 is on security fixes only. See [v2 docs](/api/websocket-provider) for the current release.
:::

`Socket` is a singleton that manages the Socket.io connection to a serial-bridge server. It forwards commands from the browser to a Node.js server that owns the physical serial port.

```typescript
import { Socket } from "webserial-core";
```

> **Peer dependency** — the Socket integration requires `socket.io-client` to be installed:
>
> ```bash
> npm install socket.io-client
> ```

## Server setup

You need a companion Node.js server. A minimal example is included in the `tests/ws-serial-bridge/` directory of the repository. It listens for `connectDevice`, `disconnectDevice`, `disconnectAll`, and `cmd` events and proxies them through the `serialport` npm package.

## Configuration

### `Socket.configure(uri?, options?)`

Sets the URI and Socket.io options **before** calling `prepare()`. Throws if `prepare()` has already been called.

```typescript
configure(uri?: string, options?: Partial<ManagerOptions & SocketOptions>): void
```

```javascript
Socket.configure("http://192.168.1.10:3001", { transports: ["websocket"] });
```

Default URI: `http://localhost:3001`.

***

### `Socket.prepare()`

Creates the `socket.io-client` instance and registers all internal event handlers. Safe to call multiple times — subsequent calls are no-ops if already connected.

```typescript
prepare(): void
```

***

### `Socket.disconnect()`

Closes the socket and cleans up all listeners.

```typescript
disconnect(): void
```

## Device interaction

### `Socket.connectDevice(config)`

Emits `connectDevice` to the server with the device configuration object.

```typescript
connectDevice(config: object): void
```

The `config` object matches `device.configDeviceSocket`.

***

### `Socket.disconnectDevice(config)`

Emits `disconnectDevice` to the server.

```typescript
disconnectDevice(config: object): void
```

***

### `Socket.disconnectAllDevices()`

Emits `disconnectAll` to the server — useful for cleanup on page unload.

```typescript
disconnectAllDevices(): void
```

***

### `Socket.write(data)`

Emits `cmd` to the server, which forwards the bytes to the serial port.

```typescript
write(data: object): void
```

## State

```typescript
Socket.isConnected(): boolean
Socket.isDisconnected(): boolean
Socket.socketId: string | null  // Socket.io socket ID
Socket.uri: string              // current server URI
Socket.options: object          // current Socket.io options
```

## Window events

The singleton dispatches these events on `window` so that `Core` instances can react to socket state changes:

| Event                        | Description                             |
| ---------------------------- | --------------------------------------- |
| `serial:socket:connected`    | Socket successfully connected           |
| `serial:socket:disconnected` | Socket disconnected or connection error |

## Usage example

```javascript
import { Arduino } from "./arduino.js";
import { Socket } from "webserial-core";

// 1. Configure before any device uses it
Socket.configure("http://localhost:3001");
Socket.prepare();

// 2. Create device in socket mode
const arduino = new Arduino({ socket: true, no_device: 1 });

arduino.on("serial:connected", () => console.log("Connected via socket"));
arduino.on("serial:disconnected", () => console.log("Disconnected"));

// 3. Connect — Core handles the connectDevice emit internally
arduino.connect().catch(console.error);
```

---

---
url: /v1/api/serial-error.md
---

# SerialError

::: warning Legacy v1 docs
v1 is on security fixes only. See [v2 docs](/api/abstract-serial-device) for the current release.
:::

`SerialError` is a structured error class that wraps serial communication failures with a typed code and optional context.

```typescript
import { SerialError, SerialErrorCode } from "webserial-core";
```

## Constructor

```typescript
new SerialError(
  message: string,
  code?: SerialErrorCode,
  context?: Record<string, unknown>
)
```

| Parameter | Default                         | Description                                              |
| --------- | ------------------------------- | -------------------------------------------------------- |
| `message` | —                               | Human-readable description                               |
| `code`    | `SerialErrorCode.UNKNOWN_ERROR` | Error category from `SerialErrorCode`                    |
| `context` | `undefined`                     | Extra key/value information (port name, baud rate, etc.) |

## `SerialErrorCode` enum

| Value                   | Description                                   |
| ----------------------- | --------------------------------------------- |
| `CONNECTION_FAILED`     | Could not open the serial port                |
| `DISCONNECTION_FAILED`  | Port failed to close cleanly                  |
| `WRITE_FAILED`          | Writing bytes to the port failed              |
| `READ_FAILED`           | Reading bytes from the port failed            |
| `TIMEOUT`               | No response received within the allotted time |
| `PORT_NOT_FOUND`        | Serial port no longer found / unplugged       |
| `PERMISSION_DENIED`     | Browser denied access to the port             |
| `DEVICE_NOT_SUPPORTED`  | Device type is not supported                  |
| `INVALID_CONFIGURATION` | Bad constructor options                       |
| `SOCKET_ERROR`          | Socket.io communication error                 |
| `UNKNOWN_ERROR`         | General uncategorised error                   |

## Properties

| Property    | Type                                   | Description                |
| ----------- | -------------------------------------- | -------------------------- |
| `name`      | `string`                               | Always `"SerialError"`     |
| `message`   | `string`                               | Human-readable message     |
| `code`      | `SerialErrorCode`                      | Error category             |
| `context`   | `Record<string, unknown> \| undefined` | Optional extra context     |
| `timestamp` | `Date`                                 | When the error was created |
| `stack`     | `string \| undefined`                  | V8 stack trace             |

## Methods

### `toJSON()`

Returns a plain object suitable for logging or serialisation.

```typescript
toJSON(): Record<string, unknown>
```

```javascript
const err = new SerialError(
  "Failed to connect",
  SerialErrorCode.CONNECTION_FAILED,
  { baudRate: 9600 },
);

console.log(err.toJSON());
// {
//   name: "SerialError",
//   message: "Failed to connect",
//   code: "CONNECTION_FAILED",
//   context: { baudRate: 9600 },
//   timestamp: "2024-01-15T10:30:00.000Z",
//   stack: "..."
// }
```

### `toString()`

Returns a formatted single-line string.

```typescript
toString(): string
// "SerialError [CONNECTION_FAILED]: Failed to connect | Context: {"baudRate":9600}"
```

## Usage

```javascript
arduino.on("serial:error", (event) => {
  const err = event.detail;
  if (err instanceof SerialError) {
    console.error(`[${err.code}] ${err.message}`, err.context);
  } else {
    console.error(err);
  }
});
```

---

---
url: /v1/api/events.md
---

# Events

::: warning Legacy v1 docs
v1 is on security fixes only. See [v2 docs](/api/events) for the current release.
:::

v1 uses a custom `CustomEvent`-based system. Listen with `device.on(eventName, handler)`. The handler receives the native `CustomEvent`; payload is always in `event.detail`.

```javascript
arduino.on("serial:connected", (event) => {
  console.log("connected!", event.detail);
});
```

## Device events

| Event                    | Detail                             | Description                                                             |
| ------------------------ | ---------------------------------- | ----------------------------------------------------------------------- |
| `serial:connecting`      | `null`                             | Emitted when the connection process starts                              |
| `serial:connected`       | `null`                             | Emitted when the device is fully connected and ready                    |
| `serial:disconnected`    | `object \| null`                   | Emitted when the device disconnects (detail may carry an error message) |
| `serial:need-permission` | `null`                             | User must interact with the browser to grant port access                |
| `serial:unsupported`     | `null`                             | Web Serial API is not available in this browser                         |
| `serial:reconnect`       | `{}`                               | Emitted on a connection timeout when still in `connect` phase           |
| `serial:message`         | device-specific                    | Emitted from your `serialMessage()` implementation                      |
| `serial:corrupt-message` | `{ code }`                         | Emitted from your `serialCorruptMessage()` implementation               |
| `serial:sent`            | `{ action, bytes }`                | Emitted after bytes are written to the port                             |
| `serial:timeout`         | `{ message, action, code, bytes }` | Emitted when a queued command does not receive a response in time       |
| `serial:soft-reload`     | `{}`                               | Emitted by `softReload()`; use it to reset your local state             |
| `serial:error`           | `Error \| DOMException`            | Any uncaught error from connection or I/O                               |
| `serial:lost`            | `null`                             | Emitted when the port is unexpectedly removed/closed                    |
| `debug`                  | `{ type, data }`                   | Internal debug event (only fired when debug mode is active)             |

## Registry event

| Event    | Detail                    | Description                                                |
| -------- | ------------------------- | ---------------------------------------------------------- |
| `change` | `{ devices, dispatcher }` | Fired on `Devices.instance` whenever context state changes |

## Socket events (window-level)

When `socket: true` is set in the constructor, these events are dispatched on `window`:

| Event                        | Description                      |
| ---------------------------- | -------------------------------- |
| `serial:socket:connected`    | Socket.io connection established |
| `serial:socket:disconnected` | Socket.io connection lost        |

## Event detail shapes

### `serial:timeout`

```typescript
{
  message: string;   // "Operation response timed out."
  action: string;    // the queue action (e.g. "connect", "hi")
  code: Uint8Array | string[] | null;
  bytes: Uint8Array | string[];
  no_code: number;
}
```

### `serial:sent`

```typescript
{
  action: string; // the queue action
  bytes: Uint8Array; // the bytes that were written
}
```

### `serial:disconnected`

```typescript
{
  error?: string;    // reason, e.g. "Port is closed, not readable or writable."
}
```

---

---
url: /v1/examples/arduino.md
---

# Arduino example

::: warning Legacy v1 docs
v1 is on security fixes only. For new projects use [v2](/examples/web-serial).
:::

This is a complete working example of connecting to an Arduino via v1 of webserial-core.

## Arduino firmware

Upload the following sketch to your board:

```cpp
// firmware.ino

void setup() {
  Serial.begin(9600);
}

void loop() {
  if (Serial.available() > 0) {
    String comando = Serial.readStringUntil('\n');

    if (comando.startsWith("CONNECT")) {
      Serial.println("connected");
    } else if (comando.startsWith("CREDITS")) {
      Serial.println("created by danidoble");
    } else if (comando.startsWith("HI")) {
      Serial.println("hello there");
    } else {
      Serial.println("ara ara, what are you doing?");
    }
  }
}
```

## Device class

```javascript
// arduino.js
import { Core, Devices } from "webserial-core";

export class Arduino extends Core {
  constructor({
    filters = null,
    config_port = {
      baudRate: 9600,
      dataBits: 8,
      stopBits: 1,
      parity: "none",
      bufferSize: 32768,
      flowControl: "none",
    },
    no_device = 1,
  } = {}) {
    super({ filters, config_port, no_device });

    this.__internal__.device.type = "arduino";
    Devices.registerType("arduino");

    if (Devices.getByNumber(this.typeDevice, no_device)) {
      throw new Error(`Device arduino #${no_device} already exists`);
    }

    this.__internal__.time.response_connection = 2000;
    this.__internal__.time.response_general = 2000;
    this.__internal__.serial.delay_first_connection = 1000;

    Devices.add(this);
    this.getResponseAsString();
  }

  serialSetConnectionConstant() {
    return this.add0x(this.parseStringToBytes("CONNECT"));
  }

  serialMessage(codex) {
    const message = {
      code: codex,
      name: "unknown",
      description: "Unknown command",
      request: "unknown",
      no_code: 400,
    };

    switch (codex) {
      case "connected":
        Object.assign(message, {
          name: "connected",
          description: "Connection established",
          request: "connect",
          no_code: 100,
        });
        break;
      case "created by danidoble":
        Object.assign(message, {
          name: "thanks",
          description: "Thanks for using this software",
          request: "credits",
          no_code: 101,
        });
        break;
      case "hello there":
        Object.assign(message, {
          name: "hello there",
          description: "Hi human",
          request: "hi",
          no_code: 102,
        });
        break;
    }

    this.dispatch("serial:message", message);
  }

  async sayCredits() {
    await this.appendToQueue(this.parseStringToBytes("CREDITS"), "credits");
  }

  async sayHi() {
    await this.appendToQueue(this.parseStringToBytes("HI"), "hi");
  }

  async sendCustomCode({ code = "" } = {}) {
    if (typeof code !== "string") throw new TypeError("code must be a string");
    await this.appendToQueue(this.parseStringToBytes(code), "custom");
  }
}
```

## Connection script

```javascript
// main.js
import { Arduino } from "./arduino.js";

export const arduino = new Arduino();

arduino.on("serial:message", (event) => {
  console.log("[message]", event.detail);
});

arduino.on("serial:timeout", (event) => {
  console.warn("[timeout]", event.detail);
});

arduino.on("serial:error", (event) => {
  console.error("[error]", event.detail);
});

arduino.on("serial:disconnected", () => {
  document.getElementById("log").textContent += "Disconnected\n";
  toggleUI(false);
});

arduino.on("serial:connecting", () => {
  document.getElementById("log").textContent += "Connecting…\n";
});

arduino.on("serial:connected", () => {
  document.getElementById("log").textContent += "Connected!\n";
  toggleUI(true);
});

arduino.on("serial:need-permission", () => {
  document.getElementById("log").textContent +=
    "Permission required — click Connect\n";
});

arduino.on("serial:soft-reload", () => {
  // reset your local variables here
});

arduino.on("serial:unsupported", () => {
  document.getElementById("unsupported").hidden = false;
});

function toggleUI(connected) {
  document.getElementById("connect").hidden = connected;
  document.getElementById("disconnect").hidden = !connected;
}

function tryConnect() {
  arduino.connect().catch(console.error);
}

document.addEventListener("DOMContentLoaded", () => {
  tryConnect();
  document.getElementById("connect").addEventListener("click", tryConnect);
  document.getElementById("disconnect").addEventListener("click", async () => {
    await arduino.disconnect().catch(console.error);
    document.getElementById("log").textContent += "Disconnected by user\n";
  });
  document
    .getElementById("hi")
    .addEventListener("click", () => arduino.sayHi().catch(console.error));
  document
    .getElementById("credits")
    .addEventListener("click", () => arduino.sayCredits().catch(console.error));
});
```

## HTML

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>webserial-core v1 — Arduino demo</title>
    <script src="./main.js" type="module"></script>
  </head>
  <body>
    <h1>Arduino Demo</h1>

    <button id="connect">Connect to serial</button>
    <button id="disconnect" hidden>Disconnect</button>
    <button id="hi">Say Hi</button>
    <button id="credits">Get credits</button>

    <div id="need-permission" hidden>
      Permission denied — click <strong>Connect to serial</strong> to try again.
    </div>

    <div id="unsupported" hidden>
      This browser does not support the Web Serial API. Please use Chrome 89+ or
      Edge 89+.
    </div>

    <pre id="log">Log:&#10;</pre>
  </body>
</html>
```

## Multiple devices

To manage two Arduino boards simultaneously:

```javascript
import { Arduino } from "./arduino.js";
import { Devices } from "webserial-core";

const a1 = new Arduino({ no_device: 1 });
const a2 = new Arduino({ no_device: 2 });

// Connect both at once
await Devices.connectToAll();

// Send a command to board 2 only
await a2.sayHi();
```

---

---
url: /v1/examples/socket-bridge.md
---

# Socket.io Bridge example

::: warning Legacy v1 docs
v1 is on security fixes only. For new projects use the [v2 WebSocket provider](/api/websocket-provider).
:::

The Socket.io integration lets you access the serial port from a browser that is **not physically connected** to the device (e.g., a tablet or remote machine on the same network). A small Node.js server owns the USB/serial connection and proxies it over a WebSocket.

## Architecture

```
Browser  ──WebSocket──▶  Node.js bridge server  ──serial port──▶  Device
         (socket.io)      (serialport + socket.io)
```

## Server (Node.js)

```javascript
// server.js
import { SerialPort } from "serialport";
import { Server } from "socket.io";
import { createServer } from "http";

const httpServer = createServer();
const io = new Server(httpServer, { cors: { origin: "*" } });

const ports = new Map(); // deviceUUID → SerialPort

io.on("connection", (socket) => {
  console.log("Browser connected:", socket.id);

  socket.on("connectDevice", async ({ config }) => {
    const { uuid, connectionBytes, config: portConfig, info } = config;

    const portPath = info.portName ?? (await autoDetect(portConfig));
    if (!portPath) {
      socket.emit("response", { uuid, type: "error", data: "PORT_NOT_FOUND" });
      return;
    }

    const port = new SerialPort({
      path: portPath,
      baudRate: portConfig.baudRate,
      autoOpen: false,
    });

    await new Promise((res, rej) =>
      port.open((err) => (err ? rej(err) : res())),
    );

    ports.set(uuid, port);

    // Forward incoming data back to the browser
    port.on("data", (data) => {
      socket.emit("response", {
        uuid,
        name: config.name,
        deviceNumber: config.deviceNumber,
        type: "success",
        data: Array.from(data),
      });
    });

    // Send connection bytes
    port.write(Buffer.from(connectionBytes));

    socket.emit("response", { uuid, type: "info", data: "PORT_OPENED" });
  });

  socket.on("cmd", ({ uuid, bytes }) => {
    ports.get(uuid)?.write(Buffer.from(bytes));
  });

  socket.on("disconnectDevice", ({ config }) => {
    const port = ports.get(config.uuid);
    port?.close();
    ports.delete(config.uuid);
    socket.emit("response", { uuid: config.uuid, type: "disconnect" });
  });

  socket.on("disconnectAll", () => {
    for (const [uuid, port] of ports) {
      port.close();
      ports.delete(uuid);
    }
  });

  socket.on("disconnect", () => {
    // clean up all ports this browser owned
    for (const [uuid, port] of ports) {
      port.close();
      ports.delete(uuid);
    }
  });
});

httpServer.listen(3001, () => console.log("Bridge listening on :3001"));
```

Install the server dependencies:

```bash
npm install serialport socket.io
```

## Browser (device class)

The device class is identical to the [Arduino example](./arduino) with one addition — pass `socket: true` to the constructor:

```javascript
// arduino-socket.js
import { Core, Devices } from "webserial-core";

export class Arduino extends Core {
  constructor({ no_device = 1 } = {}) {
    super({
      no_device,
      socket: true, // ← enable socket mode
    });
    this.__internal__.device.type = "arduino";
    Devices.registerType("arduino");
    Devices.add(this);
    this.getResponseAsString();

    // Tell the bridge which port to open
    this.portPath = "/dev/ttyUSB0"; // or "COM3" on Windows
  }

  serialSetConnectionConstant() {
    return this.add0x(this.parseStringToBytes("CONNECT"));
  }

  serialMessage(codex) {
    this.dispatch("serial:message", { code: codex });
  }
}
```

## Browser (connection script)

```javascript
// main.js
import { Arduino } from "./arduino-socket.js";
import { Socket } from "webserial-core";

// 1. Point to your bridge server
Socket.configure("http://localhost:3001");
Socket.prepare();

// 2. Create device — socket mode is set in the constructor
const arduino = new Arduino({ no_device: 1 });

arduino.on("serial:connected", () => console.log("Connected via socket!"));
arduino.on("serial:disconnected", () => console.log("Disconnected"));
arduino.on("serial:message", (e) => console.log(e.detail));

// 3. Connect — Core sends connectDevice over the socket automatically
arduino.connect().catch(console.error);
```

## Custom parser

The bridge server can use two parsers (configured via `device.socketPortParser`):

| Parser               | Property                         | Description                                          |
| -------------------- | -------------------------------- | ---------------------------------------------------- |
| `inter-byte-timeout` | `socketPortParserInterval` (ms)  | Emits after silence — good for text protocols        |
| `byte-length`        | `socketPortParserLength` (bytes) | Emits every N bytes — good for fixed-frame protocols |

```javascript
// inside your constructor:
this.socketPortParser = "inter-byte-timeout";
this.socketPortParserInterval = 30; // ms
```

---

---
url: /es.md
---