System Configuration

This document provides the information necessary to configure the COSMOS Command and Telemetry Server and other top level configuration options for your unique project.

Configuration file formats for the following are provided:

  • system.txt (found in config/system)
  • target.txt (found in config/targets/TARGETNAME)
  • cmd_tlm_server.txt (found in config/targets/TARGETNAME and config/tools/cmd_tlm_server)
  • crc.txt (found in data/crc.txt)

System Configuration

The COSMOS system configuration is performed by system.txt in the config/system directory. This file declares all the targets that will be used by COSMOS as well as top level configuration information which is primarily used by the Command and Telemetry Server.

By default, all COSMOS tools use the config/system/system.txt file. However, all tools can take a custom system configuration file by passing the “–system " option to the tool when it starts. NOTE: Mixing system configuration files between tools can be confusing as some tools could be configured with more or less targets than the Command and Telemetry Server. However, this is the only way to control which targets, ports, paths, and log writers are used by the various tools.

AUTO_DECLARE_TARGETS

Automatically load all the target folders under config/targets into the system

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. This keyword is REQUIRED unless you individually declare your targets using the DECLARE_TARGET keyword.

DECLARE_TARGET

Declare a COSMOS target and name it

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.

Parameter Description Required
Target Name The directory name which contains the target information. This must match a directory under config/targets.

Valid Values: Any Target Name
True
Substitute Target Name 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 directory name given above. False
Target Filename 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. False

Example Usage:

DECLARE_TARGET INST INST2 inst.txt

DECLARE_GEM_TARGET

Declare a COSMOS target which resides in a Ruby gem

COSMOS targets can be distributed in gem form in which case they must be named ‘cosmos-' where is the descriptive name of the gem. See the COSMOS documentation at cosmosrb.com for for information on creating a COSMOS gem target.

Parameter Description Required
Gem Name The COSMOS gem name which must be cosmos- where is the descriptive gem name. In the above example, the target will be named 'GEM-NAME' (note the cosmos- prefix is stripped off). True
Substitute Target Name 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. False
Target Filename 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. False

PORT

Set a Server Port

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.

Parameter Description Required
Port Name 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 and Telemetry Servers together as it also accepts commands. CTS_CMD_ROUTER - This port provides access to a stream of all command packets that have been accepted by COSMOS.

Valid Values: CTS_API, TLMVIEWER_API, CTS_PREIDENTIFIED, CTS_CMD_ROUTER
True
Port Value Port number to use for the specified port name True

Example Usage:

PORT CTS_API 7777 # Default
PORT TLMVIEWER_API 7778 # Default
PORT CTS_PREIDENTIFIED 7779 # Default

LISTEN_HOST

(Since 4.0.0)

IP addresses or host names to bind API ports to

Parameter Description Required
Host Port Name 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 and Telemetry Servers together as it also accepts commands. CTS_CMD_ROUTER - This port provides access to a stream of all command packets that have been accepted by COSMOS.

Valid Values: CTS_API, TLMVIEWER_API, CTS_PREIDENTIFIED, CTS_CMD_ROUTER
True
Host Value 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 allows for chaining two or more Servers out of the box. True

CONNECT_HOST

(Since 4.0.0)

IP addresses or host names to connect tools to

Parameter Description Required
Host Port Name 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 and Telemetry Servers together as it also accepts commands. CTS_CMD_ROUTER - This port provides access to a stream of all command packets that have been accepted by COSMOS.

Valid Values: CTS_API, TLMVIEWER_API, CTS_PREIDENTIFIED, CTS_CMD_ROUTER
True
Host Value 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. True

PATH

Set a Server Path

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

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.

Parameter Description Required
Path Name Path name to set.

Valid Values: LOGS, TMP, SAVED_CONFIG, TABLES, PROCEDURES, HANDBOOK
True
Path Value File system path to use for the specified path name True

Example Usage:

PATH LOGS './logs' # Default location of system and tool log files
PATH TMP './tmp' # Default location of temporary marshal files
PATH SAVED_CONFIG './saved_config' # Default location of saved configurations (see note)
PATH TABLES './tables' # Default location of table files
PATH PROCEDURES './procedures' # Default location of Script procedure files
PATH HANDBOOKS './handbooks' # Default location to place handbook files

