cosmos 4.2.4 → 4.5.0

data/data/config/housekeeping_params.yaml

@@ -69,3 +69,17 @@ SHOW_LIMITS_LINES:
       description: Whether to display the limits lines
       required: true
       values: ['TRUE','FALSE']
+DART_REDUCTION:
+  summary: What kind of DART reduction to use for the data item
+  parameters:
+    - name: Reduction Time Period
+      description: DART reduces data over minute, hour, and day
+      required: true
+      values: ['NONE','MINUTE','HOUR','DAY']
+DART_REDUCED_TYPE:
+  summary: What kind of DART reduction type to use for the data item
+  parameters:
+    - name: Reduction Type
+      description: DART calculates an average, minimum, maximum and standard deviation over the time period
+      required: true
+      values: ['AVG','MIN','MAX','STDDEV']

data/data/config/interface_modifiers.yaml

@@ -35,6 +35,17 @@ LOG:
       required: true
       description: Log writer name as defined by PACKET_LOG_WRITER
       values: \D\S*
+LOG_STORED:
+  summary: Enable logging of stored telemetry on the interface by the specified log writer
+  description: LOG_STORED allows you to specify a different log writer for stored telemetry
+    (telemetry which has the 'stored' flag set in the packet). By default the stored telemetry
+    is intermingled in the normal log file.
+  warning: Choosing a custom log writer can prevent COSMOS from reading back your log files
+  parameters:
+    - name: Name
+      required: true
+      description: Log writer name as defined by PACKET_LOG_WRITER
+      values: \D\S*
 DONT_LOG:
   summary: Disable logging commands and telemetry on this interface
 LOG_RAW:
@@ -73,8 +84,9 @@ OPTION:
     - name: Name
       required: true
       description: The option to set. COSMOS defines several options on the core provided
-        interfaces. The SerialInterface defines FLOW_CONTROL which can be NONE (default) or RTSCTS
-        and DATA_BITS which changes the data bits of the serial interface.
+        interfaces. The SerialInterface defines FLOW_CONTROL which can be NONE (default) or RTSCTS,
+        STRUCT to directly set fields in the Windows DCB or POSIX structure and it defines
+        DATA_BITS which changes the data bits of the serial interface.
         The TcpipServerInterface defines LISTEN_ADDRESS which is the IP address to accept
         connections on (default 0.0.0.0) and AUTO_SYSTEM_META which will automatically send
         SYSTEM META when the interface connects (default false).

data/data/config/item_modifiers.yaml

@@ -131,6 +131,15 @@ GENERIC_READ_CONVERSION_START:
       GENERIC_READ_CONVERSION_START
         value * 1.5  # Convert the value by a scale factor
       GENERIC_READ_CONVERSION_END
+  parameters:
+    - name: Converted Type
+      required: false
+      description: Type of the converted value
+      values: <%= %w(INT UINT FLOAT STRING BLOCK) %>
+    - name: Converted Bit Size
+      required: false
+      description: Bit size of converted value
+      values: \d+
 GENERIC_READ_CONVERSION_END:
   summary: Complete a generic read conversion
 LIMITS:
@@ -157,7 +166,8 @@ LIMITS:
       values: \d+
     - name: Initial State
       required: true
-      description: Whether limits monitoring for this telemetry item is initially enabled or disabled
+      description: Whether limits monitoring for this telemetry item is initially enabled or disabled.
+        Note if you have multiple LIMITS items they should all have the same initial state.
       values: ['ENABLED', 'DISABLED']
     - name: Red Low Limit
       required: true

data/data/config/launcher.yaml

@@ -60,7 +60,10 @@ TOOL:
       required: true
       description: 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.
