|
<< Click to Display Table of Contents >>
Configuring ASCII Commands |
ASCII commands are assembled to send or extract data from I/O packets according to a device's protocol. For each format for sending and receiving, an index or ID is associated. A command can have any numbers or letters in ASCII format, fixed or with variable fields. To create variable fields, the general rule is to use the %Nt format, as described on the next table.
Available formats for ASCII commands
Format |
Description |
|---|---|
% |
Symbol identifying a variable field. If a message must send a % (percentage) character, use the value "%%" |
N (optional) |
Number of characters or formatter. If a field is a real number, N can be a real number, such as 5.2, which indicates five or more numbers on the integer part plus two numbers on the fractional part |
t |
Data type. Possible values are d: Signed decimal, u: Unsigned decimal, x: Hexadecimal, f: Real number, b: Binary (character's binary value), s: String (characters of any type), t: Text (only characters that can be printed, that is, whose ASCII code is greater or equal to 32 or 20h), or n: Interprets a decimal value in BCD format |
NOTE |
For s (String) and t (text) data types, there are subtypes @ and #, which can be used when users want to extract only a portion of a String or a text: •Use the @ symbol to identify a special character as a String's initial delimiter •Use the # symbol to identify a special character as a String's final delimiter. Users can also define this special character in hexadecimal notation, by using the h symbol followed by two more characters representing its ASCII character in hexadecimal •Use the %s format to extract a full String •Use the %@g#;s format to extract a substring from the g character to the ; (semicolon) character •Use the %@h02#h03s format to extract a substring from the 0x02 character to the 0x03 character •Delimiter characters of symbols @ and # are not part of data extraction representing a substring of %s format |
Users can also insert or check special characters /r (carriage return), /n (line feed), and any other special character in the format /hXX, by inserting characters / (slash mark) or \ (backslash) followed by r, n, or h directly on the TX or RX message. Insertion or comparison is performed directly with special characters /r (13), /n (10), or /hXX, in which XX represents a special character in hexadecimal format with two digits.
Users can also define which byte is the initial byte of data reception, which byte is the final byte of data reception, and whether these bytes must be part of data extraction, according to the next options:
•[xx: Defines which byte starts data reception, in which xx is in hexadecimal notation and included in data extraction
•]xx: Defines which byte ends data reception, in which xx is in hexadecimal notation and included in data extraction
•(xx: Defines which byte starts data reception, in which xx is in hexadecimal notation and not included in data extraction
•)xx: Defines which byte ends data reception, in which xx is in hexadecimal notation and not included in data extraction
In addition, for RX responses that use the ]xx or )xx terminator bytes and if there is a need to discard a few bytes that follow immediately, users can add a parameter to indicate the number of bytes that must be discarded by this Driver after receiving this byte terminator, aiming to clear data's reception buffer.
To use this parameter to discard the last n bytes, use the expression "*nn" right after the parameter that defines data reception's terminator byte, that is, ]xx*nn or )xx*nn, in which nn is in decimal notation and represents the number of bytes received and discarded by this Driver.
The next tables contain examples of usage for ASCII commands.
Usage examples
Protocol |
Goal |
Configuration |
TX: <STX>query<ETX> RX: <STX>1200<ETX> |
Send a query command to a device and extract a response's numerical value |
•ID: 1 (one) •TX: /h02query/h03 •RX: (02%u)03 •N1/B1: 0 (zero, sends and receives a command) •N2/B2: 1 (one, command's ID) •Read Tag: 1200 |
The TX packet is assembled to send a query command according to the structure of a device's protocol, that is, by using "/h02" (byte STX 0x02) + "query" + "/h03" (byte ETX 0x03).
The RX packet is assembled with format "(02" (starting not including STX 0x02) + "%u" + ")03" (ending not including ETX 0x03), in which the %u parameter extracts data in unsigned numerical format.
Usage examples
Protocol |
Goal |
Configuration |
TX: $memory13<CR><LF> RX: $34.45<CR><LF> |
Send a memory command plus a memory position to a device and extract a response's numerical value |
•ID: 1 (one) •TX: $memory%u/r/n •RX: (24%f)0D*1 •N1/B1: 1 (one, TX values) •N2/B2: 1 (one, command's ID) •Write Tag: 13 •N1/B1: 0 (zero, sends and receives a command) •N2/B2: 1 (one, command's ID) •Read Tag: 34.45 |
The TX packet requires configuring a memory position. To do so, the TX packet is assembled by inserting a variable field %u, to be defined by writing a Tag with the N1/B1 parameter equal to 1 (one, TX values). After filling in the variable field %u with a numerical value, in this example the value 13, users can send the TX packet to a device in the format "$" + "memory" + "13" + /r (byte CR 0x0D) + /n (byte LF 0x0A).
The RX packet is assembled with the format "(24" (starting not including "$") + "%f" + ")0D*1" (ending not including CR 0x0D + discarding of the LF 0x0A byte that follows), in which the %f parameter extracts data in real numerical format.
Usage examples
Protocol |
Goal |
Configuration |
TX: #GetData<CR><LF> RX: #12;452;75<CR><LF> |
Send a #GetData command to a device and extract three numerical values from the response |
•ID: 1 (one) •TX: #GetData/r/n •RX: (23%u;%u;%u)0D*1 •N1/B1: 0 (zero, sends and receives a command) •N2/B2: 1 (one, command's ID) •Read BlockTag: •Element 1: 12 •Element 2: 452 •Element 3: 75 |
The TX packet is assembled to send a GetData command according to the structure of a device's protocol, that is, by using "#" + "GetData" + /r (byte CR 0x0D) + /n (byte LF 0x0A).
The RX packet is assembled with format "(23" (starting not including "#") + "%u" + ";" + "%u" + ";" + "%u" + ")0D*1" (ending not including CR 0x0D + discarding of the LF 0x0A byte that follows), in which three %u formats are extracted by using a Block Tag with three Elements, each one representing a %u format.
Usage examples
Protocol |
Goal |
Configuration |
TX: <STX>DeviceName<ETX> RX: <STX>Personal Computer <ETX> |
Send a DeviceName command to a device and extract a value in String format from the response |
•ID: 1 (one) •TX: /h02DeviceName/h03 •RX: (02%s)03 •N1/B1: 0 (zero, sends and receives a command) •N2/B2: 1 (one, command's ID) •Read Tag: "Personal Computer" |
The TX packet is assembled to send a DeviceName command according to the structure of a device's protocol, that is, by using /h02 (byte STX 0x02) + "DeviceName" + /h03 (byte ETX 0x03).
The RX packet is assembled with format "(02" (starting not including STX 0x02) + "%s" + ")03" (ending not including ETX 0x03), in which the %s parameter extract data in String format.
Usage examples
Protocol |
Goal |
Configuration |
TX: <STX>DeviceName<ETX> RX: <STX>Personal Computer <ETX> |
Send a DeviceName command to a device and extract a substring from the response's value |
•ID: 1 (one) •TX: /h02DeviceName/h03 •RX: (02%@r#as)03 •N1/B1: 0 (zero, sends and receives a command) •N2/B2: 1 (one, command's ID) •Read Tag: "son" |
The TX packet is assembled to send a DeviceName command according to the structure of a device's protocol, that is, by using /h02 (byte STX 0x02) + "DeviceName" + /h03 (byte ETX 0x03).
The RX packet is assembled with format "(02" (starting not including STX 0x02) + "%@r#as" + ")03" (ending not including ETX 0x03), in which the %@r#as parameter extracts a substring between the initial "r" character and the final "a" character from the value "Personal Computer", resulting in a "son" substring.