Tool Configuration

Please see Telemetry Screen Configuration for instructions on configuring Telemetry Viewer. Please see Telemetry Grapher Configuration for instructions on configuring Telemetry Grapher.


Launcher Configuration

Launcher configuration files define the icons and buttons presented in the Launcher and define how programs are launched. These files are expected to be placed in the config/tools/launcher directory and have a .txt extension. The default configuration file is named launcher.txt.

To specify a different configuration file add ‘–config launcher.txt’ when starting the Launcher. For example, on Windows create a new Batch file at the top of your COSMOS configuration that looks like the following:

call tools\Launcher.bat --config launcher_config.txt

On Linux create a new executable file at the top of your COSMOS configuration that looks like the following:

ruby tools\Launcher --config launcher_config.txt

Keywords:

TITLE

The TITLE keyword changes the title of the COSMOS Launcher.

Parameter Description Required
Title Launcher title. Defaults to "COSMOS Launcher" without this keyword. Yes

Example Usage:

TITLE 'Program Launcher'

TOOL_FONT

The TOOL_FONT keyword sets the font used for tool buttons. It should only be used once as the last encountered setting will apply to all button labels. The default font if this keyword is not used is 12px Arial.

Parameter Description Required
Font Family The font family to use. Valid choices are "Arial", "Calibri", "Cambria", "Candara", "Castellar", "Centaur", "Century", "Chiller", "Consolas", "Constantia", "Courier", "Courier New", "Dotum", "Elephant", "Euphemia", "Fixedsys", "Georgia", "Impact", "Lucida", "Papyrus", "Rockwell", "Rod", "System", "Tahoma", "Terminal", "Times New Roman", "Verdana", "Wide Latin". Yes
Font Size The size of the font in standard points. Yes

Example Usage:

TOOL_FONT Courier 10

LABEL_FONT

The LABEL_FONT keyword sets the font used for labels. It should only be used once as the last encountered setting will apply to all labels. The default font if this keyword is not used is 16px Tahoma.

Parameter Description Required
Font Family The font family to use. Valid choices are "Arial", "Calibri", "Cambria", "Candara", "Castellar", "Centaur", "Century", "Chiller", "Consolas", "Constantia", "Courier", "Courier New", "Dotum", "Elephant", "Euphemia", "Fixedsys", "Georgia", "Impact", "Lucida", "Papyrus", "Rockwell", "Rod", "System", "Tahoma", "Terminal", "Times New Roman", "Verdana", "Wide Latin". Yes
Font Size The size of the font in standard points. Yes
Example Usage:
LABEL_FONT Arial 20

LABEL

The LABEL keyword creates a label of text in the current font style.

Parameter Description Required
Text The text of the label. Yes

Example Usage:

LABEL Utilities

DIVIDER

The DIVIDER keyword creates a horizontal line between tools. It takes no parameters and is purely for decoration.

NUM_COLUMNS

The NUM_COLUMNS keyword specifies how launcher buttons should be created per row in the GUI. The default is 4.

Parameter Description Required
Columns The number of launcher buttons per row before Launcher automatically creates a new row of buttons. Yes

TOOL

The TOOL keyword specifies one tool that can be launched. The syntax varies if it is being used standalone or for a multi-tool.

Syntax when standalone:

Parameter Description Required
Button Text Label that is put on the button that launches the tool Yes
Shell Command Command that is executed to launch the tool. (The same thing you would type at a command terminal). Note that you can include tool parameters here which will be applied when the tool starts. Yes
Icon Filename Filename of a an icon located in the data directory. Passing 'nil' or an empty string '' will result in Launcher using the default COSMOS icon. No
Tool Parameters Tool parameters as you would type on the command line. Specifying parameters here rather than in "Shell Command" will cause a dialog box to appear which allows the user to edit parameters if desired. Expected to be in parameter name/parameter value pairs. i.e. —config filename.txt. NOTE: The full configuration option name must be used rather than the short name. NOTE: These parameters will override any parameters specified in the Shell Command. Also, multiple options can be specified by seperating options with a pipe character | No

Example Usage:

TOOL "Command and Telemetry Server" "RUBYW tools/CmdTlmServer" cts.png --config cmd_tlm_server.txt
TOOL "Script Runner" "RUBYW tools/ScriptRunner" nil --width 600 --height 800

Syntax when used within the MULTITOOL keywords:

Parameter Description Required
Shell Command Command that is executed to launch the tool. (The same thing you would type at a command terminal) Yes

Example Usage: See MULTITOOL_START

MULTITOOL_START

The MULTITOOL_START keyword starts the creation of a single icon/button that will launch multiple tools.

Parameter Description Required
Button Text Label that is put on the button that launches the tools Yes
Icon Filename Filename of a an icon located in the data directory. Passing 'nil' or an empty string '' will result in Launcher using the default COSMOS icon. No
Example Usage:
MULTITOOL_START "COSMOS"
  TOOL "RUBYW tools/CmdTlmServer -x 827 -y 2 -w 756 -t 475 -c cmd_tlm_server.txt"
  DELAY 5
  TOOL "RUBYW tools/TlmViewer -x 827 -y 517 -w 424 -t 111"
