Often a script needs to watch a particular data item, and either display it for the user or make sure it has a particular value. For example, a script may need to make sure the generator is not running before continuing.
To accomplish this, the script first must define the data items it is to watch. This is done with the DEFINE command. It requires a thorough knowledge of the RV-C documentation to use this command.
DEFINE tag pgn:instance [datum *multiplier, +/-offset]
The tag is the name that will be used to refer to this data item, e.g. GENSTATUS. It cannot contain any spaces. The PGN refers to the RV-C parameter group that contains the data item, and if the PGN supports multiple instances, the instance number is required. The datum indicates both the data type and its location within the PGN. The multiplier and offset are used when the data item requires mathematical conversion.
The DATUM field has the following forms. The x and y parameters indicate the location within the PGN. Both are indexed starting at 1, so F11 is the first flag in the first byte of the PGN, while B8 is the last byte of the data packet.
For example,
: Genset Operating Status
DEFINE GENSETSTATUS 1FFDC [B1]
: Genset Engine Load
DEFINE GENSETLOAD 1FFDC [B6 *0.5]
: Furnace #1 Operating Mode
DEFINE FURN1MODE 1FFE4:01 [F21]
: Thermostat #1 Set Point Heat (in Celsius)
DEFINE THERM1HEAT 1FFE2:01 [W4 *0.03125 -273]
If the PGN is the DM1 (FECA), then the Instance refers to the DSA field of the DM1.
To display the value in the Monitor window, substitute the MONITOR command for the DEFINE. The MONITOR command is almost identical:
MONITOR tag pgn:instance [datum *multiplier, +/-offset] "Text"
The "text" indicates how the data item will be displayed in the window, and has no bearing on the tag. You may add spaces in the "text", but not in the tag.
: Thermostat #2 Cool Point
MONITOR THERM2COOL 1FFE2 [W6 *0.03125 -273] "Cool Point #2 (Celsius)"