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

DECLARE_GEM_MULTI_TARGET

Declare a COSMOS target which resides in a Ruby gem with multiple targets

COSMOS targets can be distributed in gem form in which case they must be named ‘cosmos-' where 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.

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
Target Name	The directory name which contains the target information. This must match a directory under the first level of the gem base directory.	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_HASH_FILE

(Since 4.4.0)

Add a file to the hashing sum calculation

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 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_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. The default hashing algorithm is MD5, but other Ruby Digest algorithms are also supported, like SHA1 and SHA256

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

Example Usage:

ADD_HASH_FILE lib/user_version.rb

CLASSIFICATION

(Since 4.3.0)

Add a classification banner to the top of all the COSMOS tools

Parameter	Description	Required
Display Text	The text to display in the classification banner	True
Color Name	Red Hex	The color name or the red value of a RGB triplet	True
Green Hex	The green value of a RGB triplet	False
Blue Hex	The blue value of a RGB triplet	False

Example Usage:

CLASSIFICATION Unclassified green
CLASSIFICATION Secret 255 114 0

HASHING_ALGORITHM

(Since 4.4.0)

Specify which Ruby Digest hashing algorithm to use

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

Parameter	Description	Required
Algorithm	Digest algorithm, one of MD5, RMD160, SHA1, SHA256, SHA384, SHA512	True

Example Usage:

HASHING_ALGORITHM SHA256

ALLOW_ROUTER_COMMANDING

(Since 4.5.0)

Allow routers to receive and forward commands to interfaces

Example Usage:

ALLOW_ROUTER_COMMANDING

X_CSRF_TOKEN

(Since 4.5.0)

Secret token passed with API calls

Parameter	Description	Required
token	Token passed with api calls	True

Example Usage:

X_CSRF_TOKEN Secret

ALLOW_ORIGIN

(Since 4.5.0)

Allow a specific HTTP Origin header in Api calls

This keyword should only be used if COSMOS needs to be commanded from a web server.

Parameter	Description	Required
origin	Hostname colon port of origin	True

Example Usage:

ALLOW_ORIGIN 1.2.4.4:8080

ALLOW_HOST

Allow a specific HTTP Host header in Api calls

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

Parameter	Description	Required
host	Hostname colon port of host	True

Example Usage:

ALLOW_HOST 1.2.4.4:7777

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.

CMD_UNIQUE_ID_MODE

Flags that commands to this target are identified in a mixed variety of ways

Ideally all commands for a target are identified using the exact same fields in a header for each command. If this target identifies packets using different fields for some commands than others, then this flag must be set to force a brute force identification method.

Using this mode significantly slows packet identification

TLM_UNIQUE_ID_MODE

Flags that telemetry to this target are identified in a mixed variety of ways

Ideally all telemetry for a target are identified using the exact same fields in a header for each packet. If this target identifies packets using different fields for some telemetry packets than others, then this flag must be set to force a brute force identification method.

Using this mode significantly slows packet identification

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

LOG_STORED

Enable logging of stored telemetry on the interface by the specified log writer

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.

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.

PROTOCOL

(Since 4.0.0)

Protocols modify the interface by processing the data

Protocols can be either READ, WRITE, or READ_WRITE. READ protocols act on the data received by the interface while write acts on the data before it is sent out. READ_WRITE applies the protocol to both reading and writing.

There is only one built in protocol implemented by override_protocol.rb. This protocol allows for Scripts to use the override_tlm() and normalize_tlm() methods to permanently change a telemetry value. Note, this differs from set_tlm() as set_tlm() is over-written by new incoming telemetry.

For information on creating your own custom protocol please see cosmosrb.com/docs/protocols

Parameter	Description	Required
Type	Whether to apply the protocol on incoming data, outgoing data, or both Valid Values: READ, WRITE, READ_WRITE	True
Protocol Filename or Classname	Ruby file name or class name which implements the protocol	True
Protocol specific parameters	Additional parameters used by the protocol	False

OPTION

Set a parameter on an interface

When an option is set the interface class calls the set_option method. Custom interfaces can override set_option to handle any additional options they want.

Parameter	Description	Required
Name	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, 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).	True
Parameters	Parameters to pass to the option	False

ROUTER Modifiers

The following keywords must follow a ROUTER keyword.

ROUTE

Map an interface to a router

Once an interface has been mapped to a router, all its received telemetry will be sent out through the router.

Parameter	Description	Required
Interface	Name of the interface	True

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

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

LOG_STORED

Enable logging of stored telemetry on the interface by the specified log writer

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

PROTOCOL

(Since 4.0.0)

Protocols modify the interface by processing the data

Parameter	Description	Required
Type	Whether to apply the protocol on incoming data, outgoing data, or both Valid Values: READ, WRITE, READ_WRITE	True
Protocol Filename or Classname	Ruby file name or class name which implements the protocol	True
Protocol specific parameters	Additional parameters used by the protocol	False

OPTION

Set a parameter on an interface

When an option is set the interface class calls the set_option method. Custom interfaces can override set_option to handle any additional options they want.

Parameter	Description	Required
Name	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, 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).	True
Parameters	Parameters to pass to the option	False

BACKGROUND_TASK Modifiers

The following keywords must follow a BACKGROUND_TASK keyword.

STOPPED

Indicate the background task should not be automatically started

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