COSMOS COSMOS Logo

v5

Plugins

Introduction

This document provides the information necessary to configure a COSMOS plugin. Plugins are how you configure and extend COSMOS 5.

Plugins are where you define targets (and their corresponding command and telemetry packet definitions), where you configure the interfaces needed to talk to targets, where you can define routers to stream raw data out of COSMOS, how you can add new tools to the COSMOS user interface, and how you can run additional microservices to provide new functionality.

Each plugin is built as a Ruby gem and thus has a .gemspec file which builds it. Plugins have a plugin.txt file which declares all the variables used by the plugin and how to interface to the target(s) it contains.

Concepts

Target

Targets are the external pieces of hardware and/or software that COSMOS communicates with. These are things like Front End Processors (FEPs), ground support equipment (GSE), custom software tools, and pieces of hardware like satellites themselves. A target is anything that COSMOS can send commands to and receive telemetry from.

Interface

Interfaces implement the physical connection to one or more targets. They are typically ethernet connections implemented using TCP or UDP but can be other connections like serial ports. Interfaces send commands to targets and receive telemetry from targets.

Router

Routers flow streams of telemetry packets out of COSMOS and receive streams of commands into COSMOS. The commands are forwarded by COSMOS to associated interfaces. Telemetry comes from associated interfaces.

Tool

COSMOS Tools are web-based applications the communicate with the COSMOS APIs to perform takes like displaying telemetry, sending commands, and running scripts.

Microservice

Microservices are persistent running backend code that runs within the COSMOS environment. They can process data and perform other useful tasks.

Plugin Directory Structure

COSMOS plugins have a well-defined directory structure as follows:

Folder / File Description
plugin.txt Configuration file for the plugin. This file is required and always named exactly plugin.txt. See later in this document for the format.
LICENSE.txt License for the plugin. COSMOS Plugins should be licensed in a manner compatible with the AGPLv3, unless they are designed only for use with COSMOS Enterprise Edition (or only for use at Ball), in which case they can take on any license as desired.
cosmos-PLUGINNAME.gemspec or cosmosc2-PLUGINNAME.gemspec This file should have the name of the plugin with a .gemspec extension. For example cosmos-demo.gemspec. The name of this file is used in compiling the plugin contents into the final corresponding -.gem plugin file. ie. cosmos-demo-5.0.0.gem. COSMOS plugins should always begin with the cosmos- or cosmosc2- prefix to make them easily identifiable in the Rubygems repository. The contents of this file take on the Rubygems spec format as documented at: https://guides.rubygems.org/specification-reference/
Rakefile This is a helper ruby Rakefile used to build the plugin. In general, the exact same file as provided with the COSMOS demo plugins can be used, or other features can be added as necessary for your plugin project. This file is typically just used to support building the plugin by running “rake build VERSION=X.X.X” where X.X.X is the plugin version number. A working Ruby installation is required.
README.md Use this file to describe your plugin. It is typically a markdown file that supports nice formatting on Github.
targets/ This folder is required if any targets are defined by your plugin. All target configuration is included under this folder. It should contain one or more target configurations
targets/TARGETNAME This is a folder that contains the configuration for a specific target named TARGETNAME. The name is always defined in all caps. For example: targets/INST. This is typically the default name of the target, but well-designed targets will allow themselves to be renamed at installation. All subfolders and files below this folder are optional and should be added as needed.
targets/TARGETNAME/cmd_tlm This folder contains the command and telemetry definition files for the target. These files capture the format of the commands that can be sent to the target, and the telemetry packets that are expected to be received by COSMOS from the target. Note that the files in this folder are processed in alphabetical order by default. That can matter if you reference a packet in another file (it should already have been defined). See the Command and Telemetry Configuration Guides for more information.
targets/TARGETNAME/data Use this folder to store any general data that is needed by the target. For example, any image files would be stored here.
targets/TARGETNAME/lib This folder contains any custom code required by the target. Good examples of custom code are custom Interface classes and protocols. See the Interface documentation for more information. Try to give any custom code a unique filename that starts with the name of the target. This can help avoid name conflicts that can occur if two different targets create a custom code file with the same filename.
targets/TARGETNAME/procedures This folder contains target specific procedures and helper methods which exercise functionality of the target. These procedures should be kept simple and only use the command and telemetry definitions associated with this target. See the Scripting Guide for more information.
targets/TARGETNAME/screens This folder contains telemetry screens for the target. See Screen Configuration for more information.
targets/TARGETNAME/target.txt This file contains target specific configuration such as which command parameters should be ignored by Command Sender. See Target Configuration for more information.
microservices/ This folder is required if any microservices are defined by your plugin. All microservice code and configuration is included in this folder. It should contain one or more MICROSERVICENAME subfolders
microservices/MICROSERVICENAME This is a folder that contains the code and any necessary configuration for a specific microservice named MICROSERVICENAME. The name is always defined in all caps. For example: microservices/EXAMPLE. This is typically the default name of the microservice, but well-designed microservices will allow themselves to be renamed at installation. All subfolders and files below this folder are optional and should be added as needed.
tools/ This folder is required if any tools are defined by your plugin. All tool code and configuration is included in this folder. It should contain one or more toolname subfolders
tools/toolname This is a folder that contains all the files necessary to serve a web-based tool named toolname. The name is always defined in all lowercase. For example: tools/base. Due to technical limitations, the toolname must be unique and cannot be renamed at installation. All subfolders and files below this folder are optional and should be added as needed.

