SerialPort

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 plan.

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.

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:

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.

// 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:

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.