As someone who has worked with non-standard device connectivity using OmniServer for over 16 years, I consider myself well-versed in some of the more obscure nuances of certain protocols that a user might need to implement and how to do so in OmniServer. It's very common for non-standard device protocols to simply be some combination of ASCII alpha-numeric characters with some special characters mixed in for starting messages, terminating messages or as delimiters.
Many OmniServer users may not be aware, though, that there are certain ASCII characters that are used in OmniServer protocol messages that have special meaning. So when you come across a device protocol that requires those characters to be sent or receive as-is (namely backslashes, curly braces and square brackets), there is some special handling required when configuring your OmniServer protocol .
Returning and expanding our "Did You Know" OmniServer blog post series, I'll cover the usage of some common special syntax characters for OmniServer protocol messages and how to, when needed, escape their special status in the message so they can be treated as their original ASCII equivalent instead.
So previous users of OmniServer know that OmniServer makes it possible to configure a custom protocol/driver without custom code based on device vendor protocol documentation (or potentially other sources, when protocol documentation isn't available). So, once you've reviewed your protocol documentation and confirmed the format of messages to either be sent to the device or received from the device, you'll be configuring those messages in an OmniServer protocol. This tells OmniServer how to send or receive those messages and parse the appropriate byte or bytes in those messages.
By default, any ASCII (alphanumeric) characters you type into an OmniServer protocol message are treated as their literal ASCII equivalent.
For example the example above, the 1234abcd portion of the message would be treated as literally ASCII 1234abcd, which translates to Hex values (as the bytes of would be viewed in a packet sniffer or OmniServer's own I/O Monitor diagnostic tool) of:
0x31 0x32 0x33 0x34 0x61 0x62 0x63 0x64
Since not all protocols are ASCII based, though, OmniServer has to be able to send other number system formats, such as Hexadecimal or Binary. To that end, there are number of ways to specify non-ASCII formats but the most commonly used and easiest is by using special formatting or shorthand utilizing a backslash (\) character.
Using the Backslash to Define OmniServer Number Formats
The ASCII Backslash character (\) is useful in OmniServer because it can be used to easily define Hexadecimal or Binary Decimal number notation on the fly.
- For Binary Decimal Numbers (0 - 255) - You can use the \nnn format in your OmniServer message. For example:
- To send a Decimal 56 (i.e. Hex 0x38 or ASCII 8) -> \56
- To send a Decimal 56 (i.e. Hex 0x38 or ASCII 8) -> \56
- For Hexadecimal Numbers (00 - FF) - You can use the \xhh. For example:
- To send a Hexadecimal A6 -> \xA6
- To send a Hexadecimal A6 -> \xA6
For protocols using either of those formats, the backslash shorthand syntax makes it easy to implement bytes in those formats on the fly.
Other Special Characters in OmniServer Protocol Messages
While the majority of ASCII characters can be entered into an OmniServer message directly as-is, the following characters have special functionality with respect to formatting in an OmniServer protocol message:
- Backslash ( \ ) - As we've already discussed, the Backslash ( \ ) character has importance in OmniServer protocol messages for formatting non-ASCII number representations.
- Curly Braces ( { } ) - Curly braces are used in pairs to surround certain types of special sequences in an OmniServer protocol message. They are used when defining an Item, Control Sequences (such as a Carriage Return ( {$CR} ), for instance), an Error Detection Code (an 8-bit Checksum ( {$CSUM8} ) for instance), a Register, a Topic Variable and other types of special sequences in a protocol message.
- Square Brackets ( [ ] ) - Square brackets are used in pairs to surround bytes or sequences in a OmniServer protocol message that should be used in an Error Detection Code calculation - they tell OmniServer where to start and which bytes to use as the input for the calculation.
Since these characters are treated specially in OmniServer, then there is special handling required if your device's protocol requires that you send one of these characters (or receive one as part of a device response).
How to Escape Special Characters in an OmniServer Protocol Message
So if a command or response for your device's protocol will include a backslash, left or right curly braces and/or left or right square brackets, you need to tell OmniServer how to "escape" that character's special handling so that OmniServer treats it as the literal character instead.
To do that, fittingly enough, you actually will need to use the Backslash (\) character as a prefix for the special character that you need to be treated literally. To send or receive a left curly brace ({) for instance, you'd do the following in the message of your OmniServer protocol:
- \{
And, yes, this applies for all of the special characters we've discussed, including the Backslash (\) character itself, handled as:
- \\
The first backslash escapes the special status of the following character such that it's treated literally by OmniServer.
Alternately, if you're worried that could introduce confusion for other users looking at your protocol messages in OmniServer, you can also insert the Hexadecimal equivalent of the special character instead of the ASCII character itself, so you'd use one of the following:
- To represent a literal Backslash ( \ ) in an OmniServer message:
- 0x5C
- \x5C
- \92
- To represent a literal Left Curly Brace ( { ) in an OmniServer message:
- 0x7B
- \x7B
- \123
- To represent a literal Right Curly Brace ( } ) in an OmniServer message:
- 0x7D
- \x7D
- \125
- To represent a literal Left Square Bracket ( [ ) in an OmniServer message:
- 0x5B
- \x5B
- \91
- To represent a literal Right Square Bracket ( ] ) in an OmniServer message:
- 0x5D
- \x5D
- \93
Any of those methods will allow you to successfully use those special characters as the literal value, though, based on your preference. Given that using the Backslash as an escape sequence/character just before the actual character requires the smallest amount of typing/characters in an OmniServer message, that is typically the method I personally use when configuring a protocol message.
Hopefully this either provides you some additional insights on why you might have had issues with these "special" characters in the past or will arm you with the knowledge you need to avoid any issues using these characters in your OmniServer protocols in the future.
Where can I get more information?
If you're new to non-standard device connectivity, perhaps you have a device with a protocol manual but you’re not really sure how to get started. As always, we're happy to help with a complimentary review of your protocol documentation and we have a library of detailed how-to video tutorials for OmniServer available here.
You can always feel free to contact us with your questions and remember to subscribe to our blog for more quick and easy OmniServer tutorials and tips. And, if you haven't already, make sure to download the latest free trial version of OmniServer to get started connecting your own non-standard devices.
