react-native-web-serial-api 0.0.1

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "react-native-web-serial-api",
+  "version": "0.0.1",
+  "description": "W3C Web Serial API (navigator.serial) for React Native on Android, backed by a USB-serial TurboModule (built on mik3y/usb-serial-for-android).",
+  "main": "lib/commonjs/index.js",
+  "react-native": "lib/commonjs/index.js",
+  "source": "src/index.ts",
+  "types": "lib/typescript/src/index.d.ts",
+  "scripts": {
+    "prepare": "bob build",
+    "clean": "node -e \"require('fs').rm(\\\"./lib\\\", { recursive: true }, () => {console.log(\\\"'lib' folder deleted\\\")})\"",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src",
+    "format": "biome check --write src"
+  },
+  "keywords": [
+    "react-native",
+    "android",
+    "web-serial",
+    "web serial api",
+    "serial",
+    "usb",
+    "usb-serial",
+    "turbomodule",
+    "navigator.serial",
+    "ftdi",
+    "cp210x",
+    "ch340",
+    "pl2303",
+    "cdc-acm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uzlopak/react-native-web-serial-api.git"
+  },
+  "author": "Aras Abbasi <arasabbasi@gmail.com>",
+  "license": "MIT",
+  "codegenConfig": {
+    "name": "WebSerialApiSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "dev.webserialapi"
+    }
+  },
+  "dependencies": {
+    "web-streams-polyfill": "^4.3.0"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@react-native/babel-preset": "0.85.3",
+    "@types/react": "^19.2.6",
+    "react": "19.2.3",
+    "react-native": "0.85.3",
+    "react-native-builder-bob": "^0.41.0",
+    "typescript": "6.0.3"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,9 @@
+// Consumed by the React Native CLI in host apps. This package is Android-only,
+// so opt out of iOS autolinking (there is no podspec / iOS implementation).
+module.exports = {
+  dependency: {
+    platforms: {
+      ios: null,
+    },
+  },
+};

package/scripts/deploy-release.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+#
+# Build and install a standalone RELEASE build of the example app.
+#
+# A release build embeds the JS bundle (assets/index.android.bundle) into the
+# APK, so the app runs WITHOUT Metro / a dev server. The JS bundler runs once
+# at build time; after install the app is fully self-contained.
+#
+# Usage:
+#   ./scripts/deploy-release.sh           # build, install on the connected device, launch
+#   ./scripts/deploy-release.sh --build   # build the APK only (no install)
+#   ./scripts/deploy-release.sh --no-launch
+#   DEVICE=192.168.1.50:5555 ./scripts/deploy-release.sh   # target a specific adb device
+#
+# Environment overrides (auto-detected if unset):
+#   JAVA_HOME      - JDK 17 (RN 0.85 / Gradle 8.13 require JDK 17-21)
+#   ANDROID_HOME   - Android SDK location
+#   NODE_BIN       - directory containing a Node >= 20 binary (RN 0.85 metro needs it)
+#
+set -euo pipefail
+
+APP_ID="dev.react_native_web_serial_api.example"
+MAIN_ACTIVITY="${APP_ID}/.MainActivity"
+
+# Resolve paths relative to this script so it works from any CWD.
+# This script lives in <repo>/scripts; the buildable app is in <repo>/example
+# (the repo-root android/ is the library module and has no gradlew).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+EXAMPLE_DIR="$REPO_ROOT/example"
+ANDROID_DIR="$EXAMPLE_DIR/android"
+APK="$ANDROID_DIR/app/build/outputs/apk/release/app-release.apk"
+
+# --- arg parsing ---------------------------------------------------------
+DO_INSTALL=1
+DO_LAUNCH=1
+for arg in "$@"; do
+  case "$arg" in
+    --build)     DO_INSTALL=0; DO_LAUNCH=0 ;;
+    --no-launch) DO_LAUNCH=0 ;;
+    -h|--help)   grep '^#' "$0" | grep -v '^#!' | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "Unknown option: $arg" >&2; exit 1 ;;
+  esac
+done
+
+# --- toolchain auto-detection -------------------------------------------
+# JDK 17 (only override if the current java isn't already 17-21).
+if [ -z "${JAVA_HOME:-}" ]; then
+  for d in /usr/lib/jvm/java-17-openjdk-amd64 /usr/lib/jvm/java-21-openjdk-amd64 \
+           /usr/lib/jvm/temurin-17-jdk-amd64; do
+    [ -d "$d" ] && export JAVA_HOME="$d" && break
+  done
+fi
+[ -n "${JAVA_HOME:-}" ] && echo "JAVA_HOME=$JAVA_HOME"
+
+# Android SDK.
+if [ -z "${ANDROID_HOME:-}" ]; then
+  for d in "$HOME/Android/Sdk" "$HOME/Library/Android/sdk" "${ANDROID_SDK_ROOT:-}"; do
+    [ -n "$d" ] && [ -d "$d" ] && export ANDROID_HOME="$d" && break
+  done
+fi
+if [ -z "${ANDROID_HOME:-}" ]; then
+  echo "ERROR: Android SDK not found. Set ANDROID_HOME." >&2
+  exit 1
+fi
+echo "ANDROID_HOME=$ANDROID_HOME"
+export PATH="$ANDROID_HOME/platform-tools:$PATH"
+
+# Node >= 20 (RN 0.85 metro-config uses Array.prototype.toReversed()).
+need_node() { node -e 'process.exit(typeof [].toReversed==="function"?0:1)' 2>/dev/null; }
+if [ -n "${NODE_BIN:-}" ]; then
+  export PATH="$NODE_BIN:$PATH"
+fi
+if ! command -v node >/dev/null 2>&1 || ! need_node; then
+  # Try the newest nvm-managed Node >= 20.
+  if [ -d "$HOME/.nvm/versions/node" ]; then
+    for v in $(ls -1 "$HOME/.nvm/versions/node" | sort -Vr); do
+      if "$HOME/.nvm/versions/node/$v/bin/node" -e 'process.exit(typeof [].toReversed==="function"?0:1)' 2>/dev/null; then
+        export PATH="$HOME/.nvm/versions/node/$v/bin:$PATH"
+        break
+      fi
+    done
+  fi
+fi
+if ! need_node; then
+  echo "ERROR: need Node >= 20 (found $(node -v 2>/dev/null || echo none)). Set NODE_BIN." >&2
+  exit 1
+fi
+echo "node=$(node -v)"
+
+# --- pick adb device -----------------------------------------------------
+adb_target=()
+if [ -n "${DEVICE:-}" ]; then
+  adb connect "$DEVICE" >/dev/null 2>&1 || true
+  adb_target=(-s "$DEVICE")
+fi
+
+# --- build ---------------------------------------------------------------
+echo "==> Building release APK (embeds JS bundle)…"
+( cd "$ANDROID_DIR" && ./gradlew :app:assembleRelease )
+
+if [ ! -f "$APK" ]; then
+  echo "ERROR: APK not found at $APK" >&2
+  exit 1
+fi
+echo "==> Built: $APK ($(du -h "$APK" | cut -f1))"
+
+[ "$DO_INSTALL" -eq 1 ] || { echo "Build-only mode; done."; exit 0; }
+
+# --- install -------------------------------------------------------------
+echo "==> Installing on device…"
+# Capture output instead of piping into `grep -q`: under `set -o pipefail`,
+# grep closing the pipe early can make a successful install report failure.
+install_out="$(adb "${adb_target[@]}" install -r "$APK" 2>&1)" || true
+echo "$install_out"
+if ! grep -q "Success" <<<"$install_out"; then
+  echo "==> Reinstall failed (likely signature mismatch); uninstalling and retrying…"
+  adb "${adb_target[@]}" uninstall "$APP_ID" >/dev/null 2>&1 || true
+  adb "${adb_target[@]}" install "$APK"
+fi
+
+[ "$DO_LAUNCH" -eq 1 ] || { echo "Installed (not launched)."; exit 0; }
+
+# --- launch --------------------------------------------------------------
+echo "==> Launching $MAIN_ACTIVITY…"
+adb "${adb_target[@]}" shell am start -n "$MAIN_ACTIVITY" >/dev/null
+echo "==> Done. The app runs standalone (no Metro needed)."