+        here which will be applied when the tool starts. COSMOS defines three helper
+        keywords to execute tools - LAUNCH, LAUNCH_TERMINAL, and LAUNCH_GEM. LAUNCH
+        starts a GUI Ruby tool without a terminal. LAUNCH_TERMINAL starts a Ruby tool
+        with a terminal window. LAUNCH_GEM launches a Ruby tool distributed with a gem.
       values: .+
     - name: Icon Filename
       required: false
@@ -101,7 +104,10 @@ MULTITOOL_START:
           required: true
           description: 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.
+            here which will be applied when the tool starts. COSMOS defines three helper
+            keywords to execute tools - LAUNCH, LAUNCH_TERMINAL, and LAUNCH_GEM. LAUNCH
+            starts a GUI Ruby tool without a terminal. LAUNCH_TERMINAL starts a Ruby tool
+            with a terminal window. LAUNCH_GEM launches a Ruby tool distributed with a gem.
           values: .+
       modifiers:
         DONT_CAPTURE_IO:
@@ -115,3 +121,7 @@ MULTITOOL_START:
           values: \d+
 MULTITOOL_END:
   summary: Ends the creation of a multi-tool button
+AUTO_GEM_TOOLS:
+  summary: Automatically installs COSMOS tool gems
+  description: Traverses the installed rubygems looking for COSMOS gems named cosmos-xxxx.gem.
+    If the gem has a tools directory, the tool launcher will be added as a TOOL in the Launcher.

data/data/config/param_item_modifiers.yaml

@@ -11,12 +11,12 @@ FORMAT_STRING:
 UNITS:
   summary: Add displayed units
   example: |
-    UNITS Celcius C
+    UNITS Celsius C
     UNITS Kilometers KM
   parameters:
     - name: Full Name
       required: true
-      description: Full name of the units type, e.g. Celcius
+      description: Full name of the units type, e.g. Celsius
       values: .*
     - name: Abbreviated
       required: true
@@ -44,3 +44,8 @@ META:
       required: false
       description: One or more values to be stored for this Meta Name
       values: .*
+OVERLAP:
+  summary: This item is allowed to overlap other items in the packet
+  description: If an item's bit offset overlaps another item, COSMOS issues a warning. This keyword explicitly
+    allows an item to overlap another and supresses the warning message.
+  since: 4.4.1

data/data/config/parameter_modifiers.yaml

@@ -68,6 +68,16 @@ WRITE_CONVERSION:
     takes extra parameters and must always implement the call method. The conversion
     factor is applied to the value entered by the user before it is written into
     the binary command packet and sent.
+
+    <div class="note info">
+    <h5>Multiple write conversions on command parameters</h5>
+    <p>When a command is built, each item gets written (and write conversions are run)
+    to set the default value. Then items are written (again write conversions are run)
+    with user provided values. Thus write conversions can be run twice. Also there are
+    no guarantees which parameters have already been written. The packet itself has a
+    given_values() method which can be used to retrieve a hash of the user provided
+    values to the command. That can be used to check parameter values passed in.</p>
+    </div>
   example: |
     WRITE_CONVERSION the_great_conversion.rb 1000
 
@@ -151,6 +161,16 @@ GENERIC_WRITE_CONVERSION_START:
     compatibility). The last line of ruby code given should return the converted
     value. The GENERIC_WRITE_CONVERSION_END keyword specifies that all lines of
     ruby code for the conversion have been given.
+
+    <div class="note info">
+    <h5>Multiple write conversions on command parameters</h5>
+    <p>When a command is built, each item gets written (and write conversions are run)
+    to set the default value. Then items are written (again write conversions are run)
+    with user provided values. Thus write conversions can be run twice. Also there are
+    no guarantees which parameters have already been written. The packet itself has a
+    given_values() method which can be used to retrieve a hash of the user provided
+    values to the command. That can be used to check parameter values passed in.</p>
+    </div>
   warning: Generic conversions are not a good long term solution. Consider creating
     a conversion class and using WRITE_CONVERSION instead. WRITE_CONVERSION is easier
     to debug and higher performance.