DEFAULT_PACKET_LOG_WRITER

Set the class used when creating binary packet log files

Overriding the default log writer can break the ability to write log files that COSMOS can interpret. Proceed with caution!

Parameter Description Required
Filename Ruby file to use when instantiating a new log writer True
parameter Parameters which are passed to the log read upon initialization False

Example Usage:

DEFAULT_PACKET_LOG_WRITER packet_log_writer.rb

DEFAULT_PACKET_LOG_READER

Set the class used when reading binary packet log file

Overriding the default log read can break the ability to read log files. Proceed with caution!

Parameter Description Required
Filename Ruby file to use when instantiating a new log writer True
parameter Parameters which are passed to the log read upon initialization False

Example Usage:

DEFAULT_PACKET_LOG_READER packet_log_reader.rb

STALENESS_SECONDS

Number of seconds before marking the packet stale

A stale packet is identified in telemetry screens by all the telemetry items in the stale packet being colored purple..

Parameter Description Required
Seconds Integer number of seconds before packets are marked stale True

Example Usage:

STALENESS_SECONDS 30

ENABLE_DNS

(Since 3.5.0)

Enable reverse DNS lookups for tools

Enables reverse DNS lookups when tools connect to the Command and Telemetry Server’s pre-identified socket or to any target using the TCPIP Server Interface. As of COSMOS 3.5.0 the default is to not use DNS.

DISABLE_DNS

Disable reverse DNS lookups for tools

Disable reverse DNS lookups when tools connect to the Command and Telemetry Server’s pre-identified socket or to any target using the TCPIP Server Interface. This is useful when you are in an environment where DNS is not available. As of COSMOS 3.5.0 the default is to not use DNS

ENABLE_SOUND

(Since 3.5.0)

Enable audible sounds when popups occur

Enable sound makes any prompts that occur in ScriptRunner/TestRunner make an audible sound when they popup to alert the operator of needed input.

ALLOW_ACCESS

White list machines that are allowed to connect to the Server

Parameter Description Required
Name or IP Address Machine name to allow access or you can specify ‘ALL’ to allow all machines access True

Example Usage:

ALLOW_ACCESS ALL

META_INIT

(Since 4.0.0)

Specify a file to initialize the SYSTEM META packet

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.

Parameter Description Required
Filename Filename, either fully qualified, or relative to Cosmos::USERPATH True

TIME_ZONE_UTC

(Since 3.10.0)

Report all times as UTC

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.

ADD_MD5_FILE

(Since 4.0.0)

Add a file to the MD5 sum calculation

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 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 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 re-process the cmd/tlm defintions and create a new set of marshal files.

Parameter Description Required
Filename Filename, either fully qualified, or relative to Cosmos::USERPATH True

Example Usage:

ADD_MD5_FILE lib/user_version.rb

Target Configuration

Each target is self contained in a target directory named after the target and placed in the config/targets directory. In the target directory there is a configuration file named target.txt which configures the individual target.

REQUIRE

Requires a Ruby file

Ruby files must be required to be available to call in other code. Files are first required from the target’s lib folder. If no file is found the Ruby system path is checked which includes the base COSMOS/lib folder.

Parameter Description Required
Filename Filename to require. For files in the target’s lib directory simply supply the filename, e.g. “REQUIRE my_file”. Files in the base COSMOS lib directory also should just list the filename. If a file is in a folder under the lib directory then you must specify the folder name, e.g. “REQUIRE folder/my_file”. The filename can also be an absolute path but this is not common. Note the “.rb” extension is optional when specifying the filename. True

Example Usage:

REQUIRE limits_response.rb

IGNORE_PARAMETER

Ignore the given command parameter

Hint to other COSMOS tools to hide or ignore this command parameter when processing the command. For example, Command Sender and Command Sequence will not display the parameter (by default) when showing the command and Script Runner code completion will not display the parameter.

Parameter Description Required
Parameter Name The name of a command parameter. Note that this parameter will be ignored in ALL the commands it appears in. True

Example Usage:

IGNORE_PARAMETER CCSDS_VERSION

IGNORE_ITEM

Ignore the given telemetry item

