Metadata is data about data, i.e. information describing the data like when it was taken, version information, etc. COSMOS has explicit support for metadata, especially since the 4.0.0 release.

Metadata Overview

In versions of COSMOS prior to 4.0.0, metadata could be defined in any target / packet combination. In the COSMOS demo we defined metadata in the META target and DATA packet. You would then explicitly tell COSMOS where this metadata was defined by passing the target and packet name to the tools. Here is a example of an old (pre 4.0.0) cmd_tlm_server.txt configuration file:

PACKET_LOG_WRITER DEFAULT meta_packet_log_writer.rb META DATA config/data/meta_init.txt
COLLECT_METADATA META DATA

Here is an example of a current (post 4.0.0) cmd_tlm_server.txt configuration file:

PACKET_LOG_WRITER DEFAULT packet_log_writer.rb nil true nil 2000000000 nil false
COLLECT_METADATA

The PACKET_LOG_WRITER and COLLECT_METADATA keywords no longer have to specify where the metadata is stored because COSMOS 4.0.0 standardized the metadata definition in the SYSTEM target and META packet. You’ll notice the old cmd_tlm_server.txt file specified the location of a meta_init.txt file. This file contains the default values to use when initializing the metadata dialog. In post COSMOS 4.0.0 this file is defined in system.txt using the META_INIT keyword like so:

META_INIT config/data/meta_init.txt

Note that you do not have to define all the items in your metadata in your meta_init file. Any items not found in meta_init will simply be blank in the dialog. If you try to set any of the COSMOS reserved items (defined below) they will simply be overriden with the COSMOS defined values.

If you do not define any metadata in your system (you don’t declare the SYSTEM META packet), COSMOS will automatically define the following items:

  • SYSTEM META PKTID - Always 1 and used to identify the packet
  • SYSTEM META CONFIG - Configuration name (MD5 checksum)
  • SYSTEM META COSMOS_VERSION - COSMOS Version (e.g. 4.1.1)
  • SYSTEM META USER_VERSION - Defined by the USER_VERSION constant. Typically set in lib/user_version.rb in your configuration.
  • SYSTEM META RUBY_VERSION - Ruby Version (e.g. 2.4.2p198)

These items help identify the telemetry being collected by the currently running instance of the COSMOS Server. In fact, every time COSMOS starts a new log file it adds the SYSTEM META packet to the beginning. This behavior was possible prior to COSMOS 4.0.0 but required using the special meta_packet_log_writer in the cmd_tlm_server.txt definition as shown in the first cmd_tlm_server.txt example.

Defining Metadata

If you want to add your own fields to the COSMOS metadata you must define the standard COSMOS metadata items and then append your new values. For example, the COSMOS demo defines the following in targets/SYSTEM/cmd_tlm/meta_tlm.txt:

TELEMETRY SYSTEM META BIG_ENDIAN "System Meta Data Telemetry Packet"
  APPEND_ID_ITEM PKTID 8 UINT 1 "Packet Id"
  APPEND_ITEM CONFIG 256 STRING "Configuration Name"
  APPEND_ITEM COSMOS_VERSION 240 STRING "COSMOS Version"
    META READ_ONLY
  APPEND_ITEM USER_VERSION 240 STRING "User Project Version"
    META READ_ONLY
  APPEND_ITEM RUBY_VERSION 240 STRING "Ruby Version"
    META READ_ONLY
  APPEND_ITEM OPERATOR_NAME 512 STRING "Operator Name"

Here we see the demo defining their own new metadata item called OPERATOR_NAME after the standard COSMOS items. Note that the definition of the standard COSMOS items is important! If you misspell an item, declare the wrong data type, or have the size wrong, COSMOS will warn you that the definition is incorrect and then define the standard set of items as described above. Thus if you’re trying to create additional items and do not see them, make sure you haven’t defined the COSMOS standard items incorrectly. (Note: COSMOS 4.1.2 fixed a bug in this automatic generation of metadata items)

You can also see the use of the META READ_ONLY keyword being used in the demo configuration. This means that the metadata dialog which is opened when the COLLECT_METADATA keyword is used will display these items as read only as shown below:

Demo MetaData

Also note that you can declare metadata items with STATES and they will be displayed as dropdowns in the metadata dialog. For example if you add the following to the SYSTEM META packet:

APPEND_ITEM UUT 32 UINT "Unit under test"
  STATE ARTICLE_0 0
  STATE ARTICLE_1 1

You would see this:

MetaData Dropdown

Test Runner also has the ability to require the user to acknowledge the metadata dialog. If you add COLLECT_METADATA to the Test Runner configuration file you will see the metadata dialog upon starting any test. This is useful to force the test operator to think about anything in the metadata that might have changed prior to running the test. In addition, this forces a new telemetry file to be created with this new metadata information (remember each new binary file contains a SYSTEM META packet at the beginning).

Metadata is a useful way to add information which can’t be determined by the available hardware targets. The OPERATOR_NAME in the demo is an obvious example. Start using metadata to your advantage to help you distinguish your telemetry.

If you have a question which would benefit the community or find a possible bug please use our Github Issues.