data/data/config/screen.yaml

@@ -146,6 +146,8 @@ NAMED_WIDGET:
       required: true
       description: The unique parameters for the given widget type
       values: .+
+STAY_ON_TOP:
+  summary: Force a screen to stay on top of all other windows
 # Even though these are technically SCREEN modifiers we load them at the top_frame
 # level so they appear as available keywords
 <%= MetaConfigParser.load('widgets.yaml').to_meta_config_yaml(0) %>

data/data/config/script_runner.yaml

@@ -7,6 +7,15 @@ LINE_DELAY:
       description: Delay in seconds before the next line is executed. A value of
         0 means to execute the scripts as fast as possible.
       values: '[0-9]*\.?[0-9]+'
+PAUSE_ON_ERROR:
+  summary: Set or clear the pause on error checkbox
+  description: If this is checked, Script Runner will pause if the test encounters
+    an error. Otherwise the error will be logged but the script will continue.
+  parameters:
+    - name: Enable
+      required: true
+      description: Whether to pause when the script encounters an error
+      values: ['TRUE', 'FALSE']
 MONITOR_LIMITS:
   summary: Log limits events to the Script Runner log file while a script is running
   description: Limits events are always logged by the Command and Telemetry Server

data/data/config/system.yaml

@@ -1,7 +1,8 @@
 ---
 AUTO_DECLARE_TARGETS:
   summary: Automatically load all the target folders under config/targets into the system
-  description: When automatically discovering target folders the COSMOS naming convention
+  description:
+    When automatically discovering target folders the COSMOS naming convention
     must be followed. Target folders must be uppercase and be named according to how
     COSMOS will access them. For example, if you create a config/targets/INST directory,
     COSMOS will create a target named 'INST' which is how it will be referenced.
@@ -9,7 +10,8 @@ AUTO_DECLARE_TARGETS:
     DECLARE_TARGET keyword.
 DECLARE_TARGET:
   summary: Declare a COSMOS target and name it
-  description: Declare target is used in place of AUTO_DECLARE_TARGETS to give more
+  description:
+    Declare target is used in place of AUTO_DECLARE_TARGETS to give more
     fine grained control over how the target folder is loaded and named within COSMOS.
     This is required if AUTO_DECLARE_TARGET is not present.
   example: DECLARE_TARGET INST INST2 inst.txt
@@ -26,7 +28,8 @@ DECLARE_TARGET:
         the target name will be the directory name given above.
     - name: Target Filename
       required: false
-      description: The name of the file in the target directory which contains the
+      description:
+        The name of the file in the target directory which contains the
         configuration information for the target. By default this is 'target.txt'
         but if you want to rename this you need to set this parameter.
 DECLARE_GEM_TARGET:
@@ -38,7 +41,8 @@ DECLARE_GEM_TARGET:
   parameters:
     - name: Gem Name
       required: true
-      description: The COSMOS gem name which must be cosmos-<gem-name> where <gem-name>
+      description:
+        The COSMOS gem name which must be cosmos-<gem-name> where <gem-name>
         is the descriptive gem name. In the above example, the target will be named
         'GEM-NAME' (note the cosmos- prefix is stripped off).
       values: .+
@@ -49,12 +53,47 @@ DECLARE_GEM_TARGET:
         the target name will be the gem name as described above.
     - name: Target Filename
       required: false
