Did You Know? How to Use Character Translations in OmniServer

5 min read

May 18, 2017 2:00:00 PM


Those of you who are aware of OmniServer will already know that it is primarily used to retrieve information from devices that use ‘non-standard’ protocols to communicate such as weight scales, barcode readers, and printers.

But were you aware that OmniServer is also capable of handling advanced protocols where the devices send special characters/bytes that need to be handled in a specific way?  In this second post in our "OmniServer Did You Know?" blog series, keep reading to find out how to use a feature called "translations" in OmniServer with certain protocols that require special handling.

A significant concern in communication protocol design is how to handle devices that will send out ‘preamble’ characters – that is, characters prefixed to a special control characters to ensure that the device and/or master do not inadvertently mistake one character sequence for another.  OmniServer provides an elegant method for handling this type of situation with a capability called "translations".

What is a translation in OmniServer?  For most protocols, if you've used OmniServer, data that is sent or received is "what you see is what you get" type data.  An ASCII "A" is transmitted or received and interpreted as an ASCII "A".  But what if your device is expecting something else as part of it's special handling in its communication protocol?

If you missed our first post on accessing web service data with OmniServer, get caught up here!

OmniServer translations are a configuration concept in an OmniServer protocol where a table of characters are defined such that, when those characters are encountered in either a send, a receive or both, they should actually be interpreted as a different defined character or sequence of characters.

Why Would I Need To Do This?

With devices that have such protocols implemented where "preamble" characters are used to defined a special handling situation, OmniServer translations make it possible to properly parse those data packets.  A common example of this is with devices that send a “double DLE”, where two DLE characters (ASCII 16, Hex 10) are sent by the device to represent a single DLE character.

Another very common situation where this becomes a problem is when data transmission is done with binary encoded information, and not the ASCII representation. For example, when an STX character (0x02, ASCII 2) represents the beginning of a new frame, how can the device differentiate between an STX character, and any data values that happen to have a 0x02 in it?

Most devices in such situations will, therefore, prefix an STX character that should be treated as the beginning of a new frame with a DLE character such that 0x10 0x02 represents a start of text.  That way a 0x02 not prefixed by a 0x10 will be treated as just that, a binary 2.

It's just another way that OmniServer provides advanced custom protocol server capabilities allowing the successful integration of devices that would otherwise require custom code.

How Can I Do This?

At this point, you might be panicking and thinking “man this sounds difficult”.  Fortunately, that is far from being the case here. Setting up a translation is quite easy:

(For new users, if you'd like an introduction to using OmniServer, please click here.)

1.  In the OmniServer Configuration, either open your existing protocol configuration or create a new protocol.

Image - Opening an Existing OmniServer Protocol

2.  Double-click the Protocol Settings option in the top left of the Protocol Definition window.

Image - Accessing General OmniServer Protocol Settings

3.  Navigate to the Translations tab.

Image - Translations Section in OmniServer

4.  Click the New button to add a new translation:


  1. Select the Mode to define which direction the translation should be applied to the protocol: Send Only, Receive Only, or both Send and Receive.
  2. In the Computer field, type the character sequence as it will appear to the OmniServer (so, on a Send, this would be the pre-translation of the request and on a Receive, this would be the post-translation of the response from the device).
  3. In the Remote field, type the character sequence as the device will be sending it, or as the device will expect to receive it. (so, on a Send, this would be the post-translation value being sent to the device and on a Receive this would be the pre-translation of the response from the device).
  4. Note:  For both the Computer and Remote fields, you can also double-click in the field to open the Sequence Builder to select from common control characters such as carriage return and line feed, as opposed to typing them.

Image - Defining a New OmniServer Translation

5.  Click the OK button to save the new translation. (And don't forget to save the protocol afterwards!)

Image - Translations List in OmniServer Protocol

So that was pretty easy, right?  But you're probably asking what the other checkboxes in the Translations section are used for.

Compute EDCs on computer messages tells OmniServer to calculate all of the error detection routines (checksums, CRCs, etc.), where applicable, based upon the message after translation - that is, after the "remote" message has been translated to the "computer" message. Only rarely would you not have this checked.

Data fields in messages default to being translated tells OmniServer that all of the data fields will be translated by default. If this box is not checked, then the only way any field will be translated is if you add the "T+" field modifier in your protocol messages. Usually, you will want to keep this one checked as well.

Where can I get more information?

Do you have a protocol that you’re not really sure about?  As always, we're happy to help with a complimentary protocol review of your protocol documentation or to answer questions you may have.

Email us at support@softwaretoolbox.com with your questions and subscribe to our blog for more quick and easy OmniServer tutorials and tips.  Then, make sure to download the OmniServer trial to try it yourself for free.

Click to Download OmniServer Free Trial

Kevin Rutherford
Written by Kevin Rutherford

Software Toolbox Technical Blog

We're engineers like you, so this blog focuses on "How to" appnotes, videos, tech team tips, product update announcements, user case studies, and other technical updates.  Subscribe to updates below. Your feedback and questions on posts are always welcomed - just use the area at the bottom of any post.

Subscribe to our Blog

Recent Posts

Posts by Topic

See all