Skip to main content

Plugins

Introduction

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

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 plugin.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 described in detail in the Code Generator documentation.

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.

ParameterDescriptionRequired
Variable NameThe name of the variableTrue
Default ValueDefault value of the variableTrue

NEEDS_DEPENDENCIES

(Since 5.5.0)
Indicates the plugin needs dependencies and sets the GEM_HOME environment variable

If the plugin has a top level lib folder or lists runtime dependencies in the gemspec, NEEDS_DEPENDENCIES is effectively already set. Note that in Enterprise Edition, having NEEDS_DEPENDENCIES adds the NFS volume mount to the Kuberentes pod.

INTERFACE

Defines a connection to a physical target

Interfaces are what OpenC3 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. OpenC3 defines many built in interfaces or you can define your own as long as it implements the interface protocol.

ParameterDescriptionRequired
Interface NameName of the interface. This name will appear in the Interfaces tab of the Server and is also referenced by other keywords. The OpenC3 convention is to name interfaces after their targets with '_INT' appended to the name, e.g. INST_INT for the INST target.True
FilenameRuby file to use when instantiating the interface.

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

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

INTERFACE Modifiers

The following keywords must follow a INTERFACE keyword.

MAP_TARGET

Maps a target name to an interface

ParameterDescriptionRequired
Target NameTarget name to map to this interfaceTrue

Example Usage:

INTERFACE DATA_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil BURST
  MAP_TARGET DATA

MAP_CMD_TARGET

(Since 5.2.0)
Maps a target name to an interface for commands only

ParameterDescriptionRequired
Target NameCommand target name to map to this interfaceTrue

Example Usage:

INTERFACE CMD_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil BURST
  MAP_CMD_TARGET DATA # Only DATA commands go on the CMD_INT interface

MAP_TLM_TARGET

(Since 5.2.0)
Maps a target name to an interface for telemetry only

ParameterDescriptionRequired
Target NameTelemetry target name to map to this interfaceTrue

Example Usage:

INTERFACE TLM_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil BURST
  MAP_TLM_TARGET DATA # Only DATA telemetry received on TLM_INT interface

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.

ParameterDescriptionRequired
DelayDelay 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_RAW

Deprecated, use LOG_STREAM

LOG_STREAM

(Since 5.5.2)
Log all data on the interface exactly as it is sent and received

LOG_STREAM does not add any OpenC3 headers and thus can not be read by OpenC3 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.

ParameterDescriptionRequired
Cycle TimeAmount of time to wait before cycling the log file. Default is 10 min. If nil refer to Cycle Hour and Cycle Minute.False
Cycle SizeAmount of data to write before cycling the log file. Default is 50MB.False
Cycle HourThe time at which to cycle the log. Combined with Cycle Minute to cycle the log daily at the specified time. If nil, the log will be cycled hourly at the specified Cycle Minute. Only applies if Cycle Time is nil.False
Cycle MinuteSee Cycle Hour.False

Example Usage:

INTERFACE EXAMPLE example_interface.rb
  # Override the default log time of 600
  LOG_STREAM 60

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.

For information on creating your own custom protocol please see Protocols

ParameterDescriptionRequired
TypeWhether to apply the protocol on incoming data, outgoing data, or both

Valid Values: READ, WRITE, READ_WRITE
True
Protocol Filename or ClassnameRuby filename or class name which implements the protocolTrue
Protocol specific parametersAdditional parameters used by the protocolFalse

Example Usage:

INTERFACE DATA_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil nil
  MAP_TARGET DATA
  # Rather than defining the LENGTH protocol on the INTERFACE line we define it here
  PROTOCOL READ LengthProtocol 0 16 0 1 BIG_ENDIAN 4 0xBA5EBA11
INTERFACE DATA_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil BURST
  MAP_TARGET DATA
  PROTOCOL READ IgnorePacketProtocol INST IMAGE # Drop all INST IMAGE packets

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.

ParameterDescriptionRequired
NameThe option to set. OpenC3 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).True
ParametersParameters to pass to the optionFalse

Example Usage:

INTERFACE SERIAL_INT serial_interface.rb COM1 COM1 115200 NONE 1 10.0 nil
  OPTION FLOW_CONTROL RTSCTS
  OPTION DATA_BITS 8

SECRET

(Since 5.3.0)
Define a secret needed by this interface

Defines a secret for this interface and optionally assigns its value to an option

ParameterDescriptionRequired
TypeENV or FILE. ENV will mount the secret into an environment variable. FILE mounts the secret into a file.True
Secret NameThe name of the secret to retrieveTrue
Environment Variable or File PathEnvironment variable name or file path to store secretTrue
Option NameInterface option to pass the secret valueFalse
Secret Store NameName of the secret store for stores with multipart keysFalse

Example Usage:

SECRET ENV USERNAME ENV_USERNAME USERNAME
SECRET FILE KEY "/tmp/DATA/cert" KEY

ENV

(Since 5.7.0)
Sets an environment variable in the microservice.

ParameterDescriptionRequired
KeyEnvironment variable nameTrue
ValueEnvironment variable valueTrue

Example Usage:

ENV COMPANY OpenC3

WORK_DIR

(Since 5.7.0)
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.

ParameterDescriptionRequired
DirectoryWorking 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

Example Usage:

WORK_DIR '/openc3/lib/openc3/microservices'

PORT

(Since 5.7.0)
Open port for the microservice

Kubernetes needs a Service to be applied to open a port so this is required for Kubernetes support

ParameterDescriptionRequired
NumberPort numberTrue
ProtocolPort protocol. Default is TCP.False

Example Usage:

PORT 7272

CMD

(Since 5.7.0)
Command line to execute to run the microservice.

Command line to execute to run the microservice.

ParameterDescriptionRequired
ArgsOne or more arguments to exec to run the microservice.True

Example Usage:

CMD ruby interface_microservice.rb DEFAULT__INTERFACE__INT1

CONTAINER

(Since 5.7.0)
Docker Container

Container to execute and run the microservice in. Only used in COSMOS Enterprise Edition.

ParameterDescriptionRequired
ArgsName of the containerFalse

ROUTE_PREFIX

(Since 5.7.0)
Prefix of route

Prefix of route to the microservice to expose externally with Traefik

ParameterDescriptionRequired
Route PrefixRoute prefix. Must be unique across all scopes. Something like /myprefixTrue

Example Usage:

ROUTE_PREFIX /interface

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.

ParameterDescriptionRequired
NameName of the routerTrue
FilenameRuby file to use when instantiating the interface.

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

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

TARGET

Defines a new target

ParameterDescriptionRequired
Folder NameThe target folderTrue
NameThe 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 INST

TARGET Modifiers

The following keywords must follow a TARGET keyword.

CMD_BUFFER_DEPTH

(Since 5.2.0)
Number of commands to buffer to ensure logged in order

ParameterDescriptionRequired
Buffer DepthBuffer depth in packets (Default = 5)True

CMD_LOG_CYCLE_TIME

Command binary logs can be cycled on a time interval.

ParameterDescriptionRequired
TimeMaximum 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.

ParameterDescriptionRequired
SizeMaximum file size in bytes (default = 50_000_000)True

CMD_LOG_RETAIN_TIME

How long to keep raw command logs in seconds.

ParameterDescriptionRequired
TimeNumber 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.

ParameterDescriptionRequired
TimeMaximum 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.

ParameterDescriptionRequired
SizeMaximum file size in bytes (default = 50_000_000)True

CMD_DECOM_LOG_RETAIN_TIME

How long to keep decom command logs in seconds.

ParameterDescriptionRequired
TimeNumber of seconds to keep decom command logs (default = nil = Forever)True

TLM_BUFFER_DEPTH

(Since 5.2.0)
Number of telemetry packets to buffer to ensure logged in order

ParameterDescriptionRequired
Buffer DepthBuffer depth in packets (Default = 60)True

TLM_LOG_CYCLE_TIME

Telemetry binary logs can be cycled on a time interval.

ParameterDescriptionRequired
TimeMaximum 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.