MULTITOOL_END

MULTITOOL_END

The MULTITOOL_END keyword ends the creation of a multi-tool button.

Example Usage: See MULTITOOL_START

DELAY

The DELAY keyword inserts a delay between launching multiple tools. It is only valid within the MULTITOOL keywords.

Parameter Description Required
Delay Time to delay in seconds Yes

Example Usage: See MULTITOOL_START

Example File

Example File: <Cosmos::USERPATH>/config/tools/launcher/launcher.txt

TITLE "Demo Launcher"
FONT tahoma 12
NUM_COLUMNS 4
MULTITOOL_START "COSMOS" NULL
 TOOL "RUBYW tools/CmdTlmServer -x 827 -y 2 -w 756 -t 475 -c cmd_tlm_server.txt"
 DELAY 5
 TOOL "RUBYW tools/TlmViewer -x 827 -y 517 -w 424 -t 111"
 TOOL "RUBYW tools/PacketViewer -x 827 -y 669 -w 422 -t 450"
 TOOL "RUBYW tools/ScriptRunner -x 4 -y 2 -w 805 -t 545"
 TOOL "RUBYW tools/CmdSender -x 4 -y 586 -w 805 -t 533"
MULTITOOL_END
TOOL "Command and Telemetry Server" "RUBYW tools/CmdTlmServer" "cts.png" --config cmd_tlm_server.txt
TOOL "Limits Monitor" "RUBYW tools/LimitsMonitor" "limits_monitor.png"
DIVIDER
LABEL "Commanding and Scripting"
TOOL "Command Sender" "RUBYW tools/CmdSender" "cmd_sender.png"
TOOL "Script Runner" "RUBYW tools/ScriptRunner" "script_runner.png"
TOOL "Test Runner" "RUBYW tools/TestRunner" "test_runner.png"
DIVIDER
LABEL Telemetry
TOOL "Packet Viewer" "RUBYW tools/PacketViewer" "packet_viewer.png"
TOOL "Telemetry Viewer" "RUBYW tools/TlmViewer" "tlm_viewer.png"
TOOL "Telemetry Grapher" "RUBYW tools/TlmGrapher" "tlm_grapher.png"
TOOL "Data Viewer" "RUBYW tools/DataViewer" "data_viewer.png"
DIVIDER
LABEL Utilities
TOOL "Telemetry Extractor" "RUBYW tools/TlmExtractor" "tlm_extractor.png"
TOOL "Command Extractor" "RUBYW tools/CmdExtractor" "cmd_extractor.png"
TOOL "Handbook Creator" "RUBYW -Ku tools/HandbookCreator" "handbook_creator.png"
TOOL "Table Manager" "RUBYW tools/TableManager" "table_manager.png"

Limits Monitor Configuration

Limits Monitor has the ability to ignore telemetry items and no longer monitor them for transition to the yellow and red state. This is useful for known telemetry item configuration problems. Note that while telemetry items may be ignored in Limits Monitor, their states are still being recorded by the Command and Telemetry Server.

Keywords:

IGNORE_ITEM

The IGNORE_ITEM keyword instructs Limits Monitor to ignore a particular telemetry item when reporting the overall system limits state.

Parameter Description Required
Target Name Name of the telemetry target Yes
Packet Name Name of the telemetry packet Yes
Item Name Name of the telemetry item Yes

Example Usage:

IGNORE_ITEM INST HEALTH_STATUS TEMP1
IGNORE_ITEM INST HEALTH_STATUS TEMP2

IGNORE_PACKET

The IGNORE_PACKET keyword instructs Limits Monitor to ignore all telemetry items for a specified packet when reporting the overall system limits state.

Parameter Description Required
Target Name Name of the telemetry target Yes
Packet Name Name of the telemetry packet Yes

Example Usage:

IGNORE_PACKET INST HEALTH_STATUS

IGNORE_STALE (COSMOS >= 4.0)

The IGNORE_STALE keyword instructs Limits Monitor to ignore the staleness of a specified packet when reporting the overall system limits state. Note that only packet staleness is ignored; if the packet is received and an item is out-of-limits, that will still count against the overal system limits state unless the item or packet is separately ignored with the IGNORE_ITEM or IGNORE_PACKET keyword.

Parameter Description Required
Target Name Name of the telemetry target Yes
Packet Name Name of the telemetry packet Yes

Example Usage:

IGNORE_STALE INST HEALTH_STATUS

COLOR_BLIND

The COLOR_BLIND keyword instructs Limits Monitor to use a color-blind accessibility mode. In this mode, the value for out-of-limits items have a code appended to indicate the limits status. The code is r = red low, y = yellow low, g = green low, B = blue, G = green or green high, Y = yellow high, R = red high.

Example Usage:

COLOR_BLIND

IGNORE_OPERATIONAL_LIMITS

The IGNORE_OPERATIONAL_LIMITS keyword instructs Limits Monitor to ignore GREEN_HIGH or GREEN_LOW limits states for items that have operational limits defined. If this keyword is used, items with operational limits will only show up in limits monitor if they go yellow or red.

Example Usage:

IGNORE_OPERATIONAL_LIMITS