-      description: The name of the file in the target directory which contains the
+      description:
+        The name of the file in the target directory which contains the
+        configuration information for the target. By default this is 'target.txt'
+        but if you want to rename this you need to set this parameter.
+DECLARE_GEM_MULTI_TARGET:
+  summary: Declare a COSMOS target which resides in a Ruby gem with multiple targets
+  description: COSMOS targets can be distributed in gem form in which case they
+    must be named 'cosmos-<gem-name>' where <gem-name> is the descriptive name of
+    the gem. Multiple Targets can be packaged into a single gem. This directive
+    will tell COSMOS where to look for a target inside the first directory level
+    of the gem.  The sub-directory name must be all uppercase and must contain a
+    sub-directory named 'cmd_tlm'. See the COSMOS documentation at cosmosrb.com
+    for for information on creating a COSMOS gem target.
+  parameters:
+    - name: Gem Name
+      required: true
+      description:
+        The COSMOS gem name which must be cosmos-<gem-name> where <gem-name>
+        is the descriptive gem name. In the above example, the target will be named
+        'GEM-NAME' (note the cosmos- prefix is stripped off).
+      values: .+
+    - name: Target Name
+      required: true
+      description: The directory name which contains the target information.
+        This must match a directory under the first level of the gem base directory.
+      values: .+
+    - name: Substitute Target Name
+      required: false
+      description: The target name in the COSMOS system. This is how the target
+        will be referred to in scripts. If this is not given (or given as nil)
+        the target name will be the gem name as described above.
+    - name: Target Filename
+      required: false
+      description:
+        The name of the file in the target directory which contains the
         configuration information for the target. By default this is 'target.txt'
         but if you want to rename this you need to set this parameter.
 PORT:
   summary: Set a Server Port
-  description: Port is used to set the default ports used by the Command and Telemetry Server.
+  description:
+    Port is used to set the default ports used by the Command and Telemetry Server.
     It is not necessary to set this option unless you wish to override the defaults
     (given in the example usage). Overriding ports is necessary if you want to run
     two Command and Telemetry Servers on the same computer simultaneously.
@@ -65,7 +104,8 @@ PORT:
   parameters:
     - name: Port Name
       required: true
-      description: CTS_API - This port is what tools connect to to communicate with the COSMOS Scripting API.
+      description:
+        CTS_API - This port is what tools connect to to communicate with the COSMOS Scripting API.
         TLMVIEWER_API - This port is used to remotely open and close telemetry screens in Telemetry Viewer.
         CTS_PREIDENTIFIED - This port provides access to a preidentified stream of all telemetry packets
         in the system. This is currently used by Telemetry Grapher and can be used to chain Command
@@ -83,7 +123,8 @@ LISTEN_HOST:
   parameters:
     - name: Host Port Name
       required: true
-      description: CTS_API - This port is what tools connect to to communicate with the COSMOS Scripting API.
+      description:
+        CTS_API - This port is what tools connect to to communicate with the COSMOS Scripting API.
         TLMVIEWER_API - This port is used to remotely open and close telemetry screens in Telemetry Viewer.
         CTS_PREIDENTIFIED - This port provides access to a preidentified stream of all telemetry packets
         in the system. This is currently used by Telemetry Grapher and can be used to chain Command
@@ -93,7 +134,8 @@ LISTEN_HOST:
       values: <%= %w(CTS_API TLMVIEWER_API CTS_PREIDENTIFIED CTS_CMD_ROUTER) %>
     - name: Host Value
       required: true
-      description: The IP address or host name to bind the Host Port Name to. By default,
+      description:
+        The IP address or host name to bind the Host Port Name to. By default,
         the CTS_API and TLMVIEWER_API are bound to localhost meaning that only tools
         on the same machine can connect. By default, CTS_PREIDENTIFIED and CTS_CMD_ROUTER
         are bound to '0.0.0.0' to allow for tools on any machines to connect. This
@@ -105,7 +147,8 @@ CONNECT_HOST:
   parameters:
     - name: Host Port Name
       required: true
-      description: CTS_API - This port is what tools connect to to communicate with the COSMOS Scripting API.
+      description:
+        CTS_API - This port is what tools connect to to communicate with the COSMOS Scripting API.
         TLMVIEWER_API - This port is used to remotely open and close telemetry screens in Telemetry Viewer.
         CTS_PREIDENTIFIED - This port provides access to a preidentified stream of all telemetry packets
         in the system. This is currently used by Telemetry Grapher and can be used to chain Command
