The constructor has no parameters - it creates an instance but does not open any interface.

If this handler should be used as long as the PClient is running, it should be created e.g. in a project init script and assigned to a global variable.

Prototype:

var myRS232 = new RS232Handler();

Example:

// Generate a global RS232 handler

myRS232_handler = new RS232Handler();

This method opens the RS232 interface with an optionally specified baud rate and a wait time for the RS232 read function.

If called without parameters or with unsupported values, the RS 232 interface is initialized with 115200 bit/s and 100 ms wait time.

it is always initialized to use:

8 data bits

No parity

1 stop bit

these settings can NOT be changed at the moment.

The following baud rates [bit/s] can be configured:

50

75

110

134

150

300

600

1200

1800

2400

4800

9600

19200

38400

57600

115200

230400

460800

500000

576000

921600

1000000

1152000

1500000

Every other value will result in a setting of 115200 bit/s.

The wait time means that the read function will wait for that time if the RS232 buffer is empty. This can be used when communicating with a device that needs some time to deliver an answer to a write.

The wait time can be set in steps of 100 from 0 to 25500 ms.

Prototype:

var result = <RS232Handler instance>.init(number newBaudrate,number waitTime);

Examples:

// Open an RS232 interface with the default settings of 115200 baud / s and 100 ms wait time)

myRS232.init();

// Open an RS232 interface with 9600 baud / s and 100 ms wait time)

myRS232.init(9600);

// Open an RS232 interface with 576000 baud / s and 0 ms wait time)

myRS232.init(576000,0);

Return values:

0 - port successfully opened

2 - port cannot be opened

3 - parameters cannot be applied to port

10 - current settings cannot be read from port

If the target machine (i.e. printer) should not accept UTF-8 encoded text, this property allows the modification of strings before they are sent.

Reading is not affected - the read method only returns an array of the raw bytes received.

The following encodings are supported:

   Big5

   Big5-HKSCS

   CP949

   EUC-JP

   EUC-KR

   GB18030

   HP-ROMAN8

   IBM 850

   IBM 866

   IBM 874

   ISO 2022-JP

   ISO 8859-1 to 10

   ISO 8859-13 to 16

   Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg, and Tml

   KOI8-R

   KOI8-U

   Macintosh

   Shift-JIS

   TIS-620

   TSCII

   UTF-8

   UTF-16

   UTF-16BE

   UTF-16LE

   UTF-32

   UTF-32BE

   UTF-32LE

   Windows-1250 to 1258

Prototype:

myRS232.encoding = STRING <encoding name>;

Example:

// Change the encoding to Windows 1252

myRS232.encoding = "Windows-1252";

This method returns the baud rate currently used for the serial port.

Prototype:

var myBaudrate = myRS232.getBaudrate();

The method returns 0 if the port is not initialized yet.

Note that this method can't actually read the current baud rate. It returns the saved value of the last baud rate that has been set successfully with the .init method.

This method returns a string containing the path and device file currently opened by this instance.

This mainly exists for debugging.

Prototype:

var port = myRS232.getPort();

Example:

// Retrieve the filepath and device name of the RS232 port

var myPort = myRS232.getPort();

print("RS 232 port used : '" + myPort + "'.");

This method writes a string or number array to the serial port.

This only works if the RS232Handler instance has been created and initialized before.

It accepts a character string as well as an array of numbers as buffer to be sent via serial interface.

Strings will be converted to UTF-8 format used everywhere in PClient if 'RS232Handler.encoding' is not modified.

As a second parameter, one can provide the number of bytes to send from the buffer i.e. this allows to use a buffer which could contain more than one wants to send currently.

If an array of numbers is provided, the size is limited to the size of the array - even if a greater number is provided in 'bytesToSend'.

If a string is provided, the size is considered to be characters. Depending on the desired encoding the number of bytes sent can differ.

If the buffer is provided as string, the 'encoding' property of 'RS232Handler' is used to convert the string before sending (see examples).

Prototype:

var errorCode = RS232Handler.writeFromBuffer(<String or number array>, optional number charactersToSend);

Examples:

// Since UTF-8 is used for character encoding in PClient the special characters are sent as two or more bytes by default

// which in the following example can result in unprintable characters.

// Special characters in this example are sent as two bytes each (for default UTF-8).

myRS232.writeFromBuffer("Special characters: 'ÄÖÜ äöü'\r\n");

// If the receiver expects special characters according to an extended ASCII encoding

// the special characters have to be provided as an array of numbers.

// If 'latin 1' (ISO 8859) is expected the same text as above could look like this:

myRS232.writeFromBuffer("Special characters: '");

myRS232.writeFromBuffer([0xc4, 0xd6, 0xdc, 0x20, 0xe4, 0xf6, 0xfc]);

myRS232.writeFromBuffer("'\r\n");

// In order to convert the data sent to another character table one can define the 'encoding' property of 'myRS232':

myRS232.encoding = "Windows-1252";

// Now even the special characters will only be sent as one byte:

myRS232.writeFromBuffer("Special characters: 'ÄÖÜ äöü'\r\n");

Return values:

0 - write successful

2 - port is not opened yet

6 - writing failed

Calling this method reads all data currently available on the RS232 interface and stores it in a number array.

Without a parameter, the method reads up to 1024 bytes.

With an optional parameter the number of bytes can be limited.

If no data is available, an empty array will be returned after the set wait time.

This method entirely relies on the buffering of the underlying driver.

Note that this is a very simple interface intended to e.g. read some configuration data from a printer.

It is by no means designed to frequently read data e.g. from a GPS receiver or other similar source.

If this warning should not prevent you from trying anyways: Expect lag in the PClient (drawing) performance (as both share the same thread) and be aware that you have to manage getting the data at the right time and in the right amount somehow without blocking the PClient with 'busy waiting'.

Prototype:

var number[] = RS232Handler.readIntoBuffer(number bytesToRead);

Example:

//Read the RS232 interface

var readArray = myRS232.readIntoBuffer();

//convert the numeric array into a String

var arrayAsString = String.fromCharCode.apply(null, readArray);

// show data received in String Field [57]:

setProperty(57, "Preview Value", arrayAsString);