react-native-web-serial-api 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aras Abbasi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# 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).
+
+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.
+
+- 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`)
+
+> **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.
+
+## Installation
+
+```sh
+npm install react-native-web-serial-api
+# or
+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.
+
+## 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.
+  const port = await serial.requestPort({
+    filters: [{usbVendorId: 0x0403}], // optional — e.g. only FTDI devices
+  });
+
+  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
+  console.log(value);
+  reader.releaseLock();
+
+  await port.close();
+}
+```
+
+### Control & status signals
+
+```ts
+await port.setSignals({dataTerminalReady: true, requestToSend: false});
+const {clearToSend, dataCarrierDetect, ringIndicator, dataSetReady} =
+  await port.getSignals();
+```
+
+### Connect / disconnect events
+
+```ts
+serial.addEventListener('connect', () => console.log('device attached'));
+serial.addEventListener('disconnect', () => console.log('device detached'));
+
+port.addEventListener('disconnect', () => console.log('this port went away'));
+```
+
+### Listing already-permitted ports
+
+```ts
+const ports = await serial.getPorts();
+```
+
+## API
+
+The package exposes:
+
+| Export | Description |
+| --- | --- |
+| `serial` | A ready-to-use `Serial` instance (`navigator.serial` equivalent). |
+| `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. |
+| 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).
+
+```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:
+
+- **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).
+
+### 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.
+
+```sh
+cd example
+npm install
+npm run web          # dev server at http://localhost:5173
+# npm run web:build  # production build into example/dist
+```
+
+> 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.
+
+## 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).
+
+## License
+
+MIT © Aras Abbasi

package/android/build.gradle

@@ -0,0 +1,62 @@
+buildscript {
+  // Allow the library to be built either standalone (using the *_ defaults from
+  // gradle.properties) or as part of a host app (using the host's rootProject.ext).
+  ext.getExtOrDefault = { name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["WebSerialApi_" + name]
+  }
+
+  // When autolinked into a host app, the Android Gradle Plugin is already on the
+  // root project's buildscript classpath, so we must not redeclare it here. Only
+  // pull it in (with an explicit version) when building this library standalone.
+  def agpVersion = rootProject.ext.has("agpVersion") ? rootProject.ext.get("agpVersion") : "8.7.2"
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    if (project == rootProject) {
+      classpath "com.android.tools.build:gradle:$agpVersion"
+    }
+  }
+}
+
+apply plugin: "com.android.library"
+// Drives React Native Codegen for the TurboModule spec declared in package.json -> codegenConfig
+apply plugin: "com.facebook.react"
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["WebSerialApi_" + name]).toInteger()
+}
+
+android {
+  namespace "dev.webserialapi"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+  // usb-serial-for-android is published on JitPack
+  maven { url "https://jitpack.io" }
+}
+
+dependencies {
+  // The version of react-native is set by the host app's React Native Gradle Plugin
+  implementation "com.facebook.react:react-android"
+  implementation "com.github.mik3y:usb-serial-for-android:3.10.0"
+  // PortPickerActivity extends AppCompatActivity and uses the AppCompat dialog theme
+  implementation "androidx.appcompat:appcompat:1.7.0"
+}

package/android/gradle.properties

@@ -0,0 +1,6 @@
+# Fallback values used when the library is built standalone (i.e. when the host
+# app's rootProject.ext does not provide these). Inside a host app the app's
+# values take precedence (see getExtOrDefault in build.gradle).
+WebSerialApi_compileSdkVersion=35
+WebSerialApi_targetSdkVersion=34
+WebSerialApi_minSdkVersion=24

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,21 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-feature android:name="android.hardware.usb.host" />
+
+    <application>
+        <!-- Native dialog shown by serial.requestPort() to let the user pick a port -->
+        <activity
+            android:name="dev.webserialapi.PortPickerActivity"
+            android:exported="false"
+            android:theme="@style/Theme.AppCompat.Dialog" />
+
+        <!-- Emits a "disconnect" JS event when a USB serial device is unplugged -->
+        <receiver
+            android:name="dev.webserialapi.UsbDetachReceiver"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.hardware.usb.action.USB_DEVICE_DETACHED" />
+            </intent-filter>
+        </receiver>
+    </application>
+</manifest>