1.2.4.2 ASYNC procedures

Device drivers may define ASYNC procedures which handle messages sent by a device without a foregone request sent by the MNC. While the sat-nms device driver architecture is targeted to devices which only reply if requested to do this, ASYNC procedures provide a ways to handle unsolicited messages.

Basic concept

The concept behind ASYN procedures is a communication protocol which listens to the device all the time, reads all messages coming from the device. Each message is forwarded to the ASYNC procedures defined to check which procedure is in charge for this particular message.

The check ist done by comparing so called message tags to a reference value defined for the procedure. For JSON based protocols the message tag is one value in the JSON document.

There are a number of constraints you have to consider if a device sends messages without being requested to, specially if the device responds to requests and sends unsolicited messages as well:

  1. Reading data from a device asynchronously requires a sat-nms communication protocol definition that supports this. The protocol must listen to the device all the time and forward any incoming message to the device driver. If the protocol does not support this, no ASYNC procedures will be executed in a driver, even if they are defined.
  2. You can no longer assume, that reading a device's reply after sending a request contains the expected data. You have to design the driver in a way, that all commands and status requests are sent in PUT procedures without reading the device's reply. All replies ans unsolicited messages have to be read in ASYNC procedures.
  3. There are devices which provide separate communication channels for replies to requests and for asynchronous messages. With such a protocol the above restriction does not apply.
  4. Commands and requests never must be sent from within an ASYNC procedure. As the ASYNC procedure runs asynchronously to the device driver thread, this may collide with commands sent from a PUT procedure.

PROC ASYNC for JSON coded protocols

For JSON based protocols the definition of an asynchronous procedure starts with the keywords PROC ASYNC OBJECT, followed by an object path definition as used with the REST SET and REST PARSE statements. You find an extensive description about the JSON object model and object paths in chapter 2.2.6 REST I/O functions

proc-async-object.gif

The object path definition is terminated either by the keyword EXISTS or a = character and the reference value this JSON object gets compared to. The reference value may be a quoted string or the content of a driver variable. The procedure body gets executed if the JSON object defined by the object path contains a value equal to the reference value following the = character.

If the keyword EXISTS is used, the procedure gets executed if an object at the given location exists in the message, the value assigned to it doesn't care.

PROC ASYNC for SNMP protocols

With SNMP, PROC ASYNC TRAP may be used to process traps issued by a device. The syntax for this kind of procedure is as follows:

proc-async-trap.gif

The keywords PROC ASYNC TRAP are followed by the SNMP trap number and a pattern text. The SNMP trap calls this procedure if it has been issued from the IP address set for this device, the SNMP trap number matches the number stated with this procedure and the text submitted by the trap receiver contains the pattern text.

The trap receiver in the M&C software processes every trap it receives and translates it to a multiline string which is passed to the procedure(s) which are in charge for this trap. The first line of this string contains the trap type, the IP address from which it was issued, the trap number and the specific number. If there are SNMP varbinds with this trap, for each varbind a line follows with the OID and the value if this varbind.

Example:

V1TRAP from 127.0.0.1 trapno=6 specific=99
1.3.6.1.4.1.53491.550.2.3.19.0=-76.33
1.3.6.1.4.1.53491.550.2.3.24.0=2

The varbinds may be interpreted with INPUT statements in the procedure body:

PROC ASYNC TRAP 6 "53491.550.2.3.19.0"
    INPUT "53491.550.2.3.19.0=" TRM 10 inputLevel
    INPUT "53491.550.2.3.24.0=" TRM 10 XLT tLock inputLock

The procedure above gets called for a trap (6) containing a varbind ending on "53491.550.2.3.19.0". The value of this varbind gets assigned to the driver variable inputLevel. The varbind ending on "53491.550.2.3.24.0" is assigned to 'inputLock' after translating it from the SNMP number encoding to the value expected in the driver. Using OID fragements starting with the deivce's enterprise ID is a reliable way to identify varbind OIDs in the trap text.

Remarks