SerialConnectionCapacitor

A Capacitor plugin for serial port communication in web and mobile applications.

Installation

npm install serialconnectioncapacitor
npx cap sync

for Android Only , 24 and above, serial port need a rooted android 
capacitor 5.0.1 special version for VMC using polling and timing method
if you need another version please find the versions 
it uses native libs libserial_port.so , I have built for many architures , thanks grok that guided me along!

Android Setup

Add the following permission to your AndroidManifest.xml:

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

Events

The plugin emits the following events:

| Event Name | Description | Data Structure | |------------|-------------|----------------| | connectionOpened | When connection is established | { message: string } | | connectionError | When connection fails | { error: string } | | nativeWriteSuccess | When data is written successfully | { message: string } | | writeError | When write operation fails | { error: string } | | dataReceived | When data is received | { data: string } | | readError | When read operation fails | { error: string } | | readingStopped | When reading is stopped | { message: string } | | connectionClosed | When connection is closed | { message: string } |

Event Handling Example

import { serialConnectionCapacitor } from 'serialconnectioncapacitor';

// Connection events
serialConnectionCapacitor.addEvent('connectionOpened', (event) => {
  console.log('Connection established:', event.message);
});

// Data events
serialConnectionCapacitor.addEvent('dataReceived', (event) => {
  console.log('Received data:', event.data);
});

// Error handling
serialConnectionCapacitor.addEvent('readError', (event) => {
  console.error('Read error:', event.error);
});

serialConnectionCapacitor.addEvent('connectionError', (event) => {
  console.error('Connection error:', event.error);
});

// Cleanup
serialConnectionCapacitor.addEvent('connectionClosed', (event) => {
  console.log('Connection closed:', event.message);
});

API

• listPorts()
• listUSBDevices()
• openSerial(...)
• openUSB(...)
• openUsbSerial(...)
• sendNV9Command(...)
• checkUSBStatus()
• getUSBDeviceInfo(...)
• testUSBConnection(...)
• requestUSBPermission(...)
• openSerialEssp(...)
• write(...)
• writeVMC(...)
• writeMT102(...)
• writeADH814(...)
• writeEssp(...)
• startReading()
• startReadingVMC()
• startReadingMT102()
• startReadingADH814()
• startReadingEssp()
• stopReading()
• stopNV9Polling()
• close()
• requestID(...)
• scanDoorFeedback(...)
• pollStatus(...)
• setTemperature(...)
• startMotor(...)
• acknowledgeResult(...)
• startMotorCombined(...)
• startPolling(...)
• stopPolling()
• querySwap(...)
• setSwap(...)
• switchToTwoWireMode(...)
• addListener(SerialPortEventTypes, ...)
• removeAllListeners()
• Interfaces
• Type Aliases

Plugin interface for serial port communication.

listPorts()

listPorts() => Promise<{ ports: { [key: string]: number; }; }>

Lists available serial ports.

Returns: Promise<{ ports: { [key: string]: number; }; }>

listUSBDevices()

listUSBDevices() => Promise<{ devices: string; count: number; }>

Lists only USB devices

Returns: Promise<{ devices: string; count: number; }>

openSerial(...)

openSerial(options: SerialPortOptions) => Promise<{ success: boolean; message: string; portName: string; baudRate: number; connectionType: string; isNV9?: boolean; }>

Opens a serial port connection.

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | ----------------------------------------------------- | | options | SerialPortOptions | Connection options including port path and baud rate. |

Returns: Promise<{ success: boolean; message: string; portName: string; baudRate: number; connectionType: string; isNV9?: boolean; }>

openUSB(...)

openUSB(options: { portName: string; }) => Promise<{ success: boolean; message: string; portName: string; connectionType: string; }>

Opens a USB serial port connection explicitly.

| Param | Type | Description | | ------------- | ---------------------------------- | --------------------------------------- | | options | { portName: string; } | Connection options including port name. |

Returns: Promise<{ success: boolean; message: string; portName: string; connectionType: string; }>

openUsbSerial(...)

openUsbSerial(options: SerialPortOptions) => Promise<any>

Opens a USB serial port connection.

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | ----------------------------------------------------- | | options | SerialPortOptions | Connection options including port path and baud rate. |

Returns: Promise<any>

sendNV9Command(...)

sendNV9Command(options: NV9CommandOptions) => Promise<{ success: boolean; event: string; command: string; data?: any; error?: string; }>

Sends an NV9 SSP command to the USB device

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | ------------------- | | options | NV9CommandOptions | NV9 command options |

Returns: Promise<{ success: boolean; event: string; command: string; data?: any; error?: string; }>

checkUSBStatus()

checkUSBStatus() => Promise<{ usbManagerAvailable: boolean; totalUsbDevices: number; devices?: string; usbSerialPortOpen: boolean; isNV9Mode: boolean; isPolling: boolean; serialPortOpen: boolean; }>

Checks USB connection status

