CCSDS Space Link Extension (SLE) protocols
README.md

ocaml-sle #

CCSDS Space Link Extension (SLE) services for OCaml.

A mission rarely owns every ground station it talks to. Space Link Extension (SLE, CCSDS 913.1-B-2) is the protocol by which a mission's control centre, the SLE user, receives telemetry frames from and sends telecommands to a ground station run by someone else, the SLE provider, over TCP. sle implements the user side of the SLE services as state machines without I/O, and sle-eio runs them over an Eio TCP connection.

The sle package covers:

  • RAF, Return All Frames: every downlinked frame;
  • RCF, Return Channel Frames: the frames of selected virtual channels;
  • ROCF, Return Operational Control Field: the CLCW of selected channels;
  • FCLTU, Forward CLTU: telecommand uplink;
  • FSP, Forward Space Packet: packet uplink with COP-1 directives;
  • the Transport Mapping Layer (TML) that frames SLE messages over TCP, and ISP1 authentication.

A virtual channel is a logical stream multiplexed onto the one physical link by a channel number in each frame header. The CLCW (Communications Link Control Word, CCSDS 232.0-B) is the 4-byte report the spacecraft puts in the Operational Control Field of each telemetry frame, saying which telecommand frames it has accepted. A CLTU (Communications Link Transmission Unit, CCSDS 231.0-B) is the uplink unit: a telecommand frame BCH-encoded and wrapped in a start sequence and a tail sequence. COP-1 (CCSDS 232.1-B) is the go-back-N retransmission protocol that the CLCW acknowledgements drive, and its directives are the commands that set it up (initialise, resume, set the window).

TML puts an 8-byte header before each message: a type byte (1 for an SLE PDU, 2 for the context message, 3 for a heartbeat), three reserved bytes and the payload length as a big-endian 32-bit integer (Sle.Tml). The initiating TML sends one Context after TCP opens and then sends SLE PDUs without waiting for a Context reply (CCSDS 913.1-B-2 3.3.4.1). It carries the protocol identifier ISP1, the heartbeat interval and the dead factor. ISP1 authenticates the BIND with a credential of an 8-byte CDS time, a random number and a digest (SHA-1 up to SLE version 3, SHA-256 from version 4) over the time, the random number, the username and the password (Sle.Isp1, CCSDS 913.1-B-2 section 3.1.2.2). The password never crosses the wire, and the receiver refuses a credential whose time is too far from its own clock, so a captured one cannot be replayed later.

Sle.Raf_client owns initiating Context transmission, credential generation, operation completion and interleaved frame buffering without IO. sle-eio interprets its effects and the pure TML liveness decisions. Its bind API is RAF-specific. Only one operation is pending at a time; a competing request returns the typed Sle.Raf_client.Busy refusal without reading a return. Buffered transfers have configurable frame-count and encoded-octet limits, including metadata; a buffer keeps its retention credit until its last queued frame is consumed. On failure, the terminal cause is retained and already accepted frames remain drainable. return_timeout_period (1 to 600 seconds, local default 60) separately bounds confirmed operations even while heartbeats arrive. Timers use mono_clock; clock supplies only the wall time for ISP1 credentials. A local credential-preparation refusal completes its request before any invocation is sent. The association and admitted frames remain available; a new explicit request obtains fresh credentials. The caller switch owns one persistent heartbeat writer. Pending HBT writes are coalesced by the pure liveness state; only completed transmission resets HBT. HBR remains independent while writes are blocked. Successful reads and operation completion leave a partial heartbeat write running. The stream adapter closes on fatal errors; TCP urgent-data peer-abort transport is not implemented.

sle-eio drives BIND, UNBIND and the RAF service; the other services are available as state machines in sle but not yet wired to the Eio client.

Installation #

Install with opam:

$ opam install sle sle-eio

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

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

Usage #

Receive RAF frames #

let ( let* ) = Result.bind

let with_raf_session ~sw ~net ~clock ~mono_clock ~random config ~initiator_id
    ~responder_port_id ~service_instance_id f =
  let* client = Sle_eio.connect ~sw ~net ~clock ~mono_clock ~random config in
  let* _version =
    Sle_eio.bind client
      ~initiator_id
      ~responder_port_id
      ~version:5
      ~service_instance_id
  in
  let* () =
    Sle_eio.start_raf client
      ~start_time:None ~stop_time:None
      ~requested_quality:Sle.Frame_quality.All_frames
  in
  let result = f client in
  let _ = Sle_eio.stop_raf client in
  let _ = Sle_eio.unbind client ~reason:Sle.Bind.End in
  Sle_eio.close client;
  result

let run () =
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let config =
    Sle_eio.default_config
      ~host:"sle-provider.example.com" ~port:5100
  in
  let outcome =
    with_raf_session
      ~sw
      ~net:(Eio.Stdenv.net env :> [ `Generic ] Eio.Net.ty Eio.Resource.t)
      ~clock:(Eio.Stdenv.clock env)
      ~mono_clock:(Eio.Stdenv.mono_clock env)
      ~random:(Eio.Stdenv.secure_random env)
      config
      ~initiator_id:"user"
      ~responder_port_id:"RAF"
      ~service_instance_id:
        [
          (Sle.Service_instance_id.Service_agreement, "1");
          (Sle.Service_instance_id.Service_package, "1");
          (Sle.Service_instance_id.Return_service, "raf");
          (Sle.Service_instance_id.Raf, "onlt1");
        ]
      (fun client ->
        let rec loop () =
          match Sle_eio.recv_frame client with
          | Ok frame ->
              Fmt.pr "RAF frame: %d bytes@." (Bytes.length frame.data);
              loop ()
          | Error (Sle.Raf_client.Transport_error Closed) -> Ok ()
          | Error e -> Error e
        in
        loop ())
  in
  match outcome with
  | Ok () -> ()
  | Error e -> Fmt.epr "SLE error: %a@." Sle_eio.pp_error e

The with_raf_session helper connects, binds, starts the service and tears it all down again, so the callback only handles recv_frame.

API #

Client lifecycle #

  • Sle_eio.connect ~sw ~net ~clock ~mono_clock ~random config opens the TCP connection and sends the initiating TML Context.
  • Sle_eio.bind t ~initiator_id ~responder_port_id ~version ~service_instance_id
  • Sle_eio.unbind t ~reason
  • Sle_eio.close t

RAF transfer #

  • Sle_eio.start_raf t ~start_time ~stop_time ~requested_quality
  • Sle_eio.stop_raf t
  • Sle_eio.recv_frame t is the next frame, with its data, quality and earth receive time.

Configuration #

let config =
  { (Sle_eio.default_config ~host:"provider" ~port:5100) with
    Sle_eio.auth =
      Some { username = "user"; password = "secret";
             algo = Sle.Isp1.Sha256 };
  }

Authentication is ISP1. The default configuration sends a heartbeat every 25 seconds and gives up on the peer after three missed ones. Those are the defaults of Sle_eio.default_config (heartbeat_interval = 25, dead_factor = 3), proposed to the provider in the TML context message: a peer silent for 25 x 3 = 75 seconds is declared dead.

References #

  • CCSDS 913.1-B-2: Space Link Extension, Internet Protocol for Transfer Services.
  • CCSDS 911.1-B-4 (RAF), 911.2-B-3 (RCF), 911.5-B-3 (ROCF), 912.1-B-4 (FCLTU) and 912.3-B-3 (FSP): the service specifications.

Licence #

ISC. See LICENSE.md.