Merge pull request 'Some DHB docs' (#551) from eive/fsfw:mueller/dhb-docs into development
All checks were successful
fsfw/fsfw/pipeline/head This commit looks good
All checks were successful
fsfw/fsfw/pipeline/head This commit looks good
Reviewed-on: #551
This commit is contained in:
commit
f24de22e9b
36
README.md
36
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
|
||||
|
@ -1,3 +1,110 @@
|
||||
.. _dhb-prim-doc:
|
||||
|
||||
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;
|
||||
}
|
||||
|
@ -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 <https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/>`_. You can set up a
|
||||
documentation build system using the following commands
|
||||
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.
|
||||
|
||||
.. 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
|
||||
|
@ -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 <dhb-prim-doc>`.
|
||||
|
||||
Modes and Health
|
||||
--------------------
|
||||
|
Loading…
Reference in New Issue
Block a user