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 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.
Copy link
On this page