Skip to content

Commit

Permalink
Merge pull request #887 from OpenC3/docs
Browse files Browse the repository at this point in the history 
New docusaurus based docs website
  • Loading branch information
@ryanmelt
ryanmelt authored Oct 20, 2023
2 parents 82858c1 + 8076d54 commit 5dc5bb7
Show file tree
Hide file tree
Showing 636 changed files with 36,507 additions and 5 deletions.
20 changes: 20 additions & 0 deletions docs.openc3.com/.gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Dependencies
/node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
42 changes: 42 additions & 0 deletions docs.openc3.com/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Website

This is the OpenC3 COSMOS Documentation Website
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.

### Installation

```
$ yarn
```

### Local Development

```
$ yarn start
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

### Build

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.

### Deployment

Using SSH:

```
$ USE_SSH=true yarn deploy
```

Not using SSH:

```
$ GIT_USER=<Your GitHub username> yarn deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
3 changes: 3 additions & 0 deletions docs.openc3.com/babel.config.js
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
3 changes: 3 additions & 0 deletions docs.openc3.com/build.sh
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
yarn
cd scripts && ruby generate_docs_from_yaml.rb && cd ..
yarn build
8 changes: 8 additions & 0 deletions docs.openc3.com/docs/configuration/_category_.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "Configuration",
"position": 2,
"link": {
"type": "generated-index",
"slug": "/configuration"
}
}
59 changes: 59 additions & 0 deletions docs.openc3.com/docs/configuration/_command.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
sidebar_position: 4
title: Commands
---

<!-- Be sure to edit _command.md because command.md is a generated file -->

## Command Definition Files

