@senxor/capacitor-serial

@senxor/capacitor-serial is the Capacitor transport for Senxor.js. It lets you discover and connect Senxor devices from a Capacitor application (for example, an Android app running inside a WebView) and gives you ready-to-use Senxor instances from @senxor/core.

Use this package together with:

• @senxor/core – provides the Senxor device controller and processing helpers.
• capacitor-serial-plugin – a native Capacitor plugin that exposes USB serial ports.

Installation

In your Capacitor app project, install the JavaScript dependencies:

pnpm add @senxor/core @senxor/capacitor-serial
pnpm add capacitor-serial-plugin

Then run Capacitor sync so the native project picks up the plugin:

npx cap sync

Android configuration

On Android you must ensure that:

• The JitPack Maven repository is available so the native plugin can be resolved.
• USB permissions and device filters are correctly declared in your manifest.

JitPack repository

In your Android project-level Gradle file (for example, android/build.gradle in a standard Capacitor project), add the JitPack repository to the list of repositories:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

If your project uses dependencyResolutionManagement instead of allprojects, add the same maven { url 'https://jitpack.io' } entry to the appropriate repositories block.

USB permissions and filters

Your Android manifest must declare USB permissions and, typically, a device filter so that the system knows which USB devices should trigger your app. A minimal configuration looks similar to:

<uses-permission android:name="android.permission.USB_PERMISSION" />
<uses-feature
    android:name="android.hardware.usb.host"
    android:required="true" />

Inside your main activity, you can also declare an intent filter and metadata for USB device attachment, for example:

<activity
    android:name=".MainActivity"
    android:exported="true">

    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <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>

The exact requirements may vary depending on the version of capacitor-serial-plugin. Always refer to that plugin's documentation for the most up-to-date Android configuration details and sample device_filter definitions.

Capacitor Configuration

In your Capacitor configuration file (for example, capacitor.config.ts), you need to configure the UsbSerial plugin to use the correct data encoding and buffer size. For example:

export default {
  plugins: {
    UsbSerial: {
      dataEncoding: "base64",
      dataBufferSize: 8192,
    },
  },
};

Quick start

Once your Capacitor project is configured and the native plugin is installed, you can use @senxor/capacitor-serial from your web code to discover Senxor devices and work with Senxor instances.

import {
  listCapacitorSerialSenxors,
  onCapacitorSerialSenxorConnect,
} from "@senxor/capacitor-serial";
import {
  nomalizeSenxorData,
  applyColorMap,
  type SenxorData,
} from "@senxor/core";

async function initDevices() {
  const devices = await listCapacitorSerialSenxors();

  for (const senxor of devices) {
    await senxor.open();

    senxor.onError((error) => {
      console.error("Senxor error:", error);
    });

    senxor.onData((data: SenxorData) => {
      const normalized = nomalizeSenxorData(data);
      const image = applyColorMap(normalized, "rainbow2");
      // Render `image` to a canvas or process it further
    });

    await senxor.startStreaming();
  }

  // Optionally, listen for new devices being connected while the app is running
  onCapacitorSerialSenxorConnect(async (senxor) => {
    await senxor.open();
    await senxor.startStreaming();
  });
}

The Senxor instances you receive here behave the same way as in other transports. For more details about the Senxor API and available processors, see the @senxor/core README.

API

listCapacitorSerialSenxors()

import { listCapacitorSerialSenxors } from "@senxor/capacitor-serial";

const devices = await listCapacitorSerialSenxors();

Returns an array of Senxor instances for Senxor devices the native serial layer currently reports as connected. Use this at app startup or whenever you want to refresh the device list. Call open() on each instance when you are ready to talk to the device.

onCapacitorSerialSenxorConnect(listener)

import { onCapacitorSerialSenxorConnect } from "@senxor/capacitor-serial";

const unsubscribe = onCapacitorSerialSenxorConnect((senxor) => {
  // A new Senxor device has been connected
});

// Later, to stop listening:
unsubscribe();

Registers a listener that runs when a new compatible Senxor device is attached while your app is running. The listener receives a Senxor instance you can open() and stream from. Returns an unsubscribe function that removes the listener.

Working with @senxor/core

@senxor/capacitor-serial focuses on integrating with the native Capacitor serial plugin and returning Senxor instances. After you obtain a Senxor from this package, you will typically:

• Use open(), close(), startStreaming(), and stopStreaming() to control the device session.
• Subscribe to onData and onError to receive frames and handle errors.
• Use processors from @senxor/core (such as nomalizeSenxorData, createGrayScaleImageData, and applyColorMap) to normalize and visualize frames.

For a full description of the Senxor class, error types, and processing helpers, see the @senxor/core README.

Example project

This repository includes a Capacitor example application that demonstrates how to:

• Configure the Android project with the required repositories and USB permissions.
• Install and sync the capacitor-serial-plugin.
• Discover and stream from Senxor devices inside a Capacitor WebView.

Look for the examples/capacitor-serial directory in the Senxor.js repository for a complete, runnable example built on top of @senxor/capacitor-serial and @senxor/core.