Your Protocol Document and Integrating a Non-Standard Device

So you've been tasked with bringing data from a new device (maybe a weigh scale or barcode scanner or RFID system) into your HMI/SCADA system.  But you just have a protocol document from the manufacturer.  And for this new device, there is no existing, off-the-shelf connectivity driver or server available.

So what now? Do you contact a custom software development house?  That gets very expensive and time-consuming very quickly.

This post, the first of three, goes through what to look for in that protocol document from the manufacturer to know how to begin using OmniServer to integrate your device without requiring custom code in a fast, affordable manner that provides industry-standard client interfaces such as OPC DA and UA.

As you’re probably aware, there are a multitude of “non-standard” devices out there that don’t have a common protocol like Modbus where there are existing drivers or servers on the market for integrating those devices.  Devices like barcode scanners, weigh scales, printers, RFID systems, sensors and so many more will more commonly have some form of documentation that the manufacturer has written that provides details on the commands and responses necessary to communicate with their devices.

Historically, it has been cost-prohibitive to integrate such devices so many times a company chooses to operate the devices offline and manually collected required readings from the devices.  Or you could have a custom driver developed for your device which is also a very cost-prohibitive method.

This post covers a more user-friendly method of integrating your devices.  OmniServer is a user-configurable option that allows you to, without code, build a custom driver to communicate with your non-standard devices.  We’ll explain the procedure for planning the development of a protocol in OmniServer. Rather than show specific capabilities of OmniServer, we’ll look into the place where every protocol designer begins - the manufacturer's protocol document.  All of the examples shown in this post came from actual real-world protocol documents.

As you can imagine, digging into technical documents is a deeper technical topic that can be intimidating to some who haven’t had a lot of experience finding information in protocol documents.  Just be aware that our professional services team regularly takes care of all these details for you, and can also train you and/or your integrator in how to support it going forward.  We even have pre-bundled packages of license + services to make it easy and low risk.  So we have you covered for situations where you don’t have the time or the desire to dissect the protocol yourself.

Steps to Designing a Protocol

To begin developing a protocol in OmniServer, you’ll need to do the following:

• Obtain the manufacturer's protocol document for your device.
  
  Before any protocol can be developed in OmniServer, you need to know the format of the data stream coming from the device, or the format of the data stream you need to send to the device to get the information you need.
  
  This data format is commonly referred to as the protocol, and the document that describes the protocol is called the protocol document.
  
  There can be many different documents where the manufacturer may place the protocol information. For example, you may find the information in the User's Manual, a Technical Manual, or a Programmer's Guide.
  
  
• Look for any mention of the port settings for the device.
  
  For serial devices, this primarily refers to the usual suspects: Baud Rate, Parity, Stop Bits, and the like.
  
  
  
  Normally, all of this information is fairly straightforward and easy to find. It will look something like this:
  
  All data is sent and received in the ASCII HEX character format using 10 bits, 1 start bit, 8 data bits, no parity, and 1 stop bit.
  
  Or, like this:
  
  Communication link UART configuration:
       9600 Baud
       8 Data Bits
       No Parity
       1 Stop bit
  
  For ethernet devices, documentation will normally mention what setup needs to be done to obtain an IP address and port number for the device.  For either device type, the documentation will typically include what the default settings are.
  
  
  
  For example, it might look like this:
  
  Once you have assigned an IP address to your device, you can access the port using that IP address with the port number 2000.
  
  Once you have all of that information, you can then create your Device in OmniServer.
  
  

