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.
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):
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.
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.
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.
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.
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.