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.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
}
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. |
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);
}
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.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.Last modified 4mo ago