Hint to other COSMOS tools to hide or ignore this telemetry item when processing the telemetry. For example, Packet Viewer will not display the item (by default) when showing the packet.

Parameter Description Required
Item name The name of a telemetry item. Note that this item will be ignored in ALL the telemetry it appears in. True

Example Usage:

IGNORE_ITEM CCSDS_VERSION

COMMANDS

Process the given command definition file

This keyword is used to explicitly add the command definition file to the list of command and telemetry files to process.

Usage of this keyword overrides automatic command and telemetry file discovery. If this keyword is used, you must also use the TELEMETRY keyword to specify the telemetry files to process.

Parameter Description Required
Filename Name of a command definition file in the target’s cmd_tlm directory, e.g. “cmd.txt”. True

Example Usage:

COMMANDS inst_cmds_v2.txt
TELEMETRY inst_tlm_v2.txt

TELEMETRY

Process the given telemetry definition file

This keyword is used to explicitly add the telemetry definition file to the list of command and telemetry files to process.

Usage of this keyword overrides automatic command and telemetry file discovery. If this keyword is used, you must also use the COMMAND keyword to specify the command files to process.

Parameter Description Required
Filename Name of a telemetry definition file in the target’s cmd_tlm directory, e.g. “tlm.txt”. True

Example Usage:

COMMANDS inst_cmds_v2.txt
TELEMETRY inst_tlm_v2.txt

AUTO_SCREEN_SUBSTITUTE

Automatically substitute the target’s name in screen definitions

Targets can be renamed when they are declared which would break any screen definitions using the explicit target name. This keyword automatically replaces the target name in the screen definitions with the actual target name.

Replaces ALL target names in a screen definition file, so this is not suitable for screens with multiple targets.

Command and Telemetry Server Configuration

The Command and Telemetry Server’s configuration file is found in config/tools/cmd_tlm_server. This file is used to configure the server by primarily mapping the interfaces to the targets they service.

TITLE

Sets the Command and Telemetry Server window title

Parameter Description Required
Text Text to put in the title of the Command and Telemetry Server window True

PACKET_LOG_WRITER

Declare a packet log writer

Packet log writer is used to declare a packet log writer class and give it a name which can be referenced by an interface. This is required if you want interfaces to have their own dedicated log writers or want to combine various interfaces into a single log file. By default, COSMOS logs all data on all interfaces into a single command log and a single telemetry log. This keyword can also be used if you want to declare a different log file class to create log files.

You should NOT override the default without consulting a COSMOS expert as this may break the ability to successfully read and write log files.

Parameter Description Required
Log Writer Name The name of the log writer as reference by other cmd_tlm_server keywords. This name also appears in the Logging tab on the Command and Telemetry Server. True
Filename Ruby file to use when instantiating a new log writer True
Parameters Optional parameters to pass to the log writer class when instantiating it. False

Example Usage:

PACKET_LOG_WRITER DEFAULT packet_log_writer.rb # Default
# The default logger filename will be <DATE>_cosmostlm.bin and will create a new log every 1MB
PACKET_LOG_WRITER DEFAULT packet_log_writer.rb cosmos true nil 1000000
# Create a logger named COSMOS_LOG which creates a new log every 5 min (600s)
PACKET_LOG_WRITER COSMOS_LOG packet_log_writer.rb cosmos true 600

AUTO_INTERFACE_TARGETS

Automatically use each target’s cmd_tlm_server.txt file to define the interface

Look for a cmd_tlm_server.txt file at the top level of each target directory and use this file to configure the interface for that target. This is a good way of keeping the knowledge of how to interface to a target within that target. However, if you use substitute target names (by using DECLARE_TARGET) or use different IP addresses then this will not work and you’ll have to use the INTERFACE_TARGET or INTERFACE keyword.

INTERFACE_TARGET

Load the specified target’s cmd_tlm_server.txt configuration file

Parameter Description Required
Target Name Name of the target

Valid Values: Any Target Name
True
Configuration File Configuration file name which contains the interface configuration. Defaults to ‘cmd_tlm_server.txt’. False

Example Usage:

INTERFACE_TARGET COSMOS # Look in the COSMOS target directory for cmd_tlm_server.txt
INTERFACE_TARGET COSMOS config.txt # Look in the COSMOS target directory for config.txt

