---
title: "SerialPort"
description: "Version and platform compatibility"
permalink: /docs/runtime/js-ts-apis/serialport/
---
# SerialPort

* Available on Android and Windows Desktop.
* Support for binary data was introduced in version **4.59.0** of the Container for Android and Windows desktop.
* USB-based SerialPort devices are only supported on Windows.

<Enterprise>

The SerialPort API is available to customers on the [Enterprise](/pricing/) plan.

</Enterprise>

The SerialPort API allows applications to directly communicate to external devices that support the serial port protocol. On Android, the devices have to support the Bluetooth Serial Port Profile or [SPP](https://developer.android.com/docs/android/bluetooth/BluetoothSocket.html/).

To use the SerialPort API, a global `SerialPort` object is available.

#### Checking if SerialPort is supported

A `SerialPort.info()` function is available to check if the user's device has access to the serial port. It returns an object:

| Field | Type | Description |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `supported` | boolean | Indicates if SerialPort is supported on the current device. Supported on Android and Windows only. |
| `multipleConnections` | boolean | Some devices are able to connect to more than one device at a time. This property indicates if the device is able to do so. Multiple connections are only supported on Windows. |
| `rawModeSupported` | boolean | Indicates if the device supports reading data in raw (binary) mode. |

Since the SerialPort object is not available in containers below 4.26, a check is needed to avoid an error, for example:

```javascript
if(typeof SerialPort != 'undefined' && SerialPort.info().supported) {
  // Use SerialPort
} else {
  // Handle unsupported case
}
```

#### Listing SerialPort devices

Connecting and pairing of devices happens outside of the Container i.e. the user is responsible for pairing an external device using their specific device's instructions. To get a list of paired devices, call the `SerialPort.list()` function. It returns an array of device objects that contain the following fields:

| Field | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `address` | string | The device's physical address. On Android, this will be a MAC address. On Windows, this will be a COM port. The `address` is used to connect to the device. |
| `name` | string | Sometimes a device has a descriptive name that makes it easier for the user to identify the device they are trying to connect to. If it isn't available, it will default to `address`. This is only used for display purposes. |

#### Connecting to a device

To connect to a device, the `address` is required from `SerialPort.list()`, but can also be entered manually or hardcoded if known.

To connect, use `SerialPort.connect(address, options, readHandler)`.

| Parameter | Description |
| ------------- | ------------------------------------------------------------------------------------- |
| `address` | Address from `SerialPort.list()` |
| `options` | Object with configuration options. See below for more details. |
| `readHandler` | Callback that gets called containing all data that was received from the serial port. |

The following fields can exist in the `options` object:

| Option | Type | Description |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `baudRate` | integer | The Baud Rate of the device that you are trying to connect to. This is only applicable on Windows, since Android manages this. |
| `rawMode` | boolean | If the connection should be opened in raw (binary) mode. Defaults to `false`. |

```javascript
// eg. address
var address = 'ab:12:cd:34:ef:56';
// blank options
var options = {}; // use `var options = {rawMode: true};` for binary support
var readHandler = function(data) {
  // data received from serial port
  console.log(data);  
}
// use a try .. catch, since an exception may be thrown.
try {
  var serialPort = SerialPort.connect(address, options, readHandler);
} catch (err) {
  console.log(err);
}
```

#### Writing to a device

The `SerialPort.connect` function returns a SerialPort instance. From the example above, to write:

```javascript
var serialPort = SerialPort.connect(address, options, readHandler);

// writing string data
var stringData = "Data to write to device";
serialPort.write(stringData);

// writing binary data ("Hello" in hexadecimal)
var binaryData = [0x48, 0x65, 0x6c, 0x6c, 0x6f];
serialPort.write(binaryData);
```

Note that the `readHandler` that was passed to the `connect` function will receive responses from the serial port if given, and not the `write` function.

#### Closing and resetting

To close a connection, call `close()` on the connection object, e.g. `serialPort.close()`.

To reset the serial port, call `SerialPort.reset()`. This closes all open ports.