Returns: Promise<{ usbManagerAvailable: boolean; totalUsbDevices: number; devices?: string; usbSerialPortOpen: boolean; isNV9Mode: boolean; isPolling: boolean; serialPortOpen: boolean; }>

getUSBDeviceInfo(...)

getUSBDeviceInfo(options: { portName: string; }) => Promise<any>

Gets detailed USB device info

| Param | Type | Description | | ------------- | ---------------------------------- | ----------- | | options | { portName: string; } | Port name |

Returns: Promise<any>

testUSBConnection(...)

testUSBConnection(options: { portName: string; }) => Promise<any>

Tests USB connection with a specific device

| Param | Type | Description | | ------------- | ---------------------------------- | ----------- | | options | { portName: string; } | Port name |

Returns: Promise<any>

requestUSBPermission(...)

requestUSBPermission(options: { portName: string; }) => Promise<any>

Requests USB permission for a device

| Param | Type | Description | | ------------- | ---------------------------------- | ----------- | | options | { portName: string; } | Port name |

Returns: Promise<any>

openSerialEssp(...)

openSerialEssp(options: SerialPortOptions) => Promise<any>

Opens a USB serial port connection for ESSP.

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | ----------------------------------------------------- | | options | SerialPortOptions | Connection options including port path and baud rate. |

Returns: Promise<any>

write(...)

write(options: { data: string; }) => Promise<any>

Writes data to the serial port.

| Param | Type | Description | | ------------- | ------------------------------ | --------------------------------------------- | | options | { data: string; } | Write options containing the command to send. |

Returns: Promise<any>

writeVMC(...)

writeVMC(options: { data: string; }) => Promise<any>

Writes data to the serial port for VMC.

| Param | Type | Description | | ------------- | ------------------------------ | --------------------------------------------- | | options | { data: string; } | Write options containing the command to send. |

Returns: Promise<any>

writeMT102(...)

writeMT102(options: { data: string; }) => Promise<any>

Writes data to the serial port for VMC.

| Param | Type | Description | | ------------- | ------------------------------ | --------------------------------------------- | | options | { data: string; } | Write options containing the command to send. |

Returns: Promise<any>

writeADH814(...)

writeADH814(options: { data: string; }) => Promise<any>

Writes data to the serial port for ADH814.

| Param | Type | Description | | ------------- | ------------------------------ | --------------------------------------------- | | options | { data: string; } | Write options containing the command to send. |

Returns: Promise<any>

writeEssp(...)

writeEssp(options: { data: string; }) => Promise<any>

Writes data to the serial port for ESSP.

| Param | Type | Description | | ------------- | ------------------------------ | --------------------------------------------- | | options | { data: string; } | Write options containing the command to send. |

Returns: Promise<any>

startReading()

startReading() => Promise<any>

Starts reading data from the serial port.

Returns: Promise<any>

startReadingVMC()

startReadingVMC() => Promise<any>

Starts reading data from the serial port for VMC.

Returns: Promise<any>

startReadingMT102()

startReadingMT102() => Promise<any>

Starts reading data from the serial port for MT102.

Returns: Promise<any>

startReadingADH814()

startReadingADH814() => Promise<any>

Starts reading data from the serial port for ADH814.

Returns: Promise<any>

startReadingEssp()

startReadingEssp() => Promise<any>

Starts reading ESSP data from the serial port.

Returns: Promise<any>

stopReading()

stopReading() => Promise<any>

Stops reading data from the serial port.

Returns: Promise<any>

stopNV9Polling()

stopNV9Polling() => Promise<{ success: boolean; message: string; }>

Stops NV9 polling

Returns: Promise<{ success: boolean; message: string; }>

close()

close() => Promise<{ success: boolean; message: string; }>

Closes the serial port connection.

Returns: Promise<{ success: boolean; message: string; }>

requestID(...)

requestID(options: { address: number; }) => Promise<any>

| Param | Type | | ------------- | --------------------------------- | | options | { address: number; } |

Returns: Promise<any>

scanDoorFeedback(...)

scanDoorFeedback(options: { address: number; }) => Promise<any>

| Param | Type | | ------------- | --------------------------------- | | options | { address: number; } |

Returns: Promise<any>

pollStatus(...)

pollStatus(options: { address: number; }) => Promise<any>

| Param | Type | | ------------- | --------------------------------- | | options | { address: number; } |

Returns: Promise<any>

setTemperature(...)

setTemperature(options: { address: number; mode: number; tempValue: number; }) => Promise<any>

| Param | Type | | ------------- | ------------------------------------------------------------------ | | options | { address: number; mode: number; tempValue: number; } |

Returns: Promise<any>

startMotor(...)

startMotor(options: { address: number; motorNumber: number; }) => Promise<any>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { address: number; motorNumber: number; } |

Returns: Promise<any>

acknowledgeResult(...)

acknowledgeResult(options: { address: number; }) => Promise<any>

| Param | Type | | ------------- | --------------------------------- | | options | { address: number; } |

Returns: Promise<any>

