- OCaml 74%
- C 19%
- Java 7%
- Shell <1%
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 #
- CCSDS 132.0-B-3: TM Space Data Link Protocol
- CCSDS 232.1-B-2: Communications Operation Procedure-1 (COP-1)
Licence #
ISC License. See LICENSE.md for details.