Script Runner Configuration

The Script Runner Configuration File affects both the Script Runner tool and the Test Runner tool. It defines where to look for procedures and other scripting settings. The configuration file is named script_runner.txt.

Keywords:

LINE_DELAY

The LINE_DELAY keyword specifies the amount of time in seconds before the next line of a script will be executed. This allows the user to easily watch as a script progresses.

Parameter Description Required
Delay Delay in seconds before the next line is executed. A value of 0 means to execute the scripts as fast as possible. Yes

Example Usage:

LINE_DELAY 1.0 # Delay for 1 second between lines

MONITOR_LIMITS

The MONITOR_LIMITS keyword specifies that Script Runner should log limits events while a script is running. These limit evens will be printed in the script runner log file. Note that this has no effect of the Command and Telemetry Server which always logs limits events.

PAUSE_ON_RED

The PAUSE_ON_RED keyword specifies that Script Runner should pause a running script if a red limit occurs

Example File

Example File: <Cosmos::USERPATH>/config/tools/script_runner/script_runner.txt

LINE_DELAY 0.1
MONITOR_LIMITS
PAUSE_ON_RED

Telemetry Extractor Configuration

Telemetry Extractor configuration files define what telemetry points that telemetry extractor should pull out of a log file. These files are expected to be placed in the tools/config/tlm_extractor directory and have a .txt extension. The default configuration file is named tlm_extractor.txt.

Keywords:

DELIMITER

The DELIMITER keyword specifies an alternative column delimiter over the default of a tab character.

Parameter Description Required
Delimiter Character or string to use as a delimiter. For example ','. Yes

Example Usage:

DELIMITER ','

FILL_DOWN

The FILL_DOWN keyword causes Telemetry Extractor it to insert a value into every row of the output. For example, if you have the following telemetry extractor configuration file:

ITEM INST HEALTH_STATUS PKTID
ITEM INST HEALTH_STATUS COLLECTS
ITEM INST ADCS POSX
ITEM INST ADCS POSX

Your normal output might look something like this:

TARGET PACKET PKTID COLLECTS POSX POSX
INST ADCS -579296 -579296
INST HEALTH_STATUS 1 0
INST ADCS -578683 -578683

with FILL_DOWN enabled it would like this this:

TARGET PACKET PKTID COLLECTS POSX POSX
INST ADCS -579296 -579296
INST HEALTH_STATUS 1 0 -579296 -579296
INST ADCS 1 0 -578683 -578683

Note that in the second INST ADCS packet the PKTID and COLLECTS values are “filled down” even though they were not present in that packet. This makes it easier to graph multiple values across packets in Excel.

DOWNSAMPLE_SECONDS

The DOWNSAMPLE_SECONDS keyward causes Telemetry Extractor to downsample data to only output a value every X seconds of time.

Parameter Description Required
Seconds Number of seconds to skip between values output Yes

Example Usage:

DOWNSAMPLE_SECONDS 5

MATLAB_HEADER

The MATLAB_HEADER keyword cause Telemetry Extractor to prepend the Matlab comment symbol of ‘%’ to the header lines in the output file.

UNIQUE_ONLY

The UNIQUE_ONLY keyword causes Telemetry Extractor to only output a row if one of the extracted values has changed. This can be used to extract telemetry items over a large time period by only outputting those values where items have changed.

UNIQUE_IGNORE

The UNIQUE_IGNORE keyword is used in conjunction with UNIQUE_ONLY to control which items should be checked for changing values. This list of telemetry items (not target names or packet names) always includes the COSMOS metadata items named RECEIVED_TIMEFORMATTED and RECEIVED_SECONDS. This is because these items will always change from packet to packet which would cause them to ALWAYS be printed if UNIQUE_ONLY was used. To avoid this, but still include time stamps in the output, UNIQUE_IGNORE includes these items. If you have a similar telemetry item that you want to display in the output, but not be used to determine uniqueness, use this keyword.

Parameter Description Required
Item Name Name of the item to exclude from the uniqueness criteria (see above). Note that all items with this name in all target packets are affected. Yes

SHARE_COLUMNS

The SHARE_COLUMNS keyword causes Telemetry Extractor to put telemetry items with the same name into the same column in the output. For example if you have the following configuration file:

ITEM INST HEALTH_STATUS PKTID
ITEM INST ADCS PKTID

Your normal output would look something like this:

TARGET PACKET PKTID PKTID
INST ADCS 1
INST HEALTH_STATUS 1
INST ADCS 1

Note how both telemetry packets got their own unique PKTID column. With SHARE_COLUMNS enabled you would get something like this:

TARGET PACKET PKTID
INST ADCS 1
INST HEALTH_STATUS 1
INST ADCS 1

Note how both packets share the one PKTID column. This applies to all telemetry items with identical names. If you want to share columns for only specific items, use the SHARE_COLUMN keyword instead.

SHARE_COLUMN (COSMOS >= 3.9.2)

The SHARE_COLUMN keyword causes Telemetry Extractor to put specific telemetry items with the same name into the same column in the output. This is similar to the behavior of the SHARE_COLUMNS keyword, except it is used to share individual items instead of all items. The SHARE_COLUMN keyword can be used multiple times to share different common items.

