react-native-web-serial-api 0.0.3 → 0.2.0

package/README.md

@@ -1,18 +1,26 @@
 # react-native-web-serial-api
 
-> The [W3C Web Serial API](https://wicg.github.io/serial/) (`navigator.serial`) for **React Native on Android**, backed by a USB-serial TurboModule built on top of [`mik3y/usb-serial-for-android`](https://github.com/mik3y/usb-serial-for-android).
+> The [W3C Web Serial API](https://wicg.github.io/serial/) (`navigator.serial`) for React Native on Android, backed by a USB-serial TurboModule built on top of [`mik3y/usb-serial-for-android`](https://github.com/mik3y/usb-serial-for-android).
 
-Talk to USB serial devices (FTDI, CP210x, CH340/CH341, PL2303, CDC-ACM …) from React Native using the **exact same API you already know from the browser** — `serial.requestPort()`, `port.open()`, `port.readable`, `port.writable`, and so on.
+Use the same API you already know from the browser - `serial.requestPort()`, `port.open()`, `port.readable`, `port.writable`, `getPorts()`, `setSignals()`, and `getSignals()` - in a React Native app that talks to USB serial devices.
 
-- Spec-compliant `Serial` / `SerialPort` implementation (`getPorts`, `requestPort`, `open`, `close`, `readable`, `writable`, `setSignals`, `getSignals`, `forget`, `connect`/`disconnect` events)
-- New Architecture **TurboModule**
-- Native port-picker dialog + USB permission handling
-- Backed by Web Streams (`ReadableStream` / `WritableStream`)
-- Drop-in for code written against the browser Web Serial API (on web it transparently uses the native `navigator.serial`)
+## At a glance
 
-> **Platform support:** Android only. On web (`react-native-web`) the package delegates to the browser's native Web Serial API. There is no iOS implementation (iOS does not allow generic USB-serial access), so iOS autolinking is disabled.
+- Spec-style `Serial` / `SerialPort` implementation
+- New Architecture TurboModule
+- Native port picker and Android USB permission handling
+- Web Streams under the hood (`ReadableStream` / `WritableStream`)
+- Works with browser-style code on web by delegating to the native `navigator.serial`
 
-## Installation
+## Platform support
+
+| Platform | Support | Notes |
+| --- | --- | --- |
+| Android | Yes | Native USB-serial support through the TurboModule. |
+| Web | Yes | Delegates to the browser's native `navigator.serial`. |
+| iOS | No | Generic USB-serial access is not available, so autolinking is disabled. |
+
+## Quick start
 
 ```sh
 npm install react-native-web-serial-api
@@ -20,49 +28,27 @@ npm install react-native-web-serial-api
 yarn add react-native-web-serial-api
 ```
 
-This is a New Architecture library, so make sure your app has the New Architecture enabled (default in recent React Native). No manual linking is required — the module is autolinked.
-
-### Android setup
-
-The library ships its own `AndroidManifest.xml` that declares the port-picker activity, the detach receiver, and the `android.hardware.usb.host` feature, so usually **no extra configuration is needed**.
-
-If you want your app to be **launched automatically when a matching device is plugged in**, add an intent filter to your launcher activity in `android/app/src/main/AndroidManifest.xml`:
-
-```xml
-<activity android:name=".MainActivity" ...>
-  <intent-filter>
-    <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
-  </intent-filter>
-  <!-- The device_filter resource is provided by the library -->
-  <meta-data
-    android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
-    android:resource="@xml/device_filter" />
-</activity>
-```
-
-The bundled `@xml/device_filter` matches the common USB-serial chips (CDC-ACM, FTDI `0x0403`, CP210x `0x10C4`, CH34x `0x1A86`, PL2303 `0x067B`). Provide your own `res/xml/device_filter.xml` to override it.
+This is a New Architecture library. Make sure your app has the New Architecture enabled. No manual linking is required - the module is autolinked.
 
-## Usage
+### Minimal usage
 
 ```ts
 import {serial} from 'react-native-web-serial-api';
 
 async function run() {
-  // Shows a native dialog to pick a port, then requests USB permission.
+  // Must be called from a user gesture on web.
   const port = await serial.requestPort({
-    filters: [{usbVendorId: 0x0403}], // optional — e.g. only FTDI devices
+    filters: [{usbVendorId: 0x0403}], // optional, for example FTDI only
   });
 
   await port.open({baudRate: 115200, dataBits: 8, stopBits: 1, parity: 'none'});
 
-  // Write
   const writer = port.writable.getWriter();
   await writer.write(new TextEncoder().encode('Hello\n'));
   writer.releaseLock();
 
-  // Read
   const reader = port.readable.getReader();
-  const {value} = await reader.read(); // value is a Uint8Array
+  const {value} = await reader.read();
   console.log(value);
   reader.releaseLock();
 
@@ -70,127 +56,235 @@ async function run() {
 }
 ```
 
-### Control & status signals
+## Android setup
 
-```ts
-await port.setSignals({dataTerminalReady: true, requestToSend: false});
-const {clearToSend, dataCarrierDetect, ringIndicator, dataSetReady} =
-  await port.getSignals();
+The library ships its own `AndroidManifest.xml` that declares the port picker activity, the detach receiver, and the `android.hardware.usb.host` feature, so usually no extra configuration is needed.
+
+If you want your app to launch automatically when a matching device is plugged in, add an intent filter to your launcher activity in `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<activity android:name=".MainActivity" ...>
+  <intent-filter>
+    <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
+  </intent-filter>
+  <meta-data
+    android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
+    android:resource="@xml/device_filter" />
+</activity>
 ```
 
-### Connect / disconnect events
+The bundled `@xml/device_filter` matches common USB-serial chips:
+
+- CDC-ACM
+- FTDI `0x0403`
+- CP210x `0x10C4`
+- CH34x `0x1A86`
+- PL2303 `0x067B`
+
+Provide your own `res/xml/device_filter.xml` to override it.
+
+## Which API should I use?
+
+| Use case | Start with | Why |
+| --- | --- | --- |
+| Real hardware in your app | `Serial` / `SerialPort` | The browser-style Web Serial API you already know. |
+| Quick in-memory smoke tests | `InMemorySerialTransport` + `LoopbackDevice` | Fastest way to exercise bytes without hardware. |
+| Protocol tests against a simulated peripheral | `SimulatedDevice` + `createDeviceFixture` + `SerialClient` | Gives you both sides of the conversation in one test. |
+| App-to-app or emulator-to-host testing | `exposeSimulatedDevice` + `WebSocketSerialTransport` | Runs the same simulated device behind a real WebSocket bridge. |
+
+## Core concepts
+
+### `serial`
+
+The package exports a ready-to-use `serial` singleton, which is the equivalent of `navigator.serial`.
 
 ```ts
-serial.addEventListener('connect', () => console.log('device attached'));
-serial.addEventListener('disconnect', () => console.log('device detached'));
+import {serial} from 'react-native-web-serial-api';
 
-port.addEventListener('disconnect', () => console.log('this port went away'));
+const ports = await serial.getPorts();
 ```
 
-On Android, `serial` fires `connect` when a USB device is **attached** _and_ when
-the app is **granted USB permission** for a device (the latter matters because
-Android revokes permission on unplug, so a re-attached device only becomes
-accessible — and shows up in `getPorts()` — once permission is re-granted).
-Simply subscribing with `serial.addEventListener('connect', …)` is enough to
-receive these; you don't need to call `getPorts()` first. A common pattern is to
-re-run `getPorts()` on every `connect`/`disconnect` to keep a device list fresh.
+### Permissions
+
+There are two different permission concepts:
 
-### Listing already-permitted ports
+- `serial.requestPort()` is the Web Serial permission flow. In Android mode it shows the native picker and requests Android USB permission for the selected device.
+- Android USB permission can also be granted outside the app, for example through the system attach dialog or an `USB_DEVICE_ATTACHED` intent filter.
+
+On Android, `serial.getPorts()` returns the devices the app can currently access through Android USB permission, regardless of how that permission was obtained. On web, `getPorts()` returns ports previously granted by the site in the browser's persistent permission store.
 
 ```ts
 const ports = await serial.getPorts();
+const port = await serial.requestPort();
 ```
 
-## Permission model (Android vs. Web Serial)
-
-There are two distinct notions of "permission" in play, and they behave
-differently on Android than in the browser:
-
-- **Web Serial permission grant** — `serial.requestPort()`. In the browser this
-  records a site-level grant for the chosen port; on Android it shows a native
-  picker and requests the Android USB permission for the selected device. This
-  is the mechanism for gaining access to a device you don't have access to yet,
-  and it is **unchanged** by anything below.
-- **Native Android USB permission** — `UsbManager` permission for a device.
-  This can be granted **outside** the app entirely: when you plug a device in,
-  Android may show its own _"Open <app> to handle this USB device? / use by
-  default for this device"_ dialog, or the app may have been launched via a
-  `USB_DEVICE_ATTACHED` intent filter. In those cases the app already holds USB
-  permission without ever calling `requestPort()`.
-
-**`serial.getPorts()` in Android/native mode** returns **every probed
-USB-serial port the app can currently access through Android USB permission** —
-regardless of how that permission was obtained. So a device granted via the
-system attach dialog appears in `getPorts()` even though `requestPort()` was
-never called for it. Probed devices the app does **not** yet have permission for
-are excluded; use `requestPort()` to gain access to those.
+### Connect and disconnect events
 
 ```ts
-// All devices accessible right now (natively-granted OR previously requested):
-const ports = await serial.getPorts();
+serial.addEventListener('connect', () => console.log('device attached'));
+serial.addEventListener('disconnect', () => console.log('device detached'));
 
-// Gain access to a device you don't have permission for yet:
-const port = await serial.requestPort();
+port.addEventListener('disconnect', () => console.log('this port went away'));
+```
+
+On Android, `serial` fires `connect` when a USB device is attached and when the app is granted USB permission for a device. A common pattern is to re-run `getPorts()` on every `connect` / `disconnect` so your device list stays fresh.
+
+### Control and status signals
+
+```ts
+await port.setSignals({dataTerminalReady: true, requestToSend: false});
+const {clearToSend, dataCarrierDetect, ringIndicator, dataSetReady} =
+  await port.getSignals();
 ```
 
-On the **web**, `getPorts()` returns the ports the user has previously granted
-the site via `requestPort()` (the browser's persistent permission store) — the
-native "attach dialog" notion does not apply.
+### Browser-only option note
 
-> Note: this is a deliberate, Android-appropriate reading of the Web Serial
-> spec's `getPorts()` ("ports the site has been granted access to"). On Android
-> the unit of access is the OS-level USB permission, so a device the OS has
-> already authorized for the app is, by definition, one the app has been
-> granted access to.
+In Android USB mode, `allowedBluetoothServiceClassIds` is not supported by `requestPort()` and will throw a `TypeError` if provided.
 
-## API
+## API reference
 
 The package exposes:
 
 | Export | Description |
 | --- | --- |
-| `serial` | A ready-to-use `Serial` instance (`navigator.serial` equivalent). |
+| `serial` | A ready-to-use `Serial` instance. |
 | `Serial`, `SerialPort` | The Web Serial API classes. |
 | `UsbSerial` | Lower-level access to the raw USB-serial TurboModule (Android only). |
-| `Event`, `EventTarget` | The event primitives used by the polyfill. |
+| `Event`, `EventTarget` | Polyfill implementations used only when the runtime does not already provide these globals. |
 | Types | `SerialOptions`, `SerialOutputSignals`, `SerialInputSignals`, `SerialPortInfo`, `SerialPortFilter`, `SerialPortRequestOptions`. |
 
 ## Example app
 
-The [`example/`](./example) app is a React Native port of [SimpleUsbTerminal](https://github.com/kai-morich/SimpleUsbTerminal) built entirely on this package's Web Serial API — a **Devices** list (with baud-rate selection) and a **Terminal** (colored receive/send log, HEX mode, newline selection, clear, control-lines row with RTS/DTR toggles, flow control, and Send BREAK).
+The [`example/`](./example) app is a React Native port of [SimpleUsbTerminal](https://github.com/kai-morich/SimpleUsbTerminal) built on this package's Web Serial API. It includes:
+
+- a Devices screen with baud-rate selection
+- a Terminal screen with colored send / receive logs
+- HEX mode
+- newline selection
+- clear
+- control lines with RTS / DTR toggles
+- flow control
+- Send BREAK
+
+### Run the example on Android
 
 ```sh
-# install the library's build tooling
 npm install
-
-# install and run the example on Android
 cd example
 npm install
 npm run android
 ```
 
-Because it uses the Web Serial API, a few SimpleUsbTerminal details map differently:
+Because the example uses the Web Serial API, a few details differ from SimpleUsbTerminal:
 
-- **Driver/chip name** isn't exposed by the Web Serial API (`getInfo()` returns only VID/PID), so rows show `Vendor/Product` plus a best-effort chip label from known vendor IDs.
-- **Flow control** is limited to *None* / *Hardware (RTS-CTS)* — XON/XOFF and DTR/DSR aren't in the Web Serial spec. Changing it reconnects the port.
-- The Android background **foreground-service notification** is omitted (it's service plumbing unrelated to serial I/O).
+- Driver / chip name is not exposed by the Web Serial API. Rows show `Vendor/Product` plus a best-effort chip label from known vendor IDs.
+- Flow control is limited to `None` and `Hardware (RTS-CTS)`. XON/XOFF and DTR/DSR are not in the Web Serial spec. Changing it reconnects the port.
+- The Android foreground-service notification is omitted because it is service plumbing unrelated to serial I/O.
 
 ### Run the example in the browser
 
-The example also runs as a web app via [`react-native-web`](https://necolas.github.io/react-native-web/) + [Vite](https://vite.dev/). On web, the package delegates to the browser's native `navigator.serial`, so the exact same `App.tsx` talks to real serial hardware over WebUSB-style permissions.
+The example also runs as a web app via [`react-native-web`](https://necolas.github.io/react-native-web/) and [Vite](https://vite.dev/). On web, the package delegates to the browser's native `navigator.serial`, so the same `App.tsx` talks to real serial hardware through browser permissions.
 
 ```sh
 cd example
 npm install
-npm run web          # dev server at http://localhost:5173
-# npm run web:build  # production build into example/dist
+npm run web
+# npm run web:build
+```
+
+Web Serial works in Chromium-based browsers over a secure context. `http://localhost` counts. `requestPort()` must be called from a user gesture, and the example's Request port button handles that.
+
+## Testing and simulation
+
+The transport layer lets you test without USB hardware, whether you want a quick loopback check, a stateful simulated peripheral, or a full WebSocket E2E path. The example app also includes a Self Test screen and a Virtual device (demo) mode.
+
+### Fast in-memory test
+
+```ts
+import {Serial} from 'react-native-web-serial-api';
+import {
+  InMemorySerialTransport,
+  LoopbackDevice,
+} from 'react-native-web-serial-api/testing';
+
+const transport = new InMemorySerialTransport();
+transport.addDevice(
+  new LoopbackDevice({usbVendorId: 0x0403, usbProductId: 0x6001}),
+  {hasPermission: true},
+);
+
+const serial = new Serial(transport);
 ```
 
-> Web Serial only works in **Chromium-based browsers** (Chrome / Edge / Opera) over a **secure context** (`http://localhost` counts), and `requestPort()` must be called from a user gesture — the demo's "Request port" button handles that.
+### Host-side protocol test
+
+```ts
+import {createDeviceFixture, SimulatedDevice} from 'react-native-web-serial-api/testing';
+
+class Thermometer extends SimulatedDevice {
+  readonly usbVendorId = 0x10c4;
+  readonly usbProductId = 0xea60;
+
+  onOpen() {
+    this.send('READY\r\n');
+  }
+
+  emitTemperature(value: number) {
+    this.send(`temp=${value}\r\n`);
+  }
+}
+
+const {client, simulatedDevice, whenOpened} =
+  await createDeviceFixture(new Thermometer());
+
+await client.open({baudRate: 115200});
+await whenOpened();
+simulatedDevice.emitTemperature(21.5);
+expect(await client.readLine()).toBe('temp=21.5');
+await client.close();
+```
+
+For the full guide to `SerialClient`, `createDeviceFixture`, fault injection, `runTestSuite`, `compareTestResults`, `exposeSimulatedDevice`, and the conformance suites, see [TESTING.md](TESTING.md).
+
+## Remote serial over WebSocket
+
+You can drive a real serial port plugged into another machine. This is useful for developing in a Chromium browser or an Android emulator that cannot see the USB device directly, or for remote debugging.
+
+On the host machine, run the bundled CLI:
+
+```sh
+npx -p react-native-web-serial-api expose-serial-websocket \
+  --port /dev/ttyUSB0 --baudrate 115200
+# add --allow-remote to bind 0.0.0.0
+```
+
+In the app:
+
+```ts
+import {Serial} from 'react-native-web-serial-api';
+import {WebSocketSerialTransport} from 'react-native-web-serial-api/websocket';
+
+const serial = new Serial(new WebSocketSerialTransport('ws://localhost:8080'));
+const [port] = await serial.getPorts();
+await port.open({baudRate: 115200});
+const writer = port.writable!.getWriter();
+await writer.write(new TextEncoder().encode('Hello serial!\n'));
+```
+
+The example app includes this under Devices -> menu -> Remote serial (WebSocket).
+
+The WebSocket carries raw serial bytes as binary frames and a small JSON control protocol as text frames (`setLineCoding`, `setSignals` / `getSignals`, `startReading` / `stopReading`, `flush`, `break`, and so on). By default the bridge binds to `localhost`. Use `--allow-remote` only on trusted networks.
+
+## Troubleshooting
+
+- If Android never shows your device, confirm USB host support and the device filter.
+- If `requestPort()` does nothing on web, make sure it is called from a button tap or other user gesture.
+- If the app works on web but not Android, check that New Architecture is enabled and the device has Android USB permission.
+- If `getPorts()` is empty on Android, unplug and replug the device, then grant permission again if Android revoked it.
 
 ## How it works
 
-The JavaScript layer (`src/`) implements the Web Serial API on top of a thin TurboModule (`NativeUsbSerial`) whose native Android implementation (`android/src/main/java/dev/webserialapi/`) wraps `usb-serial-for-android`. Reads/writes are bridged to `ReadableStream`/`WritableStream` via [`web-streams-polyfill`](https://github.com/MattiasBuelens/web-streams-polyfill).
+The JavaScript layer in `src/` implements the Web Serial API on top of a thin TurboModule (`NativeUsbSerial`) whose native Android implementation in `android/src/main/java/dev/webserialapi/` wraps `usb-serial-for-android`. Reads and writes are bridged to `ReadableStream` / `WritableStream` via [`web-streams-polyfill`](https://github.com/MattiasBuelens/web-streams-polyfill) when the runtime does not already provide Web Streams globals.
 
 ## License