• Look for the protocol information itself.
  
  While finding the communication details above is normally the easiest part, finding the details on the protocol can sometimes be more difficult depending on how the document was written. Each manufacturer has their own unique way of presenting this kind of information.
  
  I also recommend another post covering some quirks of good vs. bad protocol documents
  
  
  
  Basically, what you want to look for is any information that describes the format of the data stream that comes from the device and/or the format of the data stream that must be sent to the device in order to retrieve information or start commands. The style of this description may be in the form of just a textual list, like this:
  
  Command Format:
     SYNC   - 16H
     COMMAND - 01H
     ADDRESS LOW
     ADDRESS HIGH
     COUNT LOW
     COUNT HIGH
     CRC LOW
     CRC HIGH
  
  Or a table like this:
  
  

  SYNC 16H

  CMD 01H

  ADDR LOW

  ADDR HIGH

  COUNT LOW

  COUNT HIGH

  CRC LOW

  CRC HIGH

  
  In this example, each byte of the data stream is described in detail. It can be determined that this example (which shows a command to be sent out to the device) is eight bytes in length. The first byte is always 16H, the second byte is always 01H, the next two bytes represent an address, the next two a count, and the final two a CRC.
  
  This is also what is called a Binary protocol. How do we know? One clue is that most descriptions will have the term ASCII in them to denote a text-based protocol (i.e. human-readable characters only). Also, the COMMAND and SYNC bytes above are represented by the postfix H. This indicates the byte is represented in Hexadecimal which usually means that the number is contained within one-byte. And since 01H is not a printable ASCII character, it is safe to assume that this is a binary protocol.
  
  It’s important to know that not all descriptions do a great job of telling you what type of data it uses. It is possible that each "byte" above is actually two bytes of information, with the data stream using ASCII HEX numbers instead.
  
  For example, if the description comes with a sample data stream you can use as a reference, a Binary protocol may look like this (where each block is one byte):
  
  

  SYNC   0x16

  CMD   0x01

  ADDR LOW 0x15

  ADDR HIGH 0x00

  COUNT LOW 0x0A

  COUNT HIGH 0x00

  CRC LOW 0xDC

  CRC HIGH 0x13

  
  While an ASCII HEX protocol may look like this (where each block is two bytes):
  
  

  SYNC   "16" 0x31 0x36

  CMD   "01" 0x30 0x31

  ADDR LOW "15" 0x31 0x35

  ADDR HIGH "00" 0x30 0x30

  COUNT LOW "0A" 0x30 0x45

  COUNT HIGH "00" 0x30 0x30

  CRC LOW "DC" 0x44 0x43

  CRC HIGH "13" 0x31 0x33

  
  Here is another example:
  
  The SPC serial output format for the test result consists of a series of carriage return separated fields.  The order, format and fields description are listed below. Standard ASCII characters are used and the format of the pressure and leak-rate fields are dependent on the pressure range and units selected.  Each field is separated by <CR> and the complete record is terminated by <CR> <LF>.
  
  

  Field	Description
  aaaa	4 digit test number (0000 to 9999)
  bbbbb	5 character serial number
  cccccccc	8 character sequence name (blank if not in sequence)
  dd	2 digit sequence step (0 to 5, blank if not in sequence)

  
  In this example, it tells you that the protocol is using an ASCII format, that each field is separated by Carriage Returns and the record itself ends with a Carriage Return / Line Feed combination.
  
  Finally, here is another example of data being sent to a printer:
  
  A        # 1 39 PLC DROP ONE ACTIVE
  A        # 1 14 ALARM OFF
  N        # 1 39 PLC DROP ONE ACTIVE
  
  And that is all of the information you are given. In this particular case, we have to make some educated guesses.
  
  Since the data is going to a printer, and the printer must have ASCII data to print correctly, we can be fairly certain that this is an ASCII protocol. With each data field appearing on a different line, we can then assume that a Carriage Return / Line Feed combination is at the end of each line.
  
  Finally, it's a good bet that there are four fields in this record: A Status field ("A" or "N"); two Alarm Numbers/Types ("1" and "39") and an alarm description (the text).
  
  So you can see there is a fair amount of variability regarding how a device manufacturer documents the details of their communication protocol.  That is one of the reasons why we offer complimentary protocol reviews to help you determine compatibility of your protocol with OmniServer and professional services where you’d prefer us to just handle it for you.
  

How to deal with Error Detection Codes (Checksum, CRC, LRC,  BCC, etc.)?

• Checksums
  
  "The checksum is calculated by adding up all of the bytes from the character after the Start-of-Text character up to and including the End-of-Text character"
  
  or
  
  "To calculate the checksum, add up the ASCII value of each byte in the message and append it to the end of the message."
  
  
• LRCs (Longitudinal Redundancy Check - also known as BCC or XOR)
  
  "The checksum is calculated by XORing all the bytes in the message excluding the Start-of-Header byte."
  
  or
  
  "To calculate the CRC, XOR only the data bytes. Ignore the header bytes."
  
  or
  
  "To determine the CRC, use a standard BCC calculation on all the bytes in the message."
  
  
• CRCs (Cyclic Redundancy Check)
  
  A little more complicated, a CRC applies an algorithm to the sequence of characters. Each algorithm normally uses a "polynomial" and optionally some base number.
  
  For example:
  
  "The CRC-16 check process is applied to all transmitted bytes expect pad and sync bytes....divide by the generator polynomial G(x) = 1 + x2 + x15 + x16."
  
  or
  
  "The Krieger-X15 uses a CRC with the base value of -1 (0xFFFFh) and a polynomial of x16 + x14 + x5 + 1."

So before you can determine the CRC to use, you need to know the polynomial and any base value for the calculation.

There is a lot of variability in how EDCs are documented so they are one of the more complex fields to deal with in a protocol.  Fortunately, OmniServer provides an extensive set of pre-defined Error Detection Codes when creating a protocol that work for a majority of protocols.

And, for those situations where one of the pre-defined EDCs will not work, OmniServer also supports creating custom EDCs using the elements of the EDC described in the protocol document.  It’s another reason why our complimentary protocol reviews and affordable professional services are popular for users who would really just like us to take care of it all for you while delivering training and support like you would get with any off-the-shelf driver.

Once you know what to look for in a manufacturer’s protocol documentation, it becomes much more straightforward to integrate your non-standard devices with OmniServer.  Make sure to subscribe to our blog so you don’t miss the rest of this series on designing your OmniServer protocol and also other useful posts on addressing industrial automation challenges.