Files and Streams

Two standard components describe what a platform stores and streams: files, the on-board directory and its transfer protocol, and stream, the continuous payload streams. Their names are fixed; the MCS generates their measures. This page is the catalogue reference; how transfers and streams run is in File Transfers and Continuous Streams.

The files component#

components:
  files:
    file_types: [lttm, log, image, sw_patch]
    transfer:
      protocol: chunked
      max_chunk: 1024 B
      checksum: crc32
      list: list_files
      read: {tc: read_chunk, args: [file_id, offset, length]}
      write: {tc: write_chunk, args: [file_id, offset, data]}
    telecommands:
      list_files: {changes_state: false}
      read_chunk:
        changes_state: false
        args:
          file_id: {type: u32}
          offset: {type: u32, unit: B}
          length: {type: u16, unit: B}
      write_chunk:
        args:
          file_id: {type: u32}
          offset: {type: u32, unit: B}
          data: {type: bytes}
        verify: [echo]
      activate_file:                # activation of an uploaded file: never implicit
        hazardous: true
        args:
          file_id: {type: u32}
        verify: [echo]
      delete_file:
        args:
          file_id: {type: u32}

The files component declares file_types (required), transfer and its telecommands. It declares no instances, measures, derived nor alarms (catalogue::files-component): its instances are the on-board files, known at run time, and its measures are generated. No other component may declare file_types or transfer (catalogue::not-files).

File types#

file_types lists the kinds of on-board files (lttm, log, image, sw_patch…), as an enum: identifiers, at least one, none twice. A procedure input is typed by one of them, input lttm: file_id of lttm, and the compiler checks the type; whether the file exists is checked when the run executes.

Generated measures#

Every file of the directory is an instance of files, named by its on-board identifier in decimal: files[12].size.

The driver decodes the listing into samples of file_type, size, checksum and generation; the transfer manager publishes transfer. These measures follow the path of any measure (compute stage, current value table), so procedures use them in check, expect and wait until:

step "Download LTTM"
  uses sat: platform-v3
  input lttm: file_id of lttm
  download sat.files[lttm]
  expect sat.files[lttm].transfer is PROCESSED within 8 min

The values of transfer are NONE, REQUESTED, PARTIAL, COMPLETE, VERIFIED, PROCESSED, CORRUPTED and SUPERSEDED. A file deleted on board keeps its last values, dated from the last listing where it appeared.

Transfer protocol#

read and write name a telecommand of files and list three of its arguments, in order:

• read: {tc: <telecommand>, args: [<file id>, <offset>, <length>]};
• write: {tc: <telecommand>, args: [<file id>, <offset>, <data>]}.

The compiler checks that the telecommand exists and has these arguments (catalogue::invalid-transfer).

Chunked. The transfer manager sends the read telecommand for the missing ranges, at most max_chunk each, pass after pass, and the write telecommand for an upload. The driver extracts the chunks from the downlink frames. Keep read_chunk and list_files at changes_state: false, and give write_chunk verify: [echo]: a range written is acquired when its telecommand is VERIFIED (or COMPLETE).

CFDP. The CFDP entity of the driver (CCSDS 727.0, class 2) requests and retransmits the data: read and write are refused. The listing telecommand stays useful: without it, nothing can be downloaded (a download targets a listed generation), and an upload is verified by the on-board CFDP entity alone.

files:
  file_types: [lttm, log]
  transfer:
    protocol: cfdp
    checksum: crc32
    list: list_files
  telecommands:
    list_files: {changes_state: false}

Checksums. When a download is complete, the transfer manager computes the checksum of the protocol on the assembled file and compares it with the listed one: equal gives VERIFIED, different gives CORRUPTED. Without algorithm or listed checksum, the file is VERIFIED with the reason "no checksum to verify". md5 is accepted by the compiler but not computed by the transfer manager: such a transfer stays COMPLETE, with the reason.

Telecommands addressed to a file#

A procedure addresses a file by an input of type file_id of <type>, never by a literal identifier: sat.files[lttm]. An argument named file_id receives the identifier of the instance and is not written in with:

step "Free LTTM"
  uses sat: platform-v3
  input lttm: file_id of lttm
  check sat.files[lttm].transfer is PROCESSED
  send delete_file to sat.files[lttm]

Deleting a file on board is never automatic: it takes an explicit telecommand in a procedure. An upload never activates what it writes either: activation (a patch, a table) is a separate, usually hazardous telecommand such as activate_file.

The stream component#

A stream is continuous payload data (imaging, video, instrument data) that the MCS carries and archives without decoding it.

components:
  stream:
    streams:
      camera: {rate: 256 kbit/s}
    telecommands:
      start_stream:
        verify: [echo]
      stop_stream:
        verify: [echo]
    alarms:
      stream_gap:
        severity: warning
        when: delta(gaps, 30 s) > 0

• streams (required) lists the streams by identifier, each with its nominal rate: a positive rate such as 256 kbit/s or 2 Mbit/s (catalogue::invalid-stream).
• The instances of stream are its streams (enum stream.stream_id): the component declares no instances nor measures (catalogue::stream-component). No other component may declare streams (catalogue::not-stream).
• It declares the telecommands that start and stop its streams, sent to a stream: send start_stream to sat.stream[camera]. It may declare derived measures and alarms.

Generated measures#

The transfer manager measures them on the segments received and publishes them every second, and once at zero rate when the stream stops. They are measures of the platform, not of the drivers: a driver does not have to cover them. A sequence number going back is a restart of the stream, not a gap.