CCSDS File Delivery Protocol (CCSDS 727.0-B-5) for space file transfer
cfdp: rewrite README — document state machines, wire codecs, Eio transport, correct Entity_id API
+100
-29
+100
-29
README.md
+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