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

• Install
• Android
  • build.gradle
  • AndroidManifest.xml
• Configuration
  • Examples
• API
  • connectedDevices()
  • openSerial(...)
  • closeSerial()
  • readSerial()
  • writeSerial(...)
  • addListener('log', ...)
  • addListener('connected', ...)
  • addListener('attached', ...)
  • addListener('detached', ...)
  • addListener('data', ...)
  • addListener('error', ...)
  • getDataEncoding()
  • removeAllListeners()
  • Interfaces
    • UsbSerialDevice
    • UsbSerialOptions
    • PluginListenerHandle

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>