basic.serial.javascript

Interface SignStixSerial

SignStixSerial

Javascript-to-Player interface for communicating with serial devices connected to the Player via USB. Note that this particular interface is only supported on M12S devices and later.

The general procedure for using a serial device is as follows:

1. Call getDevicesInfo() to identify (via the vendor ID and product ID) the USB device of interest.
2. Call requestPermission(...) to gain permission to use that USB device. Pass in the devicePath gleaned from the previous step.
3. Call connect(...) to set up a connection to the serial device.
4. Call startReading(...) to listen continuously for data coming back from the serial device.
5. Call write(...) to send data to the serial device.
6. Call close() to terminate the connection to the serial device.

Function Summary

Modifier and Type	Function and Description
void	close(int connectionId) Close down the argument connection.
void	closeAll() Close down all open connections.
int	connect(String devicePath, String driverName, int baudRate, int stopBits, int dataBits, int parity) Attempt to connect to the serial device identified by the devicePath.
String	getDevicesInfo() Find information about the USB devices currently connected to the Player.
void	requestPermission(String devicePath, String jsFunctionName) Request permission to use the USB serial device identified by the devicePath.
void	startReading(int connectionId, String jsFunctionName) Start reading data from the argument connection.
void	stopReading(int connectionId) Stop reading from the argument connection.
void	write(int connectionId, String hexData) Send the bytes represented by the hexData to the serial device associated with the connectionId.
void	writePreClose(int connectionId, String hexData) Arrange for the argument hex data to be sent to the serial device associated with the argument connection ID immediately before the connection is closed.

Function Detail

getDevicesInfo

String getDevicesInfo()

Find information about the USB devices currently connected to the Player.

Returns:

an array of JSON objects containing the values:

• devicePath (string) - the device path e.g. "/dev/bus/usb/001/003"
• vendorId (string) - the ID of the device vendor in HEX.
• productId (string) - the ID of the product vendor in HEX.
• productName (string) - the name of the product (if known - this may be null).

Since:

Player 3.0.1

requestPermission

void requestPermission(String devicePath,
                       String jsFunctionName)

Request permission to use the USB serial device identified by the devicePath. Note that on some devices, user interaction may be required (e.g. confirming a pop-up dialog) to grant permission.

Parameters:

devicePath - the path of the serial device as determined from getDevicesInfo().

jsFunctionName - the name of a Javascript function which will be called when the permission request process completes. It should take parameters as follows:

1. String devicePath - the path of the device.
2. bool success - true if permission was granted.

Since:

Player 3.0.1

connect

int connect(String devicePath,
            String driverName,
            int baudRate,
            int stopBits,
            int dataBits,
            int parity)

Attempt to connect to the serial device identified by the devicePath. Permission should have been requested first, otherwise the call may fail.

Parameters:

devicePath - the path of the serial device as determined from getDevicesInfo().

driverName - pass in "ch34" to use the CH34xUART driver. Pass in "usb" to use FTDI or PL2303. Further drivers/devices may be supported in future.

baudRate - one of {600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600}.

stopBits - one of {1, 2}.

dataBits - one of {5, 6, 7, 8}.

parity - one of {0=None, 1=Odd, 2=Even, 3=Mark, 4=Space}.

Returns:

the connection ID (>=1) if successful, or 0 otherwise.

Since:

Player 3.0.1

write

void write(int connectionId,
           String hexData)

Send the bytes represented by the hexData to the serial device associated with the connectionId.

Parameters:

connectionId - the connection to communicate with.

hexData - a String of bytes in hexadecimal format.

Since:

Player 3.0.1

writePreClose

void writePreClose(int connectionId,
                   String hexData)

Arrange for the argument hex data to be sent to the serial device associated with the argument connection ID immediately before the connection is closed.

This can be used to ensure an orderly disconnection from a device in the case when the connection is closed automatically e.g. when moving to a different sign.

Parameters:

connectionId - the connection to communicate with.

hexData - a String of bytes in hexadecimal format, or null to cancel a previous instruction.

Since:

Player 3.0.1

startReading

void startReading(int connectionId,
                  String jsFunctionName)

Start reading data from the argument connection.

Parameters:

connectionId - the ID of the connection.

jsFunctionName - the name of a Javascript function which will be called when data is received. It should take parameters as follows:

1. int connectionId - the ID of the connection that received the data.
2. String hexData - a string of bytes in hexadecimal format.

Since:

Player 3.0.1

stopReading

void stopReading(int connectionId)

Stop reading from the argument connection.

Parameters:

connectionId - the ID of the connection.

Since:

Player 3.0.1

close

void close(int connectionId)

Close down the argument connection. If the connection is currently reading, it will be stopped from reading first.

This should be called when communication is over to free-up resources. Do not attempt further operations on a closed connection.

Parameters:

connectionId - the ID of the connection.

Since:

Player 3.0.1

closeAll

void closeAll()

Close down all open connections. If connections are currently reading, they will be stopped from reading first.

This should be called when communication is over to free-up resources. Do not attempt further operations on closed connections.

Since:

Player 3.3.0.