ParameterDescriptionRequired
SizeMaximum file size in bytes (default = 50_000_000)True

TLM_LOG_RETAIN_TIME

How long to keep raw telemetry logs in seconds.

ParameterDescriptionRequired
TimeNumber 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.

ParameterDescriptionRequired
TimeMaximum 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.

ParameterDescriptionRequired
SizeMaximum file size in bytes (default = 50_000_000)True

TLM_DECOM_LOG_RETAIN_TIME

How long to keep decom telemetry logs in seconds.

ParameterDescriptionRequired
TimeNumber 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.

ParameterDescriptionRequired
TimeNumber 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.

ParameterDescriptionRequired
TimeNumber 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.

ParameterDescriptionRequired
TimeNumber 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.

ParameterDescriptionRequired
TimeNumber 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.

ParameterDescriptionRequired
TimeNumber of seconds to keep all reduced telemetry logs (default = nil = Forever)True

CLEANUP_POLL_TIME

Period at which to run the cleanup process.

ParameterDescriptionRequired
TimeNumber of seconds between runs of the cleanup process (default = 900 = 15 minutes)True

REDUCER_DISABLE

Disables the data reduction microservice for the target

REDUCER_MAX_CPU_UTILIZATION

Maximum amount of CPU utilization to apply to data reduction

ParameterDescriptionRequired
Percentage0 to 100 percent (default = 30)True

TARGET_MICROSERVICE

(Since 5.2.0)
Breaks a target microservice out into its own process.

Can be used to give more resources to processing that is falling behind. If defined multiple times for the same type, will create multiple processes. Each process can be given specific packets to process with the PACKET keyword.

ParameterDescriptionRequired
TypeThe target microservice type. Must be one of DECOM, COMMANDLOG, DECOMCMDLOG, PACKETLOG, DECOMLOG, REDUCER, or CLEANUPTrue

PACKET

(Since 5.2.0)
Packet Name to allocate to the current TARGET_MICROSERVICE.

ParameterDescriptionRequired
Packet NameThe packet name. Does not apply to REDUCER or CLEANUP target microservice types.True

DISABLE_ERB

(Since 5.12.0)
Disable ERB processing

Disable ERB processing for the entire target or a set of regular expressions over its filenames

ParameterDescriptionRequired
RegexRegex to match against filenames. If match, then no ERB processingFalse

MICROSERVICE

Defines a new microservice

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

ParameterDescriptionRequired
Microservice Folder NameThe exact name of the microservice folder in the plugin. ie. microservices/MicroserviceFolderNameTrue
Microservice NameThe specific name of this instance of the microservice in the OpenC3 systemTrue

Example Usage:

MICROSERVICE EXAMPLE openc3-example

MICROSERVICE Modifiers

The following keywords must follow a MICROSERVICE keyword.

ENV

Sets an environment variable in the microservice.

ParameterDescriptionRequired
KeyEnvironment variable nameTrue
ValueEnvironment variable valueTrue

Example Usage:

MICROSERVICE EXAMPLE openc3-example
  ENV COMPANY OpenC3

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.

ParameterDescriptionRequired
DirectoryWorking 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

Example Usage:

MICROSERVICE EXAMPLE openc3-example
  WORK_DIR .

PORT

(Since 5.0.10)
Open port for the microservice

Kubernetes needs a Service to be applied to open a port so this is required for Kubernetes support

ParameterDescriptionRequired
NumberPort numberTrue
ProtocolPort protocol. Default is TCP.False

Example Usage:

MICROSERVICE EXAMPLE openc3-example
  PORT 7272

TOPIC

Associate a Redis topic

Redis topic to associate with this microservice. Standard OpenC3 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.

ParameterDescriptionRequired
Topic NameRedis Topic to associate with the microserviceTrue

Example Usage:

MICROSERVICE EXAMPLE openc3-example
  # Manually assigning topics is an advanced topic and requires
  # intimate knowledge of the internal COSMOS data structures.
  TOPIC DEFAULT__openc3_log_messages
  TOPIC DEFAULT__TELEMETRY__EXAMPLE__STATUS

TARGET_NAME