Parameter Description Required
Item Name Name of the telemtry item Yes
Item Type RAW, FORMATTED, or WITH_UNITS (CONVERTED is implied if the parameter is omitted) No

For example, if you have the following telemetry extractor configuration file:

SHARE_COLUMN TIMESECONDS
ITEM INST HEALTH_STATUS TIMESECONDS
ITEM INST ADCS TIMESECONDS
ITEM INST HEALTH_STATUS PKTID
ITEM INST ADCS PKTID

Your output would look something like this:

TARGET PACKET TIMESECONDS PKTID PKTID
INST ADCS 1234567 1
INST HEALTH_STATUS 1234568 1
INST ADCS 1234569 1

Note how both packets share the same TIMESECONDS column, but each packet has its own PKTID column.

FULL_COLUMN_NAMES (COSMOS >= 3.9.2)

The FULL_COLUMN_NAMES keyword causes Telemetry Extractor to use TARGET PACKET ITEM as the column header for each column instead of just ITEM. Note that the common TARGET and PACKET columns are not generated when this mode is active. For example if you have the following configuration file:

ITEM INST HEALTH_STATUS PKTID
ITEM INST ADCS PKTID

Your normal output would look something like this:

TARGET PACKET PKTID PKTID
INST ADCS 1
INST HEALTH_STATUS 1
INST ADCS 1

Note that the TARGET and PACKET information is catpured in common TARGET and PACKET columns, but the PKTID column names are not fully qualified. With FULL_COLUMN_NAMES enabled you would get something like this:

INST HEALTH_STATUS PKTID INST ADCS PKTID
1
1
1

Note that there are no TARGET or PACKET columns, but the column names include TARGET and PACKET instead.

DONT_OUTPUT_FILENAMES

The DONT_OUTPUT_FILENAMES keyword prevents Telemetry Extractor from outputing the list of input filenames at the top of each output file.

TEXT

The TEXT keyword allows you to place arbitrary text in the Telemetry Extractor output. It also allows you to dynamically create Excel formulas using a special syntax.

Parameter Description Required
Header The column header text Yes
Text Text to put in the output file. The special character '%' will be translated to the current row of the output file. This is useful for Excel formulas which need a reference to a cell. Remember the first two columns are always the TARGET and PACKET and telemetry items start in column 'C' in Excel. Yes

Example Usage:

TEXT "Calc" "=C%*D%" # Excel will calculate the C column times the D column

ITEM

The ITEM keyword specifies a telemetry item to extract.

Parameter Description Required
Target Name Name of the telemetry target Yes
Packet Name Name of the telemetry packet Yes
Item Name Name of the telemetry item Yes
Item Type RAW, FORMATTED, or WITH_UNITS (CONVERTED is implied if the parameter is omitted) No

Example File

Example File: <Cosmos::USERPATH>/config/tools/tlm_extractor/tlm_extractor.txt

FILL_DOWN
MATLAB_HEADER
DELIMITER ","
SHARE_COLUMNS
DOWNSAMPLE_SECONDS 5

DONT_OUTPUT_FILENAMES

UNIQUE_ONLY
UNIQUE_IGNORE TEMP1
ITEM INST HEALTH_STATUS TIMEFORMATTED
ITEM INST HEALTH_STATUS TEMP1 RAW
ITEM INST HEALTH_STATUS TEMP2 FORMATTED
ITEM INST HEALTH_STATUS TEMP3 WITH_UNITS
ITEM INST HEALTH_STATUS TEMP4
TEXT "Calc" "=D%*G%" # Calculate TEMP1 (RAW) times TEMP4

Test Runner Configuration

Test Runner configuration files define what tests should be run with what options. These files are expected to be placed in the tools/config/test_runner directory and have a .txt extension. The default configuration file is named test_runner.txt.

Keywords:

LOAD_UTILITY

The LOAD_UTILITY keyword specifies a test procedure to run. This procedure will be found automatically in the procedures directory or can be given by a path relative to the COSMOS install directory or by an absolute path. This keyword is used to load the script and execute it line by line by showing the current execution point. Sometimes you want to load utility code that is NOT executed line by line but is executed in the background. For example, a CRC routine or other long running calculation. The Ruby keyword ‘load’ can be used for this purpose, e.g. ‘load utility.rb’. This code will be loaded but not shown when executing.

Parameter Description Required
Filename Name of the test file in quotes Yes

Example Usage:

LOAD_UTILITY 'example_test.rb'
LOAD_UTILITY '../../example_test.rb' # Relative path from the base of the COSMOS configuration
LOAD_UTILITY 'C:/procedures/example_test.rb' # Absolute path (not cross platform)

REQUIRE_UTILITY

This keyword behaves exactly like LOAD_UTILITY and has been deprecated.

RESULTS_WRITER

The RESULTS_WRITER keyword allows you to specify a different Ruby file to interpret and print the Test Runner results. This file must define a class which implements the Cosmos::ResultsWriter API.

Parameter Description Required
Filename Name of the Ruby file which implements a results writer Yes
Class Parameters Parameters to pass to the constructor of the results writer Class specific

