Serial

Some platforms support connecting hardware via serial port, either directly via UART or via USB. This can be leveraged to integrate a wide variety of hardware into your digital signage application.

Such hardware could be, for example, printers, payment terminals or sensors.

warning

• Before using this API, ensure that the display supports serial via sos.display.supports("SERIAL").
• More info HERE.
• Samsung Kiosk serial connection only works over serial ports, not over USB ports

All methods

Method	Description	Supported since
openSerialPort()	Open a new serial port	4.4.0

openSerialPort()

Creates a new instance of serial port. You can then use that instance to handle the communication.

Param	Type	Required	Description
options	Object	Yes	Object containing configuration of the serial port

Options

Property	Type	Required	Description
device	String	No	Specifies the device address
baudRate	Number	Yes	Specifies the data transmission speed in bits per second
parity	none, even, mark or space	No	Specifies the form of error checking, whether (or what) extra bits are added to a byte
databits	Number	No	Specifies the number of bits in a byte
stopbits	Number	No	Specifies the number of bits used to signal the end of a communication packet
rtscts	Boolean	No	Enables or disables RTS/CTS handshaking over the serial port. Currently supported by selected models of BrightSign
:::

Here is the options object defined as Typescript interface:

interface ISerialPortOptions {
    device?: string;
    baudRate: number;
    parity?: 'none' | 'even' | 'mark' | 'odd' | 'space';
    databits?: number;
    stopbits?: number;
    rtscts?: boolean;
}

Javascript example

// Open default serial port based platform
const serialPort = await sos.hardware.openSerialPort({
    baudRate: 115200,
});

// Open specific serial port
const serialPort = await sos.hardware.openSerialPort({
    device: '/dev/ttyUSB0',
    baudRate: 115200,
});

info

Device address is different per platform (at least for now). Kindly find the respective device address:

Device type	Default value	Other values for device
RaspberryPi / Linux	/dev/ttyUSB0	/dev/ttyUSB0
Windows	COM3	COM3 (typically, but check your Win machine if this does not work)
Samsung Kiosk	PORT1	PORT1, PORT2, PORT3
Android	/dev/ttyusb0	/dev/ttyusb0
BrightSign	0	0 (Serial jack /dev/ttyS0), 1 (GPIO port /dev/ttyS1), USB:A/0 (USB-to-serial /dev/ttyUSB0)

Serial port methods

Once you create a serial port instance using openSerialPort() method listed above, you can call following methods on it.

Method	Description	Supported since
onData()	Call a listener callback anytime the opened serial port receiving data.	4.4.0
write()	Write data to the serial port	4.4.0
close()	Close serial port	4.4.0

onData()

Call a listener callback anytime the opened serial port receiving data. The listener will stop if the serial port is closed.

Since data may be either text or binary, it's emitted as Uint8Array and should be processed further according to the requirements of your application.

Javascript example

In case of binary data:

// serial port instance previously created via sos.hardware.openSerialPort()
serialPort.onData((data) => {
    // data is array of numbers so can be processed as binary
});

In case of text data:

// serial port instance previously created via sos.hardware.openSerialPort()
serialPort.onData((data) => {
    const dataString = [...data].map((char) => String.fromCharCode(char)).join('');
});

write()

Write data to the serial port. The data can be a string of hexadecimal digits, array of numbers or Uint8Array. And converted to hexadecimals

Javascript example

// serial port instance previously created via sos.hardware.openSerialPort()
await serialPort.write('68656c6c6f'); // hexadecimal string
await serialPort.write([ 10, 20, 30, 40 ]); // array of numbers
await serialPort.write(Uint8Array.from([ 10, 20, 30, 40 ])); // Uint8Array

close()

Close serial port and prevent any more communication

Javascript example

// serial port instance previously created via sos.hardware.openSerialPort()
await serialPort.close();

Errors

Following errors may occur when working with the serial ports. However they don't reflect on actual physical connectivity of the ports due to Samsung b2bapi does not register these events.

Code	Type	Message
50602	InternalHardwareError	Failed to open serial port
50603	InternalHardwareError	Closing serial port that isn't open
50603	InternalHardwareError	Failed to close serial port
50604	InternalHardwareError	Writing to a serial port that isn't open
50604	InternalHardwareError	Failed to write to serial port