- OCaml 94%
- Python 4%
- C 2%
- Java <1%
- Shell <1%
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 configopens the TCP connection and sends the initiating TML Context.Sle_eio.bind t ~initiator_id ~responder_port_id ~version ~service_instance_idSle_eio.unbind t ~reasonSle_eio.close t
RAF transfer #
Sle_eio.start_raf t ~start_time ~stop_time ~requested_qualitySle_eio.stop_raf tSle_eio.recv_frame tis 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.