Example Usage:

RESULTS_WRITER my_results_writer.rb

ALLOW_DEBUG

Whether to allow the user to enable the debug line where the user can enter arbitrary statements.

PAUSE_ON_ERROR

The PAUSE_ON_ERROR keyword sets or clears the pause on error checkbox. If this is checked, Test Runner will pause if the test encounters an error. Otherwise the error will be logged but the script will continue.

Parameter Description Required
True or False Whether to pause when the script encounters an error Yes

Example Usage:

PAUSE_ON_ERROR TRUE # default

CONTINUE_TEST_CASE_AFTER_ERROR

The CONTINUE_TEST_CASE_AFTER_ERROR keyword sets or clears the continue test case after error checkbox. If this is checked, Test Runner will continue executing the current test case after encountering an error. Otherwise the test case will stop at the error and the next test case will execute.

Parameter Description Required
True or False Whether to continue the test case when the script encounters an error Yes

Example Usage:

CONTINUE_TEST_CASE_AFTER_ERROR TRUE # default

ABORT_TESTING_AFTER_ERROR

The ABORT_TESTING_AFTER_ERROR keyword sets or clears the abort testing after error checkbox. If this is checked, Test Runner will stop executing after the current test case completes (how it completes depends on CONTINUE_TEST_CASE_AFTER_ERROR). Otherwise the next test case will execute.

Parameter Description Required
True or False Whether to continue to the next test case when the script encounters an error Yes

Example Usage:

ABORT_TESTING_AFTER_ERROR FALSE # default

MANUAL

The MANUAL keyword sets the $manual global variable for all executing scripts. This variable can be checked during tests to allow for fully automated tests if it is not set, or for user input if it is set.

Parameter Description Required
True or False Whether to set the $manual global to true Yes

Example Usage:

MANUAL TRUE # default

LOOP_TESTING

The LOOP_TESTING keyword sets or clears the loop testing checkbox. If this is checked, Test Runner will continue to run whatever level of tests that were initially started. If either “Abort Testing after Error” or “Break Loop after Error” are checked, then the loop testing will stop if an error is encountered. The difference is that the “Abort Testing after Error” will stop testing immediately after the current test case completes. “Break Loop after Error” continues the current loop by executing the remaining suite or group before stopping. In the case of executing a single test case the options effectively do the same thing.

Parameter Description Required
True or False Whether to loop the selected test level Yes

Example Usage:

LOOP_TESTING FALSE # default

BREAK_LOOP_AFTER_ERROR

The BREAK_LOOP_AFTER_ERROR keyword sets or clears the break loop after error checkbox. If this is checked, Test Runner continues the current loop by executing the remaining suite or group before stopping.

Parameter Description Required
True or False Whether to break the loop after encountering an error Yes

Example Usage:

BREAK_LOOP_AFTER_ERROR FALSE # default

IGNORE_TEST

The IGNORE_TEST keyword ignores the given test class name when parsing the tests.

Parameter Description Required
Test Class Name The test class to ignore when building the list of available tests Yes

Example Usage:

IGNORE_TEST ExampleTest

IGNORE_TEST_SUITE

The IGNORE_TEST_SUITE keyword ignores the given test suite name when parsing the tests.

Parameter Description Required
Test Suite Name The test suite to ignore when building the list of available test suites Yes

Example Usage:

IGNORE_TEST_SUITE ExampleTestSuite

CREATE_DATA_PACKAGE

The CREATE_DATA_PACKAGE keyword creates a data package of every file created during the test.

Example Usage:

CREATE_DATA_PACKAGE

AUTO_CYCLE_LOGS

The AUTO_CYCLE_LOGS automatically starts a new server message log and cmd/tlm logs at the beginning and end of each test. Very useful when coupled with the CREATE_DATA_PACKAGE keyword.

Example Usage:

AUTO_CYCLE_LOGS

COLLECT_META_DATA

The COLLECT_META_DATA keyword tells TestRunner to prompt for Meta Data before starting tests.

Parameter Description Required
Target Name Meta Data Target Name Yes
Packet Name Meta Data Packet Name Yes

Example Usage:

COLLECT_META_DATA META DATA

Script Runner Configuration Keywords

Test Runner also responds to all the keywords in the Script Runner Configuration.

Example File

Example File: <Cosmos::USERPATH>/config/tools/test_runner/test_runner.txt

REQUIRE_UTILITY example_test
ALLOW_DEBUG
PAUSE_ON_ERROR TRUE
CONTINUE_TEST_CASE_AFTER_ERROR TRUE
ABORT_TESTING_AFTER_ERROR FALSE
MANUAL TRUE
LOOP_TESTING TRUE
BREAK_LOOP_AFTER_ERROR TRUE
IGNORE_TEST ExampleTest
IGNORE_TEST_SUITE ExampleTestSuite

CREATE_DATA_PACKAGE
COLLECT_META_DATA META DATA

LINE_DELAY 0
MONITOR_LIMITS
PAUSE_ON_RED

Test Runner Usage Notes

Arbitrary text can be written to the test report using the following syntax:

Cosmos::Test.puts "This test verifies requirement 2"