@@ -115,15 +158,18 @@ CONNECT_HOST:
       values: <%= %w(CTS_API TLMVIEWER_API CTS_PREIDENTIFIED CTS_CMD_ROUTER) %>
     - name: Host Value
       required: true
-      description: The IP address or host name to connect tools to. By default all
+      description:
+        The IP address or host name to connect tools to. By default all
         ports are bound to localhost so all tools connect to the local machine.
       values: .+
 PATH:
   summary: Set a Server Path
-  description: Path is used to set the default paths used by the Command and Telemetry Server
+  description:
+    Path is used to set the default paths used by the Command and Telemetry Server
     to access or create files. It is not necessary to set this option unless you wish to
     override the defaults (given in the example usage).
-  warning: The PROCEDURES path must be set for Script Runner and Test Runner to locate your
+  warning:
+    The PROCEDURES path must be set for Script Runner and Test Runner to locate your
     procedure files. You can add multiple 'PATH PROCEDURES' lines to your configuration file
     to set multiple locations.
   example: |
@@ -174,7 +220,8 @@ DEFAULT_PACKET_LOG_READER:
       since: 4.0.0
 STALENESS_SECONDS:
   summary: Number of seconds before marking the packet stale
-  description: A stale packet is identified in telemetry screens by all the telemetry
+  description:
+    A stale packet is identified in telemetry screens by all the telemetry
     items in the stale packet being colored purple..
   example: STALENESS_SECONDS 30 # Default
   parameters:
@@ -196,7 +243,8 @@ DISABLE_DNS:
     As of COSMOS 3.5.0 the default is to not use DNS
 ENABLE_SOUND:
   summary: Enable audible sounds when popups occur
-  description: Enable sound makes any prompts that occur in ScriptRunner/TestRunner
+  description:
+    Enable sound makes any prompts that occur in ScriptRunner/TestRunner
     make an audible sound when they popup to alert the operator of needed input.
   since: 3.5.0
 ALLOW_ACCESS:
@@ -205,12 +253,14 @@ ALLOW_ACCESS:
   parameters:
     - name: Name or IP Address
       required: true
-      description: Machine name to allow access or you can specify 'ALL' to allow
+      description:
+        Machine name to allow access or you can specify 'ALL' to allow
         all machines access
       values: .+
 META_INIT:
   summary: Specify a file to initialize the SYSTEM META packet
-  description: Filename should be a text file with key value pairs where the keyword
+  description:
+    Filename should be a text file with key value pairs where the keyword
     matches an item in the SYSTEM META packet. Note you do not have to specify ALL
     the items in the SYSTEM META packet.
   since: 4.0.0
@@ -221,27 +271,101 @@ META_INIT:
       values: .+
 TIME_ZONE_UTC:
   summary: Report all times as UTC
-  description: COSMOS will report all times as UTC time. If this keyword is not used,
+  description:
+    COSMOS will report all times as UTC time. If this keyword is not used,
     COSMOS will report all times as local times, where the local time zone is determined
     automatically by Ruby based upon the operating system time settings. This setting
     affects packet receive times, timestamped log filenames, message logs,
     Cmd/Tlm extractor time ranges, etc.
   since: 3.10.0
-ADD_MD5_FILE:
-  summary: Add a file to the MD5 sum calculation
-  description: Adds a file to the set of files used in marshal file MD5 sum calculation.
-    Upon startup, COSMOS calculates an MD5 sum over the command/telemetry definition files
+ADD_HASH_FILE:
+  summary: Add a file to the hashing sum calculation
+  description:
+    Adds a file to the set of files used in marshal file hashing sum calculation.
+    Upon startup, COSMOS calculates a hashing sum over the command/telemetry definition files
     for all targets. After the definitions have been processed, COSMOS saves the resulting
