Merge pull request 'Some DHB docs' (#551) from eive/fsfw:mueller/dhb-docs into development

Reviewed-on: fsfw/fsfw#551
This commit is contained in:
Ulrich Mohr 2022-02-14 16:35:10 +01:00
commit f24de22e9b
4 changed files with 167 additions and 3 deletions

View File

@ -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. 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 ## Formatting the sources
The formatting is done by the `clang-format` tool. The configuration is contained within the The formatting is done by the `clang-format` tool. The configuration is contained within the

View File

@ -1,3 +1,110 @@
.. _dhb-prim-doc:
Device Handlers Device Handlers
================== ==================
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 certain interfaces:
- 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: :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`
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 <fsfw/devicehandlers/DeviceHandlerBase.h>
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;
}

View File

@ -90,8 +90,21 @@ Building the documentation
---------------------------- ----------------------------
The FSFW documentation is built using the tools Sphinx, doxygen and breathe based on the 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/>`_. You can set up a instructions provided in `this blogpost <https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/>`_. If you
documentation build system using the following commands 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 .. 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 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. 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 .. _`Hosted FSFW example`: https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-hosted
.. _`Catch2 library`: https://github.com/catchorg/Catch2 .. _`Catch2 library`: https://github.com/catchorg/Catch2
.. _`Code coverage`: https://github.com/bilke/cmake-modules/tree/master .. _`Code coverage`: https://github.com/bilke/cmake-modules/tree/master

View File

@ -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``. for FDIR reaction. Device Handlers can be created by implementing ``DeviceHandlerBase``.
A standard FDIR component for the DH will be created automatically but can 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 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 <dhb-prim-doc>`.
Modes and Health Modes and Health
-------------------- --------------------