Using KeepAlives and LinkMonitorMode with Octane SDK and LTK

When writing applications with the Octane SDK and LTK, one common challenge is encountering network and power outages which can cause communication with Impinj readers and gateways to go down.  Enabling your application to recognize and be resilient to these outages is a crucial step in the design process.

The reader can provide a limited amount of persistent storage and use tag buffers to help minimize the amount of data loss, but as these buffers and storage space have limited space, the higher priority is to re-establish communication with the host device as soon as possible.  Knowing when these outages occur is the first step to mitigating this challenge. Our Octane Firmware and Libraries provide a feature called, 'Keepalives', which can be used to help notify both the application and reader (or gateway) that communication has gone down and appropriate steps should be taken. When the 'Keepalives' functionality is enabled on the reader, the reader will  periodically send out a Keepalive message it expects the application to respond to.  If an appropriate response from either the application/reader isn't received in a timely fashion then the communication is effectively down. 

One problem that occurs, is that by default, the reader does not take any action with regard to the connection (In other words, it leaves the connection open preventing other applications from connecting) when the Keepalive responses are missing. LinkMonitorMode is the feature used to address this shortcoming. The reader includes 'LinkMonitorMode' functionality in the firmware, though it will need to be explicitly enabled through your application. It instructs the reader to close its' LLRP connection should an unanswered response to Keepalives messages occur too many times. Without the LinkMonitorMode feature enabled, the reader can inadvertently prevent any application from connecting after a connection failure, because LLRP only allows for one connection at a time and the reader continues to think the existing connection is active.

This article will dive deeper into these two features (Keepalives and LinkMonitorMode) and explain the options available in our Octane SDK and LTK so you can successfully mitigate these outages yourself. These parameters are also described in our Reader How-To: Health Monitoring documentation, which also explains more on SNMP and Reader Events, as well.

Feature Summary:

As mentioned above, the two features that need to be enabled and configured are Keepalives and LinkMonitorMode. It is important to understand how each of these features work together in your application, so each feature is described below:

1. Keepalives - The feature implemented by our firmware to notify the application of a disconnection. A Keepalive message is sent from the reader to the application, and the application will send a Keepalives acknowledgement message back to the reader. The communication will be seen as down if either side has not sent/responded to Keepalives within the user-defined Keepalives period.
   
   
2. LinkMonitorMode - The feature implemented by our reader/gateway firmware to close whatever network connection it has when the user-defined number of Keepalive messages are missed. When the network connection is closed, the reader will still continue to perform the inventory, meaning tag reads can be lost during the time of an outage unless using the HoldReportsOnDisconnect configuration setting.

Implementing Keepalives With the Octane SDK:

In order to use these features successfully with the Octane SDK, you will need to make use of a few parameters that are mentioned below:

You will first need to create a Settings object, that you can then use to configure the Keepalive settings. The configuration parameters for the Keepalives through this settings object are shown below:

• Settings.Keepalives.Enabled - This parameter indicates whether the Keepalive event is enabled or not. In our case, we want this set to 'true'.
• Settings.Keepalives.PeriodInMs - The parameter defining the Keepalive event interval (in milliseconds) and when Keepalive messages should have been received from the reader. The default is 3000 ms.
• Settings.Keepalives.EnableLinkMonitorMode - This parameter dictates whether to use LinkMonitorMode or not. If link monitor mode is enabled, the reader will automatically shut down the network connection if it doesn't receive replies (ACKs) to Keepalive messages. You will want this parameter set to 'true'.
• Setting.Keepalives.LinkDownThreshold - This parameter specifies the number of missed Keepalive replies before the reader shuts down the network connection. The default for this parameter is set to 5.

With using Keepalives and LinkMonitorMode, it's recommended to also create event handlers for when a Keepalive is received, and when the reader has it's connection shut down (missed N Keepalive messages). You can use these handlers to alert a connection failure, as well as to try reconnecting your application to the reader. The two event handlers we use in our examples shipped with the Octane SDK are onKeepaliveReceived and OnConnectionLost

It's also important to remember to disconnect your host from the existing reader object before attempting to reconnect to the reader. This is most easily done in your onConnectionLost handler, by calling the reader.Disconnect function. We have an additional example called ReaderConnectivity, written for .Net, that shows a functional example of what we have described in this section. You can find this available for download here. 

For Impinj Partners, you can access our SDK training videos here, which go into more detail on this topic.

Implementing KeepAlives With The Octane LTK:

To implement Keepalives and LinkMonitorMode through the LTK, you will need to include a KeepaliveSpec in the SET_READER_CONFIG message sent to the reader. The KeepaliveSpec parameter is one of the available parameters for the SET_READER_CONFIG message, and is defined in the LTK Definition Files which can be found here.

The KeepaliveSpec parameter will contain two fields: KeepaliveTriggerType and PeriodicTriggerValue. The KeepaliveTriggerType can be set to either 'null', or 'periodic'. When set to 'periodic', the frequency of the Keepalive messages will be defined by the PeriodicTriggerValue, otherwise when set to 'null', this parameter is ignored and Keepalives will be disabled.

The ImpinjLinkMonitorConfiguration custom parameter will allow you to enable LinkMonitorMode on the reader. There are two fields included with this parameter, those being LinkMonitorMode and LinkDownThreshold. The LinkMonitorMode field is a custom enumeration, and can hold the value of either 'Disabled' or 'Enabled'. The LinkDownThreshold is referring to how many missed Keepalive messages to allow before making the reader close its current connection. These are further defined in the LTK Definitions documentation mentioned above.

For Impinj Partners, we have online video training that show how to set these parameters up. Impinj Partners can use the following link to access the courses, once signed into the training portal.