- OCaml 69%
- C 23%
- Java 8%
- Shell <1%
clcw #
Decoder and encoder for the CCSDS Command Link Control Word (CLCW).
A ground station sending telecommands to a spacecraft needs to know which frames arrived, which must be sent again, and whether the on-board receiver has locked out. The spacecraft reports this in the CLCW, a 32-bit word it carries in the Operational Control Field (OCF) of every TM, AOS or USLP transfer frame it sends down. The ground side of the COP-1 retransmission protocol (CCSDS 232.1-B-2) reads the report value N(R) and the lockout, wait and retransmit flags from it. The format itself is defined in section 4.2 of the TC Space Data Link Protocol (CCSDS 232.0-B-4).
The on-board half of COP-1, the Frame Acceptance and Reporting Mechanism (FARM), accepts sequence-controlled (Type-AD) frames only in order of their 8-bit sequence number N(S). N(R) is the number of the next such frame it expects, so every frame numbered below N(R) arrived. The FARM enters lockout when a frame's N(S) falls outside the window it will accept; it then discards every sequence-controlled frame until the ground sends an Unlock command, which is itself sent as an unsequenced (Type-BD) frame. The wait flag says the FARM has no buffer for another frame, and the retransmit flag says a frame was missed and the ground should send again from N(R). The FARM-B counter is the two low-order bits of the FARM's count of accepted Type-BD frames, so the ground can see that a bypass frame went through (CCSDS 232.1-B-2, sections 6.1 and 6.3).
clcw decodes and encodes that word as a typed record. It refuses a word whose
control word type or version field is not zero, both fixed by the standard, and
carries the word as an int32 so all 32 bits stay exact under js_of_ocaml and
wasm_of_ocaml.
Install #
$ opam install clcw
If opam cannot find the package, add the overlay repository first:
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install clcw
Usage #
A CLCW reaches you either as a 32-bit word or as the four octets the OCF
occupies on the wire. Clcw.of_word and Clcw.to_word handle the first,
Clcw.of_string, Clcw.of_bytes, Clcw.to_string and Clcw.to_bytes the
second, and every decoder reports failures through the same Clcw.error type.
Clcw.v builds a CLCW from its fields; it takes the virtual channel and the
report value, and every other field defaults to zero.
(* From a 32-bit word *)
let () =
let word = 0x01280032l in
match Clcw.of_word word with
| Error e -> Fmt.pr "Error: %a@." Clcw.pp_error e
| Ok clcw -> Fmt.pr "CLCW: %a@." Clcw.pp clcw
(* To a 32-bit word *)
let () =
let clcw = Clcw.v ~vcid:10 ~report_value:50 ~lockout:true () in
let word = Clcw.to_word clcw in
Printf.printf "Encoded: 0x%08lX\n" word
(* From the four octets carried in a frame's OCF *)
let () =
match Clcw.of_string "\x01\x28\x00\x32" with
| Error e -> Fmt.pr "Error: %a@." Clcw.pp_error e
| Ok clcw -> Fmt.pr "CLCW: %a@." Clcw.pp clcw
For zero-copy access to one field of a frame buffer, Clcw.codec and the
Clcw.f_* field handles plug into the wire library's Wire.Codec.get and
Wire.Codec.set.
Format #
The word is packed most significant bit first, bit 0 being the first bit on the wire:
Bit 0: Control Word Type (0=CLCW)
Bits 1-2: CLCW Version Number
Bits 3-5: Status Field
Bits 6-7: COP in Effect
Bits 8-13: Virtual Channel ID
Bits 14-15: Reserved (spare)
Bit 16: No RF Available
Bit 17: No Bit Lock
Bit 18: Lockout
Bit 19: Wait
Bit 20: Retransmit
Bits 21-22: FARM-B Counter
Bit 23: Reserved (spare)
Bits 24-31: Report Value N(R)
License #
ISC. See LICENSE.md.