Latest Build

Download Build 28 here.

Build 28 adds "Quick Scripts", which is a convenient way to run multiple RV-C commands. Typically you might use a Quick Script to send a set of configuration or test messages on the RV-C network. For example, if you want to set the network clock to a particular time, you could click on Quick Script, type the following line into the Quick Script editor, and click "Run".

SEND 1FFFE 07 12 25 03 12 00 00 FF

(This will set the clock to Noon, Christmas Day, 2007).

Attachment	Size
OmniScope.exe	176 KB

Comments, Messages, and Leading Spaces

Comments are very useful in a script, since they allow the programmer to record notes that explain the script or document its use. To create a comment, start the line with a colon (":").


: Example Script, Created 12/25/2007 by Martin Perlot
: This script doesn't really do anything!


Blank spaces at the beginning of a line are always ignored. In general, having extra blanks in a line is harmless.

If a line start with a quote character ("), the line will be displayed in the progress box. This character can also be used with an IF command. Values can also be displayed by enclosing their tags in square brackets.


DEFINE GENSTATUS 1FFDC [B1]
DEFINE GENTEMP 1FFDB [B2 *1.8 -40]
:Give the generator time to report
WAIT 5
"Generator Temperature = [GENTEMP] Degrees
IF [GENSTATUS == 0] {"The generator is stopped}


Note that the " symbol does not need a second closing symbol.

Two special items are defined for output. If [OSVERSION] is added to a quote command Omniscope adds the Omniscope version to the output. If [DATETIME] is added it adds the current date and time. Since the output window can be printed, this is an excellent tool for recording script operation.


"Quality Control Script
"Run on [DATETIME], using Omniscope [OSVERSION]


Hexadecimal

All numbers in a script must be in hexadecimal notation. This is the base-16 notation familiar to computer programmers, and it is much simpler to translate into and out of RV-C than ordinary decimal. This is because all RV-C data is encoded into packets with 8 bytes, with 8 bits in each packet. Hexadecimal is perfect for data grouped in this way.

If you are not familiar with hexadecimal, Windows includes a calculator that can quickly convert back and forth. Run Windows Calculator, and from the "View" menu select "Scientific". Then you can enter a number in decimal form and click "Hex" to see it in hexadecimal - and vice-versa.

For more help with hex, click on this tutorial.

Another key point when working with numbers in RV-C is that all RV-C values are "little endian". This mean that when a number spans more than one byte, the "least significant" byte comes first. This is the opposite of our normal decimal notation, where the "most significant", i.e. the biggest placevalue, comes first. For example, in the decimal number 321, the first digit is the hundreds place, and is the "most significant", while the last digit is the one place, and thus the "least significant".

If decimals were little-endian, we would write three hundred and twenty one as "123".

In hexadecimal, when we break down a large number such as 1FFD4 into it bytes, we start at the small end and work backwords. In this case we get D4 FF 01. As a convention, we will always use spaces to clearly indicate when we are working with bytes (in little endian).

Sending messages with SEND and CMD

The most basic use of a script is to send a message to the RV-C network. This is what the SEND command does. The syntax is simple: SEND PGN DATA. For example:


: Set date to 12/25
SEND 1FFFE FF 0C 19 FF FF FF FF FF
: Note: PGN 1FFFE is DATE_TIME_COMMAND.


If an acknowledgement is desired, the CMD command is used instead. This works just like SEND, but it then stops the script until a acknowlegement is received for the message. The user can click "Continue" or "Abort" if no acknowledgement is received.


: Start genset
CMD 1FFDA 01 FF FF FF FF FF FF FF
: Note: PGN 1FFDA is GENERATOR_COMMAND.


Most messages include eight data bytes. Sometimes a longer message is required - for example, for a PRODUCT_ID. To generate a "long message" - actually it is a series of messages - simply put more than eight data bytes in the DATA section. Omniscope automatically handles the long message protocols.

Watching Data - MONITOR and DEFINE

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.

Fxy - Flag, Byte x, Bits y, y+1.
Nxy - Nybble (4-bit), Byte x, Bits y thru y+3.
Bx - Byte
Wx - Word x, x+1
Lx - Long x thru x+3
P - The full PGN, expressed as a text string, including all eight bytes, with dot delimiters (e.g. 01.34.DA.00.FF.FF.FF.10)

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)"


Making Decisions - The "IF" Conditional

Sometimes a script needs to take different actions according to user input or what it finds on the network. This can be accomplished with the IF command.

The syntax is IF [tag == value] {command} The command can be any scripting command, and typically is a SEND or a GOTO. The tag must be already defined in a MONITOR, DEFINE, or CONSTANT statement, or it must be one of the predefined tags listed below. For example:


DEFINE PARKBRAKE 1FFF4 [F51]

@CHECKPARKBRAKE
: Get Chassis Mobility Status PGN
SEND EAFF F4 FF 01 FF FF FF FF FF
: Give a little time for a response
WAIT 1
IF [PARKBRAKE == 1] {GOTO STARTTEST}
"Please Set the Park Brake before continuing test.
PAUSE
: Check the park brake status again
GOTO CHECKPARKBRAKE

: This following part of the script won't execute unless the park brake is set
@STARTTEST

There are some special values used. N/D indicates "No Data", while Err indicates an RV-C error value. Note that there are no quotes around them.


DEFINE PARKBRAKE 1FFF4 [F51]
: If we haven't received a park brake signal, send a request
IF [PARKBRAKE == N/D] {SEND EAFF F4 FF 01 FF FF FF FF FF}


Sometimes instead of wanting to check if something is equal, we want the opposite. To check for inequality, we use the "!=" symbol.


DEFINE GENSTATUS 1FFDC [B1]
: request generator status
SEND EAFF DC FF 01 FF FF FF FF FF
: Stop the genset if it isn't already stopped
IF [GENSTATUS != 0] {SEND 1FFDA 00 FF FF FF FF FF FF FF}


You must be careful with floating point values, such as voltages or temperatures. These are calculated to three decimal places, and you must include all three in the comparison.

There are several special tags defined. These are listed in a separate entry.

Allowing User Input and Control - BUTTON and MENU

Sometimes a script needs user input - either to make choices or to trigger actions. Omniscope offers two particularly useful commands for this purpose.

The MENU command present the user with a menu, and records the user's response in the parameter list. The script can then examine PARAMS and take appropriate action.

The MENU syntax is MENU parameter "description" parameter "description" . . .

There may be any number of lines in the menu. For whichever line is chosen, the corresponding parameter is added to the parameter list. If no parameter is desired, use a single letter for the parameter.


: Set battery bank size
MENU LARGEBANK "Large Battery Bank" SMALLBANK "Small Battery Bank" X "Do Not Change Battery Size"
IF [PARAMS == LARGEBANK] {SEND 1FFC4 01 FF FF FF 00 04 FF FF}
IF [PARAMS == SMALLBANK] {SEND 1FFC4 01 FF FF FF 00 02 FF FF}


It is often smart to put a CLEARPARAMS command before the MENU command, especially if the script includes any loops.

The BUTTON command adds a line to the Monitor window which the user can click to trigger an action. It provides an easy way to create a "simulated control panel". The syntax is BUTTON "title" {command}

]
:A simple genset control panel
MONITOR GENSTATUS 1FFDC [B1] "Genset Status"
BUTTON "Start Generator" {SEND 1FFDA 01 FF FF FF FF FF FF FF}
BUTTON "Stop Generator" {SEND 1FFDA 00 FF FF FF FF FF FF FF}


