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()
• openSerial(...)
• openUsbSerial(...)
• openSerialEssp(...)
• write(...)
• writeVMC(...)
• writeMT102(...)
• writeADH814(...)
• writeEssp(...)
• startReading()
• startReadingVMC()
• startReadingMT102()
• startReadingADH814()
• startReadingEssp()
• stopReading()
• close()
• requestID(...)
• scanDoorFeedback(...)
• pollStatus(...)
• setTemperature(...)
• startMotor(...)
• acknowledgeResult(...)
• startMotorCombined(...)
• startPolling(...)
• stopPolling()
• querySwap(...)
• setSwap(...)
• switchToTwoWireMode(...)
• addListener(SerialPortEventTypes, ...)
• Interfaces
• Type Aliases

Plugin interface for serial port communication.

listPorts()

listPorts() => Promise<SerialPortListResult>

Lists available serial ports.

Returns: Promise<SerialPortListResult>

openSerial(...)

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

Opens a serial port connection.

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

Returns: Promise<any>

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>

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: SerialPortWriteOptions) => Promise<any>

Writes data to the serial port.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | --------------------------------------------- | | options | SerialPortWriteOptions | Write options containing the command to send. |

Returns: Promise<any>

writeVMC(...)

writeVMC(options: SerialPortWriteOptions) => Promise<any>

Writes data to the serial port for VMC.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | --------------------------------------------- | | options | SerialPortWriteOptions | Write options containing the command to send. |

Returns: Promise<any>

writeMT102(...)

writeMT102(options: SerialPortWriteOptions) => Promise<any>

Writes data to the serial port for VMC.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | --------------------------------------------- | | options | SerialPortWriteOptions | Write options containing the command to send. |

Returns: Promise<any>

writeADH814(...)

writeADH814(options: SerialPortWriteOptions) => Promise<any>

Writes data to the serial port for VMC.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | --------------------------------------------- | | options | SerialPortWriteOptions | Write options containing the command to send. |

Returns: Promise<any>

writeEssp(...)

writeEssp(options: SerialPortWriteOptions) => Promise<any>

Writes data to the serial port for ESSP.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | --------------------------------------------- | | options | SerialPortWriteOptions | 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 VMC.

Returns: Promise<any>

startReadingADH814()

startReadingADH814() => Promise<any>

Starts reading data from the serial port for VMC.

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>

close()

close() => Promise<any>

Closes the serial port connection.

Returns: Promise<any>

requestID(...)

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

Requests the device ID for ADH814.

| Param | Type | Description | | ------------- | --------------------------------- | ---------------------- | | options | { address: number; } | Address of the device. |

Returns: Promise<any>

scanDoorFeedback(...)

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

Scans door feedback for ADH814.

| Param | Type | Description | | ------------- | --------------------------------- | ---------------------- | | options | { address: number; } | Address of the device. |

Returns: Promise<any>

pollStatus(...)

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

Polls status for ADH814.

| Param | Type | Description | | ------------- | --------------------------------- | ---------------------- | | options | { address: number; } | Address of the device. |

Returns: Promise<any>

setTemperature(...)

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

Sets temperature for ADH814.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------ | ------------------------------------- | | options | { address: number; mode: number; tempValue: number; } | Address, mode, and temperature value. |

Returns: Promise<any>

startMotor(...)

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

Starts a motor for ADH814.

| Param | Type | Description | | ------------- | ------------------------------------------------------ | ------------------------- | | options | { address: number; motorNumber: number; } | Address and motor number. |

Returns: Promise<any>

acknowledgeResult(...)

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

Acknowledges result for ADH814.

| Param | Type | Description | | ------------- | --------------------------------- | ---------------------- | | options | { address: number; } | Address of the device. |

Returns: Promise<any>

startMotorCombined(...)

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

Starts combined motors for ADH814.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------- | ------------------------------ | | options | { address: number; motorNumber1: number; motorNumber2: number; } | Address and two motor numbers. |

Returns: Promise<any>

startPolling(...)

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

Starts polling for ADH814 status.

| Param | Type | Description | | ------------- | --------------------------------------------------- | ----------------------------- | | options | { address: number; interval: number; } | Address and polling interval. |

Returns: Promise<any>

stopPolling()

stopPolling() => Promise<any>

Stops polling for ADH814.

Returns: Promise<any>

querySwap(...)

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

Queries row/column swap status for ADH814.

| Param | Type | Description | | ------------- | --------------------------------- | ---------------------- | | options | { address: number; } | Address of the device. |

Returns: Promise<any>

setSwap(...)

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

Sets row/column swap for ADH814.

| Param | Type | Description | | ------------- | ------------------------------------------------------ | ----------------------------------------------- | | options | { address: number; swapEnabled: number; } | Address and swap enabled status (0x00 or 0x01). |

Returns: Promise<any>

switchToTwoWireMode(...)

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

Switches to two-wire mode for ADH814.

| Param | Type | Description | | ------------- | --------------------------------- | ---------------------- | | options | { address: number; } | Address of the device. |

Returns: Promise<any>

addListener(SerialPortEventTypes, ...)

addListener(eventName: SerialPortEventTypes, listenerFunc: (...args: any[]) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Add listener for serial port events.

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

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Interfaces

SerialPortListResult

Result of listing available serial ports.

| Prop | Type | Description | | ----------- | --------------------------------------- | ----------------------- | | ports | { [key: string]: number; } | Available serial ports. |

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 | a Baud rate for the serial port connection. | | dataBits | number | | | stopBits | number | | | parity | string | | | bufferSize | number | | | flags | number | |

SerialPortWriteOptions

Options for writing to a serial port.

| Prop | Type | Description | | ---------- | ------------------- | -------------------------------------------------------- | | data | string | Command to send to the serial port (hex string or text). |

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'

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