plugin.txt Configuration File

A plugin.txt configuration file is required for any COSMOS plugin. It declares the contents of the plugin and provides variables that allow the plugin to be configured at the time it is initially installed or upgraded. This file follows the standard COSMOS configuration file format of keywords followed by zero or more space separated parameters. The following keywords are supported by the plugin.txt config file:

VARIABLE

Define a configurable variable for the plugin

The VARIABLE keyword defines a variable that will be requested for the user to enter during plugin installation. Variables can be used to handle details of targets that are user defined such as specific IP addresses and ports. Variables should also be used to allow users to rename targets to whatever name they want and support multiple installations of the same target with different names. Variables can be used later in plugin.txt or in any other configuration file included in a plugin using Ruby ERB syntax. The variables are assigned to accessible local variables in the file. At a high level, ERB allows you to run Ruby code in configuration files.

Parameter Description Required
Variable Name The name of the variable True
Default Value Default value of the variable True

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 router to receive commands and output telemetry packets from one or more interfaces

Creates an router which receives command packets from their remote clients and sends them to associated interfaces. They receive telemetry packets from their interfaces and send them to their remote clients. 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.

TARGET

Defines a new target

Parameter Description Required
Folder Name The target folder True
Name The target name. While this is almost always the same as Folder Name it can be different to create multiple targets based on the same target folder. True

Example Usage:

TARGET INST

MICROSERVICE

Defines a new microservice

Defines a microservice that the plugin adds to the COSMOS system. Microservices are background software processes that perform persistent processing.

Parameter Description Required
Microservice Folder Name The exact name of the microservice folder in the plugin. ie. microservices/ True
Microservice Name The specific name of this instance of the microservice in the COSMOS system True

Example Usage:

MICROSERVICE EXAMPLE example-microservice

TOOL

Define a tool

Defines a tool that the plugin adds to the COSMOS system. Tools are web based applications that make use of the Single-SPA javascript library that allows them to by dynamically added to the running system as independent frontend microservices.

Parameter Description Required
Tool Folder Name The exact name of the tool folder in the plugin. ie. tools/ True
Tool Name Name of the tool that is displayed in the COSMOS Navigation menu True

Example Usage:

TOOL DEMO Demo

WIDGET

Define a custom widget