INTERFACE

Defines a connection to a physical target

Interfaces are what COSMOS uses to talk to a particular piece of hardware. Interfaces require a Ruby file which implements all the interface methods necessary to talk to the hardware. COSMOS defines many built in interfaces or you can define your own as long as it implements the interface protocol.

Parameter Description Required
Interface Name Name of the interface. This name will appear in the Interfaces tab of the Server and is also referenced by other keywords. The COSMOS convention is to name interfaces after their targets with ‘_INT’ appended to the name, e.g. INST_INT for the INST target. True
Filename Ruby file to use when instantiating the interface.

Valid Values: tcpip_client_interface.rb, tcpip_server_interface.rb, udp_interface.rb, serial_interface.rb, cmd_tlm_server_interface.rb, linc_interface.rb
True

Additional parameters are required. Please see the Interfaces documentation for more details.

ROUTER

Create an interface which reverses cmd/tlm data

Router creates an interface which receives command packets from their remote targets and send them out their interfaces. They receive telemetry packets from their interfaces and send them to their remote targets. This allows routers to be intermediaries between an external client and an actual device.

Parameter Description Required
Name Name of the router True
Filename Ruby file to use when instantiating the interface.

Valid Values: tcpip_client_interface.rb, tcpip_server_interface.rb, udp_interface.rb, serial_interface.rb, cmd_tlm_server_interface.rb, linc_interface.rb
True

Additional parameters are required. Please see the Interfaces documentation for more details.

COLLECT_METADATA

Prompts the user for meta data when starting the Command and Telemetry Server

BACKGROUND_TASK

Create a background task in the Command and Telemetry Server

The Server instantiates the class which must inherit from BackgroundTask and then calls the call() method which the class must implement. The call() method is only called once so if your background task is supposed to live on while the Server is running, you must implement your code in a loop with a sleep to not use all the CPU.

Parameter Description Required
Filename Ruby file which contains the background task implementation. Must inherit from BackgroundTask and implement the call method. True
Optional Arguments Optional arguments to the background task constructor False

Example Usage:

BACKGROUND_TASK example_background_task.rb

INTERFACE Modifiers

The following keywords must follow a INTERFACE keyword.

TARGET

Maps a target name to an interface

Parameter Description Required
Target Name Target name to map to this interface

Valid Values: Any Target Name
True

DONT_CONNECT

Server will not automatically try to connect to the interface at startup

DONT_RECONNECT

Server will not try to reconnect to the interface if the connection is lost

RECONNECT_DELAY

Reconnect delay in seconds

If DONT_RECONNECT is not present the Server will try to reconnect to an interface if the connection is lost. Reconnect delay sets the interval in seconds between reconnect tries.

Parameter Description Required
Delay Delay in seconds between reconnect attempts. The default is 15 seconds. True

DISABLE_DISCONNECT

Disable the Disconnect button on the Interfaces tab in the Server

Use this keyword to prevent the user from disconnecting from the interface. This is typically used in a ‘production’ environment where you would not want the user to inadvertantly disconnect from a target.

LOG

Enable logging on the interface by the specified log writer

LOG is only required if you want a log writer other than the default to log commands and telemetry on this interface

Choosing a custom log writer can prevent COSMOS from reading back your log files

Parameter Description Required
Name Log writer name as defined by PACKET_LOG_WRITER True

DONT_LOG

Disable logging commands and telemetry on this interface

LOG_RAW

Log all data on the interface exactly as it is sent and received

LOG_RAW does not add any COSMOS headers and thus can not be read by COSMOS tools. It is primarily useful for low level debugging of an interface. You will have to manually parse these logs yourself using a hex editor or other application.

Project CRC Checking

The COSMOS Launcher will check CRCs on project files if a data/crc.txt file is present. The file is made up of filename, a space character, and the expected CRC for the file. If the user updates the file from the Launcher legal dialog, the keyword USER_MODIFIED will be added to the top. This line should be deleted for an official release.

Example File:

lib/example_background_task.rb 0xCF0A70AF
lib/example_target.rb 0x5B7507D3
lib/user_version.rb 0x8F282EE9