Capacitor Serial Port Plugin

A comprehensive Capacitor plugin for serial port communication on Android devices.

Install

npm install @leonardojc/capacitor-serial-port
npx cap sync

Permissions

Android

Add these permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Note: This plugin requires root access on Android devices to access certain serial ports. Some ports like /dev/ttyS2 may be accessible without root depending on device configuration.

API

• listPorts()
• openPort(...)
• closePort()
• writeData(...)
• getStatus()
• setupPermissions(...)
• addListener('serialData', ...)
• addListener('serialError', ...)
• addListener('connectionChange', ...)
• removeAllListeners()
• Interfaces

listPorts()

listPorts() => Promise<ListPortsResult>

List available serial ports on the device

Returns: Promise<ListPortsResult>

Since: 1.0.0

openPort(...)

openPort(options: OpenPortOptions) => Promise<OpenPortResult>

Open connection to a serial port

| Param | Type | Description | | ------------- | --------------------------------------------------------- | --------------------------------------- | | options | OpenPortOptions | Configuration for opening the port |

Returns: Promise<OpenPortResult>

Since: 1.0.0

closePort()

closePort() => Promise<ClosePortResult>

Close the current serial port connection

Returns: Promise<ClosePortResult>

Since: 1.0.0

writeData(...)

writeData(options: WriteDataOptions) => Promise<WriteDataResult>

Write data to the serial port

| Param | Type | Description | | ------------- | ----------------------------------------------------------- | ---------------- | | options | WriteDataOptions | Data to write |

Returns: Promise<WriteDataResult>

Since: 1.0.0

getStatus()

getStatus() => Promise<StatusResult>

Get current status of the serial port connection

Returns: Promise<StatusResult>

Since: 1.0.0

setupPermissions(...)

setupPermissions(options: SetupPermissionsOptions) => Promise<SetupPermissionsResult>

Setup permissions for accessing the serial port (Android only)

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | ----------------------------------- | | options | SetupPermissionsOptions | Port path for permission setup |

Returns: Promise<SetupPermissionsResult>

Since: 1.0.0

addListener('serialData', ...)

addListener(eventName: 'serialData', listenerFunc: (event: SerialDataEvent) => void) => Promise<PluginListenerHandle>

Add a listener for serial data events

| Param | Type | Description | | ------------------ | --------------------------------------------------------------------------- | ---------------------------------------- | | eventName | 'serialData' | Name of the event to listen for | | listenerFunc | (event: SerialDataEvent) => void | Function to call when event occurs |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('serialError', ...)

addListener(eventName: 'serialError', listenerFunc: (event: SerialErrorEvent) => void) => Promise<PluginListenerHandle>

Add a listener for serial error events

| Param | Type | Description | | ------------------ | ----------------------------------------------------------------------------- | ---------------------------------------- | | eventName | 'serialError' | Name of the event to listen for | | listenerFunc | (event: SerialErrorEvent) => void | Function to call when event occurs |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('connectionChange', ...)

addListener(eventName: 'connectionChange', listenerFunc: (event: ConnectionChangeEvent) => void) => Promise<PluginListenerHandle>

Add a listener for connection change events

| Param | Type | Description | | ------------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------- | | eventName | 'connectionChange' | Name of the event to listen for | | listenerFunc | (event: ConnectionChangeEvent) => void | Function to call when event occurs |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin

Since: 1.0.0

Interfaces

ListPortsResult

Result from listing ports operation

| Prop | Type | Description | Since | | ----------- | --------------------------- | ------------------------------- | ------- | | ports | SerialPort[] | Array of available serial ports | 1.0.0 |

SerialPort

Represents a serial port on the device

| Prop | Type | Description | Since | | ------------------ | -------------------- | -------------------------------------- | ------- | | path | string | Path to the serial port device file | 1.0.0 | | manufacturer | string | Manufacturer information (if available) | 1.0.0 | | serialNumber | string | Serial number of the device (if available) | 1.0.0 | | vendorId | string | Vendor ID (if available) | 1.0.0 | | productId | string | Product ID (if available) | 1.0.0 | | readable | boolean | Whether the port is readable | 1.0.0 | | writable | boolean | Whether the port is writable | 1.0.0 |

OpenPortResult

Result from opening port operation

| Prop | Type | Description | Since | | ------------- | -------------------- | -------------------------------- | ------- | | success | boolean | Whether the operation was successful | 1.0.0 | | message | string | Message describing the result | 1.0.0 |

OpenPortOptions

Options for opening a serial port connection

| Prop | Type | Description | Default | Since | | -------------- | ------------------------------------------------------------ | ----------------------------------- | ------------ | ------- | | path | string | Path to the serial port device | | 1.0.0 | | baudRate | number | Baud rate for communication | 9600 | 1.0.0 | | dataBits | number | Number of data bits | 8 | 1.0.0 | | stopBits | number | Number of stop bits | 1 | 1.0.0 | | parity | 'none' | 'even' | 'odd' | 'mark' | 'space' | Parity setting | 'none' | 1.0.0 |

ClosePortResult

Result from closing port operation

| Prop | Type | Description | Since | | ------------- | -------------------- | -------------------------------- | ------- | | success | boolean | Whether the operation was successful | 1.0.0 | | message | string | Message describing the result | 1.0.0 |

WriteDataResult

Result from writing data operation

| Prop | Type | Description | Since | | ------------- | -------------------- | -------------------------------- | ------- | | success | boolean | Whether the operation was successful | 1.0.0 | | message | string | Message describing the result | 1.0.0 |

WriteDataOptions

Options for writing data to serial port

| Prop | Type | Description | Since | | ---------- | ------------------- | ---------------------------------- | ------- | | data | string | Data to write to the serial port | 1.0.0 |

StatusResult

Result from getting status operation

| Prop | Type | Description | Since | | --------------- | -------------------- | ---------------------------------------- | ------- | | connected | boolean | Whether a port is currently connected | 1.0.0 | | port | string | Path of the currently connected port | 1.0.0 |

SetupPermissionsResult

Result from setting up permissions operation

| Prop | Type | Description | Since | | ------------- | -------------------- | -------------------------------- | ------- | | success | boolean | Whether the operation was successful | 1.0.0 | | message | string | Message describing the result | 1.0.0 |

SetupPermissionsOptions

Options for setting up permissions

| Prop | Type | Description | Since | | -------------- | ------------------- | ------------------------------- | ------- | | portPath | string | Path to the serial port device | 1.0.0 |

PluginListenerHandle

Plugin listener handle for removing listeners

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

SerialDataEvent

Event fired when serial data is received

| Prop | Type | Description | Since | | --------------- | ------------------- | ------------------------------- | ------- | | data | string | The received data | 1.0.0 | | timestamp | number | Timestamp when data was received | 1.0.0 |

SerialErrorEvent

Event fired when a serial error occurs

| Prop | Type | Description | Since | | ------------- | ------------------- | ------------- | ------- | | message | string | Error message | 1.0.0 | | code | string | Error code | 1.0.0 |

ConnectionChangeEvent

Event fired when connection status changes

| Prop | Type | Description | Since | | --------------- | -------------------- | ---------------------------- | ------- | | connected | boolean | Whether currently connected | 1.0.0 | | port | string | Port path (if connected) | 1.0.0 |

Usage Example

import { SerialPort } from '@leonardojc/capacitor-serial-port';

// List available ports  
const result = await SerialPort.listPorts();
console.log('Available ports:', result.ports);

// Setup permissions (Android only, requires root)
await SerialPort.setupPermissions({ portPath: '/dev/ttyS2' });

// Open port
await SerialPort.openPort({
  path: '/dev/ttyS2',
  baudRate: 9600,
  dataBits: 8,
  stopBits: 1,
  parity: 'none'
});

// Listen for data
SerialPort.addListener('serialData', (event) => {
  console.log('Received:', event.data);
});

// Listen for errors
SerialPort.addListener('serialError', (event) => {
  console.error('Serial error:', event.message);
});

// Listen for connection changes
SerialPort.addListener('connectionChange', (event) => {
  console.log('Connection changed:', event.connected);
});

// Send data
await SerialPort.writeData({ data: 'Hello Serial Port!' });

// Get status
const status = await SerialPort.getStatus();
console.log('Connected:', status.connected);

// Close port
await SerialPort.closePort();

Platform Support

| Platform | Status | |----------|--------| | Android | ✅ | | iOS | ❌ | | Web | ✅ (Mock) |

Capacitor Version Support

| Plugin Version | Capacitor Version | Android API | Status | |----------------|-------------------|-------------|--------| | 1.1.x | 7.x | 24+ | ✅ Current | | 1.0.x | 6.x | 22+ | ⚠️ Legacy |

Requirements

• Capacitor 7.0+
• Android API Level 24+ (Android 7.0+)
• JDK 17+ for Android builds
• Root access (for most serial ports on Android)

Common Serial Ports on Android

• /dev/ttyS0, /dev/ttyS1, /dev/ttyS2, /dev/ttyS3 - System serial ports
• /dev/ttyUSB0, /dev/ttyUSB1 - USB serial adapters
• /dev/ttyACM0, /dev/ttyACM1 - Arduino/CDC ACM devices

Migration Guide

From v1.0.x to v1.1.x (Capacitor 6 → 7)

1. Update Capacitor to version 7:

   npm install @capacitor/core@^7.0.0 @capacitor/android@^7.0.0

2. Update the plugin:

   npm install @leonardojc/capacitor-serial-port@^1.1.0

3. Sync your project:

   npx cap sync

4. Update your Android project (if needed):

   • Minimum SDK is now 24 (Android 7.0)
   • Target SDK is now 35 (Android 15)
   • Java 17+ is required

5. Test thoroughly - No API changes, but underlying platform updates may affect behavior

Breaking Changes in v1.1.0

• Minimum Capacitor version: 6.x → 7.x
• Minimum Android SDK: 22 → 24
• Java compatibility: 11 → 17

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Support

If you encounter any issues or have questions, please open an issue on our GitHub repository.