The buttons stay active even after the script is complete, as does the entire contents of the Monitor window. Any command, including GOTO, can be triggered by a BUTTON.

Changing the Script Flow - GOTO, ABORT, LOOP, and EXECUTE

Sometimes a script needs to repeat itself or skip a section. This is done with the GOTO statement. It requires two statements.

First, a line must be named. This is done by starting the line with an @ sign, and continuing with a name. Then the GOTO statement is simply GOTO name.


GOTO scriptend
:
: This code will be skipped
:
@scriptend


The GOTO statement is usually used with an IF.


DEFINE GENSTATUS 1FFDC [B1]
@CHECKGEN
MAKE [GENSTATUS != N/D] BYSENDING EAFF DC FF 01 FF FF FF FF FF
IF [GENSTATUS == 0] {GOTO GEN_IS_OFF}
IF [GENSTATUS == 3] {GOTO GEN_IS_RUNNING}
IF [GENSTATUS == 5] {GOTO GEN_IS_FAULT}
WAIT 5
GOTO CHECKGEN
@GEN_IS_OFF
"Generator is Off.
GOTO SCRIPTEND
@GEN_IS_RUNNING
"Generator is Running.
GOTO SCRIPTEND
@GEN_IS_FAULT
"Generator is Faulting.
GOTO SCRIPTEND
@SCRIPTEND


