September 26, 2023

COSMOS Cmd/Tlm Naming Conventions

Command and Telemetry names within COSMOS

First some background: COSMOS identifies commands going to and data coming from a device (target) with three identifiers: TARGET, PACKET, and ITEM. These identifiers are set in the target's command and telemetry definition file. A top level COMMAND or TELEMETRY packet is declared with PARAMETERs or ITEMs (respectively) defined under them.

So how should we name these three identifiers? Most command and control systems limit the characters and item lengths, leading to unfriendly item names such as BSPKT0 TLM01 MDP01B. COSMOS provides great flexibility in command and telemetry naming conventions with virtually no limits on characters or lengths. Of course with great power comes great responsibility, so the following conventions are recommended: capitalize everything and use underscores to distinguish words.

This convention leads to target names such as SCE (spacecraft control electronics), CYRO (cryocooler), PS1 (Power Supply 1), etc. We typically use acronyms just to save on typing in scripts and screen definitions. Packet names are similar such as SOH (state of health), HEALTH_STATUS, SOLAR_PANELS, etc. Here it is common to use acronyms but also to see words connected with underscores. Item names are similar to packet names such as CCSDS_SHF (CCSDS secondary header flag), DURATION, CONNECTION_STATUS, etc. Common acronyms are used but spelling out a word generally helps with readability. While using verbose names can help with readability, it has a small tradeoff of extra typing when writing scripts and screen definitions. However, our autocomplete in Script Runner helps with item names.

Some of our customers have even used special characters to denote different versions of a command. For example, using an exclamation point to indicate a more dangerous or forceful version of a command:

COMMAND TGT ABORT BIG_ENDIAN "Tries to abort a collect on the instrument"
COMMAND TGT ABORT! BIG_ENDIAN "Force aborts a collect on the instrument"

Similarly a telemetry point could be implemented with a question mark to indicate a boolean value. For example, there is a telemetry point which indicates whether a mechanism is deployed or not. It is defined with states where 0 is not deployed and 1 is deployed:

APPEND_ITEM DEPLOYED? 16 UINT "Deployed status"
 STATE FALSE 0
 STATE TRUE 1

The value could then be obtained by calling tlm(“TGT PKT DEPLOYED?”).

Using exclamation points and question marks aren't common and typically only alphanumeric symbols are used. With the recent release of COSMOS 5.11.0 we now support UTF-8 characters in our configuration files. This can even work with command and telemetry items! So to make your life difficult you could define a telemetry item as follows (note the Pound symbol):

APPEND_ITEM @DURATION!?£ 32 FLOAT "Most recent collect duration"
Packet Viewer Display

This can even be queried by a script:

puts tlm("INST HEALTH_STATUS @DURATION!?£")

While this is possible it makes it very difficult to write scripts and is highly discouraged! However UTF-8 symbols in item descriptions or UNITS are encouraged! For example:

APPEND_ITEM CURRENT 32 FLOAT "Device current"
   UNITS micro-Ampères µA
Packet Viewer Details

There are lots of options for command and telemetry naming but the convention is to use UPPERCASE names and separate words with underscores. Whatever you do, be consistent and document any deviations.

Take a look at the latest articles from OpenC3