# WriteSerial

The WriteSerial function sends a string with the specified bytes over the serial port as a message. Then, the function sets the text in the WriteSerial cell to reflect the message.

Note: Using the WriteSerial function is not supported while Native Mode is enabled.

To use the WriteSerial 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 output terminator.

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

3. Add the WriteSerial function to the Spreadsheet. The property sheet of the WriteSerial function opens.

4. Set the external event, used for triggering the function, in the Event field.

5. Set the message in the Message field.

6. Check the Send Raw Bytes checkbox if you want to send decoded bytes (hexadecimal code point values). Leave it unchecked if you want to send bytes with UTF-8 encoding.

7. Click OK.

8. Verify that the selected vision system is online.

9. Trigger the event to send the message.

10. The message has the output terminator appended.

## WriteSerial 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.
Message | Specifies the message to send. The message can be Stringf, format output buffer, or any cell with text. You can freely define the format output buffer, it does not have to be many entries of unsigned characters. The bytes that are visible in the format output are sent exactly.
SendRawBytes | Specifies whether to send decoded bytes (hexadecimal code point values) or bytes with UTF-8 encoding. When checked, sends single byte code point values to the serial line. When unchecked, the message uses UTF-8 encoding. All strings that contain values over 0x7F are multi-byte encoded. Note: Format output buffer data is never encoded, even if the Send Raw Bytes checkbox is unchecked. For example, if you have Stringf("%c%c", 0x80, 0xA2), visible as "€¢" in the Stringf cell, you can have the following results: Send Raw Bytes checked: The bytes sent over the serial port are 0x80 0xA2. Once received, these bytes are not displayed correctly and will not look like "€¢". Send Raw Bytes unchecked: The bytes sent over the serial port are UTF-8 encoded, 0xC2 0x80 0xC2 0xA2. This makes the cell look like "€¢". Note: Stringf uses UTF-8 encoding by default.

## WriteSerial Outputs

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

Examples

Using Stringf:

The output terminator is set to 191 or hex code point (not UTF-8 encoded): 0xBF.

Cell A0 contains the image.

Cell A1 contains stringf("h%c", 0xCF). This contains a character, h, which is below code point 128 and 0xCF. The UTF-8 encoding of 128 is represented in one byte. The UTF-8 encoding of 0xCF is represented by two bytes (0xC3 0x8f) as it is above code point 128.

Sending raw data:

1. Cell A2 contains raw data, WriteSerial($A$0, $A$1, 1).

2. The vision system is set online and triggered. The event is camera, so the trigger causes a write.

3. 0x68 0xCF 0xBF is the data output in hexadecimal along with the appended output terminator.

Sending encoded data:

1. Cell A2 contains data in UTF-8 encoded format, WriteSerial($A$0, $A$1, 1).

2. The vision system is set online and triggered. The event is camera, so the trigger causes a write.

3. 0x68 0xCF 0x8F 0xBF is the data output in hexadecimal along with the appended output terminator.

Using FormatOutputBuffer

The output terminator is set to 191 or hexadecimal code point (not UTF-8 encoded) 0xBF.

Cell A0 contains the image.

Cell A1 contains FormatOutputBuffer(0, "u:u", 0x68, 0xCF). To create this, create an empty FormatOutputBuffer, then edit the string as needed. In this example, 0x68 represents a value below code point 128 and is represented by one byte. 0xCF represents a value over 128 and is represented by two bytes.

When using the FormatOutputBuffer, you can only send raw data. This means that the data does not use UTF-8 encoding and multi-byte characters are represented by code point. Checking the Send Raw Bytes checkbox does not affect the output of the WriteSerial function when using FormatOutputBuffer.

1. Cell A2 contains raw data, WriteSerial($A$0, $A$1, 1).

2. The vision system is set online and triggered. The event is camera, so the trigger causes a write.

3. 0x68 0xCF 0xBF is the data output in hexadecimal along with the appended output terminator.

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.