Binary and Hex Comms
While the majority of devices that ComScript is used with communicate in regular ASCII text, some use binary communication which is more efficient and can speed up computer and device communication (for more on binary numerals visit http://en.wikipedia.org/wiki/Binary_numeral_system). ComScript supports binary communication with connected devices by setting the type attribute in the send or collect commands to Hex(hexadecimal).
Ex. 1: <send type="Hex" string="FF" />
This command will send out an 8 bit, binary array of 1s (i.e. 11111111) which equals FF in hex and 255 in decimal.
Tip: The windows calculator easily converts between decimal, hex and binary. Be sure to click "scientific" under the view menu for this functionality.
Ex. 2: <send type="Hex" string="FE" behavior="TT" trigger="63" terminator="64" var="HexResponse" />
Let's suppose that our set device is an anemometer that communicates in binary with an RS232 serial connection. When the anemometer receives a binary value of 254 (FE in hex) it responds with a binary acknowledgement value of 63 (99 in decimal), the wind speed, the wind direction and an \"end of data\" indicator binary value of 64 (100 in decimal). A potential response in hex would look like 63, 10, 0163, 64, but each value would not be separated by commas so it would come over the serial port as 5510016364. That is 10 characters or 5 bytes (8 binary bits/byte). The first acknowledgement byte of 55 (99 in decimal), the wind speed byte of 10 (16 in decimal), two bytes for wind direction 0163 (355 in decimal), and the terminating 64 byte (100 in decimal). Note that wind direction requires two bytes because the maximum value that can be represented in 1 byte is FF or decimal 255 and wind direction could range from 0-359. Because the trigger and terminator are set to 63 and 64 respectively for the acknowledgement and terminating bytes, the variable HexResponse would equal 100163.
A hex string like 100163 does not mean much to most of us and ComScript can't fully evaluate hex values with conditional expressions. Thus, ComScript provides the parse command to convert hex arrays into individual decimal numbers. In example 3 below, ComScript will convert hex 10 into decimal 16 and hex 0163 into decimal 355, and insert those values into variables WindSpeed and WindDirection respectively.
Ex. 3: <parse hexvar="HexResonse" vars="WindSpeed, WindDirection" type="hex2vars" /> Note: no square brackets [ ] around the hexvar attribute "HexResponse", because it is being set, not referenced.
So that ComScript knows how many bytes to insert into each variable, the size of WindSpeed and WindDirection must be previously declared with the set command as indicated below.
<set vars="WindSpeed,WindDirection" type="uint8,uint16" />
The type attribute controls the number of bytes to store into the variable (see table below). A uint8 is an 1 byte unsigned integer and a uint16 is a 2 byte unsigned integer.
Please refer to the BinaryComms and HexDecimalConversion profile examples that can be downloaded from the ComScript web site for more information on binary communications and hex and decimal conversion.
Common Error: ComScript will output the error message "The given key was not present in the dictionary" when parsing hex varaiables into decimal if the hex variables were not defined. The size of the hex variable must be defined with the set command or in the config.xml file.
Type | Bytes | Range of Values |
byte (default) | 1 | 0 to +255 |
char | 2 | 0 to +65535 |
int16 | 2 | -32768 to +32767 |
int32 | 4 | -2,147,483,648 to +2,147,483,647 |
int64 | 8 | -9,223,372,036,854,775,808 to +9,223,372,036,854,775,807 |
uint16 | 2 | 0 to +65,535 |
uint32 | 4 | 0 to +4,294,967,295 |
uint64 | 8 | 0 to +1.84467440737E+19 |
float | 4 | single precision floating point -3.402823e38 to +3.402823e38 |
double | 8 | double precision floating point -1.79769313486232e308 to +1.79769313486232e308 |