The LOOP command is used to restart a script from scratch. It is not quite the same as a GOTO, in that the LOOP command clears the Monitor and Progress windows. It essentially is the equivalent of the user clicking the "Run Again" button.

The ABORT command ends the script. It also displays a message, if desired. This is typically used in an IF statement.


IF [MINVERSION != 1.00.28] {ABORT "Requires Omniscope 1.00.28 or more recent."}


The EXECUTE command allows the script to start another program. The syntax is EXECUTE "program" paramaters


DEFINE GENSTATUS 1FFDC [B1]
MAKE [GENSTATUS != N/D] BYSENDING EAFF DC FF 01 FF FF FF FF FF
:if genset in fault mode, start the troubleshooting program
IF [GENSTATUS == 5] {EXECUTE "GensetTroubleshooter.exe"}


The EXECUTE command cannot trigger the execution of another script, only a Windows program.

Forcing an RV-C Setting with MAKE

Often a script needs to make sure that an RV-C value is definitely set to a particular value. Merely sending a command isn't enough, because the target node may be temporarily off-line or impaired. To make sure that the script doesn't continue after the setting message has failed, the MAKE command is used.

The syntax is MAKE [tag == value] BYSENDING pgn data . It can also use the "!=" symbol, MAKE [tag != value] BYSENDING pgn data . The script will send the indicated message, and then it will pause the script until the expression is true. The user can click on the RETRY button to send the message again, the ABORT button to quit the script, or the CONTINUE button to continue the script even though the expression isn't satisfied.

The BYSENDING portion is optional. If the MAKE is used without the BYSENDING, the script merely pauses until the expression is true.


: This ensures the genset is off.
DEFINE GENSTATUS 1FFDC [B1]
MAKE [GENSTATUS == 0] BYSENDING 1FFDA 00 FF FF FF FF FF FF FF


Script Timing, PAUSE and WAIT

Normally Omniscope processes about 17 lines each second. It takes exactly as much time to execute any kind of command - including comments. Therefore, you can get a short pause in a script simply by adding a series of comments.

This can be important, since it takes time for devices to respond on the network. When monitoring devices on the network some care must be taken to ensure that the devices have had a chance to reply to commands and messages.

For example, the following script will not work reliably.