Defines a custom widget that can be used in Telemetry Viewer screens.

Parameter Description Required
Widget Name The name of the widget wil be used to build a path to the widget implementation. For example, WIDGET HELLOWORLD will find the as-built file tools/widgets/HelloworldWidget/HelloworldWidget.umd.min.js. See the Custom Widgets guide for more details. True

Example Usage:

WIDGET HELLOWORLD

INTERFACE Modifiers

The following keywords must follow a INTERFACE keyword.

MAP_TARGET

Maps a target name to an interface

Parameter Description Required
Target Name Target name to map to this interface 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 https://ballaerospace.github.io/cosmos-website/docs/v5/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 filename 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 and 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

MAP_TARGET

Maps a target name to an interface

Parameter Description Required
Target Name Target name to map to this interface 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 https://ballaerospace.github.io/cosmos-website/docs/v5/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 filename 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 and 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

TARGET Modifiers

The following keywords must follow a TARGET keyword.

CMD_LOG_CYCLE_TIME

Command binary logs can be cycled on a time interval.

Parameter Description Required
Time Maximum time between files in seconds (default = 600) True

CMD_LOG_CYCLE_SIZE

Command binary logs can be cycled after a certain log file size is reached.

Parameter Description Required
Size Maximum file size in bytes (default = 50_000_000) True

CMD_LOG_RETAIN_TIME

How long to keep raw command logs in seconds.

Parameter Description Required
Time Number of seconds to keep raw command logs (default = nil = Forever) True

CMD_DECOM_LOG_CYCLE_TIME

Command decommutation logs can be cycled on a time interval.

Parameter Description Required
Time Maximum time between files in seconds (default = 600) True

CMD_DECOM_LOG_CYCLE_SIZE

Command decommutation logs can be cycled after a certain log file size is reached.

Parameter Description Required
Size Maximum file size in bytes (default = 50_000_000) True

CMD_DECOM_LOG_RETAIN_TIME

How long to keep decom command logs in seconds.

Parameter Description Required
Time Number of seconds to keep decom command logs (default = nil = Forever) True

TLM_LOG_CYCLE_TIME

Telemetry binary logs can be cycled on a time interval.

Parameter Description Required
Time Maximum time between files in seconds (default = 600) True

TLM_LOG_CYCLE_SIZE

Telemetry binary logs can be cycled after a certain log file size is reached.

Parameter Description Required
Size Maximum file size in bytes (default = 50_000_000) True

TLM_LOG_RETAIN_TIME

How long to keep raw telemetry logs in seconds.

Parameter Description Required
Time Number of seconds to keep raw telemetry logs (default = nil = Forever) True

TLM_DECOM_LOG_CYCLE_TIME

Telemetry decommutation logs can be cycled on a time interval.

Parameter Description Required
Time Maximum time between files in seconds (default = 600) True

TLM_DECOM_LOG_CYCLE_SIZE

Telemetry decommutation logs can be cycled after a certain log file size is reached.

Parameter Description Required
Size Maximum file size in bytes (default = 50_000_000) True

TLM_DECOM_LOG_RETAIN_TIME

How long to keep decom telemetry logs in seconds.

Parameter Description Required
Time Number of seconds to keep decom telemetry logs (default = nil = Forever) True

REDUCED_MINUTE_LOG_RETAIN_TIME

How long to keep reduced minute telemetry logs in seconds.

Parameter Description Required
Time Number of seconds to keep reduced minute telemetry logs (default = nil = Forever) True

REDUCED_HOUR_LOG_RETAIN_TIME

How long to keep reduced hour telemetry logs in seconds.

Parameter Description Required
Time Number of seconds to keep reduced hour telemetry logs (default = nil = Forever) True

REDUCED_DAY_LOG_RETAIN_TIME

How long to keep reduced day telemetry logs in seconds.

Parameter Description Required
Time Number of seconds to keep reduced day telemetry logs (default = nil = Forever) True