You can determine the currently executing suite/group/case using the following syntax:

Cosmos::Test.current_test_suite
Cosmos::Test.current_test_group
Cosmos::Test.current_test_case

Table Manager Configuration (COSMOS >= 3.9)

Table definition files define the binary table format so the Table Manager tool knows how to create, load, and display the binary data file. Table definition files are expected to be placed in the config/tools/table_manager directory and have a .txt extension. NOTE: Table Manager was revised in COSMOS 3.9 to better match the structure of the command and telemetry definitions and thus the configurations files are NOT backwards compatible.

Keywords:

TABLEFILE

The TABLEFILE keyword specifies another file to open and process for table definitions

Parameter Description Required
File Name Name of the file. The file will be looked for in the directory of the current definition file. Yes

Example Usage:

TABLEFILE "MCConfigurationTable_def.txt"

TABLE

The TABLE keyword designates the start of a new table definition. This keyword was reworked in COSMOS 3.9 to better match the syntax of the COMMAND and TELEMETRY keywords.

Parameter Description Required
Name Name of the table in double quotes. The name will appear on the GUI tab. Yes
Endianness Whether to pack the table data as BIG_ENDIAN or LITTLE_ENDIAN Yes
Display Indicates the table is a ONE_DIMENSIONAL table which is a two column table consisting of unique rows, or a TWO_DIMENSIONAL table with multiple columns and identical rows with unique values Yes
Rows If the table is declared as TWO_DIMENSIONAL, the next parameter indicates the number of rows in the table. This parameter does not exist in ONE_DIMENSIONAL table definitions. Yes
Description Description of this table in double quotes. The description is used in mouseover popups and status line information. No

Example Usage:

TABLE "MC Configuration" BIG_ENDIAN ONE_DIMENSIONAL "Memory Control Configuration Table"
TABLE "TLM Monitoring " BIG_ENDIAN TWO_DIMENSIONAL 200 "Telemetry Monitory Table"

PARAMETER

The PARAMETER keyword defines a table parameter in the current table. This keyword was reworked in COSMOS 3.9 to utilize the existing command parser. Please see the PARAMETER and APPEND_PARAMETER documentation.

Parameter Modifiers

The following keywords modify a parameter and are only applicable after the PARAMETER keyword as defined above. They are typically indented within the definition file to show ownership to the previously defined parameter. COSMOS 3.9 reworked the parser to accept any of the existing command parameter modifiers. In addition, the Table Manager parser supports the following parameter modifiers:

HIDDEN

HIDDEN indicates that the parameter should not be shown to the user in the Table Manager GUI. The parameter still exists and will be saved to the resulting binary. This is useful for padding and other essential but non-user editable fields.

Example Usage:

PARAMETER PAD 0 32 UINT MIN MAX 0 "Padding"
  HIDDEN

UNEDITABLE

UNEDITABLE indicates that the parameter shoudl be shown to the user but no editable. This is useful for control fields which the user may be interested in but should not be able to edit.

Example Usage:

PARAMETER TABLE_ID 0 32 UINT MIN MAX 10 "Table ID"
  UNEDITABLE

Example File

**Example File: /config/table_manager/metable_def.txt**

TABLE "Mechanism Control" BIG_ENDIAN ONE_DIMENSIONAL "Mechanism Control" 
  APPEND_PARAMETER "Total Steps" 32 UINT 0 2000 0
    FORMAT_STRING "0x%0X" # Display as hex
    GENERIC_READ_CONVERSION_START
      # Depending on the state of Other Param we change this item's range
      if packet.read("Other Param") == "OLD"
        packet.get_item("Total Steps").range = (0..10)
      else
        packet.get_item("Total Steps").range = (0..2000)
      end
      # BE SURE TO RETURN THE EXISTING VALUE!!!
      value
    GENERIC_READ_CONVERSION_END
  APPEND_PARAMETER "My Param" 16 UINT 0 2000 0
    GENERIC_READ_CONVERSION_START
      value * 2
    GENERIC_READ_CONVERSION_END
    GENERIC_WRITE_CONVERSION_START
      value / 2
    GENERIC_WRITE_CONVERSION_END
  APPEND_PARAMETER "Other Param" 32 INT 0 1 1
    STATE OLD 0
    STATE NEW 1
  APPEND_PARAMETER "Float Param" 64 FLOAT MIN MAX 0.0
  APPEND_PARAMETER "String Param" 32 STRING "TEST"

TABLE "Event Action" TWO_DIMENSIONAL 3 LITTLE_ENDIAN
  APPEND_PARAMETER "Event" 16 UINT MIN MAX
  APPEND_PARAMETER "Action" 32 INT 1 2
    STATE OLD 1
    STATE NEW 2

Table Manager Configuration (COSMOS < 3.9)

Table definition files define the binary table format so the Table Manager tool knows how to create, load, and display the binary data file. Table definition files are expected to be placed in the config/tools/table_manager directory and have a .txt extension. NOTE: Table Manager was revised in COSMOS 3.9 to better match the structure of the command and telemetry definitions and thus the configurations files are NOT backwards compatible.

Keywords (COSMOS < 3.9):

TABLEFILE (COSMOS < 3.9)

