Merge pull request #147 from robamu-org/extract-components-to-spacepa…

…ckets

Extract components to spacepackets and cfdp-py

.github/workflows/ci.yml

@@ -41,6 +41,7 @@ jobs:
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v3
       with:
+        token: ${{ secrets.CODECOV_TOKEN  }}
         flags: unittests
         name: codecov-umbrella
         fail_ci_if_error: false

CHANGELOG.md

@@ -9,10 +9,19 @@ Starting from v4.0.0, this project adheres to [Semantic Versioning](http://semve
 
 # [unreleased]
 
+# [v8.0.0rc1] 2024-01-24
+
 ## Fixed
 
 - Fixed bug for acknowledged file transfer cancellation in the destination handler.
 
+## Removed
+
+- The `tmtccmd.util.countdown` and `tmtccmd.util.seqcnt` module were moved to the `spacepackets`
+  library.
+- Most of the `tmtccmd.cfdp` module was moved to the
+  [`cfdp-py` library](https://github.com/us-irs/cfdp-py).
+
 # [v8.0.0rc0] 2023-11-29
 
 ## Added

README.md

@@ -25,8 +25,6 @@ used either as a command line tool or as a GUI tool which requires a PyQt6 insta
   packets and [CCSDS Space Packets](https://public.ccsds.org/Pubs/133x0b2e1.pdf).
   This library uses the [spacepackets](https://github.com/us-irs/py-spacepackets) library for most
   packet implementations.
-- High level CFDP components which allow to build
-  [CFDP standard conformant](https://public.ccsds.org/Pubs/727x0b5.pdf) CFDP handlers.
 - Support for both CLI and GUI usage
 - Flexibility in the way to specify telecommands to send and how to handle incoming telemetry.
   This is done by requiring the user to specify callbacks for both TC specification and TM handling.

docs/api.rst

@@ -13,18 +13,7 @@ Communication Package
 
    api/com
 
-CCSDS Package 
-===================
-
-This currently also contains the CFDP support.
-
-.. toctree::
-   :maxdepth: 2
-
-   api/cfdp
-   api/cfdp.handler
-
-ECSS Package 
+ECSS & CCSDS Package 
 =========================
 
 .. automodule:: tmtccmd.pus
@@ -35,6 +24,11 @@ ECSS Package
 
    api/pus
 
+.. toctree::
+   :maxdepth: 2
+
+   api/cfdp
+
 Application Package 
 =========================
 

docs/api/cfdp.rst

@@ -1,60 +1,10 @@
-CFDP Package
-=======================
+CFDP Module
+==============
 
-Module contents
----------------
-
-.. automodule:: tmtccmd.cfdp
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Filestore Module
--------------------------------
-
-.. automodule:: tmtccmd.cfdp.filestore
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-
-Management Information Base (MIB) Module
--------------------------------------------
-
-.. automodule:: tmtccmd.cfdp.mib
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Request Module
--------------------------------
+Request Submodule
+-----------------------------
 
 .. automodule:: tmtccmd.cfdp.request
    :members:
    :undoc-members:
    :show-inheritance:
-
-User Module
--------------------------------
-
-.. automodule:: tmtccmd.cfdp.user
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Exceptions Module
--------------------------------------------
-
-.. automodule:: tmtccmd.cfdp.exceptions
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Definitions Module
---------------------------
-
-.. automodule:: tmtccmd.cfdp.defs
-   :members:
-   :undoc-members:
-   :show-inheritance:
-

docs/api/util.rst

@@ -12,22 +12,6 @@ JSON Module
    :undoc-members:
    :show-inheritance:
 
-Countdown Module
-------------------
-
-.. automodule:: tmtccmd.util.countdown
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Sequence Count Module
---------------------------
-
-.. automodule:: tmtccmd.util.seqcnt
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 Object ID Module
 ----------------------
 
@@ -44,23 +28,23 @@ Exit Module
    :undoc-members:
    :show-inheritance:
 
-tmtccmd.utility.hammingcode module
+Hamming-Code Module
 ----------------------------------
 
 .. automodule:: tmtccmd.util.hammingcode
    :members:
    :undoc-members:
    :show-inheritance:
 
-tmtccmd.utility.tmtc\_printer module
+TMTC Printer (FSFW) Module
 ------------------------------------
 
-.. automodule:: tmtccmd.util.tmtc_printer
+.. automodule:: tmtccmd.fsfw.tmtc_printer
    :members:
    :undoc-members:
    :show-inheritance:
 
-tmtccmd.utility.conf\_util module
+Configuration Utility Module
 ---------------------------------
 
 .. automodule:: tmtccmd.util.conf_util
@@ -75,3 +59,17 @@ Module contents
    :members:
    :undoc-members:
    :show-inheritance:
+
+Countdown Module
+------------------
+
+The countdown module was moved to the `spacepackets` library. Use the
+:py:mod:`spacepackets.countdown` module.
+
+Sequence Count Module
+--------------------------
+
+The sequence count module was moved to the `spacepackets` library. Use the
+:py:mod:`spacepackets.seqcount` module.
+
+.. _`spacepackets`: https://github.com/us-irs/spacepackets-py

docs/cfdp.rst

@@ -4,105 +4,7 @@
 CCSDS File Delivery Protocol (CFDP)
 ====================================
 
-The ``tmtccmd`` package offers some high-level CCSDS File Delivery Protocol (CFDP) components to
-perform file transfers according to the `CCSDS Blue Book 727.0-B-5`_. The underlying base packet
-library used to generate the packets to be sent is the `spacepackets`_ library.
-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 successfull 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 majority of the CFDP components were moved to the dedicated `cfdp-py`_ library.
+It is recommended to read its `dedicated documentation <https://cfdp-py.readthedocs.io/en/latest/>`_.
 
-The core of these high-level components are the :py:class:`tmtccmd.cfdp.handler.dest.DestHandler`
-and the :py:class:`tmtccmd.cfdp.handler.source.SourceHandler` component. These model the CFDP
-destination and CFDP source entity respectively.
-
-CFDP source entity
--------------------
-
-The :py:class:`tmtccmd.cfdp.handler.source.SourceHandler` converts a
-:py:class:`tmtccmd.cfdp.request.PutRequest` into all packet data units (PDUs) which need to be
-sent to a remote CFDP entity to perform a File Copy operation to a remote entity. The source entity
-allows freedom of communcation by only generating the packets required to be sent, and leaving the
-actual transmission of those packets to the user. The packet is returned to the user using
-the :py:class:`spacepackets.cfdp.pdu.helper.PduHolder` field of the
-:py:class:`tmtccmd.cfdp.handler.source.FsmResult` structure returned in the
-:py:meth:`tmtccmd.cfdp.handler.source.SourceHandler.state_machine` call.
-
-The state machine of the source entity will generally perform the following steps, after
-a valid :py:class:`tmtccmd.cfdp.request.PutRequest` to perform a File Copy operation was received:
-
-1. Generate the Metadata PDU to be sent to a remote CFDP entity. The PDU will be returned as a
-   :py:class:`spacepackets.cfdp.pdu.metadata.MetadataPdu` instance.
-2. Generate all File Data PDUs to be sent to a remote CFDP entity, if applicable (file not empty).
-   The PDU(s) will be returned as a :py:class:`spacepackets.cfdp.pdu.file_data.FileDataPdu`
-   instance(s).
-3. Generate an EOF PDU be sent to a remote CFDP entity.
-   The PDU will be returned as a :py:class:`spacepackets.cfdp.pdu.eof.EofPdu` instance.
-
-If this is an unacknowledged transfer with no transaction closure, the file transfer will be done
-after these steps. In any other case:
-
-**Unacknowledged transfer with requested closure**
-
-4. A Finished PDU will be awaited, for example one generated using :py:class:`spacepackets.cfdp.pdu.finished.FinishedPdu`.
-
-**Acknowledged transfer**
-
-4. A EOF ACK packet will be awaited, for example one generated using :py:class:`spacepackets.cfdp.pdu.ack.AckPdu`.
-5. A Finished PDU will be awaited, for example one generated using :py:class:`spacepackets.cfdp.pdu.finished.FinishedPdu`.
-6. A Finished PDU ACK packet will be sent to the remote CFDP entity.
-
-CFDP destination entity
-------------------------
-
-The :py:class:`tmtccmd.cfdp.handler.dest.DestHandler` can convert the PDUs sent from a remote
-source entity ID back to a file. A file copy operation on the receiver side is started with
-the reception of a Metadata PDU, for example one generated by the
-:py:class:`spacepackets.cfdp.pdu.metadata.MetadataPdu` class . After that, file packet PDUs, for
-example generated by the :py:class:`spacepackets.cfdp.pdu.file_data.FileDataPdu`, can be inserted
-into the destination handler and will be assembled into a file. The transaction will be finished
-for the following conditions:
-
-1. A valid EOF PDU, for example generated by the :py:class:`spacepackets.cfdp.pdu.eof.EofPdu`
-   class, has been inserted into the class.
-2. All check timers have elapsed. These check timers allow and out-of-order reception of EOF and
-   file data PDUs, provided that the interval between the EOF PDU and the last file data PDUs is
-   not too large. Check timer support is not implemented yet.
-3. All confirmation packets like Finished PDUs or the EOF ACK PDU have been sent back and confirmed
-   by the remote side where applicable.
-
-Current List of unimplemented features
-----------------------------------------
-
-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
-
-Example application
---------------------
-
-You can find an example application inside the
-`example directory <https://github.com/robamu-org/tmtccmd/tree/main/examples/cfdp-simple>`_
-which shows an end-to-end file transfer on a host computer. This should give you a general idea of
-how the source and destination handler work in practice.
-
-There is also a
-`test application <https://github.com/robamu-org/tmtccmd/tree/main/examples/cfdp-libre-cube-crosstest>`_
-which cross-tests the `tmtccmd` CFDP implementation with the
-`Libre Cube CFDP <https://gitlab.com/librecube/lib/python-cfdp>`_ implementation.
-
-Finally, you can see a more complex example also featuring more features of the CFDP state machines
-`here <https://github.com/robamu-org/tmtccmd/tree/main/examples/cfdp-cli-udp>`_. This example
-uses UDP servers for communication and explicitely separates the local and remote entity
-application.
-
-.. _`CCSDS Blue Book 727.0-B-5`: https://public.ccsds.org/Pubs/727x0b5.pdf
-.. _`spacepackets`: https://github.com/us-irs/spacepackets-py
+.. _cfdp-py: https://github.com/us-irs/cfdp-py

docs/conf.py

@@ -60,6 +60,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "serial": ("https://pyserial.readthedocs.io/en/latest/", None),
+    "cfdp-py": ("https://cfdp-py.readthedocs.io/en/latest/", None),
     "spacepackets": ("https://spacepackets.readthedocs.io/en/latest/", None),
     "prompt-toolkit": ("https://python-prompt-toolkit.readthedocs.io/en/latest/", None),
 }

docs/introduction.rst

@@ -33,9 +33,6 @@ Features
   more information and examples.
 - Special support for `Packet Utilisation Standard (PUS)`_ packets and `CCSDS Space Packets`_.
   This library uses the `spacepackets`_ library for most packet implementations.
-- High level CFDP components which allow to build `CFDP standard conformant`_ CFDP handlers.
-  Currently only supports unacknowledged mode. The :ref:`cfdp` chapter contains more information
-  and a link to an example application.
 - Support for both CLI and GUI usage
 - Flexibility in the way to specify telecommands to send and how to handle incoming telemetry.
   This is done by requiring the user to specify callbacks for both TC specification and TM handling.