TM Transfer Frames (CCSDS 132.0-B-3)
README.md

tm #

A spacecraft sends its telemetry to the ground in fixed-length transfer frames, each tagged with the spacecraft and the virtual channel it belongs to, so that one radio link can carry several independent streams. CCSDS defines that frame format in the TM Space Data Link Protocol (CCSDS 132.0-B-3). tm encodes and decodes TM transfer frames in OCaml.

A frame is a 6-byte primary header, a data field, an optional Operational Control Field (OCF) and an optional Frame Error Control Field (FECF), a CRC-16-CCITT over the frame. The OCF usually carries a Command Link Control Word (CLCW), which reports the state of the COP-1 command receiver on board (CCSDS 232.1-B-2). The decoder checks every length against the buffer before reading, and verifies the FECF by default.

+----------------+-------------+------+------+
| Primary Header | Data Field  | OCF  | FECF |
|   (6 bytes)    | (variable)  | (4B) | (2B) |
+----------------+-------------+------+------+

The frame length is fixed per mission; Tm.decode takes it as ?frame_len and defaults to 1115 bytes. That is 5 × 223, the information part of a Reed-Solomon (255,223) codeblock at interleaving depth 5 (CCSDS 131.0-B-4, section 4), so on a link that uses that code one frame fills one codeblock exactly.

Installation #

Install with opam:

$ opam install tm

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install tm

Usage #

The example builds a frame of the default length with no OCF, so its data field is 1115 − 6 (primary header) − 2 (FECF) = 1107 bytes; a frame that carries an OCF has 4 bytes fewer, 1103. mcfc is the master channel frame count, incremented on every frame the spacecraft sends, and vcfc the virtual channel frame count, incremented on every frame of one virtual channel; both are 8 bits and wrap at 256, and a gap in either tells the ground that a frame was lost (CCSDS 132.0-B-3, sections 4.1.2.5 and 4.1.2.6).

(* Create a TM frame. *)
let scid = Tm.scid_exn 100
let vcid = Tm.vcid_exn 2
let data = String.make 1107 '\x00'
let frame = Tm.v ~scid ~vcid ~mcfc:1 ~vcfc:2 data
let bytes = Tm.encode frame

let () =
  match Tm.decode bytes with
  | Ok frame -> Fmt.pr "SCID: %d@." (Tm.int_of_scid frame.header.scid)
  | Error e -> Fmt.epr "Error: %a@." Tm.pp_error e

Working with the CLCW #

The CLCW's report value N(R) is the sequence number of the next Type-AD telecommand frame the on-board FARM-1 expects, so every frame below it is acknowledged. Lockout means FARM-1 received a frame outside its window and now refuses every Type-AD frame until the ground sends an Unlock control command (CCSDS 232.1-B-2, section 6.3).

(* Extract CLCW from frame OCF. *)
let extract_report frame =
  match Tm.extract_clcw frame with
  | None -> Fmt.pr "No OCF present@."
  | Some (Error _) -> Fmt.pr "Invalid CLCW in OCF@."
  | Some (Ok (clcw : Clcw.t)) ->
      Fmt.pr "Report value (N(R)): %d@." clcw.report_value;
      if clcw.lockout then Fmt.pr "FARM-1 in lockout!@."

(* Create a CLCW. *)
let clcw = Tm.clcw ~vcid ~report_value:42 ~lockout:false ()
let ocf_word = Tm.encode_clcw clcw

API #

The identifiers are private integer types, so an out-of-range value cannot reach the encoder: Tm.scid is the 10-bit spacecraft identifier and Tm.vcid the 3-bit virtual channel identifier, each built with a checked constructor (Tm.scid, Tm.scid_exn). Tm.header is the primary header and Tm.t a whole frame.

Tm.decode and Tm.encode convert whole frames, and Tm.decode_header and Tm.encode_header the primary header alone. Tm.compute_fecf computes the CRC. Tm.extract_clcw reads the CLCW from a frame's OCF, and Tm.clcw, Tm.encode_clcw and Tm.decode_clcw build and convert one.

References #

Licence #

ISC License. See LICENSE.md for details.