node-red-contrib-hcl-rtist-nodes v1.0.12

Node-RED Nodes for HCL RTist

Using HCL RTist with HCL NodePlus requires the use of three custom nodes, created by HCL, specifically for integrating HCL RTist and HCL NodePlus.

With NodePlus you can implement an application that communicates with an RTist application using either Node JS or Node-RED. In Node-RED you can use the built-in nodes "tcp in", "tcp out" and "tcp request" for making, receiving and responding to TCP requests. However, NodePlus makes this even easier by means of providing three Node-RED nodes which have been specifically designed for communicating with an RTist application. You find these nodes in the HCL section of the palette. The three nodes are:

• rtist request
• rtist receive

• rtist response

These nodes communicate with an RTist application through ports that are defined on the capsule that inherits from the TCPServer library capsule. For simplicity we will from now on refer to that capsule as the "TCPServer capsule".

To make this more concrete we will use a sample model as reference. Create this sample model in your workspace by doing File - New - Example, then expand the category UML Capsule Development and select the example TCPServer_TrafficLight. The example model makes use of the TCPServer library, so you should also import it into your workspace. Perform File - Import - General - Existing Projects Into Workspace and browse to the location of the TCPServer library (by default it�s located in /rsa_rt/tcpserver/LibTcpServer). Next you can build the sample model by building one of the TCs in the example project. The TC app_prebuilt.tcjs can be directly built on Windows with Visual Studio 2017 64 bit. For other platforms you have to follow the instructions on this page to build the TCPServer library first.

In the example, the top capsule has the following composite structure:

Here, the TCPServer capsule is called "MyTCPServer", and "lightControl" is the port we can use for communicating with the RTist application. We will use this example in the description of how the Node-RED nodes for RTist work.

HCL RTist request node

The rtist request node can be used to send or invoke an event into an RTist application. It has the following properties

Command Set this property to "Send" to perform an asynchronous sending of an event, and to "Invoke" to perform a synchronous invocation of an event (similar to a remote procedure call).

Has Output By default the rtist request node has no output, but if you set this property it will get one. A message with a JSON string as payload will be emitted on the output to inform whether the command was successfully performed or not. For example:

 "{"status":"ok", "msg":"Command sendEvent succeeded!"}"

If the Command property is set to "Invoke", and the reply event carries some data, then you should have an output on the node in order to access that data. The reply event is stored in a "result" property in the JSON that is output. For example:

{{"{"status":"ok", "msg":"Command invokeEvent succeeded!", "result": [
{ "event" : "activeLightReply" , "type" : "RTString" , "data" : "RTString\"Green\"" }
]}"}}

The "status" property is set to "error" in case the command failed for some reason. In that case the "msg" property contains a description of the reason for the failure.

Host This specifies the name or IP address of the machine where the RTist application is running.

TCP Port This specifies the TCP port which the RTist application uses. By default this port number is 9911, but this is a configuration property ("port") of the TCPServer library that can be overridden, see this page.

RTist Port This is the name of a capsule port in the RTist application. The event will be sent or invoked on this port. The specified port should exist on the TCPServer capsule, and it should have at least one Out event (In event in case the port is conjugated).

If you have already specified the Host and TCP Port and the RTist application is currently running there, NodePlus will provide you with a list of all ports that are available and you can then choose a port from that list instead of typing the port name manually.

Port Index If the specified capsule port is replicated (i.e. has non-single multiplicity), then you can specify the index of the port instance to which the event will be sent or invoked. Indices are zero-based and if you don�t specify a port index, and the port is replicated, the event will be broadcasted to all port instances.

Event This is the event to send or invoke to the specified capsule port in the RTist application.

If you have already specified the Host and TCP Port and the RTist application is currently running there, NodePlus will provide you with a list of all events that can be sent to the specified port, and you can then choose an event from that list instead of typing the event name manually.

Data

If the specified event has a data parameter you can specify the actual data value here. The data value should be specified using the default ASCII encoding of the data object to pass with the event. This encoding is on the same format as you for example see if tracing the event during a model debug session. For example, to send the integer value 14 with an event, specify the data value as "int 14".

Priority

The priority at which the event should be sent. The priority is only relevant when sending an event, not when invoking it.

Incoming Event

By default the event will be delivered to the RTist application as an outgoing event on the specified capsule port. This means it will be handled in the same way as if the TCPServer capsule would have sent or invoked the event as an outgoing event on that port. However, sometimes you may instead want to handle the event in the TCPServer capsule itself. In that case you should set this property so the event is delivered as an incoming event instead.

All the above properties can also be specified in the message payload on the input of the rtist request node. This is useful when some of the properties are unknown at design time, and only known at runtime. For example, assume you have a generic rtist request node in your Node-RED flow, which is configured for sending an event to a certain port in an RTist application. If the protocol that types that port has multiple events, you can leave out the specification of the event in the node editor, and instead set it as the payload of the incoming message. Thereby you can send several events using a single rtist request node.

For the TrafficLight example we can send both the "Red", "Green" and "Yellow" events by means of 3 inject nodes, and a single rtist request node:

All properties are specified in the rtist request node, except the event, which is specified in each inject node.

For a full specification of the JSON format that is used for specifying events to be sent or invoked, see this page,

HCL RTist receive node

The RTist receive node can be used for receiving events that are sent or invoked by an RTist application, and that get routed to a port on the TCPServer capsule. It has the following properties:

TCP Port

This specifies the TCP port which the RTist application will use for transmitting events that arrive on a TCPServer capsule port. By default this port number is 2234, but this is a configuration property ("remotePort") of the TCPServer library that can be overridden, this page. Note that if your Node-RED flow runs on a different machine than the RTist application, you also must override the configuration property "remoteHost" property since it by default is "localhost".

Each time an event arrives on a port on the TCPServer capsule, which is not handled by the RTist application itself, the event will be encoded into a JSON string and made available as the payload of the rtist receive node output. The format of this JSON string is described here. As you can see, the JSON format of events sent out from an RTist application is symmetrical with the JSON format of events sent in to an RTist application. This makes it possible to directly route the output of an rtist receive node to the input of an rtist request node. Thereby you can easily create a distributed real-time application that communicates via a Node-RED flow.

HCL Rtist response node

Each TCP request made to an rtist receive node must eventually lead to an appropriate response being sent for the request. The easiest way to do that is to use an rtist response node.

The payload on the input of the rtist response node will be sent as the response for the TCP request.

If the flow was triggered by the sending of an event from the RTist application, then the rtist response node can simply make an empty response: {{msg.payload = '{}'; // empty response }}

However, if the RTist application invoked the event, then you must send a response as the JSON encoding of that reply event (possibly including a reply data value). Here is an example:

{{
{"command" : "reply", "port" : "lightControl", "event" : "durationOfInactivityReply", "data" : "int 3"}
}}

Note: The RTist application will wait until the response has been sent, so it is important not to forget to always send a response for all TCP requests that are received.