Command definition files define the command packets that can be sent to COSMOS targets. One large file can be used to define the command packets, or multiple files can be used at the user's discretion. Command definition files are placed in the target's cmd_tlm directory and are processed alphabetically. Therefore if you have some command files that depend on others, e.g. they override or extend existing commands, they must be named last. The easist way to do this is to add an extension to an existing file name. For example, if you already have cmd.txt you can create cmd_override.txt for commands that depends on the definitions in cmd.txt. Also note that due to the way the [ASCII Table](http://www.asciitable.com/) is structured, files beginning with capital letters are processed before lower case letters.

When defining command parameters you can choose from the following data types: INT, UINT, FLOAT, STRING, BLOCK. These correspond to integers, unsigned integers, floating point numbers, strings and binary blocks of data. The only difference between a STRING and BLOCK is when COSMOS reads the binary command log it stops reading a STRING type when it encounters a null byte (0). This shows up in the text log produced by Data Extractor. Note that this does NOT affect the data COSMOS writes as it's still legal to pass null bytes (0) in STRING parameters.

<div style={{"clear": 'both'}}></div>

# Command Keywords

COSMOS_META

## Example File

**Example File: TARGET/cmd_tlm/cmd.txt**

<!-- prettier-ignore -->
```ruby
COMMAND TARGET COLLECT_DATA BIG_ENDIAN "Commands my target to collect data"
PARAMETER CCSDSVER 0 3 UINT 0 0 0 "CCSDS PRIMARY HEADER VERSION NUMBER"
PARAMETER CCSDSTYPE 3 1 UINT 1 1 1 "CCSDS PRIMARY HEADER PACKET TYPE"
PARAMETER CCSDSSHF 4 1 UINT 0 0 0 "CCSDS PRIMARY HEADER SECONDARY HEADER FLAG"
ID_PARAMETER CCSDSAPID 5 11 UINT 0 2047 100 "CCSDS PRIMARY HEADER APPLICATION ID"
PARAMETER CCSDSSEQFLAGS 16 2 UINT 3 3 3 "CCSDS PRIMARY HEADER SEQUENCE FLAGS"
PARAMETER CCSDSSEQCNT 18 14 UINT 0 16383 0 "CCSDS PRIMARY HEADER SEQUENCE COUNT"
PARAMETER CCSDSLENGTH 32 16 UINT 4 4 4 "CCSDS PRIMARY HEADER PACKET LENGTH"
PARAMETER ANGLE 48 32 FLOAT -180.0 180.0 0.0 "ANGLE OF INSTRUMENT IN DEGREES"
POLY_WRITE_CONVERSION 0 0.01745 0 0
PARAMETER MODE 80 8 UINT 0 1 0 "DATA COLLECTION MODE"
STATE NORMAL 0
STATE DIAG 1
COMMAND TARGET NOOP BIG_ENDIAN "Do Nothing"
PARAMETER CCSDSVER 0 3 UINT 0 0 0 "CCSDS PRIMARY HEADER VERSION NUMBER"
PARAMETER CCSDSTYPE 3 1 UINT 1 1 1 "CCSDS PRIMARY HEADER PACKET TYPE"
PARAMETER CCSDSSHF 4 1 UINT 0 0 0 "CCSDS PRIMARY HEADER SECONDARY HEADER FLAG"
ID_PARAMETER CCSDSAPID 5 11 UINT 0 2047 101 "CCSDS PRIMARY HEADER APPLICATION ID"
PARAMETER CCSDSSEQFLAGS 16 2 UINT 3 3 3 "CCSDS PRIMARY HEADER SEQUENCE FLAGS"
PARAMETER CCSDSSEQCNT 18 14 UINT 0 16383 0 "CCSDS PRIMARY HEADER SEQUENCE COUNT"
PARAMETER CCSDSLENGTH 32 16 UINT 0 0 0 "CCSDS PRIMARY HEADER PACKET LENGTH"
PARAMETER DUMMY 48 8 UINT 0 0 0 "DUMMY PARAMETER BECAUSE CCSDS REQUIRES 1 BYTE OF DATA"
COMMAND TARGET SETTINGS BIG_ENDIAN "Set the Settings"
PARAMETER CCSDSVER 0 3 UINT 0 0 0 "CCSDS PRIMARY HEADER VERSION NUMBER"
PARAMETER CCSDSTYPE 3 1 UINT 1 1 1 "CCSDS PRIMARY HEADER PACKET TYPE"
PARAMETER CCSDSSHF 4 1 UINT 0 0 0 "CCSDS PRIMARY HEADER SECONDARY HEADER FLAG"
ID_PARAMETER CCSDSAPID 5 11 UINT 0 2047 102 "CCSDS PRIMARY HEADER APPLICATION ID"
PARAMETER CCSDSSEQFLAGS 16 2 UINT 3 3 3 "CCSDS PRIMARY HEADER SEQUENCE FLAGS"
PARAMETER CCSDSSEQCNT 18 14 UINT 0 16383 0 "CCSDS PRIMARY HEADER SEQUENCE COUNT"
PARAMETER CCSDSLENGTH 32 16 UINT 0 0 0 "CCSDS PRIMARY HEADER PACKET LENGTH"
<% 5.times do |x| %>
APPEND_PARAMETER SETTING<%= x %> 16 UINT 0 5 0 "Setting <%= x %>"
<% end %>
```
68 changes: 68 additions & 0 deletions docs.openc3.com/docs/configuration/_plugins.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
sidebar_position: 2
title: Plugins
---

<!-- Be sure to edit _plugins.md because plugins.md is a generated file -->

## 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 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. |
| openc3-PLUGINNAME.gemspec | This file should have the name of the plugin with a .gemspec extension. For example openc3-cosmos-demo.gemspec. The name of this file is used in compiling the plugin contents into the final corresponding PluginName-Version.gem plugin file. ie. openc3-cosmos-demo-5.0.0.gem. COSMOS plugins should always begin with the openc3- 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 excluding CANVAS image files. |
| 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/public | Put image files here for use in Telemetry Viewer Canvas Image widgets such as [CANVASIMAGE](telemetry-screens.md#canvasimage) and [CANVASIMAGEVALUE](telemetry-screens.md#canvasimagevalue). |
| 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:

COSMOS_META
Loading

0 comments on commit 5dc5bb7

Please sign in to comment.