DEFINE GENSTATUS 1FFDC [B1]
IF [GENSTATUS == 0] {"The genset is off}


It will fail because the script only spends 1/17 of a second waiting for the generator status to come from the genset. But if the genset is off, it will only send the generator status once every five seconds. Most likely the GENSTATUS value is N/D when the script checks it.

You can force the script to wait for five seconds by inserting 65 blank lines, or by adding a WAIT command.


DEFINE GENSTATUS 1FFDC [B1]
: Wait for five seconds.
WAIT 5
IF [GENSTATUS == 0] {"The genset is off}


This will work much more reliably. Even more reliable is using the MAKE command, which is fully explained in its own entry.


DEFINE GENSTATUS 1FFDC [B1]
MAKE [GENSTATUS != N/D] BYSENDING EAFF DC FF 01 FF FF FF FF FF
IF [GENSTATUS == 0] {"The genset is off}


Sometimes a script needs to pause for the user to perform an action. The PAUSE command suspends the script until the user clicks on the "Continue" button.


DEFINE GENSTATUS 1FFDC [B1]
"Please Start the Genset and Click the Continue Button
PAUSE
IF [GENSTATUS == 0] {"The genset is still off}


Setting Message Priority and Source Address.

By default, Omniscope uses F9 (249) as the Source Address for all of its messages. Sometimes, however, a script may need to use a different address. This is accomplished using the SOURCE command. The syntax is simply SOURCE ADDRESS.


: Pretend we are a generator!
SOURCE 40


Omniscope does not claim the indicated address, and therefore this technique can be dangerous. If another device is on the network with that address, it is just possible to create a lock-up condition that could bring down the network.

Normally messages are sent with an RV-C priority of six - a low priority. To change that value, use the PRIORITY command.


: Use a higher priority to send future messages
PRIORITY 3


Priority is rarely important, except in extreme bus loading conditions.

Setting a Target.

Certain messages require a "target". In particular, RV-C defines a set of PGNs for "proprietary" messages - messages that are specific to a particular make and model. These messages have to be directed to that specific device - in contrast to most messages which are heard by every device on the network.

By default, the target is the device selected by the user in the Device List when they start the script. The script can change this using the TARGET command. It has two forms: TARGET ADDRESS and TARGET "name".


: Set target to the generator (address 40)
TARGET 40
SEND EFXX 00 00 00 00 00 00 00 00
: Set target to the ACME 2000
TARGET "ACME 2000"
SEND EFXX FF FF FF FF FF FF FF FF


When Omniscope encounters a SEND command with the EFXX PGN, it substitutes the target address for the XX's. Thus the first SEND command shown is equivalent to "SEND EF40 00 00 00 00 00 00 00 00".

Testing with SIMRX

The SIMRX command forces Omniscope to simulate receiving the indicated message. This is a useful technique for testing a script or a program. To test a script, you can simultaneously run another script that uses the SIMRX command to simulate real network traffic. Both scripts (and any other Omniscope modules running at the time) will receive the simulated data.

The syntax is SIMRX address pgn data . Note the addition of the simulated source address.


:Set up some buttons for testing a genset monitoring script
BUTTON "Simulate Gen Off" {SIMRX 40 1FFDC 00 FF FF FF FF FF FF FF}
BUTTON "Simulate Gen On" {SIMRX 40 1FFDC 01 FF FF FF FF FF FF FF}


Using Special Tags for Special Purposes

Usually the IF and MAKE commands are used to check data from the network before sending a message or taking an action. However, the script can also use other inputs to trigger a conditional statement.

You can define your own "constant" tag with the CONSTANT command. The format is CONSTANT TAG "VALUE" , and the effect is similar to a DEFINE command except that the value is set instead of being read from the network. The main use of the CONSTANT if for testing the script, but it can also be handy for simplifying long scripts.

The PARAMS tag provides the list of parameters specified in the scripts .rvc companion file. Sometimes it is useful to create one script for several purposes, and invoke the script with different .rvc files. Each version of the .rvc file would have different parameters listed. By checking this parameter list in the script, the same script can have multiple results.

When using PARAMS, the "==" and "!=" have a different meaning. [PARAMS == value] will be true if the value is anywhere within the parameter list.

For example, consider the following script:


: disable the indicated furnaces
IF [PARAMS == FURN1] {SEND 1FFE3 01 FC FF FF FF FF FF FF}
IF [PARAMS == FURN2] {SEND 1FFE3 02 FC FF FF FF FF FF FF}
IF [PARAMS == FURN3] {SEND 1FFE3 03 FC FF FF FF FF FF FF}


This script can be invoked with several different .rvc files, each with a Params line such as:


: Disable furnace 1 and furnace 2
Params = FURN1 FURN2


For testing purposes, Omniscope also includes several commands for working with the parameter list.

CLEARPARAMS empties the parameter list.

SETPARAMS param1 param2 ... adds the indicated parameters to the list.

ASKFORPARAMS brings up a box that allows the user to modify the parameter list.

Finally, the MENU command allows another way for the user to select parameters. It is explained in another section.

Other special tags include the following.

MINVERSION

This tag indicates the Omniscope verion require to run the script. As Omniscope evolves new features are often added to the scripting, and scripts that use the new features need to check whether the user is running an up-to-date version of Omniscope. Therefore, it is a good idea to start each script with:


IF [MINVERSION != 1.00.28] {ABORT "Needs version 1.00.28 or more recent"}


TARGETMODEL checks the PRODUCT_ID of the target node. The indicated value must be anywhere within the Model designation. Note that spaces are not allowed in the expression.


IF [TARGETMODEL != VMS440] {ABORT "Target must be a VMS 440 "}


TARGETMAKE is similar, but checks the Make designation (usually this is the manufacturer.)


IF [TARGETMAKE != SILVERLEAF] {ABORT "Target must be a SilverLeaf product"}


Creating an RV-C File.

If a module doesn't already have an .rvc file, one can be created easily. An .rvc file is a plain text file containing some information regarding the module and the devices it supports. The file can be created using Notepad or any program editor. (Word processors such as Word are trickier to use, since by default they want to add formatting information to the file that Omniscope can't read.)

A typical .rvc file looks like this:


Description = PowerTech Configuration Tool
File = PowerTechTool.exe
Address = 64
DefAddress = 64
Make = POWERTECH
EOF
Revised 12/25/07


Each line has a similar syntax, except the EOF. The EOF indicates "end of file" - any text after the EOF is ignored. Each line consists of a variable name, an equal sign, and a value associated with that name. The meaning of each variable is as follows:

Description - The value indicates the text that will be shown in Omniscope's Module Box, and is how the user will see the module. This should be as descriptive as possible.

File - The value indicates the name of the program to be run. This must be a Windows executable (.exe) file.

Script - The value indicates the name of the script to be run. This must be a valid Omniscope (.scp) file. Only one module (file and/or script) can be used in an .rvc file.

Address - This determines what source address the device must have to be associated with the module. This can be a specific address, or a range such as 0-255. Note that in most cases a device's address is unpredictable. An Address value must always be supplied - use 0-255 if any address is acceptable.

DefAddress - This determines what DSA (default source address) the device must have to be associated with the module. This can be a specific address, or a range such as 0-255. The DSA identifies the general type of device (e.g. inverter, generator), but it does not indicate the manufacturer. A DefAddress value must always be supplied - use 0-255 if any product type is acceptable.

Make - This associates the module to a specific Make, as broadcast in the device's PRODUCT_ID. The match must be exact, but question marks can be used as "wildcards" to allow an inexact match.

Model - This associates the module to a specific Model, as broadcast in the device's PRODUCT_ID. The match must be exact, but question marks can be used as "wildcards" to allow an inexact match. This technique is useful for identifying a family of products or version numbers. For example, "Make = QD??" would match a QD12, QD15, or QD18. It would not match with QD9, however, since the length is not the same.

Node designers thus are advised to be consistent in the naming of their products models when devising their PRODUCT_IDs.

SN - This associates the module to a specific serial number, as broadcast in the device's PRODUCT_ID. Like Make and Model, question marks can be used as "wildcards" to allow an inexact match.

ID - This associates the module to a specific ID number, as broadcast in the device's PRODUCT_ID. Like Make and Model, question marks can be used as "wildcards" to allow an inexact match.

Params - If the module is a Windows .exe file, this value provides a set of command-line parameters that the program may require. If the module is an Omniscope Script, this value becomes the parameter list that the script can examine using the PARAMS tag. This makes it possible to use the same script for multiple purposes, or to make certain parts of a script optional. Note that any module can have multiple .rvc files associated with it. Creating several .rvc files with different parameters that all activate the same module is often simpler and easier than making multiple modules.

Message - This value is used to merely send a message, rather than start a module. For example, the following .rvc file allows the technician to start the generator from Omniscope without starting a module.


Description = Start Generator
Address = 0-255
DefAddress = 64
Message = 1FFDA 01 FF FF FF FF FF FF
EOF
(note: the DSA for a genset is 64)


Command - This is the same as Message, but Omniscope also waits for an acknowledgement of the command.

When working with .rvc files, note that Omniscope reads all the .rvc file in its directories when it starts up. Changes made to the files after Omniscope has already started won't be reflected in the program. After adding or changing an .rvc file, shut down and restart Omniscope to see the effects of the changes.