The TABLEFILE keyword specifies another file to open and process for table definitions

Parameter Description Required
File Name Name of the file. The file will be looked for in the directory of the current definition file. Yes

Example Usage:

TABLEFILE "MCConfigurationTable_def.txt"

TABLE (COSMOS < 3.9)

Parameter Description Required
Name Name of the table in double quotes. The name will appear on the GUI tab. Yes
Description Description of this table in double quotes. The description is used in mouseover popups and status line information Yes
Dimension Indicates the table is a ONE_DIMENSIONAL table which is a two column table consisting of unique rows, or a TWO_DIMENSIONAL table with multiple columns and identical rows with unique values Yes
Endianness Whether to pack the table data as BIG_ENDIAN or LITTLE_ENDIAN Yes
Identifier A unique numerical Table ID Yes

Example Usage:

TABLE "MC Configuration" "Memory Control Configuration Table" ONE_DIMENSIONAL BIG_ENDIAN 9
TABLE "TLM Monitoring" "Telemetry Monitoring Table" TWO_DIMENSIONAL BIG_ENDIAN 10

PARAMETER (COSMOS < 3.9)

Parameter Description Required
Name Name of this parameter in double quotes. Must be unique within this table. Yes
Description Description of this parameter in double quotes. The description is used in mouseover popups and status line information. Yes
Data Type Data Type of this parameter. Possible types: INT = Integer, UINT = Unsigned Integer, FLOAT = IEEE Floating point data (32 or 64 bit), STRING = ASCII string, BLOCK = Binary block of data Yes
Bit Size Bit size of this parameter. Must be greater than 0. Yes
Display Type Display Type of this parameter. Possible types: DEC = Decimal, HEX = Hex, STATE = States (must be given later), CHECK = Checkbox, STRING = Must be used for STRING data types, NONE = Must be used for BLOCK types. Appending a -U to the display type makes the field uneditable. Yes
Minimum Value Minimum allowed value for this parameter. For STRING data types this indicates the minimum number of characters. Yes
Maximum Value Maximum allowed value for this parameter. For STRING data types this indicates the maximum number of characters. Yes
Default Value Default value for this parameter Yes
Endianness Whether to pack the parameter data as BIG_ENDIAN or LITTLE_ENDIAN. No

Example Usage:

PARAMETER "Throttle" "Seconds to wait" FLOAT 32 DEC 0 0x0FFFFFFFF 2
PARAMETER "Scrubbing" "Memory Scrubbing" UINT 8 CHECK 0 1 1
PARAMETER "Pad" "Pad" UINT 16 HEX-U 0 0 0 LITTLE_ENDIAN

STATE (COSMOS < 3.9)

The STATE keyword defines a key/value pair for the current table parameter (the one most recently defined). For example, you might define states for ON = 1 and OFF = 0. This allows the word ON to be used rather than the number 1 when setting the table parameter and allows for much greater clarity and less chance for user error.

Parameter Description Required
Key The named state key. This can also be a string enclosed in double quotes. Yes
Value Value the key translates into Yes

Example Usage:

PARAMETER "Scrubbing" "Memory Scrubbing" UINT 8 STATE 0 1 1
  STATE DISABLE 0
  STATE ENABLE 1

DEFAULT (COSMOS < 3.9)

The DEFAULT keyword defines the default values for a row in a TWO_DIMENSIONAL table. Therefore, the number of DEFAULT lines defines the number of rows in the table. If no values are given after the keyword, the default as defined in the PARAMETER(s) will apply.

Parameter Description Required
Value1 The default value for the first defined PARAMETER in the TWO_DIMENSIONAL table. No
Value2 The default value for the second defined PARAMETER in the TWO_DIMENSIONAL table. No
ValueN The default value for the last defined PARAMETER in the TWO_DIMENSIONAL table. No

Example Usage:

TABLE "TLM Monitoring" "Telemetry Monitoring Table" TWO_DIMENSIONAL BIG_ENDIAN 4
  PARAMETER "Threshold" "Telemetry item threshold at which point persistance is incremented" UINT 32 HEX 0 4294967295 0
  PARAMETER "Offset" "Offset into the telemetry packet to monitor" UINT 32 DEC 0 4294967295 0
  PARAMETER "Data Size" "Amount of data to monitor (bytes)" UINT 32 STATE 0 3 0
    STATE BITS 0
    STATE BYTE 1
    STATE WORD 2

DEFAULT             # Defaults of 0, 0, 0(BITS) will be used
DEFAULT 0x2         # Override Threshold default of 0
DEFAULT 0x3 30 WORD # Note the use of STATE names

POLY_WRITE_CONVERSION (COSMOS < 3.9)

The POLY_WRITE_CONVERSION keyword adds a polynomial conversion factor to the current table parameter (the one most recently defined). This conversion factor is applied to the value entered by the user before it is written into the binary table file. All parameters with a POLY_WRITE_CONVERSION must also have a POLY_READ_CONVERSION. This read conversion should be the inverse function of the write conversion or the value might be inadvertently changed every time it is loaded and saved.

