SpaceFibre (ECSS-E-ST-50-11C)
README.md

spacefibre #

SpaceFibre (ECSS-E-ST-50-11C) data frames, virtual channels and broadcast messages in pure OCaml.

If you have worked on a spacecraft, your instruments probably reach the data handling unit over SpaceWire (ECSS-E-ST-50-12C). A SpaceWire link gives you 2 to 400 Mbit/s over LVDS and treats every packet the same. SpaceFibre replaces it with multi-gigabit serial links that can be bonded together. On one link you get several virtual channels, each with its own priority and, if you ask for it, reserved bandwidth. Data goes in CRC-protected frames. Time and network management go in broadcast messages. When a frame arrives corrupted or goes missing, the link notices from the CRC or the sequence number and resends it from a replay buffer, and your application never hears about it. The standard calls this link-level FDIR (fault detection, isolation and recovery).

I model SpaceFibre from the frames upwards. Lane bonding and the physical layer are left out. Each data frame has a virtual channel number, a payload and a CRC-32. It also has a 7-bit sequence count, which wraps at 128 and comes with the polarity flag the standard pairs with it. Its end-of-packet marker says what happens next: EOP ends the packet, EEP ends it on an error, and No_eop continues it in the following frame. You configure a virtual channel with a priority and maybe a bandwidth reservation. Broadcast messages carry a time code, a link state change or a management command.

To send, queue payloads on the multiplexer and pull frames out. It always serves the highest-priority channel that has something waiting, and it assigns the sequence numbers. On the receiving side, push frames into the demultiplexer. It complains about a gap in a channel's sequence and hands you back whole packets.

One caution. The byte layout of frames and broadcasts is my own encoding of those fields, and I have not checked it against the control words the standard puts on the wire.

Installation #

Install with opam:

$ opam install spacefibre

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 spacefibre

Usage #

(* Create and encode a data frame. *)
let f =
  Spacefibre.frame_exn ~frame_type:Data ~id:0 ~seq_count:0
    ~seq_polarity:false ~eop:EOP ~payload:"sensor data"

let bytes = Spacefibre.encode_frame f

let () =
  match Spacefibre.decode_frame bytes with
  | Ok decoded ->
      Fmt.pr "vc=%d payload=%s@."
        (Spacefibre.frame_vc_id decoded)
        (Spacefibre.frame_payload decoded)
  | Error _ -> Fmt.epr "decode error@."
(* Virtual channel multiplexing. *)
let vc0 = Spacefibre.vc_config_exn ~id:0 ~priority:0 ~scheduling:Priority_only
let vc1 = Spacefibre.vc_config_exn ~id:1 ~priority:1 ~scheduling:Priority_only
let m = Spacefibre.mux_exn [ vc0; vc1 ]

let m =
  Result.get_ok (Spacefibre.mux_enqueue m ~id:0 ~payload:"low" ~eop:EOP)

let m =
  Result.get_ok (Spacefibre.mux_enqueue m ~id:1 ~payload:"high" ~eop:EOP)

let () =
  match Spacefibre.mux_next m with
  | Some (frame, _) -> Fmt.pr "vc=%d@." (Spacefibre.frame_vc_id frame)
  | None -> ()
(* Broadcast messages. *)
let bc = Spacefibre.broadcast_exn ~btype:Time_code ~param:42 ~payload:""
let encoded = Spacefibre.encode_broadcast bc

let () =
  match Spacefibre.decode_broadcast encoded with
  | Ok decoded ->
      Fmt.pr "type=%a param=%d@." Spacefibre.pp_broadcast_type
        (Spacefibre.broadcast_type decoded)
        (Spacefibre.broadcast_param decoded)
  | Error _ -> Fmt.epr "decode error@."

Protocol layers #

+--------------------------------------------------+
| Application / SpaceWire Packet                   |
+--------------------------------------------------+
| Virtual Channel (QoS multiplexing)               |
|   priority, bandwidth reservation, scheduling    |
+--------------------------------------------------+
| Data Link: Data Frames + Broadcast Messages      |
|   VC ID, sequence numbers, CRC-32                |
+--------------------------------------------------+
| Lane (multi-lane bonding, not modelled)          |
+--------------------------------------------------+
| Physical (not modelled)                          |
|   SerDes, 8b/10b, signal conditioning            |
+--------------------------------------------------+

The two bottom layers are hardware. A serialiser and deserialiser (SerDes) turns parallel bytes into one fast bit stream and back again. The line code on that stream is 8b/10b, which spends 10 bits on every byte so the receiver sees enough transitions to recover the clock and the line carries no DC offset. You lose 25% of the raw bit rate to it.

References #

Licence #

ISC License. See LICENSE.md for details.