LOG_RETAIN_TIME

How long to keep all regular telemetry logs in seconds.

Parameter Description Required
Time Number of seconds to keep all regular telemetry logs (default = nil = Forever) True

REDUCED_LOG_RETAIN_TIME

How long to keep all reduced telemetry logs in seconds.

Parameter Description Required
Time Number of seconds to keep all reduced telemetry logs (default = nil = Forever) True

CLEANUP_POLL_TIME

Period at which to run the cleanup process.

Parameter Description Required
Time Number of seconds between runs of the cleanup process (default = 900 = 15 minutes) True

MICROSERVICE Modifiers

The following keywords must follow a MICROSERVICE keyword.

ENV

Sets an environment variable in the microservice.

Parameter Description Required
Key Environment variable name True
Value Environment variable value True

WORK_DIR

Set the working directory

Working directory to run the microservice CMD in. Can be a path relative to the microservice folder in the plugin, or an absolute path in the container the microservice runs in.

Parameter Description Required
Directory Working directory to run the microservice CMD in. Can be a path relative to the microservice folder in the plugin, or an absolute path in the container the microservice runs in. True

TOPIC

Associate a Redis topic

Redis topic to associate with this microservice. Standard COSMOS microservices such as decom_microservice use this information to know what packet streams to subscribe to. The TOPIC keyword can be used as many times as necessary to associate all needed topics.

Parameter Description Required
Topic Name Redis Topic to associate with the microservice True

TARGET_NAME

Associate a COSMOS target

COSMOS target to associate with the microservice. For standard COSMOS microservices such as decom_microservice this causes the target configuration to get loaded into the container for the microservice.

Parameter Description Required
Target Name COSMOS target to associate with the microservice True

CMD

Command line to execute to run the microservice.

Command line to execute to run the microservice.

Parameter Description Required
Args One or more arguments to exec to run the microservice. True

OPTION

Pass an option to the microservice

Generic key/value(s) options to pass to the microservice. These take the form of KEYWORD/PARAMS like a line in a COSMOS configuration file. Multiple OPTION keywords can be used to pass multiple options to the microservice.

Parameter Description Required
Option Name Name of the option True
Option Value(s) One or more values to associate with the option True

CONTAINER

Docker Container.

Container to execute and run the microservice in.

Parameter Description Required
Args Name of the container False

TOOL Modifiers

The following keywords must follow a TOOL keyword.

URL

Url used to access the tool

The relative url used to access the tool. Defaults to “/tools/".

Parameter Description Required
Url The url. If not given defaults to tools/. Generally should not be given unless linking to external tools. True

INLINE_URL

Internal url to load a tool

The url of the javascript file used to load the tool into single-SPA. Defaults to “js/app.js”.

Parameter Description Required
Url The inline url. If not given defaults to js/app.js. Generally should not be given unless using a non-standard filename. True

WINDOW

How to display the tool when navigated to

The window mode used to display the tool. INLINE opens the tool internally without refreshing the page using the Single-SPA framework. IFRAME opens external tools in an Iframe within COSMOS. NEW opens the tool in a new TAB.

Parameter Description Required
Window Mode Tool display mode

Valid Values: INLINE, IFRAME, NEW 		True

ICON

Set tool icon

Icon shown next to the tool name in the COSMOS navigation menu.

Parameter Description Required
Icon Name Icon to display next to the tool name. Icons come from Font Awesome, Material Design (https://materialdesignicons.com/), and Astro. True

CATEGORY

Category for the tool

Associates the tool with a category. In a future release this will be able to organize tools into submenus in the Navigation menu.

Parameter Description Required
Category Name Category to associate the tool with True

SHOWN

Show the tool or not

Whether or not the tool is shown in the Navigation menu. Should generally be true, except for the cosmos base tool.

Parameter Description Required
Shown Whether or not the tool is shown. TRUE or FALSE

Valid Values: true, false 		True