Associate a OpenC3 target

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

ParameterDescriptionRequired
Target NameOpenC3 target to associate with the microserviceTrue

Example Usage:

MICROSERVICE EXAMPLE openc3-example
  TARGET_NAME EXAMPLE

CMD

Command line to execute to run the microservice.

Command line to execute to run the microservice.

ParameterDescriptionRequired
ArgsOne or more arguments to exec to run the microservice.True

Example Usage:

MICROSERVICE EXAMPLE openc3-example
  CMD ruby example_target.rb

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 OpenC3 configuration file. Multiple OPTION keywords can be used to pass multiple options to the microservice.

ParameterDescriptionRequired
Option NameName of the optionTrue
Option Value(s)One or more values to associate with the optionTrue

CONTAINER

Docker Container

Container to execute and run the microservice in. Only used in COSMOS Enterprise Edition.

ParameterDescriptionRequired
ArgsName of the containerFalse

SECRET

(Since 5.3.0)
Define a secret needed by this microservice

Defines a secret for this microservice

ParameterDescriptionRequired
TypeENV or FILE. ENV will mount the secret into an environment variable. FILE mounts the secret into a file.True
Secret NameThe name of the secret to retrieveTrue
Environment Variable or File PathEnvironment variable name or file path to store secretTrue
Secret Store NameName of the secret store for stores with multipart keysFalse

Example Usage:

SECRET ENV USERNAME ENV_USERNAME
SECRET FILE KEY "/tmp/DATA/cert"

ROUTE_PREFIX

(Since 5.5.0)
Prefix of route

Prefix of route to the microservice to expose externally with Traefik

ParameterDescriptionRequired
Route PrefixRoute prefix. Must be unique across all scopes. Something like /myprefixTrue

Example Usage:

MICROSERVICE CFDP CFDP
  ROUTE_PREFIX /cfdp

DISABLE_ERB

(Since 5.12.0)
Disable ERB processing

Disable ERB processing for the entire microservice or a set of regular expressions over its filenames

ParameterDescriptionRequired
RegexRegex to match against filenames. If match, then no ERB processingFalse

TOOL

Define a tool

Defines a tool that the plugin adds to the OpenC3 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.

ParameterDescriptionRequired
Tool Folder NameThe exact name of the tool folder in the plugin. ie. tools/ToolFolderNameTrue
Tool NameName of the tool that is displayed in the OpenC3 Navigation menuTrue

Example Usage:

TOOL DEMO Demo

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/ToolFolderName".

ParameterDescriptionRequired
UrlThe url. If not given defaults to tools/ToolFolderName. 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".

ParameterDescriptionRequired
UrlThe 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 OpenC3. NEW opens the tool in a new TAB.

ParameterDescriptionRequired
Window ModeTool display mode

Valid Values: INLINE, IFRAME, NEW
True

ICON

Set tool icon

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

ParameterDescriptionRequired
Icon NameIcon 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 which becomes a submenu in the Navigation menu.

ParameterDescriptionRequired
Category NameCategory to associate the tool withTrue

SHOWN

Show the tool or not

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

ParameterDescriptionRequired
ShownWhether or not the tool is shown. TRUE or FALSE

Valid Values: true, false
True

POSITION

(Since 5.0.8)
Position of the tool in the nav bar

Position of the tool as an integer starting at 1. Tools without a position are appended to the end as they are installed.

ParameterDescriptionRequired
PositionNumerical positionTrue

DISABLE_ERB

(Since 5.12.0)
Disable ERB processing

Disable ERB processing for the entire tool or a set of regular expressions over its filenames

ParameterDescriptionRequired
RegexRegex to match against filenames. If match, then no ERB processingFalse

WIDGET

Define a custom widget

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

ParameterDescriptionRequired
Widget NameThe 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

WIDGET Modifiers

The following keywords must follow a WIDGET keyword.

DISABLE_ERB

(Since 5.12.0)
Disable ERB processing

Disable ERB processing for the entire widget or a set of regular expressions over its filenames

ParameterDescriptionRequired
RegexRegex to match against filenames. If match, then no ERB processingFalse