Crate cfdp 

cfdp - High-level support for implementing CFDP

This is a high-level support library for implementing the CCSDS File Delivery Protocol according to the CCSDS 727.0-B-5 standard.

Features

cfdp-rs currently supports following high-level features:

• Unacknowledged (class 1) file transfers for both source and destination side.
• Acknowledged (class 2) file transfers for both source and destination side.

The following features have not been implemented yet. PRs or notifications for demand are welcome!

• Suspending transfers
• Inactivity handling
• Start and end of transmission and reception opportunity handling
• Keep Alive and Prompt PDU handling

Overview

The basic idea of CFDP is to convert files of any size into a stream of packets called packet data units (PDU). CFPD has an unacknowledged and acknowledged mode, with the option to request a transaction closure for the unacknowledged mode. Using the unacknowledged mode with no transaction closure is applicable for simplex communication paths, while the unacknowledged mode with closure is the easiest way to get a confirmation of a successful file transfer, including a CRC check on the remote side to verify file integrity. The acknowledged mode is the most complex mode which includes multiple mechanism to ensure succesfull packet transaction even for unreliable connections, including lost segment detection. As such, it can be compared to a specialized TCP for file transfers with remote systems.

The goal of this library is to be flexible enough to support the use-cases of both on-board software and of ground software. It has support to make integration on std systems as simple as possible, but also has sufficient abstraction to allow for integration on no_std environments and can be used on these systems as well.

The core handlers inside this library do not allocate memory dynamically. The internal buffer size used for PDU generation and checksum calculation is statically determined via a Rust feature and defaults to 2048 bytes.

The core of this library are the crate::dest::DestinationHandler and the crate::source::SourceHandler components which model the CFDP destination and source entity respectively. You can find high-level and API documentation for both handlers in the respective crate::dest and crate::source module.

Rust Features

Default features

• std: Enables functionality relying on the standard library.
• alloc: Enables features which require allocation support. Enabled by the std feature.

Optional Features

• serde: Adds serde support for most types by adding Serialize and Deserialize derives
• defmt: Add support for the defmt by adding the defmt::Format derive on many types.

Buffer size selection

The following features can be used to select the internal buffer size used for PDU generation and checksum calculation. Selection of this value possibly limits the size of the generated PDU packets. Only one feature may be enabled.

• packet-buf-256 for 256 bytes
• packet-buf-512 for 512 bytes
• packet-buf-1k for 1024 bytes
• packet-buf-2k for 2048 bytes. This is the default.
• packet-buf-4k for 4096 bytes

Examples

This library currently features two example application which showcase how the provided components could be used to provide CFDP services.

The end-to-end test is an integration tests which spawns a CFDP source entity and a CFDP destination entity, moves them to separate threads and then performs a small file copy operation. You can run the integration test for a transfer with no closure and with printout to the standard console by running:

cargo test end_to_end_test_no_closure -- --nocapture

or with closure:

cargo test end_to_end_test_with_closure -- --nocapture

The Python Interoperability example showcases the interoperability of the CFDP handlers written in Rust with a Python implementation. The dedicated example documentation shows how to run this example.

Notes on the user hooks and scheduling

Both examples feature implementations of the UserFaultHook and the user::CfdpUser trait which simply print some information to the console to monitor the progress of a file copy operation. These implementations could be adapted for other handler integrations. For example, they could signal a GUI application to display some information for the user.

Even though both examples move the newly spawned handlers to dedicated threads, this is not the only way they could be scheduled. For example, to support an arbitrary (or bounded) amount of file copy operations on either source or destination side, those handlers could be moved into a std::collections::HashMap structure which is then scheduled inside a thread, or you could schedule a fixed amount of handlers inside a threadpool.

Re-exports

pub use alloc_mod::*;alloc

pub use std_mod::*;std

Modules

alloc_modalloc

buf_len

dest

CFDP Destination Entity Module

filestore

lost_segments

Lost Segment Store Module

request

source

CFDP Source Entity Module

std_modstd

time

user

Structs

DummyFaultHook

Dummy fault hook which implements UserFaultHook but only provides empty implementations.

DummyPduProvider

FaultHandler

This structure is used to implement the fault handling as specified in chapter 4.8 of the CFDP standard.

FaultInfo

IndicationConfig

LocalEntityConfig

Each CFDP entity handler has a LocalEntityConfiguration.

PduRawWithInfo

This is a helper struct which contains base information about a particular PDU packet. This is also necessary information for CFDP packet routing. For example, some packet types like file data PDUs can only be used by CFDP source entities.

RemoteConfigListalloc

This is a thin wrapper around a alloc::vec::Vec to store remote entity configurations. It implements the full RemoteEntityConfig trait.

RemoteConfigListHeapless

This is a thin wrapper around a heapless::vec::Vec to store remote entity configurations. It implements the full RemoteEntityConfig trait.

RemoteConfigStoreStdalloc

This is a thin wrapper around a hashbrown::HashMap to store remote entity configurations. It implements the full RemoteEntityConfig trait.

RemoteEntityConfig

This structure models the remote entity configuration information as specified in chapter 8.3 of the CFDP standard.

TransactionId

The CFDP transaction ID of a CFDP transaction consists of the source entity ID and the sequence number of that transfer which is also determined by the CFDP source entity.

Enums

EntityType

GenericSendError

Generic error type for sending a PDU via a message queue.

PacketTarget

RemoteConfigStoreError

State

TimerContext

Constants

CRC_32

crc::Crc instance using crc::CRC_32_ISO_HDLC.

CRC_32C

crc::Crc instance using crc::CRC_32_ISCSI.

Traits

PduProvider

Generic trait which models a raw CFDP packet data unit (PDU) block with some additional context information.

PduSender

RemoteConfigStore

TimerCreator

A generic trait which allows CFDP entities to create check timers which are required to implement special procedures in unacknowledged transmission mode, as specified in 4.6.3.2 and 4.6.3.3.

UserFaultHook

This trait introduces some callbacks which will be called when a particular CFDP fault handler is called.

Functions

determine_packet_target