From b25555a533dfd20c8b36bff409a4af963a79e7b8 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Thu, 10 Feb 2022 13:53:01 +0100 Subject: [PATCH 1/5] started DHB docs --- docs/devicehandlers.rst | 102 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) diff --git a/docs/devicehandlers.rst b/docs/devicehandlers.rst index 58c2df786..d1a5fb673 100644 --- a/docs/devicehandlers.rst +++ b/docs/devicehandlers.rst @@ -1,3 +1,105 @@ Device Handlers ================== +Device handler components rerpresent, control and monitor equipment, for example sensors or actuators of a spacecraft or the payload. + +Most device handlers have the same common functionality or +requirements, which are fulfilled by implementing an certain interface: + +- The handler/device needs to be commandable: :cpp:class:`HasActionsIF` +- The handler needs to communicate with the physical device via a dedicated + communication bus, for example SpaceWire, UART or SPI: :cpp:class:`DeviceCommunicationIF` +- The handler has housekeeping data which has to be exposed to the operator and/or other software + components: :cpp:class:`HasLocalDataPoolIF` +- The handler has configurable parameters +- The handler has health states, for example to indicate a broken device: + :cpp:class:`HasHealthIF` +- The handler has modes. For example there are the core modes `MODE_ON`, `MODE_OFF` + and `MODE_NORMAL` provided by the FSFW. `MODE_ON` means that a device is physically powered + but that it is not periodically polling data from the + physical device, `MODE_NORMAL` means that it is able to do that: :cpp:class`HasModesIF` + +The device handler base therefore provides abstractions for a lot of common +functionality, which can potentially avoid high amounts or logic and code duplication. + +Template Device Handler Base File +---------------------------------- + +This is an example template device handler header file with all necessary +functions implemented: + +.. code-block:: cpp + + #ifndef __TESTDEVICEHANDLER_H_ + #define __TESTDEVICEHANDLER_H_ + + #include + + class TestDeviceHandler: DeviceHandlerBase { + public: + TestDeviceHandler(object_id_t objectId, object_id_t comIF, CookieIF* cookie); + private: + void doStartUp() override; + void doShutDown() override; + ReturnValue_t buildNormalDeviceCommand(DeviceCommandId_t* id) override; + ReturnValue_t buildTransitionDeviceCommand(DeviceCommandId_t* id) override; + void fillCommandAndReplyMap() override; + ReturnValue_t buildCommandFromCommand(DeviceCommandId_t deviceCommand, const uint8_t* commandData, + size_t commandDataLen) override; + ReturnValue_t scanForReply(const uint8_t* start, size_t remainingSize, DeviceCommandId_t* foundId, + size_t* foundLen) override; + ReturnValue_t interpretDeviceReply(DeviceCommandId_t id, const uint8_t* packet) override; + uint32_t getTransitionDelayMs(Mode_t modeFrom, Mode_t modeTo) override; + ReturnValue_t initializeLocalDataPool(localpool::DataPool& localDataPoolMap, + LocalDataPoolManager& poolManager) override; + + }; + + #endif /* __TESTDEVICEHANDLER_H_ */ + +and the respective source file with sensible default return values: + +.. code-block:: cpp + #include "TestDeviceHandler.h" + + TestDeviceHandler::TestDeviceHandler(object_id_t objectId, object_id_t comIF, CookieIF* cookie) + : DeviceHandlerBase(objectId, comIF, cookie) {} + + void TestDeviceHandler::doStartUp() {} + + void TestDeviceHandler::doShutDown() {} + + ReturnValue_t TestDeviceHandler::buildNormalDeviceCommand(DeviceCommandId_t* id) { + return HasReturnvaluesIF::RETURN_OK; + } + + ReturnValue_t TestDeviceHandler::buildTransitionDeviceCommand(DeviceCommandId_t* id) { + return HasReturnvaluesIF::RETURN_OK; + } + + void TestDeviceHandler::fillCommandAndReplyMap() {} + + ReturnValue_t TestDeviceHandler::buildCommandFromCommand(DeviceCommandId_t deviceCommand, + const uint8_t* commandData, + size_t commandDataLen) { + return HasReturnvaluesIF::RETURN_OK; + } + + ReturnValue_t TestDeviceHandler::scanForReply(const uint8_t* start, size_t remainingSize, + DeviceCommandId_t* foundId, size_t* foundLen) { + return HasReturnvaluesIF::RETURN_OK; + } + + ReturnValue_t TestDeviceHandler::interpretDeviceReply(DeviceCommandId_t id, + const uint8_t* packet) { + return HasReturnvaluesIF::RETURN_OK; + } + + uint32_t TestDeviceHandler::getTransitionDelayMs(Mode_t modeFrom, Mode_t modeTo) { + return 10000; + } + + ReturnValue_t TestDeviceHandler::initializeLocalDataPool(localpool::DataPool& localDataPoolMap, + LocalDataPoolManager& poolManager) { + return HasReturnvaluesIF::RETURN_OK; + } From cdf2a90f90ed8119a6d23e05efc40b4220b8e7c5 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Thu, 10 Feb 2022 14:02:30 +0100 Subject: [PATCH 2/5] fixed up cross-ref --- docs/devicehandlers.rst | 8 ++++++-- docs/highlevel.rst | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/devicehandlers.rst b/docs/devicehandlers.rst index d1a5fb673..affaa6d90 100644 --- a/docs/devicehandlers.rst +++ b/docs/devicehandlers.rst @@ -1,7 +1,10 @@ +.. _dhb-prim-doc: + Device Handlers ================== -Device handler components rerpresent, control and monitor equipment, for example sensors or actuators of a spacecraft or the payload. +Device handler components represent, control and monitor equipment, for example sensors or actuators +of a spacecraft or the payload. Most device handlers have the same common functionality or requirements, which are fulfilled by implementing an certain interface: @@ -17,7 +20,7 @@ requirements, which are fulfilled by implementing an certain interface: - The handler has modes. For example there are the core modes `MODE_ON`, `MODE_OFF` and `MODE_NORMAL` provided by the FSFW. `MODE_ON` means that a device is physically powered but that it is not periodically polling data from the - physical device, `MODE_NORMAL` means that it is able to do that: :cpp:class`HasModesIF` + physical device, `MODE_NORMAL` means that it is able to do that: :cpp:class:`HasModesIF` The device handler base therefore provides abstractions for a lot of common functionality, which can potentially avoid high amounts or logic and code duplication. @@ -60,6 +63,7 @@ functions implemented: and the respective source file with sensible default return values: .. code-block:: cpp + #include "TestDeviceHandler.h" TestDeviceHandler::TestDeviceHandler(object_id_t objectId, object_id_t comIF, CookieIF* cookie) diff --git a/docs/highlevel.rst b/docs/highlevel.rst index 08f447772..04eb5e7b3 100644 --- a/docs/highlevel.rst +++ b/docs/highlevel.rst @@ -118,7 +118,7 @@ The DH has mechanisms to monitor the communication with the physical device whic for FDIR reaction. Device Handlers can be created by implementing ``DeviceHandlerBase``. A standard FDIR component for the DH will be created automatically but can be overwritten by the user. More information on DeviceHandlers can be found in the -related [documentation section](doc/README-devicehandlers.md#top). +related :ref:`documentation section `. Modes and Health -------------------- From 2dcf896ccad5c99130148cd67a84d70caa1a1215 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Thu, 10 Feb 2022 14:04:23 +0100 Subject: [PATCH 3/5] this sounds better --- docs/devicehandlers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devicehandlers.rst b/docs/devicehandlers.rst index affaa6d90..80b9e7a3c 100644 --- a/docs/devicehandlers.rst +++ b/docs/devicehandlers.rst @@ -7,7 +7,7 @@ Device handler components represent, control and monitor equipment, for example of a spacecraft or the payload. Most device handlers have the same common functionality or -requirements, which are fulfilled by implementing an certain interface: +requirements, which are fulfilled by implementing certain interfaces: - The handler/device needs to be commandable: :cpp:class:`HasActionsIF` - The handler needs to communicate with the physical device via a dedicated From a612fb446cb72b732d73358b17202ee3dfb96b7a Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Mon, 14 Feb 2022 16:23:21 +0100 Subject: [PATCH 4/5] added two links --- docs/devicehandlers.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/devicehandlers.rst b/docs/devicehandlers.rst index 80b9e7a3c..0008edb37 100644 --- a/docs/devicehandlers.rst +++ b/docs/devicehandlers.rst @@ -14,7 +14,8 @@ requirements, which are fulfilled by implementing certain interfaces: communication bus, for example SpaceWire, UART or SPI: :cpp:class:`DeviceCommunicationIF` - The handler has housekeeping data which has to be exposed to the operator and/or other software components: :cpp:class:`HasLocalDataPoolIF` -- The handler has configurable parameters +- The handler has configurable parameters: :cpp:class:`ReceivesParameterMessagesIF` which + also implements :cpp:class:`HasParametersIF` - The handler has health states, for example to indicate a broken device: :cpp:class:`HasHealthIF` - The handler has modes. For example there are the core modes `MODE_ON`, `MODE_OFF` From 6744a55b9b7faf8c72bb9bf4d7bff83ce87c8952 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Mon, 14 Feb 2022 16:31:13 +0100 Subject: [PATCH 5/5] docs update --- README.md | 36 ++++++++++++++++++++++++++++++++++++ docs/getting_started.rst | 25 +++++++++++++++++++++++-- 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a2261c990..89a10f4bb 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,42 @@ cmake --build . -- fsfw-tests_coverage -j The `coverage.py` script located in the `script` folder can also be used to do this conveniently. +## Building the documentations + +The FSFW documentation is built using the tools Sphinx, doxygen and breathe based on the +instructions provided in [this blogpost](https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/). If you +want to do this locally, set up the prerequisites first. This requires a ``python3`` +installation as well. Example here is for Ubuntu. + +```sh +sudo apt-get install doxygen graphviz +``` + +And the following Python packages + +```sh +python3 -m pip install sphinx breathe +``` + +You can set up a documentation build system using the following commands + +```sh +mkdir build-docs && cd build-docs +cmake -DFSFW_BUILD_DOCS=ON -DFSFW_OSAL=host .. +``` + +Then you can generate the documentation using + +```sh +cmake --build . -j +``` + +You can find the generated documentation inside the `docs/sphinx` folder inside the build +folder. Simply open the `index.html` in the webbrowser of your choice. + +The `helper.py` script located in the script` folder can also be used to create, build +and open the documentation conveniently. Try `helper.py -h for more information. + ## Formatting the sources The formatting is done by the `clang-format` tool. The configuration is contained within the diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 069e98cde..34547211e 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -90,8 +90,21 @@ Building the documentation ---------------------------- The FSFW documentation is built using the tools Sphinx, doxygen and breathe based on the -instructions provided in `this blogpost `_. You can set up a -documentation build system using the following commands +instructions provided in `this blogpost `_. If you +want to do this locally, set up the prerequisites first. This requires a ``python3`` +installation as well. Example here is for Ubuntu. + +.. code-block:: console + + sudo apt-get install doxygen graphviz + +And the following Python packages + +.. code-block:: console + + python3 -m pip install sphinx breathe + +You can set up a documentation build system using the following commands .. code-block:: bash @@ -110,6 +123,14 @@ folder. Simply open the ``index.html`` in the webbrowser of your choice. The ``helper.py`` script located in the ``script`` folder can also be used to create, build and open the documentation conveniently. Try ``helper.py -h`` for more information. +Formatting the source +----------------------- + +The formatting is done by the ``clang-format`` tool. The configuration is contained within the +``.clang-format`` file in the repository root. As long as ``clang-format`` is installed, you +can run the ``apply-clang-format.sh`` helper script to format all source files consistently. + + .. _`Hosted FSFW example`: https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-hosted .. _`Catch2 library`: https://github.com/catchorg/Catch2 .. _`Code coverage`: https://github.com/bilke/cmake-modules/tree/master