usb-serial-plugin

This plugin can be used for reading data from other device over the usb channel

This project is forked from capacitor-plugin-usb-serial

Install

npm install capacitor-serial-plugin
npx cap sync

Android

build.gradle

This plugin uses usb-serial-for-android library. You need to add the maven repository to your build.gradle file.

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

AndroidManifest.xml

This plugin requires the following feature:

<manifest ...>
    <uses-feature android:name="android.hardware.usb.host" />
    ...
</manifest>

See the Android Documentation for more information.

Configuration

| Prop | Type | Description | Default | Since | | -------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----- | | dataEncoding | 'utf8' | 'base64' | Encoding format for serial data. - 'utf8': Return data as UTF-8 decoded string (default) - 'base64': Return data as base64 encoded string | 'utf8' | 1.0.0 | | dataThrottleMs | number | Data throttle interval in milliseconds for aggregating received data. Multiple data packets received within this interval will be batched together. Helps improve performance when receiving high-frequency data. | 50 | 1.0.0 | | dataBufferSize | number | Maximum buffer size in bytes before flushing data. When the buffer reaches this size, data is sent immediately without waiting for throttle interval. | 4096 | 1.0.0 |

Examples

In capacitor.config.json:

{
  "plugins": {
    "UsbSerial": {
      "dataEncoding": "base64",
      "dataThrottleMs": 100,
      "dataBufferSize": 8192
    }
  }
}

In capacitor.config.ts:

/// <reference types="capacitor-serial-plugin" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    UsbSerial: {
      dataEncoding: "base64",
      dataThrottleMs: 100,
      dataBufferSize: 8192,
    },
  },
};

export default config;

API

• connectedDevices()
• openSerial(...)
• closeSerial()
• readSerial()
• writeSerial(...)
• addListener('log', ...)
• addListener('connected', ...)
• addListener('attached', ...)
• addListener('detached', ...)
• addListener('data', ...)
• addListener('error', ...)
• getDataEncoding()
• removeAllListeners()
• Interfaces

connectedDevices()

connectedDevices() => Promise<{ devices: UsbSerialDevice[]; }>

Get a list of currently connected USB serial devices.

Returns: Promise<{ devices: UsbSerialDevice[]; }>

openSerial(...)

openSerial(options: UsbSerialOptions) => Promise<void>

Open a serial connection to a USB device.

| Param | Type | Description | | ------------- | ------------------------------------------------------------- | --------------------------- | | options | UsbSerialOptions | - Serial connection options |

closeSerial()

closeSerial() => Promise<void>

Close the current serial connection.

readSerial()

readSerial() => Promise<{ data: string; }>

Reads data from the serial port.

Returns: Promise<{ data: string; }>

writeSerial(...)

writeSerial(options: { data: string; }) => Promise<void>

Writes data to the serial port.

| Param | Type | Description | | ------------- | ------------------------------ | ------------------- | | options | { data: string; } | - The write options |

addListener('log', ...)

addListener(eventName: 'log', listenerFunc: (data: { text: string; tag: string; }) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for log messages from the plugin.

| Param | Type | Description | | ------------------ | -------------------------------------------------------------- | --------------------------------------------------------- | | eventName | 'log' | - Must be 'log' | | listenerFunc | (data: { text: string; tag: string; }) => void | - Callback function called when log messages are received |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

addListener('connected', ...)

addListener(eventName: 'connected', listenerFunc: (data: UsbSerialDevice) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for device connection events.

| Param | Type | Description | | ------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------- | | eventName | 'connected' | - Must be 'connected' | | listenerFunc | (data: UsbSerialDevice) => void | - Callback function called when a device connects |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

addListener('attached', ...)

addListener(eventName: 'attached', listenerFunc: (data: UsbSerialDevice) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for device attachment events.

| Param | Type | Description | | ------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------------- | | eventName | 'attached' | - Must be 'attached' | | listenerFunc | (data: UsbSerialDevice) => void | - Callback function called when a device is attached |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

addListener('detached', ...)

addListener(eventName: 'detached', listenerFunc: (data: UsbSerialDevice) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for device detachment events.

| Param | Type | Description | | ------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------------- | | eventName | 'detached' | - Must be 'detached' | | listenerFunc | (data: UsbSerialDevice) => void | - Callback function called when a device is detached |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

addListener('data', ...)

addListener(eventName: 'data', listenerFunc: (data: { data: string; }) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for incoming serial data.

| Param | Type | Description | | ------------------ | ------------------------------------------------- | ------------------------------------------------ | | eventName | 'data' | - Must be 'data' | | listenerFunc | (data: { data: string; }) => void | - Callback function called when data is received |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

addListener('error', ...)

addListener(eventName: 'error', listenerFunc: (data: { error: string; }) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for error events from the serial communication.

| Param | Type | Description | | ------------------ | -------------------------------------------------- | -------------------------------------------- | | eventName | 'error' | - Must be 'error' | | listenerFunc | (data: { error: string; }) => void | - Callback function called when errors occur |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

getDataEncoding()

getDataEncoding() => Promise<{ encoding: 'utf8' | 'base64'; }>

Get the current data encoding configuration.

Returns: Promise<{ encoding: 'utf8' | 'base64'; }>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for all events.

Interfaces

UsbSerialDevice

| Prop | Type | | ---------------------- | ------------------- | | deviceId | number | | vendorId | number | | productId | number | | deviceName | string | | manufacturerName | string | | serialNumber | string |

UsbSerialOptions

| Prop | Type | | -------------- | ----------------------------------------------------------- | | deviceId | number | | portNum | number | | baudRate | number | | dataBits | number | | stopBits | number | | parity | 'none' | 'odd' | 'even' | 'mark' | 'space' | | dtr | boolean | | rts | boolean |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |