capacitor-serial

Manage serial connections to Android devices for Capacitor projects.

NB: Does not work for Web or iOS.

Install

npm install @adeunis/capacitor-serial
npx cap sync

Basic usage

    //Connection
    Serial.requestSerialPermissions({vendorId: '1111', productId: '2222', driver: SerialDriverEnum.CDC_ACM_SERIAL_DRIVER})
    .then((permissionResponse) => {
        if (!permissionResponse.granted) {
            return Promise.reject('Permission refused');
        }
        return Promise.resolve();

    })
    .then(() => Serial.openConnection({baudRate: 115200}))
    .then(() => log.info('Serial connection opend'))
    .catch((error) => log.error(error));

    //Write
    Serial.write({data: 'my_message'})
        .then(() => log.info('Data sent'))
        .catch((error: SerialError ) => {
            log.error(`error : ${error}`);
        });
    
    
    //Read
    Serial.read({readRaw: false}).then((message) => log.info(message.data));

    //Read callback 
    Serial.registerReadCallback((message, error) => {
        if (message !== undefined && message !== null) {
            log.info(message.data);

        } else if (error !== undefined && error !== null) {
            log.error(`error : ${error}`);
        }
    })

    Serial.closeConnection().then(() => log.info('Serial connection closed'));

API

• requestSerialPermissions(...)
• openConnection(...)
• closeConnection()
• write(...)
• writeHexadecimal(...)
• read(...)
• registerReadCallback(...)
• unregisterReadCallback()
• registerReadRawCallback(...)
• unregisterReadRawCallback()
• Interfaces
• Type Aliases
• Enums

requestSerialPermissions(...)

requestSerialPermissions(parameters?: SerialPermissionsParameters | undefined) => Promise<SerialPermissions>

Request permissions to connect to a device over a serial connection

| Param | Type | Description | | ---------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | parameters | SerialPermissionsParameters | Parameters used to request permissions for a specific productId and vendorId (integer value or hexadecimal string), and a specific driver |

Returns: Promise<SerialPermissions>

openConnection(...)

openConnection(parameters: SerialConnectionParameters) => Promise<void>

Open a serial connection to a device

| Param | Type | Description | | ---------------- | --------------------------------------------------------------------------------- | ------------------------------------------- | | parameters | SerialConnectionParameters | Parameters used to open a serial connection |

closeConnection()

closeConnection() => Promise<void>

Close the serial connection

write(...)

write(message: SerialMessage) => Promise<void>

Write a message to a serial connection

| Param | Type | Description | | ------------- | ------------------------------------------------------- | ---------------------------------------------------------- | | message | SerialMessage | contains the data string to write to the serial connection |

writeHexadecimal(...)

writeHexadecimal(message: SerialMessage) => Promise<void>

Write a hexadecimal message to a serial connection

| Param | Type | Description | | ------------- | ------------------------------------------------------- | ------------------------------------------------------------------------- | | message | SerialMessage | contains the data string in hexadecimal to write to the serial connection |

read(...)

read(parameters: SerialReadParameters) => Promise<SerialMessage>

Read from a serial connection

| Param | Type | Description | | ---------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | parameters | SerialReadParameters | specify if the read data should be sent back as 'raw', meaning the byte array encoded in base64 string, or as a UTF-8 decoded string |

Returns: Promise<SerialMessage>

registerReadCallback(...)

registerReadCallback(callback: SerialReadCallback) => Promise<string>

Register a callback to receive the incoming data from the serial connection

| Param | Type | Description | | -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | callback | SerialReadCallback | the callback called each time there is incoming data from the serial connection, the data being a UTF-8 decoded string |

Returns: Promise<string>

unregisterReadCallback()

unregisterReadCallback() => Promise<void>

Unregister the read callback

registerReadRawCallback(...)

registerReadRawCallback(callback: SerialReadCallback) => Promise<string>

Register a callback to receive the incoming raw data from the serial connection

| Param | Type | Description | | -------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | callback | SerialReadCallback | the callback called each time there is incoming data from the serial connection, the data being the byte array encoded in base64 string |

Returns: Promise<string>

unregisterReadRawCallback()

unregisterReadRawCallback() => Promise<void>

Unregister the read raw callback

Interfaces

SerialPermissions

| Prop | Type | | ------------- | -------------------- | | granted | boolean |

SerialPermissionsParameters

| Prop | Type | | --------------- | ------------------------------------------------------------- | | vendorId | string | number | | productId | string | number | | driver | SerialDriverEnum |

SerialConnectionParameters

| Prop | Type | | -------------- | -------------------- | | baudRate | number | | dataBits | number | | stopBits | number | | parity | number | | dtr | boolean | | rts | boolean |

SerialMessage

| Prop | Type | | ---------- | ------------------- | | data | string |

SerialReadParameters

| Prop | Type | | ------------- | -------------------- | | readRaw | boolean |

Type Aliases

SerialReadCallback

(message: SerialMessage, error?: SerialError): void

Enums

SerialDriverEnum

| Members | Value | | ---------------------------- | ----------------------------------- | | FTDI_SERIAL_DRIVER | "FtdiSerialDriver" | | CDC_ACM_SERIAL_DRIVER | "CdcAcmSerialDriver" | | CP21XX_SERIAL_DRIVER | "Cp21xxSerialDriver" | | PROLIFIC_SERIAL_DRIVER | "ProlificSerialDriver" | | CH34X_SERIAL_DRIVER | "Ch34xSerialDriver" |

SerialError

| Members | Value | | -------------------------- | ----------------------------------- | | UNKNOWN_DRIVER_ERROR | "UNKNOWN_DRIVER_ERROR" | | NO_DEVICE_ERROR | "NO_DEVICE_ERROR" | | PARAMETER_ERROR | "PARAMETER_ERROR" | | CONNECTION_ERROR | "CONNECTION_ERROR" | | PORT_CLOSED_ERROR | "PORT_CLOSED_ERROR" |