CCSDS File Delivery Protocol (CCSDS 727.0-B-5) for space file transfer
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

cfdp: rewrite README — document state machines, wire codecs, Eio transport, correct Entity_id API

+100 -29
+100 -29
README.md
··· 6 6 ## Overview 7 7 8 8 CFDP provides file transfer services for space missions with support for 9 - high-delay and disruption-prone links. It operates above the underlying 10 - data link layer and provides: 9 + high-delay and disruption-prone links: 11 10 12 11 - **Class 1**: Unacknowledged (unreliable) transfers 13 12 - **Class 2**: Acknowledged (reliable) transfers with NAK-based retransmission 14 13 15 14 ## Features 16 15 17 - - Full PDU header encoding/decoding 18 - - Entity ID support (1-8 bytes, up to 2^63-1) 19 - - Transaction sequence numbers 20 - - CRC-32 checksum support 21 - - File directive PDUs (Metadata, EOF, ACK, NAK, Finished) 22 - - Segmented file data transfers 16 + - Full PDU header encoding/decoding with variable-length entity IDs (1-8 bytes) 17 + - File directive PDUs: Metadata, EOF, ACK, NAK, Finished, Prompt, Keep Alive 18 + - Segmented file data with optional record boundaries and segment metadata 19 + - CRC-32 integrity checking on PDUs 20 + - Checksum computation: modular, CRC-32, CRC-32C, and null 21 + - State machines for all four transfer roles: 22 + - `Sender1` -- Class 1 (unacknowledged) sender 23 + - `Sender2` -- Class 2 (acknowledged) sender with NAK retransmission 24 + - `Receiver1` -- Class 1 (unacknowledged) receiver 25 + - `Receiver2` -- Class 2 (acknowledged) receiver with NAK generation 26 + - Timer management for inactivity, NAK, EOF, Finished, and Keep Alive 27 + - Wire codecs for Finished, ACK, and Prompt directives 28 + 29 + ## Packages 30 + 31 + - **cfdp** -- Core protocol: PDU types, codecs, state machines 32 + - **cfdp-eio** -- TCP transport and file I/O using Eio 23 33 24 34 ## Installation 25 35 26 36 ``` 27 - opam install cfdp 37 + opam install cfdp cfdp-eio 28 38 ``` 29 39 30 40 ## Usage 31 41 42 + ### Encoding PDUs 43 + 32 44 ```ocaml 33 45 open Cfdp 34 46 35 - (* Create entity IDs *) 36 - let source = Entity_id.of_int64 1L 37 - let dest = Entity_id.of_int64 2L 47 + (* Create entity IDs (returns t option) *) 48 + let source = Entity_id.of_int_exn 1 49 + let dest = Entity_id.of_int_exn 2 50 + 51 + (* Use default PDU config: 2-byte entity IDs, 4-byte sequence numbers *) 52 + let config = default_config 53 + 54 + (* Build a metadata PDU *) 55 + let meta = metadata ~file_size:1024L 56 + ~source_filename:"data.bin" ~dest_filename:"data.bin" () 57 + 58 + (* Encode the metadata as a directive PDU *) 59 + let hdr : header = { 60 + version = 1; pdu_type = File_directive; 61 + direction = Toward_receiver; transmission_mode = Unacknowledged; 62 + crc_present = false; large_file = false; 63 + segment_ctrl = false; segment_metadata = false; 64 + source_entity = source; transaction_seq = 1L; 65 + dest_entity = dest; data_len = 0; 66 + } 67 + let bytes = encode config (Pdu_directive (hdr, Metadata meta)) 68 + ``` 69 + 70 + ### Decoding 71 + 72 + ```ocaml 73 + match Cfdp.decode bytes with 74 + | Ok (pdu, _consumed) -> Format.printf "%a@." Cfdp.pp_pdu pdu 75 + | Error e -> Format.printf "Error: %a@." Cfdp.pp_error e 76 + ``` 77 + 78 + ### State Machine (Class 1 Sender) 79 + 80 + ```ocaml 81 + let sender = Sender1.initial (Entity_id.of_int_exn 1) in 38 82 39 - (* Create a transaction *) 40 - let seq_nr = Seq_nr.of_int64 42L 83 + let req = put_request 84 + ~dest_entity:(Entity_id.of_int_exn 2) 85 + ~source_filename:"firmware.elf" 86 + ~dest_filename:"firmware.elf" () 87 + in 41 88 42 - (* Build a file data PDU *) 43 - let header = Pdu_header.v 44 - ~source_entity:source 45 - ~dest_entity:dest 46 - ~seq_nr 47 - ~direction:`Toward_receiver 48 - ~transmission_mode:`Acknowledged 49 - () 89 + let file_size = 4096L in 90 + let read_data _offset = Bytes.create 1024 in 91 + let sender, actions = 92 + Sender1.step sender (Ev_put_request (req, file_size, read_data)) 93 + in 94 + (* Process actions: Act_send_metadata, Act_send_file_data, ... *) 95 + ignore (sender, actions) 96 + ``` 50 97 51 - (* Encode to bytes *) 52 - let bytes = Pdu_header.encode header 98 + ### File Transfer with Eio 99 + 100 + ```ocaml 101 + Eio_main.run @@ fun env -> 102 + Eio.Switch.run @@ fun sw -> 103 + let conn = 104 + Cfdp_eio.connect ~sw ~net:env#net ~host:"flatsat-1" ~port:1734 () 105 + in 106 + match Cfdp_eio.Sender.send_file conn 107 + ~src:(Fpath.v "firmware.elf") ~dst:"firmware.elf" () with 108 + | Ok tid -> Format.printf "Done: %a@." Cfdp.pp_transaction_id tid 109 + | Error msg -> Format.eprintf "Error: %s@." msg 53 110 ``` 54 111 112 + ## State Machines 113 + 114 + | Module | Class | Role | 115 + |--------|-------|------| 116 + | `Sender1` | 1 (unacknowledged) | Sender | 117 + | `Sender2` | 2 (acknowledged) | Sender with NAK retransmission | 118 + | `Receiver1` | 1 (unacknowledged) | Receiver | 119 + | `Receiver2` | 2 (acknowledged) | Receiver with NAK generation | 120 + 121 + Each state machine is event-driven: feed events in, get actions out. 122 + 123 + Timer types: `Timer_nak`, `Timer_eof`, `Timer_finished`, `Timer_inactivity`, 124 + `Timer_keep_alive`. 125 + 55 126 ## Related Work 56 127 57 - - [ION](https://sourceforge.net/projects/ion-dtn/) - NASA/JPL DTN with CFDP 58 - - [lib-cfdp](https://github.com/nasa/lib-cfdp) - NASA CFDP library 128 + - [ION](https://sourceforge.net/projects/ion-dtn/) -- NASA/JPL DTN with CFDP 129 + - [lib-cfdp](https://github.com/nasa/lib-cfdp) -- NASA CFDP library 59 130 60 131 ## References 61 132 62 - - [CCSDS 727.0-B-5](https://public.ccsds.org/Pubs/727x0b5.pdf) - CFDP Blue Book 63 - - [CCSDS 720.1-G-4](https://public.ccsds.org/Pubs/720x1g4.pdf) - CFDP Green Book 133 + - [CCSDS 727.0-B-5](https://public.ccsds.org/Pubs/727x0b5.pdf) -- CFDP Blue Book 134 + - [CCSDS 720.1-G-4](https://public.ccsds.org/Pubs/720x1g4.pdf) -- CFDP Green Book 64 135 65 136 ## Licence 66 137 67 - ISC License. See [LICENSE.md](LICENSE.md) for details. 138 + ISC