If you’re reading this blog, you likely need a way to collect data from some random device in your process – something like a barcode reader or a weigh scale or an RFID system or some other device. These are the types of device that don’t typically yield favorable results when you type “OPC Server for xyz” into a Google search.
In this blog post, I'll discuss the device manufacturer documentation that is typically provided for such devices and what some of the key information is you'll be looking for - including examples of how a good protocol document will present such information.
In your search for a communication option for your "non-standard" device, perhaps you've come across the idea of a "user-configurable" I/O server option. Maybe you’re familiar with the Software Toolbox OmniServer user configurable OPC server product. I’m going to assume, for the purposes of this post, that you’ve never heard of OmniServer and give you a quick synopsis of what OmniServer is as background before we dive in to protocol documentation specifics.
OmniServer is a fully configurable I/O server which interprets the data coming in from a device and delivers the data to any client program such as an OPC client. OmniServer takes care of all the polling and data parsing for you, and does this without the use of a programming language – everything is configured via user interface.
We just need to figure out the “format” of the data to be sent or received when communicating with the device, which is also referred to as the “protocol” for that device. In most situations, there will be some form of documentation available from the device manufacturing that provides those formatting details. (There are also situations where that’s not the case and we have to get a little more creative, but that topic will have to be covered in another post – suffice it to say that all is not lost necessarily if we don’t have a protocol document.)
Now, with respect to such documentation from the device manufacturer, the quality of these documents varies from one vendor to the next in regards to the level of detail and the information it actually contains. A good protocol document will general contain the following information in clear detail (including examples from a protocol document that did an excellent job):
1. A good table of contents.
These types of documentation are typically not short, as it will normally be an overall user manual for the device with only a portion of it being dedicated to the actual communication protocol. Making it easy to determine where in the document you can find the information you're looking for is the first step to preventing the need to skim hundreds of pages of irrelevant information.
Notice how this document has an easy-to-read table of contents that clearly indicates the sections and page numbers of the relevant communication details.
2. Any specific starting or terminating characters required for sends and/or receives.
These are traditionally starting characters such as an STX or SOH and terminating characters such as an ETX or CR. This document did a good job of explicitly saying what the start character is for each type of message and what the end/terminating character is for each response.
3. Documentation should have a section on each command/op code detailing the format of such a request and its response.
This would generally include any delimiting characters such as commas or semi-colons or spaces used between fields and definitely explicit information about the individual fields within a message.
This particular document does a good job of breaking down the fields in this request message.
And then the document has a corresponding section on the response that can be expected back for the request and breaks those fields down, as well.
4. Thorough information about any error checking codes that are required.
Ideally this will include a real example with calculated error detection code that can be used for confirming that the proper algorithm is being used.
This document details everything needed with respect to determining what error detection code would be needed in OmniServer, including how long the EDC field actually is , which actual fields in the message should be included and which ones shouldn't and the formula for calculating the value.
5. Examples of each type of request and corresponding responses should be provided
Ideally the documentation will include samples of each command and response with real data values and calculated error detection codes.
You can see that this document provided real examples with real values, even for the checksum. This is extremely helpful for making sure all spacing and placement and interpretation of values is fully understood - some documentation can be ambiguous about whether a value should be interpreted as decimal or hexadecimal or ASCII, which can require more trial-and-error during testing to determine the appropriate format.
So, just to summarize, good documentation goes a long way to reducing the amount of testing required after implementing a protocol in OmniServer for a non-standard device. A well-organized, detailed protocol document not only gives you the tools to successfully communicate with your devices using a solution like OmniServer, but allows you to do so in the most efficient manner possible.