package/src/NativeUsbSerial.ts

@@ -0,0 +1,124 @@
+import type {TurboModule} from 'react-native';
+import {TurboModuleRegistry} from 'react-native';
+
+// UsbSerialPort.ControlLine enum
+export type ControlLine = 'RTS' | 'CTS' | 'DTR' | 'DSR' | 'CD' | 'RI';
+
+// UsbSerialPort.FlowControl enum
+export type FlowControl =
+  | 'NONE'
+  | 'RTS_CTS'
+  | 'DTR_DSR'
+  | 'XON_XOFF'
+  | 'XON_XOFF_INLINE';
+
+export type PortId = {
+  deviceId: number;
+  portNumber: number;
+  usbVendorId: number;
+  usbProductId: number;
+};
+
+export type PortPickerLabels = {
+  titleSelectPort?: string;
+  titleNoPortsAvailable?: string;
+  messageNoPortsAvailable?: string;
+};
+
+export type PortFilter = {
+  usbVendorId?: number;
+  usbProductId?: number;
+};
+
+export interface Spec extends TurboModule {
+  // UsbSerialProber
+  findAllDrivers(): Promise<ReadonlyArray<PortId>>;
+
+  // Port picker dialog — shows available ports filtered by filters, requests permission for selected port
+  showPortPicker(
+    filters: ReadonlyArray<PortFilter>,
+    labels?: PortPickerLabels,
+  ): Promise<PortId>;
+
+  // UsbSerialPort lifecycle
+  open(
+    deviceId: number,
+    portNumber: number,
+    baudRate: number,
+    dataBits: number,
+    stopBits: number,
+    parity: number,
+  ): Promise<void>;
+  close(deviceId: number, portNumber: number): Promise<void>;
+  isOpen(deviceId: number, portNumber: number): boolean;
+
+  // Read/Write
+  write(
+    deviceId: number,
+    portNumber: number,
+    data: ReadonlyArray<number>,
+    timeout: number,
+  ): Promise<void>;
+  startReading(deviceId: number, portNumber: number): Promise<void>;
+  stopReading(deviceId: number, portNumber: number): Promise<void>;
+
+  // Parameters
+  setParameters(
+    deviceId: number,
+    portNumber: number,
+    baudRate: number,
+    dataBits: number,
+    stopBits: number,
+    parity: number,
+  ): Promise<void>;
+
+  // Control lines
+  setDTR(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+  setRTS(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+  getDTR(deviceId: number, portNumber: number): Promise<boolean>;
+  getRTS(deviceId: number, portNumber: number): Promise<boolean>;
+  getCD(deviceId: number, portNumber: number): Promise<boolean>;
+  getCTS(deviceId: number, portNumber: number): Promise<boolean>;
+  getDSR(deviceId: number, portNumber: number): Promise<boolean>;
+  getRI(deviceId: number, portNumber: number): Promise<boolean>;
+
+  getControlLines(
+    deviceId: number,
+    portNumber: number,
+  ): Promise<ReadonlyArray<string>>;
+  getSupportedControlLines(
+    deviceId: number,
+    portNumber: number,
+  ): Promise<ReadonlyArray<string>>;
+
+  // Flow control
+  setFlowControl(
+    deviceId: number,
+    portNumber: number,
+    flowControl: string,
+  ): Promise<void>;
+  getFlowControl(deviceId: number, portNumber: number): Promise<string>;
+  getSupportedFlowControl(
+    deviceId: number,
+    portNumber: number,
+  ): Promise<ReadonlyArray<string>>;
+
+  // Misc
+  setBreak(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+  purgeHwBuffers(
+    deviceId: number,
+    portNumber: number,
+    purgeWriteBuffers: boolean,
+    purgeReadBuffers: boolean,
+  ): Promise<void>;
+  getSerial(deviceId: number, portNumber: number): Promise<string>;
+
+  // USB permission
+  requestPermission(deviceId: number): Promise<boolean>;
+
+  // NativeEventEmitter
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.get<Spec>('NativeUsbSerial');

package/src/NativeUsbSerial.web.ts

@@ -0,0 +1,5 @@
+// On web there is no native USB-serial TurboModule. serial.web.ts delegates to
+// the browser's native navigator.serial, and UsbSerial.getUsbSerial() treats a
+// null module as "not available" — so this stub simply avoids touching
+// TurboModuleRegistry (which does not exist under react-native-web).
+export default null;

package/src/UsbSerial.ts

@@ -0,0 +1,305 @@
+import {NativeEventEmitter, NativeModules} from 'react-native';
+import NativeUsbSerial from './NativeUsbSerial';
+
+export type ControlLine = 'RTS' | 'CTS' | 'DTR' | 'DSR' | 'CD' | 'RI';
+export type FlowControl =
+  | 'NONE'
+  | 'RTS_CTS'
+  | 'DTR_DSR'
+  | 'XON_XOFF'
+  | 'XON_XOFF_INLINE';
+
+export type PortFilter = {
+  usbVendorId?: number;
+  usbProductId?: number;
+};
+
+export type PortPickerLabels = {
+  titleSelectPort?: string;
+  titleNoPortsAvailable?: string;
+  messageNoPortsAvailable?: string;
+};
+
+export type PortId = {
+  deviceId: number;
+  portNumber: number;
+  usbVendorId: number;
+  usbProductId: number;
+};
+
+export type DataEvent = {
+  deviceId: number;
+  portNumber: number;
+  data: number[];
+};
+
+export type ErrorEvent = {
+  deviceId: number;
+  portNumber: number;
+  error: string;
+};
+
+export type ConnectEvent = {
+  deviceId: number;
+  usbVendorId: number;
+  usbProductId: number;
+};
+
+export const Parity = {
+  NONE: 0,
+  ODD: 1,
+  EVEN: 2,
+  MARK: 3,
+  SPACE: 4,
+} as const;
+
+export const DataBits = {
+  FIVE: 5,
+  SIX: 6,
+  SEVEN: 7,
+  EIGHT: 8,
+} as const;
+
+export const StopBits = {
+  ONE: 1,
+  ONE_FIVE: 3,
+  TWO: 2,
+} as const;
+
+export type OpenOptions = {
+  baudRate: number;
+  dataBits?: number;
+  stopBits?: number;
+  parity?: number;
+};
+
+const DEFAULT_OPEN_OPTIONS: Required<Omit<OpenOptions, 'baudRate'>> = {
+  dataBits: DataBits.EIGHT,
+  stopBits: StopBits.ONE,
+  parity: Parity.NONE,
+};
+
+type Subscription = {remove: () => void};
+
+export class UsbSerialModule {
+  private readonly native: NonNullable<typeof NativeUsbSerial>;
+  private readonly emitter: NativeEventEmitter;
+
+  constructor() {
+    if (!NativeUsbSerial) {
+      throw new Error('NativeUsbSerial is not available');
+    }
+    this.native = NativeUsbSerial;
+    this.emitter = new NativeEventEmitter(NativeModules.NativeUsbSerial);
+  }
+
+  findAllDrivers(): Promise<ReadonlyArray<PortId>> {
+    return this.native.findAllDrivers() as Promise<ReadonlyArray<PortId>>;
+  }
+
+  showPortPicker(
+    filter: Readonly<PortFilter[]>,
+    labels?: PortPickerLabels,
+  ): Promise<PortId> {
+    return this.native.showPortPicker(filter, labels) as Promise<PortId>;
+  }
+
+  requestPermission(deviceId: number): Promise<boolean> {
+    return this.native.requestPermission(deviceId);
+  }
+
+  open(
+    deviceId: number,
+    portNumber: number,
+    options: OpenOptions,
+  ): Promise<void> {
+    const opts = {...DEFAULT_OPEN_OPTIONS, ...options};
+    return this.native.open(
+      deviceId,
+      portNumber,
+      opts.baudRate,
+      opts.dataBits,
+      opts.stopBits,
+      opts.parity,
+    );
+  }
+
+  close(deviceId: number, portNumber: number): Promise<void> {
+    return this.native.close(deviceId, portNumber);
+  }
+
+  isOpen(deviceId: number, portNumber: number): boolean {
+    return this.native.isOpen(deviceId, portNumber);
+  }
+
+  write(
+    deviceId: number,
+    portNumber: number,
+    data: number[],
+    timeout: number = 2000,
+  ): Promise<void> {
+    return this.native.write(deviceId, portNumber, data, timeout);
+  }
+
+  startReading(deviceId: number, portNumber: number): Promise<void> {
+    return this.native.startReading(deviceId, portNumber);
+  }
+
+  stopReading(deviceId: number, portNumber: number): Promise<void> {
+    return this.native.stopReading(deviceId, portNumber);
+  }
+
+  setParameters(
+    deviceId: number,
+    portNumber: number,
+    options: OpenOptions,
+  ): Promise<void> {
+    const opts = {...DEFAULT_OPEN_OPTIONS, ...options};
+    return this.native.setParameters(
+      deviceId,
+      portNumber,
+      opts.baudRate,
+      opts.dataBits,
+      opts.stopBits,
+      opts.parity,
+    );
+  }
+
+  setDTR(deviceId: number, portNumber: number, value: boolean): Promise<void> {
+    return this.native.setDTR(deviceId, portNumber, value);
+  }
+
+  setRTS(deviceId: number, portNumber: number, value: boolean): Promise<void> {
+    return this.native.setRTS(deviceId, portNumber, value);
+  }
+
+  getDTR(deviceId: number, portNumber: number): Promise<boolean> {
+    return this.native.getDTR(deviceId, portNumber);
+  }
+
+  getRTS(deviceId: number, portNumber: number): Promise<boolean> {
+    return this.native.getRTS(deviceId, portNumber);
+  }
+
+  getCD(deviceId: number, portNumber: number): Promise<boolean> {
+    return this.native.getCD(deviceId, portNumber);
+  }
+
+  getCTS(deviceId: number, portNumber: number): Promise<boolean> {
+    return this.native.getCTS(deviceId, portNumber);
+  }
+
+  getDSR(deviceId: number, portNumber: number): Promise<boolean> {
+    return this.native.getDSR(deviceId, portNumber);
+  }
+
+  getRI(deviceId: number, portNumber: number): Promise<boolean> {
+    return this.native.getRI(deviceId, portNumber);
+  }
+
+  getControlLines(
+    deviceId: number,
+    portNumber: number,
+  ): Promise<ControlLine[]> {
+    return this.native.getControlLines(deviceId, portNumber) as Promise<
+      ControlLine[]
+    >;
+  }
+
+  getSupportedControlLines(
+    deviceId: number,
+    portNumber: number,
+  ): Promise<ControlLine[]> {
+    return this.native.getSupportedControlLines(
+      deviceId,
+      portNumber,
+    ) as Promise<ControlLine[]>;
+  }
+
+  setFlowControl(
+    deviceId: number,
+    portNumber: number,
+    flowControl: FlowControl,
+  ): Promise<void> {
+    return this.native.setFlowControl(deviceId, portNumber, flowControl);
+  }
+
+  getFlowControl(deviceId: number, portNumber: number): Promise<FlowControl> {
+    return this.native.getFlowControl(
+      deviceId,
+      portNumber,
+    ) as Promise<FlowControl>;
+  }
+
+  getSupportedFlowControl(
+    deviceId: number,
+    portNumber: number,
+  ): Promise<FlowControl[]> {
+    return this.native.getSupportedFlowControl(deviceId, portNumber) as Promise<
+      FlowControl[]
+    >;
+  }
+
+  setBreak(
+    deviceId: number,
+    portNumber: number,
+    value: boolean,
+  ): Promise<void> {
+    return this.native.setBreak(deviceId, portNumber, value);
+  }
+
+  purgeHwBuffers(
+    deviceId: number,
+    portNumber: number,
+    purgeWriteBuffers: boolean,
+    purgeReadBuffers: boolean,
+  ): Promise<void> {
+    return this.native.purgeHwBuffers(
+      deviceId,
+      portNumber,
+      purgeWriteBuffers,
+      purgeReadBuffers,
+    );
+  }
+
+  getSerial(deviceId: number, portNumber: number): Promise<string> {
+    return this.native.getSerial(deviceId, portNumber);
+  }
+
+  onData(listener: (event: DataEvent) => void): Subscription {
+    return this.emitter.addListener(
+      'data',
+      listener as (...args: readonly Record<string, unknown>[]) => unknown,
+    );
+  }
+
+  onError(listener: (event: ErrorEvent) => void): Subscription {
+    return this.emitter.addListener(
+      'error',
+      listener as (...args: readonly Record<string, unknown>[]) => unknown,
+    );
+  }
+
+  onConnect(listener: (event: ConnectEvent) => void): Subscription {
+    return this.emitter.addListener(
+      'connect',
+      listener as (...args: readonly Record<string, unknown>[]) => unknown,
+    );
+  }
+
+  onDisconnect(listener: (event: ConnectEvent) => void): Subscription {
+    return this.emitter.addListener(
+      'disconnect',
+      listener as (...args: readonly Record<string, unknown>[]) => unknown,
+    );
+  }
+}
+
+let instance: UsbSerialModule | null = null;
+
+export function getUsbSerial(): UsbSerialModule {
+  if (!instance) {
+    instance = new UsbSerialModule();
+  }
+  return instance;
+}