-    objects as marshal files in a folder with the MD5 sum as part of the name.
-    The next time COSMOS runs, if the MD5 checksum of the cmd/tlm definition files
+    objects as marshal files in a folder with the hashing sum as part of the name.
+    The next time COSMOS runs, if the hashing sum of the cmd/tlm definition files
     has not changed, COSMOS can load the marshal files instead of re-processing the definitions.
-    If a file is specified with the ADD_MD5_FILE keyword, COSMOS will include it in the
-    MD5 sum calculation. This means that a change in the file will cause COSMOS to
+    If a file is specified with the ADD_HASH_FILE keyword, COSMOS will include it in the
+    hashing sum calculation. This means that a change in the file will cause COSMOS to
     re-process the cmd/tlm defintions and create a new set of marshal files.
-  since: 4.0.0
-  example: ADD_MD5_FILE lib/user_version.rb
+    The default hashing algorithm is MD5, but other Ruby Digest algorithms are also supported,
+    like SHA1 and SHA256
+  since: 4.4.0
+  example: ADD_HASH_FILE lib/user_version.rb
   parameters:
     - name: Filename
       required: true
       description: Filename, either fully qualified, or relative to Cosmos::USERPATH
       values: '.+\.rb'
+CLASSIFICATION:
+  summary: Add a classification banner to the top of all the COSMOS tools
+  since: 4.3.0
+  example: |
+    CLASSIFICATION Unclassified green
+    CLASSIFICATION Secret 255 114 0
+  parameters:
+    - name: Display Text
+      required: true
+      description: The text to display in the classification banner
+      values: ".*"
+    - name: Color Name | Red Hex
+      required: true
+      description: The color name or the red value of a RGB triplet
+      values: ".*"
+    - name: Green Hex
+      required: false
+      description: The green value of a RGB triplet
+      values: '\d+'
+    - name: Blue Hex
+      required: false
+      description: The blue value of a RGB triplet
+      values: '\d+'
+HASHING_ALGORITHM:
+  summary: Specify which Ruby Digest hashing algorithm to use
+  description:
+    Set the hashing algorithm used for config hashing, tlm_viewer hashing, and
+    script hashing. COSMOS will truncate the resulting hash string down to 32 characters
+  since: 4.4.0
+  example: HASHING_ALGORITHM SHA256
+  parameters:
+    - name: Algorithm
+      required: true
+      description: Digest algorithm, one of MD5, RMD160, SHA1, SHA256, SHA384, SHA512
+      values: .+
+ALLOW_ROUTER_COMMANDING:
+  summary: Allow routers to receive and forward commands to interfaces
+  since: 4.5.0
+  example: ALLOW_ROUTER_COMMANDING
+X_CSRF_TOKEN:
+  summary: Secret token passed with API calls
+  since: 4.5.0
+  example: X_CSRF_TOKEN Secret
+  parameters:
+    - name: token
+      required: true
+      description: Token passed with api calls
+      values: .+
+ALLOW_ORIGIN:
+  summary: Allow a specific HTTP Origin header in Api calls
+  description: This keyword should only be used if COSMOS needs to be commanded from a web server.
+  since: 4.5.0
+  example: ALLOW_ORIGIN 1.2.4.4:8080
+  parameters:
+    - name: origin
+      required: true
+      description: Hostname colon port of origin
+      values: .+
+ALLOW_HOST:
+  summary: Allow a specific HTTP Host header in Api calls
+  description:
+    By default includes ['127.0.0.1:7777', '127.0.0.1:7778', '127.0.0.1:7877', '127.0.0.1:8779', '127.0.0.1:8780'].
+    API Ports changed by a PORT line will also be added automatically.  If you need external connections you must add your ip and
+    these ports to allow external access to work for apis
+  example: ALLOW_HOST 1.2.4.4:7777
+  parameters:
+    - name: host
+      required: true
+      description: Hostname colon port of host
+      values: .+