# ReadSerial

The ReadSerial function retrieves messages from the serial line and returns them without modifying the bytes in the message string.

Note: Native Mode takes the serial connection input to process commands when enabled. Native Mode does not share the serial connection input with the ReadSerial function.

To use the ReadSerial function:

1. Verify that the selected vision system is not an emulator.

2. Verify that the Serial Configuration utility settings are correct.

   1. Update the port settings if needed.

   2. Select fixed input or variable input and specify the correct input terminator.

   For more information about the Serial Configuration utility, see the In-Sight Vision Suite Software Help on the Cognex Support site.

3. Add an external event to the Spreadsheet.

   Note: Cognex recommends to use the serial event Event(36).

4. Add the ReadSerial function to the Spreadsheet.

5. Select the cell that contains the Event function used for triggering the function to read the serial line input buffer. For example, Event(36) triggers when the serial listener determines that a message has been received, based on the configured input terminator or fixed input length.

6. Verify that the selected vision system is online.

7. Send data to the serial port on your PC or vision system.

8. The message appears in the cell of the ReadSerial function.

## ReadSerial Inputs

Parameter | Description
Event | Specifies the event that forces an update. This parameter must be a reference to one of the following: A cell containing an Event function. For more information, see Event. A cell containing a Button function. For more information, see Button.

## ReadSerial Outputs

Returns | The byte string that forms the message, or #ERR if any of the input parameters are invalid.

Examples

The input terminator is set to exclamation mark, that is, decimal point 33 or hex 0x21.

Cell A1 contains Event(36). This is the event that triggers when receiving data to the serial port.

Cell A2 contains ReadSerial(A1), pointing to the Event tool.

The ReadSerial function takes the data received as is, and assumes that the message uses UTF-8 encoding.

Receiving raw data:

1. The data sent is 0x48 0xC3 0xAF 0x21 0xC3 0xB8, which is Hï!ø in ASCII.

   - The UTF-8 encoded value of 0xC3 0xAF is "ï".

   - The UTF-8 encoded value of 0xC3 0xB8 is "ø".

2. The data received is 0x48 0xC3 0xAF, or Hï in ASCII.

   The bytes after and including the exclamation mark (input terminator) are discarded. Using StrByteLen(A2) shows that the resulting string is of length 3, which is correct, because three bytes form the string. You can verify the encoding with strbyte(A2, 1). The result is 195, or 0xC3 in hexadecimal. For strbyte(A2, 2), the result is 175, or 0xAF in hexadecimal.

Receiving encoded data:

1. The data sent is 0x48 0xBF 0x21 0x41, which is H�!A in ASCII. 0xBF is over code point 128 and does not have a proper ASCII representation when not encoded.

2. The data received is 0x48 0xBF, or H� in ASCII.

   The bytes after and including the exclamation mark (input terminator) are discarded.

   You can verify the length of the string as two bytes using StrByteLen(A2), which results in 2. You can also verify that the second byte is the expected value using strbyte(A2, 1), which results in 191, or 0xBF in hexadecimal.

Helpful Tools

You can use the following tools to help when comparing decoded and encoded strings:

Tool | Description | Notes
Exact(string1, string2) | Returns 1 if the two strings are exactly the same. Otherwise, returns 0. | N/A
Code(string, [index]) | Returns the decimal code point for a given index in the string. If no index is provided, the index is 0. For example, stringf("%c", 0x100) returns "Ā". Code("Ā") returns the first UTF-8 decimal code point in the string with value 256. | Only for UTF-8 encoded strings
StrByte(string, [index]) | Returns the raw byte at a given index position. If no index is provided, the index is 0. For example, stringf("%c", 0x100) returns "Ā". StrByte("Ā") returns the first character in the string as decimal value 196. "Ā" is stored as two bytes, 0xC4 and 0x80. 0xC4 is 196 in decimal.
Lens(string) | Returns the number of code points in a string. For example: stringf("%c", 0x100) returns "Ā". Len("Ā") returns length 1, because the string has one UTF-8 encoded character.
StrByteLen(string) | Returns the number of bytes in the string. For example, stringf("%c", 0x100) returns "Ā". Len("Ā") returns length 2, because it is encoded with two bytes, 0xC4 and 0x80.