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

package/android/build.gradle

@@ -44,6 +44,13 @@ android {
     sourceCompatibility JavaVersion.VERSION_17
     targetCompatibility JavaVersion.VERSION_17
   }
+
+  testOptions {
+    unitTests {
+      includeAndroidResources = true
+      returnDefaultValues = true
+    }
+  }
 }
 
 repositories {
@@ -59,4 +66,11 @@ dependencies {
   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"
+
+  // JVM unit tests. Robolectric provides an Android runtime so the TurboModule
+  // (which registers/unregisters BroadcastReceivers, talks to UsbManager, etc.)
+  // can be exercised without a device or emulator.
+  testImplementation "junit:junit:4.13.2"
+  testImplementation "org.robolectric:robolectric:4.14.1"
+  testImplementation "org.mockito:mockito-core:5.14.2"
 }

package/android/src/main/java/dev/webserialapi/NativeUsbSerialModule.java

@@ -31,9 +31,12 @@ import com.facebook.react.bridge.BaseActivityEventListener;
 
 import java.util.ArrayList;
 import java.util.EnumSet;
-import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicInteger;
 
 public class NativeUsbSerialModule extends NativeUsbSerialSpec {
 
@@ -43,17 +46,30 @@ public class NativeUsbSerialModule extends NativeUsbSerialSpec {
 
     private final UsbManager usbManager;
 
+    // These maps are mutated from several threads — TurboModule calls (native
+    // modules thread), the broadcast receivers (main thread) and the
+    // SerialInputOutputManager listener (its own IO thread) — so they must be
+    // concurrent to avoid corruption / ConcurrentModificationException.
     // key: "deviceId:portNumber"
-    private final Map<String, UsbSerialPort> openPorts = new HashMap<>();
-    private final Map<String, UsbDeviceConnection> openConnections = new HashMap<>();
-    private final Map<String, SerialInputOutputManager> ioManagers = new HashMap<>();
+    private final Map<String, UsbSerialPort> openPorts = new ConcurrentHashMap<>();
+    private final Map<String, UsbDeviceConnection> openConnections = new ConcurrentHashMap<>();
+    private final Map<String, SerialInputOutputManager> ioManagers = new ConcurrentHashMap<>();
 
-    // key: requestCode
-    private final Map<Integer, Promise> pendingPermissions = new HashMap<>();
-    private int nextRequestCode = 0;
+    // key: requestCode. requestPermission() is reachable from both the native
+    // modules thread (direct JS call) and the main thread (onActivityResult ->
+    // requestPermission), so the counter must be atomic to avoid two callers
+    // colliding on a request code and clobbering each other's pending promise.
+    private final Map<Integer, Promise> pendingPermissions = new ConcurrentHashMap<>();
+    private final AtomicInteger nextRequestCode = new AtomicInteger(0);
+
+    // Resumes blocking USB work (open/setParameters) off the main thread when a
+    // permission grant arrives on the broadcast-receiver (main) thread.
+    private final ExecutorService backgroundExecutor = Executors.newSingleThreadExecutor();
 
     private static final int PORT_PICKER_REQUEST_CODE = 0xAB8465;
-    private Promise pendingPortPickerPromise = null;
+    // Written from showPortPicker (module thread), read/cleared from
+    // onActivityResult (main thread) — volatile for cross-thread visibility.
+    private volatile Promise pendingPortPickerPromise = null;
 
     private final ActivityEventListener activityEventListener = new BaseActivityEventListener() {
         @Override
@@ -177,7 +193,41 @@ public class NativeUsbSerialModule extends NativeUsbSerialSpec {
         IntentFilter usbFilter = new IntentFilter();
         usbFilter.addAction(UsbManager.ACTION_USB_DEVICE_ATTACHED);
         usbFilter.addAction(UsbManager.ACTION_USB_DEVICE_DETACHED);
-        reactContext.registerReceiver(usbStateReceiver, usbFilter);
+        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.TIRAMISU) {
+            reactContext.registerReceiver(usbStateReceiver, usbFilter, Context.RECEIVER_NOT_EXPORTED);
+        } else {
+            reactContext.registerReceiver(usbStateReceiver, usbFilter);
+        }
+    }
+
+    /**
+     * Release everything acquired in the constructor and during the module's
+     * life. Without this, every JS reload / context teardown leaks the three
+     * registered receivers (kept alive against a dead ReactApplicationContext)
+     * and any open USB ports — and stacks duplicate connect/disconnect/data
+     * events from the orphaned receivers.
+     */
+    @Override
+    public void invalidate() {
+        ReactApplicationContext ctx = getReactApplicationContext();
+        try { ctx.unregisterReceiver(permissionReceiver); } catch (Exception ignored) {}
+        try { ctx.unregisterReceiver(usbStateReceiver); } catch (Exception ignored) {}
+        try { ctx.removeActivityEventListener(activityEventListener); } catch (Exception ignored) {}
+
+        for (String key : new ArrayList<>(ioManagers.keySet())) {
+            SerialInputOutputManager ioManager = ioManagers.remove(key);
+            try { if (ioManager != null) ioManager.stop(); } catch (Exception ignored) {}
+        }
+        for (String key : new ArrayList<>(openPorts.keySet())) {
+            UsbSerialPort port = openPorts.remove(key);
+            UsbDeviceConnection connection = openConnections.remove(key);
+            try { if (port != null) port.close(); } catch (Exception ignored) {}
+            try { if (connection != null) connection.close(); } catch (Exception ignored) {}
+        }
+
+        backgroundExecutor.shutdown();
+
+        super.invalidate();
     }
 
     // Helper to avoid implementing all Promise methods in anonymous classes
@@ -294,7 +344,11 @@ public class NativeUsbSerialModule extends NativeUsbSerialSpec {
                     public void onResolve(Object value) {
                         Boolean granted = (Boolean) value;
                         if (granted != null && granted) {
-                            open(fDeviceId, fPortNumber, fBaudRate, fDataBits, fStopBits, fParity, promise);
+                            // onResolve runs on the permission broadcast receiver's
+                            // (main) thread; openDevice()/port.open() do blocking USB
+                            // control transfers, so resume off the main thread.
+                            backgroundExecutor.execute(() ->
+                                open(fDeviceId, fPortNumber, fBaudRate, fDataBits, fStopBits, fParity, promise));
                         } else {
                             promise.reject("PERMISSION_DENIED", "USB permission denied");
                         }
@@ -640,6 +694,7 @@ public class NativeUsbSerialModule extends NativeUsbSerialSpec {
 
     @Override
     public void requestPermission(double deviceId, Promise promise) {
+        int requestCode = -1;
         try {
             UsbSerialDriver driver = findDriver((int) deviceId);
             if (driver == null) {
@@ -651,7 +706,7 @@ public class NativeUsbSerialModule extends NativeUsbSerialSpec {
                 return;
             }
 
-            int requestCode = nextRequestCode++;
+            requestCode = nextRequestCode.getAndIncrement();
             pendingPermissions.put(requestCode, promise);
 
             Intent intent = new Intent(ACTION_USB_PERMISSION);
@@ -671,6 +726,8 @@ public class NativeUsbSerialModule extends NativeUsbSerialSpec {
             );
             usbManager.requestPermission(driver.getDevice(), permissionIntent);
         } catch (Exception e) {
+            // Don't leave an orphaned pending promise behind if dispatch failed.
+            if (requestCode != -1) pendingPermissions.remove(requestCode);
             promise.reject("REQUEST_PERMISSION_ERROR", e.getMessage(), e);
         }
     }
@@ -720,6 +777,12 @@ public class NativeUsbSerialModule extends NativeUsbSerialSpec {
         } catch (ActivityNotFoundException e) {
             pendingPortPickerPromise = null;
             promise.reject("ACTIVITY_NOT_FOUND", e.getMessage(), e);
+        } catch (Exception e) {
+            // Any other failure to launch must also clear the pending slot,
+            // otherwise the picker is wedged forever (every future call rejects
+            // with PICKER_ALREADY_OPEN) and this promise never settles.
+            pendingPortPickerPromise = null;
+            promise.reject("PICKER_LAUNCH_FAILED", e.getMessage(), e);
         }
     }
 

package/android/src/main/java/dev/webserialapi/PortPickerActivity.java

@@ -96,41 +96,64 @@ public class PortPickerActivity extends AppCompatActivity {
             return drivers;
         }
 
-        // Guard against mismatched array lengths to avoid ArrayIndexOutOfBoundsException
-        int filterCount = Math.min(filterVendorIds.length,
-                filterProductIds != null ? filterProductIds.length : 0);
-
         List<UsbSerialDriver> filtered = new ArrayList<>();
         for (UsbSerialDriver driver : drivers) {
             int vid = driver.getDevice().getVendorId();
             int pid = driver.getDevice().getProductId();
-            for (int i = 0; i < filterCount; i++) {
-                boolean vidMatch = vid == filterVendorIds[i];
-                boolean pidMatch = filterProductIds[i] == -1 || pid == filterProductIds[i];
-                if (vidMatch && pidMatch) {
-                    filtered.add(driver);
-                    break;
-                }
+            if (matchesAnyFilter(vid, pid, filterVendorIds, filterProductIds)) {
+                filtered.add(driver);
             }
         }
         return filtered;
     }
 
+    /**
+     * Whether a device with the given vendor/product id matches any of the
+     * parallel {@code vendorIds}/{@code productIds} filter arrays. A
+     * {@code productId} of -1 is a vendor-only wildcard. Mismatched array
+     * lengths are tolerated (the shorter length wins), and empty/no filters
+     * match everything. Pure and Android-free so it can be unit tested directly.
+     */
+    static boolean matchesAnyFilter(int vid, int pid, int[] vendorIds, int[] productIds) {
+        if (vendorIds == null || vendorIds.length == 0) {
+            return true;
+        }
+        // Guard against mismatched array lengths to avoid ArrayIndexOutOfBoundsException
+        int filterCount = Math.min(vendorIds.length,
+                productIds != null ? productIds.length : 0);
+        for (int i = 0; i < filterCount; i++) {
+            boolean vidMatch = vid == vendorIds[i];
+            boolean pidMatch = productIds[i] == -1 || pid == productIds[i];
+            if (vidMatch && pidMatch) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     private void showPickerDialog() {
-        PortPickerDialogFragment dialog = PortPickerDialogFragment.newInstance(
-                this,
-                getFilteredDrivers(),
-                resolve(titleSelectPort,        DEFAULT_TITLE_SELECT_PORT),
-                resolve(titleNoPortsAvailable,  DEFAULT_TITLE_NO_PORTS_AVAILABLE),
-                resolve(messageNoPortsAvailable, DEFAULT_MESSAGE_NO_PORTS_AVAILABLE)
-        );
-        dialog.show(getSupportFragmentManager(), TAG_PICKER_DIALOG);
+        new PortPickerDialogFragment().show(getSupportFragmentManager(), TAG_PICKER_DIALOG);
     }
 
     private static String resolve(String override, String defaultValue) {
         return (override != null && !override.isEmpty()) ? override : defaultValue;
     }
 
+    // Resolved labels, read by the (possibly recreated) dialog fragment. The
+    // backing fields are restored from getIntent() in onCreate, so these survive
+    // a configuration change such as rotation.
+    String resolvedTitleSelectPort() {
+        return resolve(titleSelectPort, DEFAULT_TITLE_SELECT_PORT);
+    }
+
+    String resolvedTitleNoPortsAvailable() {
+        return resolve(titleNoPortsAvailable, DEFAULT_TITLE_NO_PORTS_AVAILABLE);
+    }
+
+    String resolvedMessageNoPortsAvailable() {
+        return resolve(messageNoPortsAvailable, DEFAULT_MESSAGE_NO_PORTS_AVAILABLE);
+    }
+
     /** Called by the DialogFragment when the user selects a port. */
     void onPortSelected(UsbDevice device, int portNumber) {
         Intent result = new Intent();
@@ -153,42 +176,28 @@ public class PortPickerActivity extends AppCompatActivity {
     }
 
     // -------------------------------------------------------------------------
-    // Static DialogFragment – survives configuration changes such as rotation
+    // Static DialogFragment – survives configuration changes such as rotation.
+    // It deliberately keeps NO transient state of its own: on every (re)creation
+    // it rebuilds the driver list and labels from the host activity, whose own
+    // state is restored from its Intent. Stashing the non-Parcelable driver list
+    // and an Activity reference on the fragment (as before) loses them on the
+    // recreation that rotation triggers, leaving an empty / dead dialog.
     // -------------------------------------------------------------------------
     public static class PortPickerDialogFragment extends DialogFragment {
 
-        // Not passed via Bundle argument because UsbSerialDriver is not Serializable/Parcelable
-        private List<UsbSerialDriver> drivers;
-        private PortPickerActivity    host;
-        private String                titleSelectPort;
-        private String                titleNoPortsAvailable;
-        private String                messageNoPortsAvailable;
-
-        static PortPickerDialogFragment newInstance(
-                PortPickerActivity host,
-                List<UsbSerialDriver> drivers,
-                String titleSelectPort,
-                String titleNoPortsAvailable,
-                String messageNoPortsAvailable) {
-            PortPickerDialogFragment f = new PortPickerDialogFragment();
-            f.host             = host;
-            f.drivers          = drivers;
-            f.titleSelectPort        = titleSelectPort;
-            f.titleNoPortsAvailable  = titleNoPortsAvailable;
-            f.messageNoPortsAvailable = messageNoPortsAvailable;
-            return f;
-        }
-
         @Override
         public android.app.Dialog onCreateDialog(Bundle savedInstanceState) {
+            PortPickerActivity act = (PortPickerActivity) requireActivity();
             Context ctx = requireContext();
 
+            List<UsbSerialDriver> drivers = act.getFilteredDrivers();
+
             if (drivers == null || drivers.isEmpty()) {
                 return new AlertDialog.Builder(ctx)
-                        .setTitle(titleNoPortsAvailable)
-                        .setMessage(messageNoPortsAvailable)
-                        .setPositiveButton(android.R.string.ok, (d, w) -> cancelAndFinish())
-                        .setOnCancelListener(d -> cancelAndFinish())
+                        .setTitle(act.resolvedTitleNoPortsAvailable())
+                        .setMessage(act.resolvedMessageNoPortsAvailable())
+                        .setPositiveButton(android.R.string.ok, (d, w) -> act.onPickerCancelled())
+                        .setOnCancelListener(d -> act.onPickerCancelled())
                         .create();
             }
 
@@ -215,21 +224,14 @@ public class PortPickerActivity extends AppCompatActivity {
             }
 
             return new AlertDialog.Builder(ctx)
-                    .setTitle(titleSelectPort)
-                    .setItems(labels.toArray(new String[0]), (d, which) -> {
-                        if (host != null) {
-                            host.onPortSelected(
+                    .setTitle(act.resolvedTitleSelectPort())
+                    .setItems(labels.toArray(new String[0]), (d, which) ->
+                            act.onPortSelected(
                                     flatDrivers.get(which).getDevice(),
-                                    flatPortNumbers.get(which));
-                        }
-                    })
-                    .setNegativeButton(android.R.string.cancel, (d, w) -> cancelAndFinish())
-                    .setOnCancelListener(d -> cancelAndFinish())
+                                    flatPortNumbers.get(which)))
+                    .setNegativeButton(android.R.string.cancel, (d, w) -> act.onPickerCancelled())
+                    .setOnCancelListener(d -> act.onPickerCancelled())
                     .create();
         }
-
-        private void cancelAndFinish() {
-            if (host != null) host.onPickerCancelled();
-        }
     }
 }

package/bin/expose-serial.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * expose-serial-websocket — bridge a local serial port to a WebSocket so a
+ * browser / React Native app can drive it through `WebSocketSerialTransport`.
+ *
+ * This is a thin Node wrapper: argument parsing and the per-connection wiring
+ * live in the package's built `websocket/bridge` module (unit-tested with
+ * fakes); here we just supply the real `serialport` and `ws` objects.
+ */
+
+let bridge;
+try {
+  bridge = require('../lib/commonjs/websocket/bridge.js');
+} catch (_e) {
+  console.error(
+    'Could not load the built bridge module. Build the package first ' +
+      '(npm run prepare) and try again.',
+  );
+  process.exit(1);
+}
+const {attachBridge, parseBridgeArgs, USAGE} = bridge;
+
+function requireOrExit(name) {
+  try {
+    return require(name);
+  } catch (_e) {
+    console.error(
+      `Missing optional dependency "${name}". Install it on this host:\n` +
+        `  npm install ${name}\n`,
+    );
+    process.exit(1);
+  }
+}
+
+function main() {
+  const args = parseBridgeArgs(process.argv.slice(2), process.env);
+
+  if (args.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (!args.port) {
+    console.error('Error: --port <path> is required.\n');
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  const {SerialPort} = requireOrExit('serialport');
+  const {WebSocketServer} = requireOrExit('ws');
+
+  const parseHexMaybe = value => {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === 'string') {
+      const trimmed = value.trim();
+      if (!trimmed) return undefined;
+      const base = /^0x/i.test(trimmed) ? 16 : 16;
+      const parsed = Number.parseInt(trimmed.replace(/^0x/i, ''), base);
+      if (Number.isFinite(parsed)) {
+        return parsed;
+      }
+    }
+    return undefined;
+  };
+
+  const normalizeInfo = info => {
+    if (!info || typeof info !== 'object') {
+      return null;
+    }
+    const usbVendorId = parseHexMaybe(info.vendorId ?? info.usbVendorId);
+    const usbProductId = parseHexMaybe(info.productId ?? info.usbProductId);
+    const serialNumber =
+      typeof info.serialNumber === 'string' ? info.serialNumber : undefined;
+    if (
+      usbVendorId === undefined &&
+      usbProductId === undefined &&
+      serialNumber === undefined
+    ) {
+      return null;
+    }
+    return {usbVendorId, usbProductId, serialNumber};
+  };
+
+  let cachedPortInfo = null;
+
+  const refreshPortInfo = async () => {
+    try {
+      const list = await SerialPort.list();
+      const match = list.find(p => p.path === args.port);
+      cachedPortInfo = normalizeInfo(match);
+    } catch {
+      // ignore metadata refresh failures
+    }
+  };
+
+  const serial = new SerialPort({path: args.port, baudRate: args.baudRate});
+  // Kick off metadata discovery in parallel; getPortInfo can still fall back to
+  // fields directly exposed by the opened serial instance.
+  void refreshPortInfo();
+
+  const getPortInfo = () => {
+    return (
+      cachedPortInfo ??
+      normalizeInfo({
+        vendorId: serial.vendorId,
+        productId: serial.productId,
+        serialNumber: serial.serialNumber,
+      })
+    );
+  };
+
+  let serialClosed = false;
+
+  serial.on('error', err => {
+    console.error(`serial error: ${err.message}`);
+    if (
+      err.message.includes('Disconnected') ||
+      err.message.includes('No such file')
+    ) {
+      serialClosed = true;
+      if (active) {
+        active.close(1011, 'Serial port disconnected');
+        active = null;
+      }
+      process.exit(1); // or attempt to reopen
+    }
+  });
+  serial.on('close', () => {
+    console.error('Serial port closed unexpectedly');
+    serialClosed = true;
+    if (active) {
+      active.close(1011, 'Serial port closed');
+      active = null;
+    }
+    process.exit(1);
+  });
+
+  const wss = new WebSocketServer({host: args.host, port: args.wsPort});
+  let active = null;
+  let detachCurrent = null;
+
+  wss.on('connection', ws => {
+    if (active) {
+      ws.close(1013, 'serial port already in use');
+      return;
+    }
+    if (!serial.isOpen || serialClosed) {
+      ws.close(1011, 'serial port not available');
+      return;
+    }
+    active = ws;
+    console.log('client connected');
+    const detach = attachBridge(serial, ws, {
+      log: m => console.error(m),
+      portInfo: getPortInfo,
+    });
+    detachCurrent = detach;
+
+    ws.on('close', () => {
+      if (detachCurrent) detachCurrent();
+      if (active === ws) active = null;
+      detachCurrent = null;
+      console.log('client disconnected');
+    });
+  });
+
+  wss.on('listening', () => {
+    console.log(
+      `Serial port ${args.port} exposed on ws://${args.host}:${args.wsPort}`,
+    );
+    if (args.host === '0.0.0.0' || args.allowRemote) {
+      console.warn(
+        '⚠  Bound to a non-localhost address — your serial port is reachable ' +
+          'from the network. Only do this on trusted networks.',
+      );
+    }
+  });
+  wss.on('error', err => {
+    console.error(`WebSocket server error: ${err.message}`);
+    process.exit(1);
+  });
+
+  let shuttingDown = false;
+  const shutdown = () => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    console.log('\nshutting down…');
+    try {
+      wss.close();
+    } catch (_e) {}
+    try {
+      if (serial.isOpen) {
+        serial.close();
+      }
+    } catch (_e) {}
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main();

package/lib/commonjs/UsbSerial.js

@@ -161,7 +161,7 @@ function getUsbSerial() {
 
 /**
  * Override the transport returned by {@link getUsbSerial}. Pass a
- * {@link SerialTransport} (e.g. a `VirtualSerialTransport`) to make the
+ * {@link SerialTransport} (e.g. an `InMemorySerialTransport`) to make the
  * singleton `serial` instance — and any `new Serial()` created without an
  * explicit transport — talk to it instead of real hardware. Pass `null` to
  * clear the override.