SHIP:Node:linkvar

From Serious Documentation
Jump to: navigation, search

Node Home

Node Type Description
linkvar Describes shared variables on the given linkset.


A linkvar nodes describe shared variables on the given linkset. linkvars always have the name and datatype property, but other properties may be available depending on the protocol selected.

Parent Nodes

The following nodes are permitted to hold this node:

Child Nodes

The following nodes are permitted to exist within this node:

Properties

Property Data Type Description
name** String The name used to identify this node in SHIPTide.
address Short Most Protocols require each variable to have a unique address/location/id number assigned
datatype** DataType linkvar's must have specific data types (e.g. Boolean); allowable types are Protocol dependent.
direction** LINKDIR Most Protocols need to understand if this is an input or output variable
value see datatype The value of the link variable.
enabled* Boolean If true (default), polling or output messages when changed are enabled.
priority

Only for A Protocol describes the packetization and method for moving data back and forth across that physical layer. SHIP supports three protocols, though not all protocols are supported across all available physical layers on a SIM:

*available at SHIPEngine run time only and cannot be set in SHIPTide. Use a Sail script at shiplaunch time if this property needs to be set when the GUI starts to run.
**available only in SHIPTide; cannot be accessed from Sail scripts at run-time.

The direction can be a bit confusing: it is always with respect to SHIPEngine. So an "output" direction means the data is supplied by SHIPEngine to the remote end of the linkset, regardless of whether the linkset is a master or slave in a master/slave environment. Similarly, and "input" direction means that the data is coming into the variable from the remote end of the linkset. Remember that "in" and "out" are with respect to your GUI in SHIPEngine.

Examples

Our example here is, perhaps, a hypothetical GUI controlling a pump. Our GUI (in a Sail script) could turn on the pump by setting the pumpOnRequest output Boolean linkvar to "true". Since Modbus masters poll their slaves, the next time the master polls slave #1 address 0x4000 ("pumpOnRequest", a Boolean), it will read a "true" at that shared variable location, indicating to the master (the pump) to turn on. It may also poll slave #1 address 0x2000 ("pumpRPMRequest", a Short) to determine the requested RPM before turning the pump on. It may continue to poll these two locations to watch for a request to stop the pump or change the RPM. Also, as the pump turns on and off, and its actual RPM changes, it may send those values to slave#1 address 0x4001 ("pumpOn", a Boolean) and 0x2002 ("pumpRPM", a Short) respectively.

Example linkset with four link variables (linkvars)

Note that just because the GUI "requests" that a remote device performs some action does not mean the remote device actually does it. The GUI (in a Sail script) might request the pump turn on, but it may not happen for whatever reason (the pump is overheated, for example). Timeouts and other mechanisms can be done in the GUI to watch for these conditions.

A good practice is to have visual indicators on the GUI reflect the actual remote state, rather than the requested state. For example, an RPM reading in the GUI should reflect the value of "pumpRPM", not "pumpRPMRequest".