startMotorCombined(...)

startMotorCombined(options: { address: number; motorNumber1: number; motorNumber2: number; }) => Promise<any>

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | { address: number; motorNumber1: number; motorNumber2: number; } |

Returns: Promise<any>

startPolling(...)

startPolling(options: { address: number; interval: number; }) => Promise<any>

| Param | Type | | ------------- | --------------------------------------------------- | | options | { address: number; interval: number; } |

Returns: Promise<any>

stopPolling()

stopPolling() => Promise<any>

Returns: Promise<any>

querySwap(...)

querySwap(options: { address: number; }) => Promise<any>

| Param | Type | | ------------- | --------------------------------- | | options | { address: number; } |

Returns: Promise<any>

setSwap(...)

setSwap(options: { address: number; swapEnabled: number; }) => Promise<any>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { address: number; swapEnabled: number; } |

Returns: Promise<any>

switchToTwoWireMode(...)

switchToTwoWireMode(options: { address: number; }) => Promise<any>

| Param | Type | | ------------- | --------------------------------- | | options | { address: number; } |

Returns: Promise<any>

addListener(SerialPortEventTypes, ...)

addListener(eventName: SerialPortEventTypes, listenerFunc: (event: any) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Add listener for serial port events.

| Param | Type | Description | | ------------------ | --------------------------------------------------------------------- | ------------------------------------ | | eventName | SerialPortEventTypes | The event to listen for. | | listenerFunc | (event: any) => void | Callback function when event occurs. |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners

Interfaces

SerialPortOptions

Options for opening a serial port connection.

| Prop | Type | Description | | -------------------- | -------------------- | --------------------------------------------------------- | | portName | string | Path to the serial port (e.g., /dev/ttyUSB0 or COM3). | | baudRate | number | Baud rate for the serial port connection. | | dataBits | number | | | stopBits | number | | | parity | string | | | bufferSize | number | | | flags | number | | | isNV9 | boolean | Enable NV9 mode for SSP protocol | | autoConnectUSB | boolean | Auto-connect to USB NV9 after serial connection |

NV9CommandOptions

Options for NV9 SSP commands

| Prop | Type | Description | | ------------- | ------------------- | --------------------------------------------------------------------- | | command | string | Command name (e.g., 'POLL', 'ENABLE', 'DISABLE', 'GET_SERIAL_NUMBER') | | args | string | Optional arguments for the command as JSON string |

PluginListenerHandle

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

Type Aliases

SerialPortEventTypes

Event types for serial port events

'portsListed' | 'serialOpened' | 'usbSerialOpened' | 'connectionClosed' | 'usbWriteSuccess' | 'dataReceived' | 'readingStarted' | 'readingStopped' | 'serialWriteSuccess' | 'commandAcknowledged' | 'commandQueued' | 'adh814Response' | 'nv9Event' | 'usbDeviceEvent'

Example Usage

import { serialConnectionCapacitor } from 'serialconnectioncapacitor';

class SerialPortManager {
  private isReading = false;

  async initialize() {
    try {
      const { ports } = await serialConnectionCapacitor.listPorts();
      if (Object.keys(ports).length === 0) {
        throw new Error('No serial ports available');
      }

      const portName = Object.keys(ports)[0];
      await serialConnectionCapacitor.open({
        portName,
        baudRate: 115200
      });

      this.setupEvents();
      return true;
    } catch (error) {
      console.error('Initialization failed:', error);
      return false;
    }
  }

  private setupEvents() {
    // Connection events
    serialConnectionCapacitor.addEvent('connectionOpened', (event) => {
      console.log('Connected:', event.message);
    });

    serialConnectionCapacitor.addEvent('connectionClosed', (event) => {
      console.log('Disconnected:', event.message);
    });

    // Data events
    serialConnectionCapacitor.addEvent('dataReceived', (event) => {
      console.log('Received:', event.data);
    });

    serialConnectionCapacitor.addEvent('nativeWriteSuccess', (event) => {
      console.log('Write successful:', event.message);
    });

    // Error events
    serialConnectionCapacitor.addEvent('readError', (event) => {
      console.error('Read error:', event.error);
    });

    serialConnectionCapacitor.addEvent('connectionError', (event) => {
      console.error('Connection error:', event.error);
    });
  }

  async startReading() {
    if (!this.isReading) {
      await serialConnectionCapacitor.startReading();
      this.isReading = true;
    }
  }

  async stopReading() {
    if (this.isReading) {
      await serialConnectionCapacitor.stopReading();
      this.isReading = false;
    }
  }

  async sendCommand(command: string) {
    await serialConnectionCapacitor.write({ command });
  }

  async cleanup() {
    await this.stopReading();
    await serialConnectionCapacitor.close();
  }
}

// Usage
const serialManager = new SerialPortManager();
await serialManager.initialize();
await serialManager.startReading();
await serialManager.sendCommand('TEST');
// ... later
await serialManager.cleanup();

License

MIT