docs.openc3.com/docs/getting-started/requirements.md
---
sidebar_position: 6
title: Requirements and Design
---
OpenC3 COSMOS is a command and control system providing commanding, scripting, and data visualization capabilities for embedded systems and systems of systems. COSMOS is intended for use during all phases of testing (board, box, integrated system) and during operations.
COSMOS is currently made up of the following applications:
1. **Command and Telemetry Server** - Provides status of realtime commanding, telemetry reception, logging, limits monitoring, and packet routing.
1. **Limits Monitor** - Monitors telemetry with defined limits and shows items that currently are or have violated limits.
1. **Command Sender** - Provides a graphical interface for manually sending individual commands.
1. **Script Runner** - Executes scripts and provides highlighting of the currently executing line. Now also includes TestRunner functionality.
1. **Packet Viewer** - Provides realtime visualization of every telemetry packet that has been defined.
1. **Telemetry Viewer** - Provides custom telemetry screen functionality with advanced layout and visualization widgets.
1. **Telemetry Grapher** - Provides realtime and offline graphing of telemetry data.
1. **Data Extractor** - Extracts telemetry and command packet log files into CSV data.
1. **Data Viewer** - Provides text based telemetry visualization for items.
1. **Bucket Explorer** - Browse the COSMOS bucket storage in any cloud environment.
1. **Table Manager** - Binary file editor with Script Runner integration for upload / download.
1. **Handbooks** - Generate html page of the command and telemetry definitions.
1. **Calendar** - Provides scheduling of commands and scripts. Also provides a framework for reserving resources.
1. **Admin** - Provides an administrative interface to COSMOS.
More detailed descriptions, requirements, and design for each tool are found later in this document. Additionally, each of the above applications is built using COSMOS libraries that are available for use as a framework to develop custom program/project applications.
## Terminology
The COSMOS system uses several terms that are important to understand. The following table defines these terms.
| Term | Definition |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Target | A COSMOS target is an embedded system that the COSMOS Command and Telemetry Server connects to using an interface in order to send commands to and/or receive telemetry from. |
| Command | A packet of information telling a target to perform an action of some sort. |
| Telemetry Packet | A packet of information providing status from a target. |
| Interface | A Ruby class that knows how to send commands to and/or receive telemetry from a target. COSMOS comes with interfaces that support TCP/IP, UDP, and serial connections. Custom interfaces are easy to add to the system. |
| Ruby | The powerful dynamic programming language used to write the COSMOS applications and libraries as well as COSMOS scripts and test procedures. |
| Configuration Files | COSMOS uses simple plain text configuration files to define commands and telemetry packets, and to configure each COSMOS application. These files are easily human readable/editable and machine readable/editable. |
| Packet Log Files | Binary files containing either logged commands or telemetry packets. |
| Message Log Files | Text files containing messages generated by the system. |
| Tool | Another name for a COSMOS application. |
## Overall Architecture and Context Diagram
The following diagram shows the COSMOS 5 architecture.
Key aspects of this architecture:
COSMOS 5 is a cloud native, containerized, microservice oriented command and control system. All the COSMOS microservices are docker containers which is why Docker is shown containing the entire COSMOS system. The green boxes on the left represent external embedded systems (Targets) which COSMOS connects to. The Redis data store contains the configuration for all the microservices, the current value table, as well as data streams containing decommutated data. The Minio data store contains plugins, targets, configuration data, text logs as well as binary logs of all the raw, decommutated, and reduced data. Users interact with COSMOS from a web browser which routes through the internal Traefik load balancer.
- COSMOS can connect to many different kinds of targets. The examples include things like Flight software (FSW), Ground Support Equipment (GSE), Labview, and COTS targets such as an Agilent power supply. Any embedded system that provides a communication interface can be connected to COSMOS.
- COSMOS ships with interfaces for connecting over TCP/IP, UDP, MQTT, and serial connections. This covers most systems, but custom interfaces can also be written to connect to anything.
- All realtime communication with targets flows through the COSMOS system. This ensures all commands and telemetry are logged.
- Every tool is configured with plain text configuration files.
- Program specific tools can be written using the COSMOS libraries that can interact with the realtime command and telemetry streams and can process logged data.
## Overall Requirements
| Reqt. ID | Description | Test Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| COSMOS-1 | All COSMOS core functionality shall be containerized. | Verify COSMOS is running in Docker |
| COSMOS-2 | The COSMOS user interface shall be accessible from Chromium based web browsers | Open COSMOS in Chrome/Edge |
| COSMOS-3 | The COSMOS user interface shall be accessible from the Firefox web browser | Open COSMOS in Firefox |
| COSMOS-4 | COSMOS shall log all commands sent | |
| COSMOS-5 | COSMOS shall log all telemetry received | |
| COSMOS-6 | COSMOS shall decommutate all telemetry packets received | |
| COSMOS-7 | COSMOS shall support autonomously attempting to connect to targets. | Verify targets are connected upon starting the CTS. |
| COSMOS-8 | COSMOS shall time stamp telemetry packets upon receipt. | Verify logged packets are timestamped. |
| COSMOS-9 | COSMOS shall time stamp telemetry packets to a resolution of 1 millisecond or better. Note: This requirement only refers to resolution. COSMOS does not run on real-time operating systems and accuracy cannot be guaranteed. | View time stamps in log. |
| COSMOS-10 | COSMOS shall time stamp received telemetry with a UTC timestamp. | Verify logged time stamps are as expected. |
| COSMOS-11 | COSMOS shall maintain a timestamped log of commands received, limits violations, and errors encountered. | View COSMOS message log. |
## Api Requirements
| Reqt. ID | Description | Test Description |
| -------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
| API-1 | The COSMOS API shall allow scripted connection and disconnection of interfaces. | Disconnect and connect an interface from a script. |
| API-2 | The COSMOS API shall allow scripted connection and disconnection of routers. | Disconnect and connect a router from a script. |
| API-3 | The COSMOS API shall allow scripted setting of the current limits set. | Select a different limits set from a script. |
| API-4 | The COSMOS API shall allow commanding of targets | Send a command |
| API-5 | The COSMOS API shall allow reading the current value of any telemetry item | Read a telemetry point |
| API-6 | The COSMOS API shall allow streaming realtime and logged telemetry packets | Stream telemetry packets |
| API-7 | The COSMOS API shall allow streaming realtime and logged command packets | Stream command packets |
| API-8 | The COSMOS API shall allow starting COSMOS scripts | Start a script using the API |
## Command and Telemetry Server
The Command and Telemetry server provides status on the the overall COSMOS installation for a specific scope.
| Reqt. ID | Description | Test Description |
| -------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| CTS-1 | The Command and Telemetry Server shall display a list of all interfaces. | View the Interfaces tab. |
| CTS-2 | The Command and Telemetry Server shall allow manual connection and disconnection of interfaces. | Press a GUI button to disconnect and connect an interface. |
| CTS-3 | The Command and Telemetry Server shall display a list of all targets. | View the Targets tab. |
| CTS-4 | The Command and Telemetry Server shall display a list of known commands. | View the Cmd Packets tab. |
| CTS-5 | The Command and Telemetry Server shall display raw command data for the most recent command received. | View the Cmd Packets tab and click the View Raw button for a command. |
| CTS-6 | The Command and Telemetry Server shall display a list of known telemetry packets. | View the Tlm Packets tab. |
| CTS-7 | The Command and Telemetry Server shall display raw telemetry packet data for the most recent telemetry packet received. | View the Tlm Packets tab and click the View Raw button for a telemetry packet. |
| CTS-8 | The Command and Telemetry Server shall display a list of all routers. | View the Routers tab. |
| CTS-9 | The Command and Telemetry Server shall allow manual connection and disconnection of routers. | Press a GUI button to disconnect and connect a router. |
| CTS-10 | The Command and Telemetry Server shall allow manually setting the current limits set. | Select a different limits set from the combobox. |
| CTS-11 | The Command and Telemetry Server shall support opening telemetry packets in Packet Viewer. | On the Tlm Packets tab click View in Packet Viewer for a telemetry packet. |
| CTS-12 | The Command and Telemetry Server shall display time stamps in local time. | View time stamps in log. |
## Limits Monitor
Limits Monitor displays all telemetry points that are currently out of limits and also shows any telemetry points that have gone out of limits since Limits Monitor was started.
| Reqt. ID | Description | Test Description |
| -------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| LM-1 | Limits Monitor shall display all telemetry points currently out of limits. | View displayed telemetry points. |
| LM-2 | Limits Monitor shall support ignoring telemetry points. | Click ignore on a telemetry point. |
| LM-3 | Limits Monitor shall keep a displayed log of limits violations. | View the log tab. |
| LM-4 | Limits Monitor shall continue displaying a telemetry point that temporarily went out of limits. | Watch until a telemetry points returns to green. |
| LM-5 | Limits Monitor shall support saving its configuration. | Save the configuration. |
| LM-6 | Limits Monitor shall support loading its configuration. | Load the configuration. |
## Command Sender
Command Sender provides an easy method to send single commands to targets. The graphical user interface provides simple dropdowns to quickly select the desired command to send organized by target name and command name. After the user has selected the command, they then fill in the desired command parameters and click send to send the command to the target.
| Reqt. ID | Description | Test Description |
| -------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| CMD-1 | Command Sender shall allow selection of a command by target name and packet name. | Select a specific command by target name and packet name in the drop down menus. |
| CMD-2 | Command Sender shall allow sending the selected command. | Send the selected command by pressing the Send button. |
| CMD-3 | Command Sender shall display non-ignored parameters for the selected command. | Select a specific command and verify the expected parameters are shown. |
| CMD-4 | Command Sender shall provide a mechanism to select state values for command parameters with states. | Select a specific state value for a specific command with states. |
| CMD-5 | Command Sender shall allow sending a manually entered value for a command parameter with states. | Manually enter a value for a specific command with states. |
| CMD-6 | Command Sender shall refuse to send commands if required parameters are not provided. | Attempt to send a command with a required parameter not filled out. |
| CMD-7 | Command Sender shall support sending commands while ignoring range checking. | Enter Ignore Range Checking mode and then send a command with an out of range parameter. |
| CMD-8 | Command Sender shall optionally display state values in hex. | Enter "Display State Values in Hex" mode and verify state values are displayed as hex. |
| CMD-9 | Command Sender shall optionally display ignored command parameters. | Enter "Show Ignored Parameters" mode and verify ignored parameters are displayed. |
| CMD-10 | Command Sender shall respect hazardous commands and notify the user before proceeding. | Send a hazardous command and verify a dialog box appears before the command is sent. Verify both accepting the dialog and declining to send. |
| CMD-11 | Command Sender shall keep a command history of each command sent. | Send a command and verify that it shows up in the command history box. |
| CMD-12 | Command Sender shall allow resending of any command in the command history. | Resend one of the commands in the command history box. |
## Script Runner
Script Runner provides a visual interface for editing and executing scripts/procedures. A full featured text editor provides syntax highlighting and code completion while developing scripts. During script execution, the currently executing line is highlighted and any logged messages are highlighted to the user. If any failure occurs, the script is paused and the user alerted. The user can then decide whether to stop the script, or ignore the failure and continue. The user can also retry the failed lines, or other nearby lines before proceeding.
Script Runner now also provides a structured methodology for designing system level scripting that mirrors the very successful pattern used in software unit tests (previously implemented in the Test Runner tool). System level tests/procedures are built up of cases that are organized into groups. For example, you might have one group that verified all of the requirements associated with a particular mechanism. Ideally you would break this down into individual cases for different scenarios. One perhaps for opening a shutter, another for closing it, etc. Cases are ideally small and independent tasks. A number of these groups are then combined into an overall suite which would be run to execute a major test such as EMI, or software FQT.
| Reqt. ID | Description | Test Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SR-1 | Script Runner shall provide a text editor for developing test scripts. | Open Script Runner and create a simple test script. Perform all standard file operations including New, Open, Reload, Close, Save, and Save As. Perform all standard editing operations such as Cut, Copy, Paste, Undo, Redo, Select All, and Comment/Uncomment lines. |
| SR-2 | Script Runner shall provide search and replace functionality. | Perform all standard search and replace functionality, including search, replace, find next, and find previous. |
| SR-3 | Script Runner shall provide code completion for cmd(), tlm(), and wait_check() COSMOS API methods. Note: Other methods may also be supported. | Create a script and exercise code completion on the mentioned keywords. |
| SR-4 | Script Runner shall execute Ruby-based COSMOS scripts. | Press start and execute a script. |
| SR-5 | Script Runner shall highlight the currently executing line of the script. | Verify that lines are highlighted as a test script executes. |
| SR-6 | Script Runner shall allow pausing an executing script. | Press pause button and verify script is paused. Press start to resume. |
| SR-7 | Script Runner shall allow stopping an executing script. | Press stop and verify script stops. |
| SR-8 | Script Runner shall pause an executing script upon the occurrence of an error. | Create a script with a statement that is guaranteed to fail and verify that the script is paused. |
| SR-9 | Script Runner shall log commands sent. | Execute a script that sends a command and verify it is logged. |
| SR-10 | Script Runner shall log text written to STDOUT. Note: Typically through the puts method. | Execute a script that uses puts to write a message and verify it is logged. |
| SR-11 | Script Runner shall log wait times. | Execute a script that includes a wait method and verify wait time is logged. |
| SR-12 | Script Runner shall log errors that occur while the script is executing. | Create a script with a check statement that is guaranteed to fail and verify it is logged. |
| SR-13 | Script Runner shall log check statement success and failure. | Create a script with a check statement that is guaranteed to fail and one that is guaranteed to succeed. Verify both the success and failure are logged. |
| SR-14 | Script Runner shall support executing selected lines. | Select a set of lines and execute them using Script->Execute Selected Lines. |
| SR-15 | Script Runner shall support executing selected lines while paused. | Select a set of lines and execute them from the right-click context menu. |
| SR-16 | Script Runner shall support starting a script from any line. | Place the mouse cursor at the desired first line and then select Script->Execute From Cursor. |
| SR-17 | Script Runner shall support a mnemonic checking function. | Select Script->Mnemonic Check. |
| SR-18 | Script Runner shall support a syntax checking function. | Select Script->Ruby Syntax Check. |
| SR-19 | Script Runner shall support viewing the script instrumentation. | Select Script->View Instrumented Script. |
| SR-20 | Script Runner shall support an disconnected mode to allow for executing scripts without a connection to the Command and Telemetry Server. | Select Script->Toggle Disconnect. Execute a script with commands and check statements and verify that it runs to completion. |
| SR-21 | Script Runner shall support a Debug terminal to aid in debugging scripts. | Select Script->Toggle Debug. |
| SR-22 | Script Runner shall support a step mode where the script will stop and wait for use interaction after each line. | Press Step to progress through the script. |
| SR-23 | Script Runner shall support breakpoint functionality. | Create a breakpoint then execute the script and verify it stops at the specified line. |
| SR-25 | Script Runner Suite Mode shall support executing individual test suites. | Execute an individual test suite. |
| SR-26 | Script Runner Suite Mode shall support executing individual test groups. | Execute an individual test group. |
| SR-27 | Script Runner Suite Mode shall support executing individual test cases. | Execute an individual test case. |
| SR-28 | Script Runner Suite Mode shall support executing test group setup and teardown methods individually. | Execute a test group setup. Execute a test group teardown. |
| SR-29 | Script Runner Suite Mode shall support executing test suite setup and teardown methods individually. | Execute a test suite setup. Execute a test suite teardown. |
| SR-30 | Script Runner Suite Mode shall create a report after executing any suite test. | Verify a report is generated after executing a suite. |
| SR-31 | Script Runner Suite Mode shall support pausing when an error occurs. | Execute a test script with the pause on error box checked and without. |
| SR-32 | Script Runner Suite Mode shall support allowing the user to proceed on an error. | Execute a test script with the Allow go/retry on error box checked and without. |
| SR-33 | Script Runner Suite Mode shall support aborting execution on an error. | Execute a test script with the abort on error box checked and without. |
| SR-34 | Script Runner Suite Mode shall support looping a test. | Execute a test script with the loop testing box checked and without. |
| SR-35 | Script Runner Suite Mode shall support breaking the looping of a test on error. | Execute a test script with the break loop on error box checked and without. |
| SR-36 | Script Runner Suite Mode shall support a user readable flag indicating that loop testing is occurring. | Execute a test script that checks the $loop_testing variable while looping and again while not looping. |
| SR-37 | Script Runner Suite Mode shall support a user readable flag indicating manual operations are desired. | Execute a test script with the manual box checked and without. |
## Packet Viewer
Packet Viewer provides a simple tool to view the realtime contents of any telemetry packet defined in the system in a tabular, key-value format.
| Reqt. ID | Description | Test Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| PV-1 | Packet Viewer shall allow selection of a telemetry packet by target name and packet name. | Select a specific telemetry packet by target name and packet name in the drop down menus. |
| PV-2 | Packet Viewer shall display the contents of the selected telemetry packet. | Ensure all items of the selected telemetry packet are displayed and updating. |
| PV-3 | Packet Viewer shall provide a mechanism to get detailed information on a telemetry item. | Right click on a telemetry item and select "Details" from the context menu. |
| PV-4 | Packet Viewer shall provide a mechanism to view a graph of any telemetry item. | Right click on a telemetry item and select "Graph" from the context menu. |
| PV-5 | Packet Viewer shall color telemetry values based upon limits state. | View a packet with items containing limits and verify they are colored. |
| PV-6 | Packet Viewer shall support a configurable polling rate. | Select File->Options and change the polling rate. |
| PV-7 | Packet Viewer shall support a color-blind mode to allow distinguishing limits states for those who are color blind. | Select View->Color Blind Mode and verify that items with limits are also displayed with a textual indication of limits state color. |
| PV-8 | Packet Viewer shall support displaying telemetry in each of the four COSMOS value types (raw, converted, formatted, and formatted with units) | In the View menu, select each of the four value types and verify values are displayed accordingly. |
## Telemetry Viewer
Telemetry Viewer provides a way to organize telemetry points into custom "screens" that allow for the creation of unique and organized views of telemetry data. Screens are made up of widgets or small GUI components that display telemetry in unique ways.
| Reqt. ID | Description | Test Description |
| -------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| TV-1 | Telemetry Viewer shall display user-defined telemetry screens. | Open a telemetry |
| TV-2 | Telemetry Viewer shall display realtime data. | Verify telemetry screens show realtime data. |
| TV-3 | Telemetry Viewer shall support saving open telemetry screens and their positions. | Open three telemetry screens and then select File->Save Configuration. |
## Telemetry Grapher
Telemetry Grapher performs graphing of telemetry points in both realtime and log file playback.
| Reqt. ID | Description | Test Description |
| -------- | -------------------------------------------------------------------------- | ------------------------------------------------------- |
| TG-1 | Telemetry Grapher shall provide line graphs of telemetry points. | Add several housekeeping data objects to a plot. |
| TG-2 | Telemetry Grapher shall support realtime graphing of telemetry. | Press Start to start realtime graphing. |
| TG-3 | Telemetry Grapher shall support graphing data from logged telemetry. | Select the menu option to graph data from a logged data |
| TG-4 | Telemetry Grapher shall support multiple plots per browser tab. | Add multiple plots. |
| TG-5 | Telemetry Grapher shall support multiple telemetry points per plot. | Add multiple data objects to one plot. |
| TG-6 | Telemetry Grapher shall support saving a variable number of data points. | Edit Points Saved. |
| TG-7 | Telemetry Grapher shall support graphing a variable duration of time. | Edit Seconds Plotted. |
| TG-8 | Telemetry Grapher shall support graphing a variable number of data points. | Edit Points Plotted. |
| TG-9 | Telemetry Grapher shall support saving its configuration. | Save the current configuration. |
| TG-10 | Telemetry Grapher shall support loading its configuration. | Load the previously saved configuration. |
## Data Extractor
Data Extractor processes logged data and extracts data into a CSV format for analysis in Excel or other tools.
| Reqt. ID | Description | Test Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| DE-1 | Data Extractor shall support adding individual telemetry points. | Add an individual telemetry point. |
| DE-2 | Data Extractor shall support adding entire telemetry packets. | Add an entire packet. |
| DE-3 | Data Extractor shall support adding entire telemetry targets. | Add all packets for a target. |
| DE-4 | Data Extractor shall support selecting the value type to extract for each telemetry point (RAW, CONVERTED, FORMATTED, WITH_UNITS) | Click an item and change the value type. |
| DE-5 | Data Extractor shall support saving configurations. | Select File->Save Config |
| DE-6 | Data Extractor shall support loading configurations. | Select File->Load Config |
| DE-7 | Data Extractor shall support deleting items | Select an Item and press delete |
## Data Viewer
Data Viewer provides for textual display of telemetry packets where other display methods are not a good fit. It is especially useful for memory dumps and for log message type data display.
| Reqt. ID | Description | Test Description |
| -------- | ------------------------------------------------------------------- | ----------------------------------------- |
| DV-1 | Data Viewer shall support realtime processing of telemetry packets. | Press Start to start realtime processing. |
| DV-2 | Data Viewer shall support logged playback of telemetry packets. | Select a time range to playback. |
| DV-3 | Data Viewer shall support textual display of telemetry packets. | View the display of data. |
| DV-4 | Data Viewer shall support multiple tabs for data display. | Switch between several tabs of data. |
| DV-5 | Data Viewer shall support deleting tabs. | Delete a tab. |
## Calendar
The Calendar tool provides a user interface and API for initiating scheduled actions in COSMOS
| Reqt. ID | Description | Test Description |
| -------- | -------------------------------------------------------------- | ------------------------------------------ |
| TL-1 | Calendar shall allow creating new timelines | Click the button and create a new timeline |
| TL-2 | Calendar shall allow scheduling commands for future execection | Add a command to a timeline |
| TL-3 | Calendar shall allow scheduling scripts for future execution | Add a script to a timeline |
| TL-4 | Calendar shall allow for reserving a resource | Add a reservation to a timeline |
| TL-5 | Calendar shall track success or failure of commands | Look at status from a completed command |
| TL-6 | Calendar shall track success or failure of scripts | Look at status from a completed script |
| TL-7 | Calendar shall allow deleting activities from timelines | Delete a preexisting item from a timeline |
| TL-8 | Calendar shall allow deleting timelines | Delete a timeline |
## Admin
The Admin tool provides administrative functionality including managing plugins for the COSMOS system
| Reqt. ID | Description | Test Description |
| -------- | ------------------------------------------------------------- | -------------------------------------------- |
| AD-1 | The Admin Tool shall allow installing plugins | Upload and Install a Plugin |
| AD-2 | The Admin Tool shall support upgrading plugins | Upgrade an installed plugin |
| AD-3 | The Admin Tool shall support uninstalling plugins | Uninstall a plugin |
| AD-4 | The Admin Tool shall display information on installed plugins | View info on Interfaces, Microservices, etc |
| AD-5 | The Admin Tool shall support editing microservices | Edit the settings for a microservice |
| AD-6 | The Admin Tool shall support discovery of plugins | Discover and download a plugin |
| AD-7 | The Admin Tool shall support adding links to external tools | Add a link to Google |
| AD-8 | The Admin Tool shall support reordering tools | Reorder tools on the tools tab |
| AD-9 | The Admin Tool shall support configuring a classification bar | Add a classification bar on the settings tab |