# SerialPort

{% hint style="info" %}
**Version and platform compatibility**

* This feature was introduced in version **4.26.0** of the JourneyApps Container for Android and Windows desktop.
* Support for binary data was introduced in version **4.59.0** of the JourneyApps Container for Android and Windows desktop.
* USB-based SerialPort devices are only supported on Windows.
* The SerialPort API is currently only available for customers on the [Enterprise](https://journeyapps.com/pricing/) plan.
  {% endhint %}

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/reference/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 the JourneyApps 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.