Did You Know? How to Setup a Heartbeat Message in OmniServer

5 min read

Sep 20, 2018 2:00:00 PM


As you probably know, OmniServer is used to retrieve information from devices that use ‘non-standard’ protocols to communicate such as weight scales, barcode readers, and printers.

In some situations, device protocols need to be designed to where the client application (HMI, SCADA or other), and not OmniServer, is in complete control of the polling. But before you send out the next message, how do you know if the device is still connected?

In this first post of a follow-up to our "OmniServer Did You Know?" blog series, we will cover how to create what is known as a heartbeat message to confirm your device is "listening" before sending the next message.

With many devices, it's not uncommon for devices to "go to sleep" after a certain amount of time where there is no activity.  Sometimes there is a configurable timeout in the device's settings that controls how long that period of inactivity is but sometimes there is not.

Many such devices can be "woken up" by sending either a specific command or sending any character or sequence of characters that is NOT a command.  This is commonly referred to as a heartbeat message

If you missed our original blog series "OmniServer Did You Know?", get caught up here!

Why Would I Need To Do This?

The consistent routine polling of a device is the mechanism used by OmniServer to determine if a device is available. If OmniServer is not allowed to control that polling as normal, then there is no way to know if the instrument has stopped communicating.

A heartbeat message can be used as an underlying poll mechanism for the device. Then the client uses a heartbeat notification item to flag a potential communications problem.

How Can I Do This?

In this example, we are going to set up OmniServer to automatically poll the instrument with the word "STATUS".  NOTE:  This is just an example - for your device, you would need to confirm what sequence/message can be used to keep the device awake but not cause any issues for the device.

OmniServer will then wait for the value of "OK" to come back. Again, this is just an example - you will need a sequence/message that can be sent to the device that result in some form of response or acknowledgement.  If nothing comes back or the instrument responds incorrectly, the Heartbeat notification item will be set to False or Zero.

  1. Create a new OmniServer item called Heartbeat as in the screenshot below. Make certain all settings match, particularly the "Item should be automatically activated" setting:

    The Heartbeat Item Definition
  2. Create a new OmniServer Command/Request message inside your protocol using the following samples.

  3. On the General tab, enter in the values as below. Notice the Notification Item. The item selected in this field is set by OmniServer to True or One whenever this particular message successfully completes.  It's also important to make sure the "Message should be automatically activated" option is enabled to ensure the message is executed even when an item isn't being requested by the client application:

    The Heartbeat Command/Request Message - General Tab
  4. On the Request tab, enter in the values as below. Remember that this is just a sample. Check with your instrument's documentation to see if there is a message that can be sent to retrieve status information:

    The Heartbeat Command/Request Message - Request Tab
  5. Finally, on the Response tab, enter in the values as below. Again, your response may be different, but the critical item is the {Heartbeat:L} at the end (where {Heartbeat}  can be the item you just created or you can select any other Integer field).

    The "L" is for the Linkage format style, and it tells OmniServer to read in the data as normal, but not to assign any data to the item nor to expect any data for that item. This is crucial in getting this command/request message to execute on a regular basis without resulting in a fault because the device isn’t returning a value for the item:

    The Heartbeat Command/Request Message - Response Tab
  6. Finally, save your protocol.

To test this protocol, create a tag in your client application to point to the item Heartbeat. This will activate the heartbeat message and continually set the item Heartbeat to the value of One until the instrument does not respond or sends out anything but "OK" as an response to the request. Therefore, anytime Heartbeat goes to Zero, you know something has gone wrong.

Can the Heartbeat message be used for other things?

In the implementation above, Heartbeat provides similar functionality to the reserved OmniServer item called Status. However, using the Notification Item increases troubleshooting capabilities.

For example, both Status and Heartbeat will go to zero (or false) once something has gone wrong with communications. However, Status is a global item, which basically means "Expected Communications has not been received somewhere within the protocol". If you have five-hundred messages, then troubleshooting which message caused the error can be troublesome.

But using the Notification Item as above (such as Heartbeat), lets you say "Expected Communications has not been received within this message". So you can use the Notification Item to pinpoint exactly where the trouble lies.

Are there any limitations to the Heartbeat message?

If your device will not accept any commands (as is the case with some barcode readers and other devices), then this scheme will not work, and OmniServer will not have any way of determining if the device is still connected, as that is a limitation of the protocol itself.

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