Parameter Description Required
C0 Coefficient #0. Yes
Cx Coefficient #x. This is the final coefficient value for the conversion. Any order polynomial conversion may be used so the value of 'x' will vary with the order of the polynomial. Note that larger order polynomials take longer to process than shorter order polynomials, but are sometimes more accurate. Yes

Example Usage:

POLY_WRITE_CONVERSION 1 2 # 2x + 1 when writing to the table binary
POLY_READ_CONVERSION -0.5 0.5 # 0.5x - 0.5 when reading from the table binary

POLY_READ_CONVERSION (COSMOS < 3.9)

The POLY_READ_CONVERSION keyword adds a polynomial conversion factor to the current table parameter (the one most recently defined). This conversion factor is applied to a table parameter read from the binary table file before it is displayed. Read conversions can be applied independently to read-only table parameters. If a table parameter is writable it must have both a read and write conversion.

Parameter Description Required
C0 Coefficient #0. Yes
Cx Coefficient #x. This is the final coefficient value for the conversion. Any order polynomial conversion may be used so the value of 'x' will vary with the order of the polynomial. Note that larger order polynomials take longer to process than shorter order polynomials, but are sometimes more accurate. Yes

Example Usage:

POLY_WRITE_CONVERSION -0.5 0.25 # 0.25x - 0.5 when writing to the table binary
POLY_READ_CONVERSION 2 4 # 2x + 4 when reading from the table binary

GENERIC_WRITE_CONVERSION_START / GENERIC_WRITE_CONVERSION_END (COSMOS < 3.9)

GENERIC_READ_CONVERSION_START / GENERIC_READ_CONVERSION_END (COSMOS < 3.9)

The generic conversion keywords add generic conversion functions to the current table parameter (the one most recently defined). This conversion factor is applied to the value entered by the user before it is written into the binary table file (for WRITE) and after it is read from the binary (for READ). The conversion is specified as ruby code that receives two implied parameters: ‘value’ which is the raw table parameter, and ‘myself’ which is a reference to the TableManager class. The last line of ruby code given should return the converted value. The conversion END keywords specify that all lines of ruby code for the conversion have been given. If a generic write conversion is created a generic read conversion must also be created. This read conversion should be the inverse of the write conversion or the value might be inadvertently changed every time it is loaded and saved.

Example Usage:

GENERIC_WRITE_CONVERSION_START
  value / 2
GENERIC_WRITE_CONVERSION_END
GENERIC_READ_CONVERSION_START
  value * 2
GENERIC_READ_CONVERSION_END

CONSTRAINT_START / CONSTRAINT_END (COSMOS < 3.9)

The constraint keyword allows the user to modify the current parameter’s allowable value range, default value, and/or conversion based on the value of another parameter.

Example Usage:

TABLE "Mechanism Control" "Description" ONE_DIMENSIONAL BIG_ENDIAN 1
  PARAMETER "Total Steps" "Total number of steps" UINT 16 HEX-U 0 2000 0
    CONSTRAINT_START
      if myself.get_table("Mechanism Control").get_packet_item("Other Param") == "OLD"
        value.range = 0..1.0\n")
        value.default = 1.0
      end
    CONSTRAINT_END
  PARAMETER "Other Param" "Yet another" INT 32 STATE -100 100 10
    STATE "OLD" 0
    STATE "NEW" 1

Example File (COSMOS < 3.9)

**Example File: /config/table_manager/metable_def.txt**

TABLE "Mechanism Control" "Mechanism Control Table" ONE_DIMENSIONAL BIG_ENDIAN 1
  PARAMETER "Total Steps" "Total number of steps" UINT 16 HEX-U 0 2000 0
    CONSTRAINT_START
      if myself.get_table("Mechanism Control").get_packet_item("Other Param") == "OLD"
        value.range = 0..1.0\n")
        value.default = 1.0
      end
    CONSTRAINT_END
    POLY_READ_CONVERSION 1 2
    POLY_WRITE_CONVERSION 2 3
  PARAMETER "My Param" "Description" UINT 16 HEX-U 0 2000 0
    GENERIC_READ_CONVERSION_START
      value * 2
    GENERIC_READ_CONVERSION_END
    GENERIC_WRITE_CONVERSION_START
      value / 2
    GENERIC_WRITE_CONVERSION_END
  PARAMETER "Other Param" "Yet another" INT 32 STATE -100 100 10
    STATE "OLD" 0
    STATE "NEW" 1
  PARAMETER "Next Param" "Another param" FLOAT 64 STATE -Float::MAX Float::MAX 0.0
    STATE OFF 0.0
    STATE ON  1.0
  PARAMETER "String Param" "This is a string" STRING 32 STRING 2 4 "TEST"
  PARAMETER "Block Param" "Raw data" BLOCK 64 NONE 0 0 0xAAAA5555AAAA5555

TABLE "Event Action" "Event Action Table" TWO_DIMENSIONAL LITTLE_ENDIAN 2
  PARAMETER "Event" "The event" UINT 16 HEX 0 65535
  PARAMETER "Action" "The action" INT 32 STATE 1 2
    STATE OLD 1
    STATE NEW 2
  DEFAULT 0 OLD
  DEFAULT 0x100 2
  DEFAULT 1000 NEW