From fd531e41e57fe36bc86e41d291051eeb37e5e158 Mon Sep 17 00:00:00 2001 From: KonradBkd <117755498+KonradBkd@users.noreply.github.com> Date: Tue, 15 Oct 2024 13:45:59 +0200 Subject: [PATCH] docs: Improve demo and troubleshooting sections (#127) * docs: Improved docs (Demos, Throubleshooting, CSS, file structure) --- Demos/Lin/CMakeLists.txt | 1 + Demos/Lin/LinDemo.cpp | 4 +- SilKit/include/silkit/capi/Lin.h | 2 +- .../silkit/services/lin/LinDatatypes.hpp | 2 +- docs/CHANGELOG.rst | 18 +- docs/CMakeLists.txt | 4 +- docs/_static/custom.css | 44 ++ docs/api/api.rst | 129 ++-- docs/api/{ => capi}/capi-can.rst | 2 + docs/api/{ => capi}/capi-data.rst | 2 + docs/api/{ => capi}/capi-ethernet.rst | 2 + docs/api/{ => capi}/capi-flexray.rst | 2 + docs/api/{ => capi}/capi-lin.rst | 3 + docs/api/{ => capi}/capi-main.rst | 2 + docs/api/{ => capi}/capi-orchestration.rst | 2 + docs/api/{ => capi}/capi-rpc.rst | 2 + docs/api/{ => capi}/capi-systemmonitor.rst | 2 + .../api/{common.rst => common-data-types.rst} | 2 + docs/api/header.rst | 2 + docs/api/memory-management.rst | 4 +- docs/{netsim => api}/netsim.rst | 75 +- docs/api/participant.rst | 6 +- docs/api/serdes.rst | 12 +- docs/api/{ => services}/can.rst | 6 +- docs/api/{ => services}/ethernet.rst | 10 +- docs/api/{ => services}/flexray.rst | 2 + .../lifecycle.rst} | 22 +- docs/api/{ => services}/lin.rst | 50 +- docs/api/{ => services}/logging.rst | 2 + docs/api/{ => services}/pubsub.rst | 20 +- docs/api/{ => services}/rpc.rst | 18 +- .../timesync.rst} | 6 +- .../systemcontroller.rst | 4 +- .../{ => system-utilities}/systemmonitor.rst | 6 +- .../can/CAN_Sender_Receiver.cpp | 0 .../eth/ETH_Erroneous_Transmissions.cpp | 0 .../eth/ETH_Sender_Receiver.cpp | 0 .../eth/ETH_State_Transitions.cpp | 0 .../lin/Go_To_Sleep.cpp | 0 .../lin/LinSlaveConfigurationHandler.cpp | 0 .../lin/Master_to_Slave_LIN_TX_ERROR.cpp | 0 .../lin/Master_to_Slave_LIN_TX_OK.cpp | 0 .../lin/Slave_to_Master_LIN_RX_ERROR.cpp | 0 .../Slave_to_Master_LIN_RX_NO_RESPONSE.cpp | 0 .../lin/Slave_to_Master_LIN_RX_OK.cpp | 0 .../lin/Slave_to_Slave_LIN_TX_OK.cpp | 0 .../examples => code-samples}/lin/Wake_Up.cpp | 0 .../memory/Memory_Dos_Donts.cpp | 0 .../simple}/CMakeLists.txt | 0 .../simple}/simple.cpp | 0 .../simple}/simple.yaml | 0 .../sync/LifecycleNoSyncSample.cpp | 0 .../sync/LifecycleWithSyncSample.cpp | 0 .../sync/SystemMonitorTwoParticipants.cpp | 0 docs/conf.py | 9 +- docs/configuration/configuration.rst | 4 +- .../experimental-configuration.rst | 4 +- .../configuration/extension-configuration.rst | 4 +- .../healthcheck-configuration.rst | 2 + docs/configuration/includes-configuration.rst | 4 +- docs/configuration/logging-configuration.rst | 2 + .../middleware-configuration.rst | 2 + docs/configuration/services-configuration.rst | 2 + docs/configuration/tracing-configuration.rst | 2 + docs/contents.rst | 7 +- docs/demos/demos.rst | 726 ++++++++++++++++++ docs/faq/faq.rst | 91 +-- docs/for-developers/developers.rst | 25 +- docs/for-users/users.rst | 13 +- docs/index.rst | 2 +- docs/licenses/license.rst | 707 +++++++++-------- docs/overview/{overview.inc => overview.rst} | 22 +- docs/simulation/simulation.rst | 15 +- docs/substitutions.rst | 3 + docs/troubleshooting/connection-guides.rst | 53 ++ docs/troubleshooting/connectivity.rst | 106 +++ .../interoperability.rst | 11 +- docs/{usage => troubleshooting}/lifecycle.rst | 9 +- docs/troubleshooting/troubleshooting.rst | 40 + docs/usage/connectivity.rst | 99 --- docs/usage/demos.rst | 632 --------------- docs/usage/troubleshooting.rst | 13 - docs/usage/utilities.rst | 133 ---- docs/utilities/utilities.rst | 148 ++++ 84 files changed, 1846 insertions(+), 1514 deletions(-) rename docs/api/{ => capi}/capi-can.rst (98%) rename docs/api/{ => capi}/capi-data.rst (95%) rename docs/api/{ => capi}/capi-ethernet.rst (98%) rename docs/api/{ => capi}/capi-flexray.rst (99%) rename docs/api/{ => capi}/capi-lin.rst (97%) rename docs/api/{ => capi}/capi-main.rst (98%) rename docs/api/{ => capi}/capi-orchestration.rst (96%) rename docs/api/{ => capi}/capi-rpc.rst (96%) rename docs/api/{ => capi}/capi-systemmonitor.rst (95%) rename docs/api/{common.rst => common-data-types.rst} (87%) rename docs/{netsim => api}/netsim.rst (86%) rename docs/api/{ => services}/can.rst (98%) rename docs/api/{ => services}/ethernet.rst (97%) rename docs/api/{ => services}/flexray.rst (99%) rename docs/api/{lifecycleService.rst => services/lifecycle.rst} (93%) rename docs/api/{ => services}/lin.rst (92%) rename docs/api/{ => services}/logging.rst (95%) rename docs/api/{ => services}/pubsub.rst (98%) rename docs/api/{ => services}/rpc.rst (98%) rename docs/api/{timeSyncService.rst => services/timesync.rst} (97%) rename docs/api/{ => system-utilities}/systemcontroller.rst (98%) rename docs/api/{ => system-utilities}/systemmonitor.rst (96%) rename docs/{api/examples => code-samples}/can/CAN_Sender_Receiver.cpp (100%) rename docs/{api/examples => code-samples}/eth/ETH_Erroneous_Transmissions.cpp (100%) rename docs/{api/examples => code-samples}/eth/ETH_Sender_Receiver.cpp (100%) rename docs/{api/examples => code-samples}/eth/ETH_State_Transitions.cpp (100%) rename docs/{api/examples => code-samples}/lin/Go_To_Sleep.cpp (100%) rename docs/{api/examples => code-samples}/lin/LinSlaveConfigurationHandler.cpp (100%) rename docs/{api/examples => code-samples}/lin/Master_to_Slave_LIN_TX_ERROR.cpp (100%) rename docs/{api/examples => code-samples}/lin/Master_to_Slave_LIN_TX_OK.cpp (100%) rename docs/{api/examples => code-samples}/lin/Slave_to_Master_LIN_RX_ERROR.cpp (100%) rename docs/{api/examples => code-samples}/lin/Slave_to_Master_LIN_RX_NO_RESPONSE.cpp (100%) rename docs/{api/examples => code-samples}/lin/Slave_to_Master_LIN_RX_OK.cpp (100%) rename docs/{api/examples => code-samples}/lin/Slave_to_Slave_LIN_TX_OK.cpp (100%) rename docs/{api/examples => code-samples}/lin/Wake_Up.cpp (100%) rename docs/{api/examples => code-samples}/memory/Memory_Dos_Donts.cpp (100%) rename docs/{usage/sample_silkit => code-samples/simple}/CMakeLists.txt (100%) rename docs/{usage/sample_silkit => code-samples/simple}/simple.cpp (100%) rename docs/{usage/sample_silkit => code-samples/simple}/simple.yaml (100%) rename docs/{api/examples => code-samples}/sync/LifecycleNoSyncSample.cpp (100%) rename docs/{api/examples => code-samples}/sync/LifecycleWithSyncSample.cpp (100%) rename docs/{api/examples => code-samples}/sync/SystemMonitorTwoParticipants.cpp (100%) create mode 100644 docs/demos/demos.rst rename docs/overview/{overview.inc => overview.rst} (94%) create mode 100644 docs/substitutions.rst create mode 100644 docs/troubleshooting/connection-guides.rst create mode 100644 docs/troubleshooting/connectivity.rst rename docs/{usage => troubleshooting}/interoperability.rst (88%) rename docs/{usage => troubleshooting}/lifecycle.rst (91%) create mode 100644 docs/troubleshooting/troubleshooting.rst delete mode 100644 docs/usage/connectivity.rst delete mode 100644 docs/usage/demos.rst delete mode 100644 docs/usage/troubleshooting.rst delete mode 100644 docs/usage/utilities.rst create mode 100644 docs/utilities/utilities.rst diff --git a/Demos/Lin/CMakeLists.txt b/Demos/Lin/CMakeLists.txt index 3d50e363a..63dc7dbbe 100644 --- a/Demos/Lin/CMakeLists.txt +++ b/Demos/Lin/CMakeLists.txt @@ -30,3 +30,4 @@ target_sources(SilKitDemoLinDynamic PRIVATE DemoLin.silkit.yaml PRIVATE NetworkSimulatorConfig.yaml ) + diff --git a/Demos/Lin/LinDemo.cpp b/Demos/Lin/LinDemo.cpp index 87b345583..c632ac137 100644 --- a/Demos/Lin/LinDemo.cpp +++ b/Demos/Lin/LinDemo.cpp @@ -506,7 +506,7 @@ try { master.DoAction(now); now += 1ms; - std::this_thread::sleep_for(200ms); + std::this_thread::sleep_for(100ms); } if (!isStopRequested) { @@ -587,7 +587,7 @@ try { slave.DoAction(now); now += 1ms; - std::this_thread::sleep_for(200ms); + std::this_thread::sleep_for(100ms); } if (!isStopRequested) { diff --git a/SilKit/include/silkit/capi/Lin.h b/SilKit/include/silkit/capi/Lin.h index 6956db4be..322d48a53 100644 --- a/SilKit/include/silkit/capi/Lin.h +++ b/SilKit/include/silkit/capi/Lin.h @@ -160,7 +160,7 @@ typedef uint8_t SilKit_LinFrameStatus; */ typedef uint8_t SilKit_LinDataLength; -//! \brief If configured with this value, the data length of the first reception will be used. +//! \brief If configured for reception with this value, the data length validation of incoming frames is skipped. const SilKit_LinDataLength SilKit_LinDataLengthUnknown = 255u; /*! \brief A LIN SilKit_LinFrame diff --git a/SilKit/include/silkit/services/lin/LinDatatypes.hpp b/SilKit/include/silkit/services/lin/LinDatatypes.hpp index 0d5259c2e..3e8584067 100644 --- a/SilKit/include/silkit/services/lin/LinDatatypes.hpp +++ b/SilKit/include/silkit/services/lin/LinDatatypes.hpp @@ -68,7 +68,7 @@ enum class LinChecksumModel : SilKit_LinChecksumModel */ using LinDataLength = SilKit_LinDataLength; -//! \brief If configured with this value, the data length of the first reception will be used. +//! \brief If configured for reception with this value, the data length validation of incoming frames is skipped. const LinDataLength LinDataLengthUnknown = SilKit_LinDataLengthUnknown; /*! \brief A LIN LinFrame diff --git a/docs/CHANGELOG.rst b/docs/CHANGELOG.rst index 7563c5d2c..8a1f0676e 100644 --- a/docs/CHANGELOG.rst +++ b/docs/CHANGELOG.rst @@ -9,6 +9,10 @@ The format is based on `Keep a Changelog (http://keepachangelog.com/en/1.0.0/) < [4.0.54] - Unreleased --------------------- +Changed +~~~~~~~ + +- Revised the documentation (demos, troubleshooting, doxygen output, file structure) [4.0.53] - 2024-10-11 --------------------- @@ -1608,7 +1612,7 @@ Changed The command line tools were updated to accept a new parameter for this. - The command line tools were modified to use lower case names with dashes: E.g., the ``IbRegistry`` is now called ``sil-kit-registry``. - See :doc:`./usage/utilities` for details. + See :doc:`./utilities/utilities` for details. - The trivial simulation and the detailed simulation have been made more consistent: @@ -3997,7 +4001,7 @@ Removed Changed ~~~~~~~ -- Updated documentation of :doc:`./usage/demos`, :doc:`./usage/utilities` and :doc:`./configuration/configuration` +- Updated documentation of :doc:`./demos/demos`, :doc:`./utilities/utilities` and :doc:`./configuration/configuration` - Participant (formerly 'ComAdapter') methods to create DataPublisher, DataSubscriber, RpcClient and RpcServer now have an additional @@ -6392,7 +6396,7 @@ This is a Quality Assured Release. Added ~~~~~ -- Documentation for the CAN controller API: :doc:`CAN Vehicle Network Controllers `. +- Documentation for the CAN controller API: :doc:`CAN Vehicle Network Controllers `. - Documentation for the Participant Controller API: :ref:`changelog-outdated-reference` (``api/participantcontroller``) (AFTMAGT-206). - Documentation for the IO Port services (AFTMAGT-201). - Documented Generic Messages API: (AFTMAGT-204). @@ -6400,9 +6404,9 @@ Added - Added docs for the ComAdapter: - Added quick start guide: usage/quickstart - Elaborate the user APIs and overview pages: :doc:`api/api` -- Add docs for :doc:`api/systemcontroller` (AFTMAGT-242). -- Add docs for :doc:`api/systemmonitor` (AFTMAGT-242). -- Add docs for :doc:`api/ethernet` (AFTMAGT-239). +- Add docs for :doc:`api/system-utilities/systemcontroller` (AFTMAGT-242). +- Add docs for :doc:`api/system-utilities/systemmonitor` (AFTMAGT-242). +- Add docs for :doc:`api/services/ethernet` (AFTMAGT-239). Changed ~~~~~~~ @@ -6686,7 +6690,7 @@ Changed - The LIN API was redesigned to provide a clearer and simpler interface. To make the transition to the new API as simple as possible, we provided extensive documentation on the new API itself including usage examples and information - about what changed in the new API: :doc:`../api/lin` + about what changed in the new API: :doc:`../api/services/lin` - Removed spdlog from the public IB API. Spdlog is still used internally but it has been removed from the public API to avoid conflicts with user specific spdlog installations. diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index c5eec00a1..1741ceb6e 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -43,6 +43,7 @@ endif() #Replace variables inside @@ with the current values configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY) + #Doxygen won't create this for us file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) @@ -56,6 +57,7 @@ set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html) # - The Sphinx config has been updated file(GLOB_RECURSE SPHINX_SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.rst) file(GLOB_RECURSE SVG_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.svg) +list(APPEND SPHINX_SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/_static/custom.css) if (UNIX) if (${SILKIT_WARNINGS_AS_ERRORS}) @@ -106,5 +108,5 @@ install( COMPONENT docs ) #add sample code so it shows in the IDE, but don't build or install it -add_executable(sample_silkit_new_config EXCLUDE_FROM_ALL usage/sample_silkit/simple.cpp) +add_executable(sample_silkit_new_config EXCLUDE_FROM_ALL code-samples/simple/simple.cpp) target_link_libraries(sample_silkit_new_config PRIVATE SilKit) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 7c126228e..abde263bf 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -13,6 +13,7 @@ max-width: 1240px; } +/* custom styling for literals: center properly and change color */ .rst-content code.literal { position: relative; top: -0.08rem; @@ -21,6 +22,7 @@ background: none; } +/* custom styling for literals + links: center properly and change color */ .rst-content code.xref { position: relative; top: -0.08rem; @@ -28,3 +30,45 @@ font-weight: 700; background: none; } + +/* custom doxygenfunction style */ + +:root { + --doxygen-font-family: Lato, proxima-nova, Helvetica Neue, Arial, sans-serif; + --codeblock-font-family: SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace; +} + +/* Font, size, weight for the function signature */ +.cpp dt.sig.sig-object.cpp { + font-family: var(--doxygen-font-family) !important; + font-size: 14px !important; + font-weight: 400; +} + +/* Color for function namespace in function signature */ +/*.cpp dt.sig.sig-object.cpp span.sig-prename.descclassname { + color: #00008B +}*/ + +/* Color for function name in function signature */ +.cpp dt.sig.sig-object.cpp span.sig-name.descname { + color: #00008B !important; + font-weight: 700; +} + +/* Color for function parameters in function signature */ +.cpp dt.sig.sig-object.cpp span.n.sig-param { + color: #00008B +} + +/* Font and color for function parameters in list */ +.cpp.function strong { + font-family: var(--doxygen-font-family); + color: #0047AB +} + +/* Font and color for exceptions in list */ +.cpp.function .cpp-expr.sig.sig-inline.cpp { + font-family: var(--doxygen-font-family); + color: #E97451 +} diff --git a/docs/api/api.rst b/docs/api/api.rst index c4aa68106..a85eac247 100644 --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -1,65 +1,74 @@ -=== -API -=== -.. |Participant| replace:: :doc:`Participant` -.. |header| replace:: :doc:`header
` +.. include:: /substitutions.rst +========= +C/C++ API +========= -This document describes the user available programming interfaces of the Vector -SIL Kit (SIL Kit). If you are not yet familiar with the SIL Kit, have a look at -the :doc:`Developers Guide<../for-developers/developers>`. +This document describes the user available programming interfaces of the Vector |ProductName|. +If you are not yet familiar with the |ProductName|, have a look at the :doc:`Developers Guide<../for-developers/developers>`. +Information on API organization in the |ProductName|: +.. toctree:: + :maxdepth: 1 + + header + memory-management + +C++ API +------- -API Entry Point and API Organization ------------------------------------- +Participant +~~~~~~~~~~~ -The Participant constitutes the main entry point into the SIL Kit API. +The Participant constitutes the main entry point into the |ProductName| API. .. toctree:: :maxdepth: 1 participant - header - memory-management - + .. _sec:api-services: Services --------- +~~~~~~~~ The services API includes common data types, supports various vehicular networks, and provides generic publish/subscribe and RPC facilities. +Logging ++++++++ + +The Logging service can be used for writing log messages of specified log levels to various types of sinks. + .. toctree:: :maxdepth: 1 - - logging + + services/logging Vehicle Network Controller -~~~~~~~~~~~~~~~~~~~~~~~~~~ -Several different vehicular networks are supported by corresponding -controller interfaces. +++++++++++++++++++++++++++ + +Several different vehicular networks are supported by corresponding controller interfaces. .. toctree:: :maxdepth: 1 - can - lin - flexray - ethernet + services/can + services/lin + services/flexray + services/ethernet Data Publish/Subscribe and RPC -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +++++++++++++++++++++++++++++++ -These services do not model a real-world bus and can be used for -generic programming and interoperability tasks. +These services do not model a real-world bus and can be used for generic programming and interoperability tasks. .. toctree:: :maxdepth: 1 - pubsub - rpc + services/pubsub + services/rpc -SIL Kit provides a recommended default serialization/deserialization API for Data Publish/Subscribe and RPC: +|ProductName| provides a recommended default serialization/deserialization API for Data Publish/Subscribe and RPC: .. toctree:: :maxdepth: 1 @@ -67,40 +76,60 @@ SIL Kit provides a recommended default serialization/deserialization API for Dat serdes State Handling and Synchronization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +++++++++++++++++++++++++++++++++++ + +The following services provide time synchronization and orchestrated state management. + +.. toctree:: + :maxdepth: 1 + + services/lifecycle + services/timesync + -The following services provide time synchronization and orchestrated state -management. +System Utilities +++++++++++++++++ + +These system utilities can be used to control and monitor the simulation as a whole. .. toctree:: :maxdepth: 1 - lifecycleService - timeSyncService - systemcontroller - systemmonitor + system-utilities/systemcontroller + system-utilities/systemmonitor Common Data Types -~~~~~~~~~~~~~~~~~ ++++++++++++++++++ + +Some data types are shared between services of the |ProductName|. + +.. toctree:: + :maxdepth: 1 + + common-data-types + +Custom Network Simulator +++++++++++++++++++++++++ .. toctree:: :maxdepth: 1 - common + netsim + C API ----- -The SIL Kit provides an additional API that allows to use the SIL Kit directly +The |ProductName| provides an additional API that allows to use the |ProductName| directly with the C programming language: .. toctree:: :maxdepth: 1 - capi-main + capi/capi-main Services -~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~ Vehicle Network Controller ++++++++++++++++++++++++++ @@ -108,10 +137,10 @@ Vehicle Network Controller .. toctree:: :maxdepth: 1 - capi-can - capi-ethernet - capi-lin - capi-flexray + capi/capi-can + capi/capi-ethernet + capi/capi-lin + capi/capi-flexray Data Publish/Subscribe and RPC ++++++++++++++++++++++++++++++ @@ -119,8 +148,8 @@ Data Publish/Subscribe and RPC .. toctree:: :maxdepth: 1 - capi-data - capi-rpc + capi/capi-data + capi/capi-rpc State Handling and Synchronization ++++++++++++++++++++++++++++++++++ @@ -128,5 +157,5 @@ State Handling and Synchronization .. toctree:: :maxdepth: 1 - capi-orchestration - capi-systemmonitor + capi/capi-orchestration + capi/capi-systemmonitor diff --git a/docs/api/capi-can.rst b/docs/api/capi/capi-can.rst similarity index 98% rename from docs/api/capi-can.rst rename to docs/api/capi/capi-can.rst index ace032839..4449c6114 100644 --- a/docs/api/capi-can.rst +++ b/docs/api/capi/capi-can.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + CAN C API ---------- diff --git a/docs/api/capi-data.rst b/docs/api/capi/capi-data.rst similarity index 95% rename from docs/api/capi-data.rst rename to docs/api/capi/capi-data.rst index 97a10e2b3..df76217e4 100644 --- a/docs/api/capi-data.rst +++ b/docs/api/capi/capi-data.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + Data Publish/Subscribe C API ---------------------------- diff --git a/docs/api/capi-ethernet.rst b/docs/api/capi/capi-ethernet.rst similarity index 98% rename from docs/api/capi-ethernet.rst rename to docs/api/capi/capi-ethernet.rst index b1d722839..7499b2cdf 100644 --- a/docs/api/capi-ethernet.rst +++ b/docs/api/capi/capi-ethernet.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + Ethernet C API -------------- diff --git a/docs/api/capi-flexray.rst b/docs/api/capi/capi-flexray.rst similarity index 99% rename from docs/api/capi-flexray.rst rename to docs/api/capi/capi-flexray.rst index dd70c6863..c2ca51a86 100644 --- a/docs/api/capi-flexray.rst +++ b/docs/api/capi/capi-flexray.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + FlexRay C API ------------- diff --git a/docs/api/capi-lin.rst b/docs/api/capi/capi-lin.rst similarity index 97% rename from docs/api/capi-lin.rst rename to docs/api/capi/capi-lin.rst index 1a913d964..ed692e713 100644 --- a/docs/api/capi-lin.rst +++ b/docs/api/capi/capi-lin.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + LIN C API --------- @@ -81,6 +83,7 @@ Enumerations and Typedefs .. doxygentypedef:: SilKit_LinFrameResponseType .. doxygentypedef:: SilKit_LinFrameStatus .. doxygentypedef:: SilKit_LinDataLength +.. doxygenvariable:: SilKit_LinDataLengthUnknown .. doxygentypedef:: SilKit_LinFrameStatusHandler_t .. doxygentypedef:: SilKit_LinGoToSleepHandler_t diff --git a/docs/api/capi-main.rst b/docs/api/capi/capi-main.rst similarity index 98% rename from docs/api/capi-main.rst rename to docs/api/capi/capi-main.rst index 639bf7ddf..41839cbee 100644 --- a/docs/api/capi-main.rst +++ b/docs/api/capi/capi-main.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _sec:capi: ================================ diff --git a/docs/api/capi-orchestration.rst b/docs/api/capi/capi-orchestration.rst similarity index 96% rename from docs/api/capi-orchestration.rst rename to docs/api/capi/capi-orchestration.rst index c75a9636c..20c1cf8c7 100644 --- a/docs/api/capi-orchestration.rst +++ b/docs/api/capi/capi-orchestration.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + Orchestration C API ---------------------------- diff --git a/docs/api/capi-rpc.rst b/docs/api/capi/capi-rpc.rst similarity index 96% rename from docs/api/capi-rpc.rst rename to docs/api/capi/capi-rpc.rst index 34083af00..bcaff6c75 100644 --- a/docs/api/capi-rpc.rst +++ b/docs/api/capi/capi-rpc.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + RPC C API ----------- diff --git a/docs/api/capi-systemmonitor.rst b/docs/api/capi/capi-systemmonitor.rst similarity index 95% rename from docs/api/capi-systemmonitor.rst rename to docs/api/capi/capi-systemmonitor.rst index 6a02fc2bc..cbdc1f13c 100644 --- a/docs/api/capi-systemmonitor.rst +++ b/docs/api/capi/capi-systemmonitor.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + System Monitor C API --------------------- diff --git a/docs/api/common.rst b/docs/api/common-data-types.rst similarity index 87% rename from docs/api/common.rst rename to docs/api/common-data-types.rst index 06468429c..47a653185 100644 --- a/docs/api/common.rst +++ b/docs/api/common-data-types.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + ========================= Common Service Data Types ========================= diff --git a/docs/api/header.rst b/docs/api/header.rst index dbeff98b9..c50c2ca57 100644 --- a/docs/api/header.rst +++ b/docs/api/header.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _sec:header: ============ diff --git a/docs/api/memory-management.rst b/docs/api/memory-management.rst index 57af69348..db20ebcdf 100644 --- a/docs/api/memory-management.rst +++ b/docs/api/memory-management.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + ================= Memory Management ================= @@ -60,7 +62,7 @@ Examples Within this section examples of how and how not to use the SIL Kit API regarding memory management are shown. .. literalinclude:: - ./examples/memory/Memory_Dos_Donts.cpp + /code-samples/memory/Memory_Dos_Donts.cpp :language: cpp :lines: 24-44 diff --git a/docs/netsim/netsim.rst b/docs/api/netsim.rst similarity index 86% rename from docs/netsim/netsim.rst rename to docs/api/netsim.rst index 8c21761fc..c4c0b6545 100644 --- a/docs/netsim/netsim.rst +++ b/docs/api/netsim.rst @@ -1,10 +1,9 @@ +.. include:: /substitutions.rst + ======================================== Custom Network Simulator ======================================== -.. |ProductName| replace:: SIL Kit -.. |Netsim| replace:: Network Simulator - .. |INetworkSimulator| replace:: :cpp:class:`INetworkSimulator` .. |ISimulatedNetwork| replace:: :cpp:class:`ISimulatedNetwork` .. |ISimulatedController| replace:: :cpp:class:`ISimulatedController` @@ -29,54 +28,54 @@ Custom Network Simulator .. _sec:sil-kit-netsim: -With the |Netsim| API, a custom network simulation for CAN, LIN, Ethernet or Flexray is made accessible. +With the |NetSim| API, a custom network simulation for CAN, LIN, Ethernet or Flexray is made accessible. The core concept is that all controller communication is redirected to a network simulator participant who performs the detailed simulation and is responsible for the final message distribution. -The scope of the |Netsim| API is to manage the message flow for incoming and outgoing messages, not to perform the simulation logic. +The scope of the |NetSim| API is to manage the message flow for incoming and outgoing messages, not to perform the simulation logic. .. warning:: - The |Netsim| API is experimental and might be changed or removed in future versions of the |ProductName|. + The |NetSim| API is experimental and might be changed or removed in future versions of the |ProductName|. .. contents:: :local: :depth: 2 -Using the |Netsim| API +Using the |NetSim| API ====================== -The usage of the |Netsim| API can be split into a configuration- and a simulation phase. -In the *configuration phase*, the |Netsim| defines the simulated networks while other participants create their controllers. -The |ProductName| takes care of informing the |Netsim| about the emerging controllers. -Vice versa, the controllers are informed that their network is simulated by the |Netsim|. -The controllers on a simulated network will route their outgoing messages exclusively to the |Netsim|. +The usage of the |NetSim| API can be split into a configuration- and a simulation phase. +In the *configuration phase*, the |NetSim| defines the simulated networks while other participants create their controllers. +The |ProductName| takes care of informing the |NetSim| about the emerging controllers. +Vice versa, the controllers are informed that their network is simulated by the |NetSim|. +The controllers on a simulated network will route their outgoing messages exclusively to the |NetSim|. Note that this behavior switch does not require any action on the participant that holds the controller. -If the controller was configured with a network name that the |Netsim| defined as a simulated network, the new routing will take place automatically. +If the controller was configured with a network name that the |NetSim| defined as a simulated network, the new routing will take place automatically. -In the *simulation phase*, each message (e.g., controller configuration, frame requests) triggers a callback on the |Netsim|. +In the *simulation phase*, each message (e.g., controller configuration, frame requests) triggers a callback on the |NetSim|. These callbacks will drive the simulation implemented by the user. -For outgoing messages, the |Netsim| API allows to produce events that can target individual controllers. +For outgoing messages, the |NetSim| API allows to produce events that can target individual controllers. E.g., a frame request will finally result in a frame transmission for all controllers and an acknowledge message for the triggering controller. Configuration phase ------------------- -The entry point of the |Netsim| API is the creation of an |INetworkSimulator| at a participant. +The entry point of the |NetSim| API is the creation of an |INetworkSimulator| at a participant. Only one network simulator per participant is allowed: -.. code-block:: cpp +.. code-block:: c++ INetworkSimulator* networkSimulator = SilKit::Experimental::Participant::CreateNetworkSimulator(participant.get()); On the |INetworkSimulator| instance, simulated networks can be registered. This affects controller of the given type in the whole |ProductName| simulation, if their configured network name and type matches. -.. code-block:: cpp +.. code-block:: c++ auto mySimulatedCanNetwork = std::make_unique("CAN1"); networkSimulator->SimulateNetwork("CAN1", SimulatedNetworkType::CAN, std::move(mySimulatedCanNetwork)); The instance ``mySimulatedCanNetwork`` passed in |SimulateNetwork| represents a specific, named simulated network. -The underlying class must inherit from the |ISimulatedNetwork| interface and must be implemented by the user of the |Netsim| API. +The underlying class must inherit from the |ISimulatedNetwork| interface and must be implemented by the user of the |NetSim| API. Its purpose is twofold: 1. Providing a producer object to send out messages to targeted controllers. @@ -84,7 +83,7 @@ Its purpose is twofold: In |SetEventProducer|, an ``IEventProducer`` instance is handed over to the user. After casting to the specific event producer for the corresponding network type (e.g. to ``ICanEventProducer``), the event producer can send targeted messages to the desired recipients. -.. code-block:: cpp +.. code-block:: c++ void MySimulatedCanNetwork::SetEventProducer(std::unique_ptr eventProducer) { @@ -102,10 +101,10 @@ Its purpose is twofold: This happens by calls from the |ProductName| to |ProvideSimulatedController|, here on the *mySimulatedCanNetwork* instance, whenever a participant creates a controller. The method provides routing information to address the controller (i.e., the *controller descriptor*) and expects the user to return an instance that implements the |ISimulatedController| interface. For the different network types, one of the specific child classes (e.g., |ISimulatedCanController| for CAN networks) must be used. - After providing the simulated controller, all messages from the original controller will be routed only to the |Netsim| and trigger message specific reception functions on the provided simulated controller instance. + After providing the simulated controller, all messages from the original controller will be routed only to the |NetSim| and trigger message specific reception functions on the provided simulated controller instance. Other controllers will no longer receive the messages. -.. code-block:: cpp +.. code-block:: c++ auto MySimulatedCanNetwork::ProvideSimulatedController(ControllerDescriptor controllerDescriptor) -> ISimulatedController* { @@ -119,7 +118,7 @@ Its purpose is twofold: return _mySimulatedControllers.back().get(); } -The following graph shows the |Netsim| API usage of the configuration phase: +The following graph shows the |NetSim| API usage of the configuration phase: .. _label:netsim-api-discovery: .. figure:: ../_static/netsim-api-discovery.svg @@ -135,14 +134,14 @@ Simulation phase Via the provided implementation of an |ISimulatedController| in |ProvideSimulatedController|, the user receives events generated by the original controller. An ``On...()`` callback exists for each possible message of a controller. E.g., if a remote controller on a simulated network intends to sends a CAN frame and calls |SendCanFrame|, |OnFrameRequest| is triggered on the |ISimulatedCanController|. -The ``On...()`` callbacks represent the message input of the |Netsim|. +The ``On...()`` callbacks represent the message input of the |NetSim|. For outgoing CAN messages, the |Produce| methods from the |ICanEventProducer| can be used. In the following code snippet, the simple simulation logic is to send out a *CAN frame transmit event* to the requesting controller and the actual *CAN frame event* as a broadcast to all controllers. Here, the |IEventProducer| was obtained in |SetEventProducer| and is stored in ``MySimulatedCanNetwork``. To target only the desired recipients, the receivers must be specified as a :ref:`span` of controller descriptors in all ``Produce()`` methods. -.. code-block:: cpp +.. code-block:: c++ void MySimulatedCanController::OnFrameRequest(const CanFrameRequest& frameRequest) { @@ -173,7 +172,7 @@ To target only the desired recipients, the receivers must be specified as a :ref _mySimulatedNetwork->GetCanEventProducer()->Produce(frameEvent, _mySimulatedNetwork->GetAllReceivers()); } -The following graph shows the corresponding event flow and |Netsim| API for the code snippet: +The following graph shows the corresponding event flow and |NetSim| API for the code snippet: .. _label:netsim-api-runtime: .. figure:: ../_static/netsim-api-runtime.svg @@ -183,30 +182,30 @@ The following graph shows the corresponding event flow and |Netsim| API for the : Exemplary simulation phase of a network simulation. -See the :ref:`Network Simulator Demo` for a complete example with class definitions and a custom scheduler. +See the :ref:`Network Simulator Demo` for a complete example with class definitions and a custom scheduler. Handling simulation time ------------------------ -A central use case of a |Netsim| is to simulate detailed time behavior of a virtual bus network. -Emulating network specific behavior is not part of the |Netsim| API and has to be implemented by the user. +A central use case of a |NetSim| is to simulate detailed time behavior of a virtual bus network. +Emulating network specific behavior is not part of the |NetSim| API and has to be implemented by the user. For a simulation with :ref:`virtual time synchronization`, this can be achieved by a custom scheduler. -The scheduler is provided with time-related events in the |Netsim| and updates the simulation time in the |SetSimulationStepHandler|. +The scheduler is provided with time-related events in the |NetSim| and updates the simulation time in the |SetSimulationStepHandler|. When the virtual time advances, the custom scheduler triggers the due events. Further, the scheduler can provide the current simulation time for the produced events as shown in the code snippets. Integrating in the |ProductName| Lifecycle ------------------------------------------ -Usually, a |Netsim| is integrated in setup with distributed participants that use a :ref:`coordinated lifecycle`. +Usually, a |NetSim| is integrated in setup with distributed participants that use a :ref:`coordinated lifecycle`. This means that it is mandatory to know beforehand which participants will take part in the simulation and that all participants agree on a starting point of the simulation. -Although it is not enforced by the |Netsim| API, this is the recommended lifecycle operation mode for |ProductName| simulations with a |Netsim|. -The central reason is that in using a coordinated lifecycle, the |Netsim| cannot miss any message sent by the controllers, especially initial configuration messages that are essential to perform the bus simulation. -The following aspects have to be considered that the |Netsim| is guaranteed to receive all messages in the distributed setup without any restrictions to the starting order of the participants: +Although it is not enforced by the |NetSim| API, this is the recommended lifecycle operation mode for |ProductName| simulations with a |NetSim|. +The central reason is that in using a coordinated lifecycle, the |NetSim| cannot miss any message sent by the controllers, especially initial configuration messages that are essential to perform the bus simulation. +The following aspects have to be considered that the |NetSim| is guaranteed to receive all messages in the distributed setup without any restrictions to the starting order of the participants: -- The |Netsim| and all participants that hold simulated controllers must use a *coordinated lifecycle*. +- The |NetSim| and all participants that hold simulated controllers must use a *coordinated lifecycle*. - As a consequence, a :ref:`System Controller` must be used that knows all required participant names. -- The |Netsim| must call |Start| before starting his lifecycle via |StartLifecycle|. +- The |NetSim| must call |Start| before starting his lifecycle via |StartLifecycle|. - The participants must not trigger any bus message before their lifecycle state reaches :cpp:enumerator:`CommunicationReady`. Read the documentation on :ref:`Lifecycle Management` for further details. @@ -216,8 +215,8 @@ The following aspects have to be considered that the |Netsim| is guaranteed to r Event flow ---------- -During the simulation, the |Netsim| is notified about all relevant calls of the controllers in the ``On...()`` callbacks. -The |Produce| methods of the |Netsim| then trigger one or more handlers on the controller. +During the simulation, the |NetSim| is notified about all relevant calls of the controllers in the ``On...()`` callbacks. +The |Produce| methods of the |NetSim| then trigger one or more handlers on the controller. The following diagrams show the connection between this event flow for the various bus systems. .. _label:netsim-api-can-event-flow: diff --git a/docs/api/participant.rst b/docs/api/participant.rst index 425777654..043690b3d 100644 --- a/docs/api/participant.rst +++ b/docs/api/participant.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + ============= Participant ============= @@ -15,7 +17,9 @@ Creating the Participant ~~~~~~~~~~~~~~~~~~~~~~~~ To create an |IParticipant| you have to include the :ref:`silkit/SilKit.hpp` and call the Participant API -factory function:: +factory function: + +.. code-block:: c++ auto config = SilKit::Config::ParticipantConfigurationFromFile("my_config.yaml"); auto participant = SilKit::CreateParticipant(config, "ParticipantName", registryUri); diff --git a/docs/api/serdes.rst b/docs/api/serdes.rst index 33e976e23..9686e95a0 100644 --- a/docs/api/serdes.rst +++ b/docs/api/serdes.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + ====================================== Data Serialization/Deserialization API ====================================== @@ -15,7 +17,7 @@ Using the Data Serialization/Deserialization API The `Data Serialization/Deserialization (SerDes) API` provides serialization and deserialization of data using a simple serialization scheme. Both `Data Publish/Subscribe API` and `RPC API` support any serialization format for the transmission of the data or arguments for maximum flexibility. However, to ensure compatibility with other simulation participants, it is strongly recommended to use `SerDes` for all data transferred via the -:doc:`Data Publish/Subscribe API` and the :doc:`RPC API`. +:doc:`Data Publish/Subscribe API` and the :doc:`RPC API`. .. admonition:: Caution @@ -37,9 +39,9 @@ Unions are currently not supported. Usage Example ~~~~~~~~~~~~~ -Consider an example type from the :ref:`Publish/Subscribe Demo`: +Consider an example type from the :ref:`Publish/Subscribe Demo`: -.. code-block:: cpp +.. code-block:: c++ struct GpsData { @@ -50,7 +52,7 @@ Consider an example type from the :ref:`Publish/Subscribe Demo Serialize(const GpsData& gpsData) { @@ -64,7 +66,7 @@ Functions to serialize and deserialize this type can be written this way: return serializer.ReleaseBuffer(); } -.. code-block:: cpp +.. code-block:: c++ GpsData Deserialize(const std::vector& data) { diff --git a/docs/api/can.rst b/docs/api/services/can.rst similarity index 98% rename from docs/api/can.rst rename to docs/api/services/can.rst index cfdbcd782..99e937828 100644 --- a/docs/api/can.rst +++ b/docs/api/services/can.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _chap:can-service-api: =================== @@ -101,7 +103,7 @@ An optional second parameter of |AddFrameTransmitHandler| allows to specify the Receiving CAN Frame Events ~~~~~~~~~~~~~~~~~~~~~~~~~~ -A |CanFrame| is received as a |CanFrameEvent| consisting of a ``transmitId`` used to identify the acknowledgement of the +A |CanFrame| is received as a |CanFrameEvent| consisting of a ``transmitId`` used to identify the acknowledgment of the frame, a timestamp and the actual |CanFrame|. The handler is called whenever a |CanFrame| is received:: auto frameHandler = [](ICanController*, const CanFrameEvent& frameEvent) @@ -203,5 +205,5 @@ This example shows a successful data transfer from one CAN controller to another CAN network. .. literalinclude:: - examples/can/CAN_Sender_Receiver.cpp + /code-samples/can/CAN_Sender_Receiver.cpp :language: cpp diff --git a/docs/api/ethernet.rst b/docs/api/services/ethernet.rst similarity index 97% rename from docs/api/ethernet.rst rename to docs/api/services/ethernet.rst index 9b42ad922..510bbd46c 100644 --- a/docs/api/ethernet.rst +++ b/docs/api/services/ethernet.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _chap:ethernet-service-api: ==================== @@ -120,7 +122,7 @@ Receiving Ethernet Frame Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An |EthernetFrame| is received as an |EthernetFrameEvent| consisting of a ``transmitId`` used to identify -the acknowledgement of the frame, a timestamp and the actual |EthernetFrame|. +the acknowledgment of the frame, a timestamp and the actual |EthernetFrame|. To receive Ethernet frames, a frame handler must be registered using |AddFrameHandler|. The handler is called whenever an Ethernet frame is received:: @@ -221,7 +223,7 @@ Simple Ethernet Sender / Receiver Example This example shows a successful data transfer from one Ethernet controller to another. .. literalinclude:: - examples/eth/ETH_Sender_Receiver.cpp + /code-samples/eth/ETH_Sender_Receiver.cpp :language: cpp State Transition Example @@ -230,7 +232,7 @@ State Transition Example This example shows the possible state transitions for an Ethernet controller. .. literalinclude:: - examples/eth/ETH_State_Transitions.cpp + /code-samples/eth/ETH_State_Transitions.cpp :language: cpp @@ -240,5 +242,5 @@ Erroneous Transmissions (Detailed Simulation only) This example shows different possible erroneous Ethernet transmissions. .. literalinclude:: - examples/eth/ETH_Erroneous_Transmissions.cpp + /code-samples/eth/ETH_Erroneous_Transmissions.cpp :language: cpp diff --git a/docs/api/flexray.rst b/docs/api/services/flexray.rst similarity index 99% rename from docs/api/flexray.rst rename to docs/api/services/flexray.rst index 6100f3bec..94fcf13e5 100644 --- a/docs/api/flexray.rst +++ b/docs/api/services/flexray.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _chap:flexray-service-api: =================== diff --git a/docs/api/lifecycleService.rst b/docs/api/services/lifecycle.rst similarity index 93% rename from docs/api/lifecycleService.rst rename to docs/api/services/lifecycle.rst index 3c4fecf90..b00dff77b 100644 --- a/docs/api/lifecycleService.rst +++ b/docs/api/services/lifecycle.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _chap:lifecycle-service-api: ================== @@ -6,7 +8,7 @@ Lifecycle Service .. Macros for docs use -.. |Participant| replace:: :doc:`Participant` +.. |Participant| replace:: :doc:`Participant` .. |IParticipant| replace:: :cpp:class:`IParticipant` .. |ITimeSyncService| replace:: :cpp:class:`ITimeSyncService` @@ -51,8 +53,8 @@ Lifecycle Service .. |Publish| replace:: :cpp:func:`Publish()` .. contents:: - :local: - :depth: 2 + :local: + :depth: 2 .. highlight:: cpp @@ -147,13 +149,21 @@ This can be used to start local timers:: } ); -The |CommunicationReadyHandler| should be used to initialize and configure :doc:`services and controllers`. +The |CommunicationReadyHandler| should be used to initialize vehicle network controllers that require an inital configuration. +This will make sure that the controller configuration is available to all participants before the simulation start. +API calls that are recommended to be used in this handler are: +* :cpp:func:`ICanController::Start()` +* :cpp:func:`ICanController::SetBaudRate()` +* :cpp:func:`ILinController::Init()` +* :cpp:func:`IEthernetController::Activate()` +* :cpp:func:`IFlexrayController::Configure()` + Communication guarantees """""""""""""""""""""""" The following communication guarantees apply to participants that utilize a Lifecycle Service and are limited to RPC and Publish/Subscribe services. -Bus systems have definitions on the protocol level for message acknowledgement. +Bus systems have definitions on the protocol level for message acknowledgment. For RPC or Publish/Subscribe however, communication guarantees depend on the implementation. In the SIL Kit, the |CommunicationReadyHandler| handler is the first point at which guarantees can be given. This implies that |StartLifecycle| has already been called. @@ -237,5 +247,5 @@ To demonstrate how to properly initialize other services, a CAN controller is in This is the recommended way to set up controllers before first use. .. literalinclude:: - examples/sync/LifecycleNoSyncSample.cpp + /code-samples/sync/LifecycleNoSyncSample.cpp :language: cpp diff --git a/docs/api/lin.rst b/docs/api/services/lin.rst similarity index 92% rename from docs/api/lin.rst rename to docs/api/services/lin.rst index bc504f508..69aaca77b 100644 --- a/docs/api/lin.rst +++ b/docs/api/services/lin.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _chap:lin-service-api: =================== @@ -134,7 +136,7 @@ initiation of the slave-to-slave communication. Initiating LIN Transmissions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Data is transferred in the form of a |LinFrame|, reception and acknowledgement is handled in the |FrameStatusHandler|. +Data is transferred in the form of a |LinFrame|, reception and acknowledgment is handled in the |FrameStatusHandler|. A LIN master can initiate the transmission of a frame using the AUTOSAR API |SendFrame| or the non-AUTOSAR API |SendFrameHeader|. If a LIN slave provides the response, |SendFrame| requires that a corresponding frame response was configured before at a LIN slave using |Init| or |SetFrameResponse|. @@ -170,7 +172,7 @@ The transmission of a frame can be initiated using |SendFrame| or |SendFrameHead 2. When using |SendFrame| with |LinFrameResponseType_SlaveResponse| or |LinFrameResponseType_SlaveToSlave|, a slave has to be preconfigured with |LinFrameResponseMode_Tx| on that ID. With these response types, only the ID of the |LinFrame| used in |SendFrame| is taken into account. The actual payload and frame settings are provided - by the Tx buffer of the responing slave. The following example assumes that a slave is configured as seen in + by the TX buffer of the responding slave. The following example assumes that a slave is configured as seen in :ref:`Initialization`:: // The slave is configured to respond on ID 0x11 @@ -185,7 +187,7 @@ and will configure itself for reception (|LinFrameResponseMode_Rx|). 3. When using |SendFrameHeader|, the transmission is initiated by sending the header. The node (either master or slave) configured with |LinFrameResponseMode_Tx| will provide the response. The actual payload and frame settings are - provided by the Tx buffer of the responing LIN node. The following example also assumes that a slave is + provided by the TX buffer of the responding LIN node. The following example also assumes that a slave is configured as seen in :ref:`Initialization`:: // Slave: @@ -200,8 +202,8 @@ and will configure itself for reception (|LinFrameResponseMode_Rx|). // Transmit the frame header, the response will be provided by the slave. master->SendFrameHeader(0x11); -Transmission acknowledgement -____________________________ +Transmission acknowledgment +___________________________ To be notified for the success or failure of the transmission, a |FrameStatusHandler| should be registered using |AddFrameStatusHandler|:: @@ -225,7 +227,7 @@ which is indicated by |LinFrameStatus_LIN_TX_ERROR|. Receiving data from a slave ___________________________ -Beside transmission acknowledgements, the |FrameStatusHandler| is also used for reception. To receive data, the +Beside transmission acknowledgment, the |FrameStatusHandler| is also used for reception. To receive data, the |FrameStatusHandler| must be registered using |AddFrameStatusHandler|, which is called by the LIN controller when a frame is received and the LIN node is configured for reception with |LinFrameResponseMode_Rx| on that LIN ID:: @@ -251,12 +253,12 @@ see |LinFrameStatus_LIN_TX_ERROR|. Data length and checksum model ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A |LinDataLength| and |LinChecksumModel| can be provided for a given ID when configuring a reception or initiating a -transmission. A frame will arrive with |LinFrameStatus_LIN_RX_ERROR| if there is a mismatch between configured and -received data length or checksum model. However, a LIN node configured for reception might not know beforehand about the -data length or checksum model provided in the response. In this case, the reception can be configured with the -wildcards |LinDataLengthUnknown| or |LinChecksumModel_Undefined| in the respective paramters of the |LinFrame| and the -data length or checksum model provided by the sender is used in the |FrameStatusHandler|. +A |LinDataLength| and |LinChecksumModel| can be provided for a given ID when configuring a reception or initiating a transmission. +A frame will arrive with |LinFrameStatus_LIN_RX_ERROR| if there is a mismatch between configured and received data length or checksum model. +However, a LIN node configured for reception might not know beforehand about the data length or checksum model provided in the response. +In this case, the reception can be configured with the wildcards |LinDataLengthUnknown| (255) or |LinChecksumModel_Undefined| in the respective parameters of the |LinFrame|. +If the wildcards are used, the validation of the incoming data length or checksum model are skipped. +The values provided by the sender are then used in the |FrameStatusHandler|. Managing the event handlers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -329,7 +331,7 @@ This example shows a successful data transfer from a LIN master to a LIN slave. the master. .. literalinclude:: - examples/lin/Master_to_Slave_LIN_TX_OK.cpp + /code-samples/lin/Master_to_Slave_LIN_TX_OK.cpp :language: cpp Successful Transmission from slave to Master @@ -339,7 +341,7 @@ This example shows a successful data transfer from a LIN slave to a LIN master. the master. .. literalinclude:: - examples/lin/Slave_to_Master_LIN_RX_OK.cpp + /code-samples/lin/Slave_to_Master_LIN_RX_OK.cpp :language: cpp Successful Transmission from slave to slave @@ -349,38 +351,38 @@ This example shows how data is transferred from one LIN slave to another one. Th LIN master. .. literalinclude:: - examples/lin/Slave_to_Slave_LIN_TX_OK.cpp + /code-samples/lin/Slave_to_Slave_LIN_TX_OK.cpp :language: cpp Erroneous Transmission from Master to Slave - Multiple Responses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This example shows what happens when a master attempts to send a Frame while there is slave that has configured a Tx +This example shows what happens when a master attempts to send a Frame while there is slave that has configured a TX response for the same LIN ID. .. literalinclude:: - examples/lin/Master_to_Slave_LIN_TX_ERROR.cpp + /code-samples/lin/Master_to_Slave_LIN_TX_ERROR.cpp :language: cpp Erroneous Transmission from Slave to Master - No Response ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This example shows what happens when a master initiates a transmission and no slave has configured a Tx response for +This example shows what happens when a master initiates a transmission and no slave has configured a TX response for this LIN ID. .. literalinclude:: - examples/lin/Slave_to_Master_LIN_RX_NO_RESPONSE.cpp + /code-samples/lin/Slave_to_Master_LIN_RX_NO_RESPONSE.cpp :language: cpp Erroneous Transmission from Slave to Master - Multiple Responses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This example shows what happens when a master initiates a transmission where multiple slaves have configured Tx +This example shows what happens when a master initiates a transmission where multiple slaves have configured TX responses for the same LIN ID. .. literalinclude:: - examples/lin/Slave_to_Master_LIN_RX_ERROR.cpp + /code-samples/lin/Slave_to_Master_LIN_RX_ERROR.cpp :language: cpp Go To Sleep @@ -389,7 +391,7 @@ Go To Sleep This example shows how to use |GoToSleep| and when the controller will switch from operational to sleep mode. .. literalinclude:: - examples/lin/Go_To_Sleep.cpp + /code-samples/lin/Go_To_Sleep.cpp :language: cpp .. admonition:: Note @@ -405,7 +407,7 @@ This example shows how to |Wakeup| a LIN bus. The example assumes that both mast I.e., the situation corresponds to the end of the previous example. .. literalinclude:: - examples/lin/Wake_Up.cpp + /code-samples/lin/Wake_Up.cpp :language: cpp Aggregated view of responding LIN slaves (experimental) @@ -418,7 +420,7 @@ controller. The calls `AddLinSlaveConfigurationHandler`, `RemoveLinSlaveConfigur reside in the `SilKit::Experimental::Services::Lin` namespace and might be changed or removed in future versions. .. literalinclude:: - examples/lin/LinSlaveConfigurationHandler.cpp + /code-samples/lin/LinSlaveConfigurationHandler.cpp :language: cpp The experimental API is defined as follows: diff --git a/docs/api/logging.rst b/docs/api/services/logging.rst similarity index 95% rename from docs/api/logging.rst rename to docs/api/services/logging.rst index 18a8308aa..4a45e2fa6 100644 --- a/docs/api/logging.rst +++ b/docs/api/services/logging.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _chap:logging-service-api: =================== diff --git a/docs/api/pubsub.rst b/docs/api/services/pubsub.rst similarity index 98% rename from docs/api/pubsub.rst rename to docs/api/services/pubsub.rst index 228ceff9b..5ec8bf985 100644 --- a/docs/api/pubsub.rst +++ b/docs/api/services/pubsub.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. Macros for docs use .. |IParticipant| replace:: :cpp:class:`IParticipant` @@ -37,7 +39,7 @@ Publishing Data on a Publisher The |IDataPublisher| is instantiated from an |IParticipant| instance by calling the |CreateDataPublisher| method. -.. code-block:: cpp +.. code-block:: c++ SilKit::Services::PubSub::PubSubSpec pubSpec{"OilTemperature", SilKit::Util::SerDes::MediaTypeData()}; auto* publisher = participant->CreateDataPublisher("PubOilTemperature", pubSpec); @@ -45,7 +47,7 @@ The |IDataPublisher| is instantiated from an |IParticipant| instance by calling Data can be transmitted using the |Publish| method of an |IDataPublisher| instance. Published messages are transmitted immediately to all matching subscribers, that is, without any modelled latency. -.. code-block:: cpp +.. code-block:: c++ SilKit::Util::SerDes::Serializer serializer; serializer.Serialize(uint32_t{110}); @@ -58,7 +60,7 @@ Receiving Data on a Subscriber The |IDataSubscriber| is instantiated from an |IParticipant| instance by calling the |CreateDataSubscriber| method. Upon incoming data from a publisher, the handler provided to the |CreateDataSubscriber| method is called. -.. code-block:: cpp +.. code-block:: c++ auto subscriberDataHandler = [](IDataSubscriber* subscriber, const DataMessageEvent& dataMessageEvent) { SilKit::Util::SerDes::Deserializer deserializer{SilKit::Util::ToStdVector(dataMessageEvent.data)}; @@ -106,7 +108,7 @@ Example: Oil Temperature Publisher - Oil Temperature Sensor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: cpp +.. code-block:: c++ // creation of the data publisher @@ -126,7 +128,7 @@ Publisher - Oil Temperature Sensor Subscriber - Engine Dashboard ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: cpp +.. code-block:: c++ // creation of the data subscriber @@ -150,7 +152,7 @@ Example: Wheel and Control with Structure (De-)Serialization Common ~~~~~~ -.. code-block:: cpp +.. code-block:: c++ struct WheelData { @@ -161,7 +163,7 @@ Common Publisher - Wheel ~~~~~~~~~~~~~~~~~ -.. code-block:: cpp +.. code-block:: c++ // creation of the data publisher @@ -185,7 +187,7 @@ Publisher - Wheel Subscriber - Wheel Monitor ~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: cpp +.. code-block:: c++ // creation of the data subscriber @@ -238,7 +240,7 @@ In addition to the matching requirements given by topic and media type, data pub The labels are stored in the |PubSubSpec|. A |MatchingLabel| can be added via |AddLabel|, see the following code snippet: -.. code-block:: cpp +.. code-block:: c++ SilKit::Services::PubSub::PubSubSpec subDataSpec{"WheelSpeed", "application/json"}; subDataSpec.AddLabel("Instance", "FrontLeftWheel", SilKit::Services::MatchingLabel::Kind::Optional); diff --git a/docs/api/rpc.rst b/docs/api/services/rpc.rst similarity index 98% rename from docs/api/rpc.rst rename to docs/api/services/rpc.rst index dc01d4f5f..353a88368 100644 --- a/docs/api/rpc.rst +++ b/docs/api/services/rpc.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. Macros for docs use .. |IParticipant| replace:: :cpp:class:`IParticipant` @@ -48,7 +50,7 @@ Calling a Remote Procedure The |IRpcClient| is instantiated from an |IParticipant| instance by calling the |CreateRpcClient| method. -.. code-block:: cpp +.. code-block:: c++ auto rpcCallResultHandler = [] (IRpcClient*, const RpcCallResultEvent& event) { if (event.callStatus == SilKit::Services::Rpc::RpcCallStatus::Success) @@ -72,7 +74,7 @@ Otherwise the call will lead to a timeout |RpcCallResultEvent|. The |IRpcClient| receives the call result in a callback specified during creation of the |IRpcClient|, and can be overwritten with |SetCallResultHandler|. The callback provides the user context pointer passed to |Call| or |CallWithTimeout|, the return data, and a call status indicating success or an error during the procedure. -.. code-block:: cpp +.. code-block:: c++ SilKit::Util::SerDes::Serializer serializer; serializer.BeginStruct(); @@ -93,7 +95,7 @@ There, the argument data and call handle are provided and can be processed. The |IRpcServer| must submit the answer to the call at a later point in time with the call handle obtained in the |RpcCallHandler| by using the |SubmitResult| method providing the return data for the calling |IRpcClient|. -.. code-block:: cpp +.. code-block:: c++ auto rpcCallHandler = [](IRpcServer* server, const RpcCallEvent& event) { SilKit::Util::SerDes::Deserializer deserializer{SilKit::Util::ToStdVector(event.argumentData)}; @@ -129,7 +131,7 @@ The next example shows how a coordinated lifecycle can be set up to guarantee th Server - Addition ~~~~~~~~~~~~~~~~~ -.. code-block:: cpp +.. code-block:: c++ auto rpcCallHandler = [](IRpcServer* server, const RpcCallEvent& event) { SilKit::Util::SerDes::Deserializer deserializer{SilKit::Util::ToStdVector(event.argumentData)}; @@ -150,7 +152,7 @@ Server - Addition Client - Addition ~~~~~~~~~~~~~~~~~ -.. code-block:: cpp +.. code-block:: c++ auto rpcCallResultHandler = [] (IRpcClient*, const RpcCallResultEvent& event) { if (event.callStatus != SilKit::Services::Rpc::RpcCallStatus::Success) @@ -185,7 +187,7 @@ This guarantees that the RPC client and server are validly connected at the time Server - Addition ~~~~~~~~~~~~~~~~~ -.. code-block:: cpp +.. code-block:: c++ #include @@ -229,7 +231,7 @@ Server - Addition Client - Addition ~~~~~~~~~~~~~~~~~ -.. code-block:: cpp +.. code-block:: c++ #include @@ -346,7 +348,7 @@ In addition to the matching requirements given by topic and media type, RPC clie The labels are stored in the |RpcSpec|. A |MatchingLabel| can be added via |AddLabel|, see the following code snippet: -.. code-block:: cpp +.. code-block:: c++ SilKit::Services::Rpc::RpcSpec rpcSpec{"OpenMirror", "application/json"}; rpcSpec.AddLabel("Instance", "FrontLeft", SilKit::Services::MatchingLabel::Kind::Optional); diff --git a/docs/api/timeSyncService.rst b/docs/api/services/timesync.rst similarity index 97% rename from docs/api/timeSyncService.rst rename to docs/api/services/timesync.rst index 0a025f879..ce6c82637 100644 --- a/docs/api/timeSyncService.rst +++ b/docs/api/services/timesync.rst @@ -1,14 +1,14 @@ +.. include:: /substitutions.rst + .. _chap:timesync-service-api: ============================ Time Synchronization Service ============================ -.. |ProductName| replace:: SIL Kit - .. |ILifecycleService| replace:: :cpp:class:`ILifecycleService` .. |ITimeSyncService| replace:: :cpp:class:`ITimeSyncService` -.. |Participant| replace:: :doc:`Participant` +.. |Participant| replace:: :doc:`Participant` .. |SetSimulationStepHandler| replace:: :cpp:func:`SetSimulationStepHandler()` .. |SimulationStepHandler| replace:: :cpp:type:`SimulationStepHandler` diff --git a/docs/api/systemcontroller.rst b/docs/api/system-utilities/systemcontroller.rst similarity index 98% rename from docs/api/systemcontroller.rst rename to docs/api/system-utilities/systemcontroller.rst index e74bdf108..a9f7c93e4 100644 --- a/docs/api/systemcontroller.rst +++ b/docs/api/system-utilities/systemcontroller.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + ================= System Controller ================= @@ -28,7 +30,7 @@ Create a System Controller The System Controller needs a valid participant instance to be created via |CreateSystemController|. -.. code-block:: cpp +.. code-block:: c++ auto participant = SilKit::CreateParticipant(configuration, participantName, connectUri); systemController = SilKit::Experimental::Participant::CreateSystemController(participant); diff --git a/docs/api/systemmonitor.rst b/docs/api/system-utilities/systemmonitor.rst similarity index 96% rename from docs/api/systemmonitor.rst rename to docs/api/system-utilities/systemmonitor.rst index 3d175eed1..e2c0e36f6 100644 --- a/docs/api/systemmonitor.rst +++ b/docs/api/system-utilities/systemmonitor.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + ======================= System Monitor ======================= @@ -101,13 +103,13 @@ Although the participants would typically reside in different processes, their interaction is shown sequentially to demonstrate cause and effect: .. literalinclude:: - examples/sync/SystemMonitorTwoParticipants.cpp + /code-samples/sync/SystemMonitorTwoParticipants.cpp :language: cpp :lines: 1-29 This might lead to the following function call invocations at runtime: .. literalinclude:: - examples/sync/SystemMonitorTwoParticipants.cpp + /code-samples/sync/SystemMonitorTwoParticipants.cpp :language: cpp :lines: 29- diff --git a/docs/api/examples/can/CAN_Sender_Receiver.cpp b/docs/code-samples/can/CAN_Sender_Receiver.cpp similarity index 100% rename from docs/api/examples/can/CAN_Sender_Receiver.cpp rename to docs/code-samples/can/CAN_Sender_Receiver.cpp diff --git a/docs/api/examples/eth/ETH_Erroneous_Transmissions.cpp b/docs/code-samples/eth/ETH_Erroneous_Transmissions.cpp similarity index 100% rename from docs/api/examples/eth/ETH_Erroneous_Transmissions.cpp rename to docs/code-samples/eth/ETH_Erroneous_Transmissions.cpp diff --git a/docs/api/examples/eth/ETH_Sender_Receiver.cpp b/docs/code-samples/eth/ETH_Sender_Receiver.cpp similarity index 100% rename from docs/api/examples/eth/ETH_Sender_Receiver.cpp rename to docs/code-samples/eth/ETH_Sender_Receiver.cpp diff --git a/docs/api/examples/eth/ETH_State_Transitions.cpp b/docs/code-samples/eth/ETH_State_Transitions.cpp similarity index 100% rename from docs/api/examples/eth/ETH_State_Transitions.cpp rename to docs/code-samples/eth/ETH_State_Transitions.cpp diff --git a/docs/api/examples/lin/Go_To_Sleep.cpp b/docs/code-samples/lin/Go_To_Sleep.cpp similarity index 100% rename from docs/api/examples/lin/Go_To_Sleep.cpp rename to docs/code-samples/lin/Go_To_Sleep.cpp diff --git a/docs/api/examples/lin/LinSlaveConfigurationHandler.cpp b/docs/code-samples/lin/LinSlaveConfigurationHandler.cpp similarity index 100% rename from docs/api/examples/lin/LinSlaveConfigurationHandler.cpp rename to docs/code-samples/lin/LinSlaveConfigurationHandler.cpp diff --git a/docs/api/examples/lin/Master_to_Slave_LIN_TX_ERROR.cpp b/docs/code-samples/lin/Master_to_Slave_LIN_TX_ERROR.cpp similarity index 100% rename from docs/api/examples/lin/Master_to_Slave_LIN_TX_ERROR.cpp rename to docs/code-samples/lin/Master_to_Slave_LIN_TX_ERROR.cpp diff --git a/docs/api/examples/lin/Master_to_Slave_LIN_TX_OK.cpp b/docs/code-samples/lin/Master_to_Slave_LIN_TX_OK.cpp similarity index 100% rename from docs/api/examples/lin/Master_to_Slave_LIN_TX_OK.cpp rename to docs/code-samples/lin/Master_to_Slave_LIN_TX_OK.cpp diff --git a/docs/api/examples/lin/Slave_to_Master_LIN_RX_ERROR.cpp b/docs/code-samples/lin/Slave_to_Master_LIN_RX_ERROR.cpp similarity index 100% rename from docs/api/examples/lin/Slave_to_Master_LIN_RX_ERROR.cpp rename to docs/code-samples/lin/Slave_to_Master_LIN_RX_ERROR.cpp diff --git a/docs/api/examples/lin/Slave_to_Master_LIN_RX_NO_RESPONSE.cpp b/docs/code-samples/lin/Slave_to_Master_LIN_RX_NO_RESPONSE.cpp similarity index 100% rename from docs/api/examples/lin/Slave_to_Master_LIN_RX_NO_RESPONSE.cpp rename to docs/code-samples/lin/Slave_to_Master_LIN_RX_NO_RESPONSE.cpp diff --git a/docs/api/examples/lin/Slave_to_Master_LIN_RX_OK.cpp b/docs/code-samples/lin/Slave_to_Master_LIN_RX_OK.cpp similarity index 100% rename from docs/api/examples/lin/Slave_to_Master_LIN_RX_OK.cpp rename to docs/code-samples/lin/Slave_to_Master_LIN_RX_OK.cpp diff --git a/docs/api/examples/lin/Slave_to_Slave_LIN_TX_OK.cpp b/docs/code-samples/lin/Slave_to_Slave_LIN_TX_OK.cpp similarity index 100% rename from docs/api/examples/lin/Slave_to_Slave_LIN_TX_OK.cpp rename to docs/code-samples/lin/Slave_to_Slave_LIN_TX_OK.cpp diff --git a/docs/api/examples/lin/Wake_Up.cpp b/docs/code-samples/lin/Wake_Up.cpp similarity index 100% rename from docs/api/examples/lin/Wake_Up.cpp rename to docs/code-samples/lin/Wake_Up.cpp diff --git a/docs/api/examples/memory/Memory_Dos_Donts.cpp b/docs/code-samples/memory/Memory_Dos_Donts.cpp similarity index 100% rename from docs/api/examples/memory/Memory_Dos_Donts.cpp rename to docs/code-samples/memory/Memory_Dos_Donts.cpp diff --git a/docs/usage/sample_silkit/CMakeLists.txt b/docs/code-samples/simple/CMakeLists.txt similarity index 100% rename from docs/usage/sample_silkit/CMakeLists.txt rename to docs/code-samples/simple/CMakeLists.txt diff --git a/docs/usage/sample_silkit/simple.cpp b/docs/code-samples/simple/simple.cpp similarity index 100% rename from docs/usage/sample_silkit/simple.cpp rename to docs/code-samples/simple/simple.cpp diff --git a/docs/usage/sample_silkit/simple.yaml b/docs/code-samples/simple/simple.yaml similarity index 100% rename from docs/usage/sample_silkit/simple.yaml rename to docs/code-samples/simple/simple.yaml diff --git a/docs/api/examples/sync/LifecycleNoSyncSample.cpp b/docs/code-samples/sync/LifecycleNoSyncSample.cpp similarity index 100% rename from docs/api/examples/sync/LifecycleNoSyncSample.cpp rename to docs/code-samples/sync/LifecycleNoSyncSample.cpp diff --git a/docs/api/examples/sync/LifecycleWithSyncSample.cpp b/docs/code-samples/sync/LifecycleWithSyncSample.cpp similarity index 100% rename from docs/api/examples/sync/LifecycleWithSyncSample.cpp rename to docs/code-samples/sync/LifecycleWithSyncSample.cpp diff --git a/docs/api/examples/sync/SystemMonitorTwoParticipants.cpp b/docs/code-samples/sync/SystemMonitorTwoParticipants.cpp similarity index 100% rename from docs/api/examples/sync/SystemMonitorTwoParticipants.cpp rename to docs/code-samples/sync/SystemMonitorTwoParticipants.cpp diff --git a/docs/conf.py b/docs/conf.py index dfdd5c904..8adf3fa1d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -68,10 +68,10 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'overview/overview.rst'] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +#pygments_style = 'sphinx' # -- Options for HTML output ------------------------------------------------- @@ -86,6 +86,10 @@ 'using/windows': ['windowssidebar.html', 'searchbox.html'], } +html_theme_options = { + 'navigation_depth': 5 +} + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". @@ -94,3 +98,4 @@ html_css_files = [ 'custom.css' ] + diff --git a/docs/configuration/configuration.rst b/docs/configuration/configuration.rst index a2fa5036b..7c3eadde5 100644 --- a/docs/configuration/configuration.rst +++ b/docs/configuration/configuration.rst @@ -1,9 +1,9 @@ +.. include:: /substitutions.rst + ======================================== Configuration ======================================== -.. |ProductName| replace:: SIL Kit - .. _sec:sil-kit-config-yaml: The Vector |ProductName| provides optional configuration to enhance flexibility and control through use of YAML files. diff --git a/docs/configuration/experimental-configuration.rst b/docs/configuration/experimental-configuration.rst index 67d8398bb..331475577 100644 --- a/docs/configuration/experimental-configuration.rst +++ b/docs/configuration/experimental-configuration.rst @@ -1,11 +1,11 @@ +.. include:: /substitutions.rst + .. _sec:cfg-participant-experimental: =================================================== Experimental Configuration =================================================== -.. |ProductName| replace:: SIL Kit - .. contents:: :local: :depth: 3 diff --git a/docs/configuration/extension-configuration.rst b/docs/configuration/extension-configuration.rst index 4e9859a66..5f9be0846 100644 --- a/docs/configuration/extension-configuration.rst +++ b/docs/configuration/extension-configuration.rst @@ -1,11 +1,11 @@ +.. include:: /substitutions.rst + .. _sec:cfg-participant-extensions: =================================================== Extensions Configuration =================================================== -.. |ProductName| replace:: SIL Kit - .. contents:: :local: :depth: 3 diff --git a/docs/configuration/healthcheck-configuration.rst b/docs/configuration/healthcheck-configuration.rst index e613d9460..c91b73c13 100644 --- a/docs/configuration/healthcheck-configuration.rst +++ b/docs/configuration/healthcheck-configuration.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _sec:cfg-participant-healthcheck: =================================================== diff --git a/docs/configuration/includes-configuration.rst b/docs/configuration/includes-configuration.rst index 9e44c7364..182c665bc 100644 --- a/docs/configuration/includes-configuration.rst +++ b/docs/configuration/includes-configuration.rst @@ -1,11 +1,11 @@ +.. include:: /substitutions.rst + .. _sec:cfg-participant-includes: ====================== Includes Configuration ====================== -.. |ProductName| replace:: SIL Kit - .. |ParticipantConfigurationFromFile| replace:: :cpp:func:`ParticipantConfigurationFromFile()` .. |ParticipantConfigurationFromString| replace:: :cpp:func:`ParticipantConfigurationFromString()` diff --git a/docs/configuration/logging-configuration.rst b/docs/configuration/logging-configuration.rst index 4a7701fb8..0bd985840 100644 --- a/docs/configuration/logging-configuration.rst +++ b/docs/configuration/logging-configuration.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _sec:cfg-participant-logging: =================================================== diff --git a/docs/configuration/middleware-configuration.rst b/docs/configuration/middleware-configuration.rst index e062edc96..36538e6b8 100644 --- a/docs/configuration/middleware-configuration.rst +++ b/docs/configuration/middleware-configuration.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + .. _sec:cfg-participant-middleware: .. |NormalOperationNotice| replace:: It is *not* required to set this field under normal circumstances. diff --git a/docs/configuration/services-configuration.rst b/docs/configuration/services-configuration.rst index 408161b8b..4f0063790 100644 --- a/docs/configuration/services-configuration.rst +++ b/docs/configuration/services-configuration.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + =============================================================== Communication Services (CAN, LIN, FlexRay, Ethernet, Data, RPC) =============================================================== diff --git a/docs/configuration/tracing-configuration.rst b/docs/configuration/tracing-configuration.rst index 2240633a7..74354f3bd 100644 --- a/docs/configuration/tracing-configuration.rst +++ b/docs/configuration/tracing-configuration.rst @@ -1,3 +1,5 @@ +.. include:: /substitutions.rst + ================================ Tracing and Replay Configuration ================================ diff --git a/docs/contents.rst b/docs/contents.rst index c1f863cd5..d28c9ba0c 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -10,11 +10,10 @@ Contents for-developers/developers simulation/simulation api/api - usage/demos + demos/demos configuration/configuration - netsim/netsim - usage/utilities - usage/troubleshooting + utilities/utilities + troubleshooting/troubleshooting faq/faq licenses/license CHANGELOG diff --git a/docs/demos/demos.rst b/docs/demos/demos.rst new file mode 100644 index 000000000..7d39935ea --- /dev/null +++ b/docs/demos/demos.rst @@ -0,0 +1,726 @@ +.. include:: /substitutions.rst + +====================== +Demos +====================== + +.. |UtilDir| replace:: ./SilKit/bin +.. |DemoDir| replace:: ./SilKit/bin +.. |Monitor| replace:: |UtilDir|/sil-kit-monitor +.. |Registry| replace:: |UtilDir|/sil-kit-registry +.. |SystemController| replace:: |UtilDir|/sil-kit-system-controller + +.. |DemoAbstractCAN| replace:: + The `CanWriter` application sends CAN frames to the `CanReader` application including frame acknowledgment handling. +.. |DemoAbstractETH| replace:: + The `EthernetWriter` application sends Ethernet frames to the `EthernetReader` application including frame acknowledgment handling. +.. |DemoAbstractLIN| replace:: + A two-node LIN Setup with a `LinMaster` and a `LinSlave` application. + Includes a simple scheduling mechanism and demonstrates controller sleep / wakeup handling. +.. |DemoAbstractFlexRay| replace:: + A two-node FlexRay Setup with a full cluster and node parametrization. Includes POC Status handling, buffer updates and reconfiguration. + This Demo requires a separate `Network Simulator` application to simulate the details of the FlexRay cluster, which is not included in the |ProductName|. +.. |DemoAbstractPubSub| replace:: + One application publishes GPS and temperature data, another application subscribes to these topics. + Including (de-)serialization of the C++ structures into a transmittable format. +.. |DemoAbstractRPC| replace:: + The RPC server application provides two simple functions which are called by a RPC client application. + Includes (de-)serialization of the function parameters. +.. |DemoAbstractBenchmark| replace:: + This demo sets up a simulation with various command line arguments for benchmarking purposes. + A configurable amount of participants are spawned by a single process on different threads. + The demo calculates averaged running times, throughput, speed-up and message rates for performance evaluation. +.. |DemoAbstractLatency| replace:: + A sender and a receiver application use the Publish/Subscribe services and measure the round trip time of the communication. + This setup is useful to evaluate the performance of a |ProductName| setup running on different platforms. + E.g., between a local host, a virtual machine, a remote network, etc. +.. |DemoAbstractNetSim| replace:: + Demonstrates the usage of the experimental |ProductName| NetworkSimulator API. + A custom network simulation for CAN is set up, the network simulator application can be used together with the CAN demo. + + +This chapter describes the demo projects showcasing the core features of the |ProductName|. +Available demos are: + +.. list-table:: + :widths: 40 220 + :header-rows: 1 + + * - Demo + - Abstract + * - :ref:`sec:can-demo` + - |DemoAbstractCAN| + * - :ref:`sec:eth-demo` + - |DemoAbstractETH| + * - :ref:`sec:lin-demo` + - |DemoAbstractLIN| + * - :ref:`sec:flexray-demo` + - |DemoAbstractFlexRay| + * - :ref:`sec:pubsub-demo` + - |DemoAbstractPubSub| + * - :ref:`sec:rpc-demo` + - |DemoAbstractRPC| + * - :ref:`sec:benchmark-demo` + - |DemoAbstractBenchmark| + * - :ref:`sec:latency-demo` + - |DemoAbstractLatency| + * - :ref:`sec:netsim-demo` + - |DemoAbstractNetSim| + + +.. _sec:build-demos: + +Building the Demos +~~~~~~~~~~~~~~~~~~ + +The |ProductName| Demos are not available as pre-built binaries and have to be compiled from source first. + +* If you plan to use the demos as a starting point for further development, start by cloning the `SIL Kit git repository `_. + Don't forget to call ``git submodule update --init --recursive`` after cloning the repository for the first time. + Using the build instructions below will build the complete |ProductName| library including the Demos. +* If you just want to try out the demos, download a `SIL Kit release package `_ which also includes all sources. + Using the build instructions below will only build the |ProductName| Demos and use the precompiled library of the package. +* Building the Demos from the installation folder of the SIL Kit MSI Installer is strongly discouraged, as all involved tools require administrative privileges if the default installation directory is used. + +There are several options to build the demos, all require the installation of a C++ compiler and CMake. + +.. admonition:: Note + + If you don't have any experience with setting up C++ / CMake projects, we recommend using VS Code and a `SIL Kit release package `_. + VS Code is free to use, and the prerequisites can be quickly set up using the recommended VS Code extensions. + +VS Code +------- + +#. Install the VS Code extensions `C/C++` and `CMake` +#. Open the folder with VS Code + + a. For the git repository: open the root folder of the repository + b. For a |ProductName| package: open the `SilKit-Demos` folder +#. Opening the folder automatically starts the CMake configuration step. + You can also manually call this step in the CMake extension page under `Project Status | Configure`. +#. In the CMake extension page, build the project under `Project Status | Build` +#. Locate the binaries + + a. For the git repository: The binaries reside in ``_build///`` + b. For a |ProductName| package: The binaries reside in ``/SilKit/bin`` + +Visual Studio +------------- + +#. Make sure Visual Studio is set up for C++ and CMake is installed +#. Open the folder with Visual Studio + + a. For the git repository: open the root folder of the repository + b. For a |ProductName| package: open the `SilKit-Demos` folder +#. Opening the folder automatically starts the CMake configuration step. + You can also manually call this step under `Project | Configure Cache`. +#. Build the project with `Build | Build All` +#. Locate the binaries + + a. For the git repository: The binaries reside in ``_build///`` + b. For a |ProductName| package: The binaries reside in ``/SilKit/bin`` + +Command Line +------------ + +#. Make sure a C++ compiler and CMake is installed +#. Open a terminal + + a. For the git repository: navigate to the root folder of the repository + b. For a |ProductName| package: navigate to ``/SilKit-Demos`` +#. Run the following commands: + + * ``mkdir build`` + * ``cd build`` + * ``cmake ..`` + * ``cmake --build .`` +#. Locate the binaries + + a. For the git repository: The binaries reside in ``build///`` + b. For a |ProductName| package: The binaries reside in ``/SilKit/bin`` + +Due to the large variety of terminals, different operating systems and availability of environment variables, the previous instruction can fail for several reasons. +Usually, the configuration step performed in ``cmake ..`` will give useful hints of what went wrong. + +Advanced CMake configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Build the Demos from a |ProductName| package against your own target library + The distributed Demos, as packaged by CPack, are preconfigured to build against a copy of the |ProductName| binaries in ``../SilKit/``. + This can be overridden by providing your own ``SilKit`` CMake target library, before the demos are configured by CMake. + Or by changing the ``find_package(SilKit ... PATHS path/to/SilKit)`` statement directly in the ``./SilKit-Demos/CMakeLists.txt`` directory. + + +.. admonition:: Note + + In the following, the paths to run the demos are relative to the top level of the pre-built |ProductName| package. + To adapt them to run from a git repository build, you have to change the relative path to the configuration file. + E.g. use ``../../../Demos/Can/DemoCan.silkit.yaml`` instead of ``./SilKit-Demos/Can/DemoCan.silkit.yaml``. + + Further, the command line instructions use forward slashes for paths. + When using Windows (e.g. Powershell), these have to be replaced with backward slashed. + E.g., instead of ``./SilKit/bin/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanReader``, use ``.\SilKit\bin\SilKitDemoCan .\SilKit-Demos\Can\DemoCan.silkit.yaml CanReader`` + + +.. _sec:can-demo: + +CAN Demo +~~~~~~~~ + +Abstract + |DemoAbstractCAN| +Source location + ``./SilKit-Demos/Can`` +Requirements + * :ref:`sil-kit-registry` + * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) + * :ref:`sil-kit-monitor` (optional) + * SIL Kit Network Simulator (optional) +Parameters + * ```` + File name of the participant configuration to be used; + use ``DemoCan.silkit.yaml`` for an example configuration. + * ```` + The name of the participant within the simulation; must either be ``CanWriter`` or ``CanReader``. + * ``[RegistryUri]`` + The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). + * ``[--async]`` + If async flag is set, the participant will join the simulation unsynchronized and it will not need + the |SystemController| to start. +Parameter Example + .. parsed-literal:: + + # Creates a CAN Writer Process with the registry's default URI + |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanWriter + +System Example + Run the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Monitor (optional): + |Monitor| + + # CAN Reader: + |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanReader + + # CAN Writer: + |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanWriter + + # System Controller: + |SystemController| CanReader CanWriter + + To run the demo without virtual time synchronization, use the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # CAN Reader: + |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanReader --async + + # CAN Writer: + |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanWriter --async + +Notes + * The writer sends CAN frames at a fixed rate of one frame per simulation step (1ms). + * Both reader and writer sleep for 1 second per simulation step to slow down the execution. + + +.. _sec:eth-demo: + +Ethernet Demo +~~~~~~~~~~~~~ + +Abstract + |DemoAbstractETH| +Source location + ``./SilKit-Demos/Ethernet`` +Requirements + * :ref:`sil-kit-registry` + * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) + * :ref:`sil-kit-monitor` (optional) + * SIL Kit Network Simulator (optional) +Parameters + * ```` + File name of the participant configuration to be used; + use ``DemoEthernet.silkit.yaml`` for an example configuration. + * ```` + The name of the participant within the simulation; must either be ``EthernetWriter`` or + ``EthernetReader``. + * ``[RegistryUri]`` + The ``silkit://`` URI of the registry to connect to; defaults to ``silkit://localhost:8500`` (optional). + * ``[--async]`` + If async flag is set, the participant will join the simulation unsynchronized and it will not need + the |SystemController| to start. +Parameter Example + .. parsed-literal:: + + # Creates an Ethernet Writer Process with the registry's default URI: + |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetWriter +System Example + Run the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Monitor (optional): + |Monitor| + + # Ethernet Reader: + |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetReader + + # Ethernet Writer: + |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetWriter + + # System Controller: + |SystemController| EthernetReader EthernetWriter + + To run the demo without virtual time synchronization, use the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Ethernet Reader: + |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetReader --async + + # Ethernet Writer: + |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetWriter --async +Notes + * The writer sends Ethernet frames at a fixed rate of one frame per simulation step (1ms). + * Both reader and writer sleep for 1 second per simulation step to slow down execution. + + +.. _sec:lin-demo: + +LIN Demo +~~~~~~~~ + +Abstract + |DemoAbstractLIN| +Source location + ``./SilKit-Demos/Lin`` +Requirements + * :ref:`sil-kit-registry` + * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) + * :ref:`sil-kit-monitor` (optional) + * SIL Kit Network Simulator (optional) +Parameters + * ```` + File name of the participant configuration to be used; + use ``DemoLin.silkit.yaml`` for an example configuration. + * ```` + The name of the participant within the simulation; + must either be ``EthernetWriter`` or ``EthernetReader``. + * ``[RegistryUri]`` + The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). + * ``[--async]`` + If async flag is set, the participant will join the simulation unsynchronized and it will not need the |SystemController| to start. +Parameter Example + .. parsed-literal:: + + # Creates a LIN Master Process with the registry's default URI: + |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinMaster +System Example + Run the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Monitor (optional): + |Monitor| + + # LIN Master: + |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinMaster + + # LIN Slave: + |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinSlave + + # System Controller: + |SystemController| LinSlave LinMaster + + To run the demo without virtual time synchronization, use the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # LIN Master: + |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinMaster --async + + # LIN Slave: + |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinSlave --async + +Notes + * Both Master and Slave sleep for 100ms per simulation step to slow down execution. + +.. _sec:flexray-demo: + +FlexRay Demo +~~~~~~~~~~~~ + +Abstract + |DemoAbstractFlexRay| +Source location + ``./SilKit-Demos/FlexRay`` +Requirements + * :ref:`sil-kit-registry` + * :ref:`sil-kit-system-controller` + * SIL Kit Network Simulator (mandatory) + * :ref:`sil-kit-monitor` (optional) +Parameters + * ```` + File name of the participant configuration to be used; + use ``DemoFlexRay.silkit.yaml`` for an example configuration. + * ```` + The name of the participant within the simulation; must either be ``Node0`` or + ``Node1``. + * ``[RegistryUri]`` + The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). +Parameter Example + .. parsed-literal:: + + # Creates a FlexRay Process for Node 0 with the registry's default URI: + |DemoDir|/SilKitDemoFlexRay ./SilKit-Demos/FlexRay/DemoFlexRay.silkit.yaml Node0 +System Example + Run the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Network Simulator (assumed to be in PATH, necessary): + sil-kit-network-simulator ./SilKit-Demos/FlexRay/NetworkSimulatorConfig.yaml + + # Monitor (optional): + |Monitor| + + # Node 0: + |DemoDir|/SilKitDemoFlexRay ./SilKit-Demos/FlexRay/DemoFlexRay.silkit.yaml Node0 + + # Node 1: + |DemoDir|/SilKitDemoFlexRay ./SilKit-Demos/FlexRay/DemoFlexRay.silkit.yaml Node1 + + # System Controller: + |SystemController| Node0 Node1 NetworkSimulator +Notes + * Starting the FlexRay cycle takes quite some time, which is accurately modeled by the SIL Kit Network Simulator. + * It takes somewhat between 50 and 100 ms until the first FlexRay messages are transmitted. + +.. _sec:pubsub-demo: + +Publish/Subscribe Demo +~~~~~~~~~~~~~~~~~~~~~~~~ + +Abstract + |DemoAbstractPubSub| +Source location + ``./SilKit-Demos/PubSub`` +Requirements + * :ref:`sil-kit-registry` + * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) + * :ref:`sil-kit-monitor` (optional) +Parameters + * ```` + File name of the participant configuration to be used; + use ``DemoPubSub.silkit.yaml`` for an example configuration. + * ```` + The name of the participant within the simulation; must either be ``Publisher`` or + ``Subscriber``. + * ``[RegistryUri]`` + The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). + * ``[--async]`` + If async flag is set, the participant will join the simulation unsynchronized and it will not need + the |SystemController| to start. +Parameter Example + .. parsed-literal:: + + # Creates a publisher with the registry's default URI: + |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Publisher +System Example + Run the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Monitor (optional): + |Monitor| + + # Publisher: + |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Publisher + + # Subscriber: + |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Subscriber + + # System Controller: + |SystemController| Publisher Subscriber + + To run the demo without virtual time synchronization, use the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Publisher: + |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Publisher --async + + # Subscriber: + |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Subscriber --async + +Notes + * The publisher and subscriber show how to serialize/deserialize different kinds of data with the built-in :doc:`Data Serialization API`. + +.. _sec:rpc-demo: + +RPC Demo +~~~~~~~~ + +Abstract + |DemoAbstractRPC| +Source location + ``./SilKit-Demos/Rpc`` +Requirements + * :ref:`sil-kit-registry` + * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) + * :ref:`sil-kit-monitor` (optional) +Parameters + * ```` + File name of the participant configuration to be used; + use ``DemoRpc.silkit.yaml`` for an example configuration. + * ```` + The name of the participant within the simulation; must either be ``Server`` or + ``Client``. + * ``[RegistryUri]`` + The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). + * ``[--async]`` + If async flag is set, the participant will join the simulation unsynchronized and it will not need + the |SystemController| to start. +Parameter Example + .. parsed-literal:: + + # Creates an RPC server process with the registry's default URI: + |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Server +System Example + Run the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Monitor (optional): + |Monitor| + + # Server: + |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Server + + # Client: + |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Client + + # System Controller: + |SystemController| Server Client + + To run the demo without virtual time synchronization, use the following commands in separate terminals: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Server: + |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Server --async + + # Client: + |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Client --async + +Notes + * ``Client`` participant has two RPC clients which call the ``Add100`` and ``Sort`` functions on the ``Server`` participant's two RPC servers. + + +.. _sec:benchmark-demo: + +Benchmark Demo +~~~~~~~~~~~~~~ + +Abstract + |DemoAbstractBenchmark| +Source location + ``./SilKit-Demos/Benchmark`` +Requirements + None (The demo starts its own instance of the registry and system controller). +Positional Parameters + * ``[numberOfSimulationRuns]`` + Sets the number of simulation runs to perform. + * ``[simulationDuration]`` + Sets the virtual simulation duration . + * ``[numberOfParticipants]`` + Sets the number of simulation participants . + * ``[messageCount]`` + Sets the number of messages to be send in each simulation step. + * ``[messageSizeInBytes]`` + Sets the message size . + * ``[registryURi]`` + The URI of the registry to start. +Optional Parameters + * ``--help`` + Show the help message. + * ``--registry-uri`` + The URI of the registry to start. Default: silkit://localhost:8500 + * ``--message-size`` + Sets the message size in bytes. Default: 1000 + * ``--message-count`` + Sets the number of messages to be send in each simulation step. Default: 50 + * ``--number-participants`` + Sets the number of simulation participants . Default: 2 + * ``--number-simulation-runs`` + Sets the number of simulation runs to perform. Default: 4 + * ``--simulation-duration`` + Sets the simulation duration (virtual time). Default: 1s + * ``--configuration`` + Path and filename of the participant configuration YAML file. Default: empty + * ``--write-csv`` + Path and filename of CSV file with benchmark results. Default: empty +System Examples + * Launch the benchmark demo with default arguments but 3 participants: + + .. parsed-literal:: + + |DemoDir|/SilKitDemoBenchmark --number-participants 3 + * Launch the benchmark demo with positional arguments and a configuration file that enforces TCP communication: + + .. parsed-literal:: + + |DemoDir|/SilKitDemoBenchmark 4 1 2 1 10 --configuration ./SilKit-Demos/Benchmark/DemoBenchmarkDomainSocketsOff.silkit.yaml +Notes + * This benchmark demo produces timings of a configurable simulation setup. + participants exchange messages of bytes per simulation step with a fixed simulation step size of 1ms and run for seconds (virtual time). + * This simulation run is repeated times and averages over all runs are calculated. + Results for average runtime, speedup (virtual time/runtime), throughput (data size/runtime), message rate (count/runtime) including the standard deviation are printed. + * The demo uses publish/subscribe controllers with the same topic for the message exchange, so each participant broadcasts the messages to all other participants. + The configuration file ``DemoBenchmarkDomainSocketsOff.silkit.yaml`` can be used to disable domain socket usage for more realistic timings of TCP/IP traffic. With ``DemoBenchmarkTCPNagleOff.silkit.yaml``, Nagle's algorithm and domain sockets are switched off. + * The demo can be wrapped in helper scripts to run parameter scans, e.g., for performance analysis regarding different message sizes. + See ``.\SilKit-Demos\Benchmark\msg-size-scaling\Readme.md`` and ``.\SilKit-Demos\Benchmark\performance-diff\Readme.md`` for further information. + + +.. _sec:latency-demo: + +Latency Demo +~~~~~~~~~~~~ + +Abstract + |DemoAbstractLatency| +Source location + ``./SilKit-Demos/Benchmark`` +Requirements + * :ref:`sil-kit-registry` +Positional Parameters + * ``[messageCount]`` + Sets the number of messages to be send in each simulation step. + * ``[messageSizeInBytes]`` + Sets the message size. + * ``[registryURi]`` + The URI of the registry to start. +Optional Parameters + * ``--help`` + Show the help message. + * ``--isReceiver`` + This process is the receiving counterpart of the latency measurement. Default: false + * ``--registry-uri`` + The URI of the registry to start. Default: silkit://localhost:8500 + * ``--message-size`` + Sets the message size. Default: 1000 + * ``--message-count`` + Sets the number of messages to be send in each simulation step. Default: 1000 + * ``--configuration`` + Path and filename of the participant configuration YAML file. Default: empty + * ``--write-csv`` + Path and filename of csv file with benchmark results. Default: empty +System Examples + * Launch the two LatencyDemo instances with positional arguments in separate terminals: + .. parsed-literal:: + + |DemoDir|/SilKitDemoLatency 100 1000 + |DemoDir|/SilKitDemoLatency 100 1000 --isReceiver + + * Launch the LatencyDemo instances with a configuration file that enforces TCP communication: + .. parsed-literal:: + + |DemoDir|/SilKitDemoLatency 100 1000 --configuration ./SilKit-Demos/Benchmark/DemoBenchmarkDomainSocketsOff.silkit.yaml + |DemoDir|/SilKitDemoLatency 100 1000 --isReceiver +Notes + * This latency demo produces timings of a configurable simulation setup. + Two participants exchange messages of bytes without time synchronization. + * The demo uses publish/subscribe controllers performing a message round trip (ping-pong) to calculate latency and throughput timings. + * Note that the two participants must use the same parameters for valid measurement and one participant must use the ``--isReceiver`` flag. + + +.. _sec:netsim-demo: + +Network Simulator Demo +~~~~~~~~~~~~~~~~~~~~~~ + +Abstract + |DemoAbstractNetSim| +Source location + ``./SilKit-Demos/NetworkSimulator`` +Requirements + * :ref:`sil-kit-registry` + * :ref:`sil-kit-system-controller` + * :ref:`sil-kit-monitor` (optional) +Parameters + * ```` + File name of the participant configuration to be used; + use ``DemoNetSim.silkit.yaml`` for an example configuration. + * ```` + The name of the participant within the simulation. + * ``[RegistryUri]`` + The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). +Parameter Example + .. parsed-literal:: + + # Start the Network Simulator Demo with the given configuration file and participant name + |DemoDir|/SilKitDemoNetSim ./SilKit-Demos/NetworkSimulator/DemoNetSim.silkit.silkit.yaml NetworkSimulator +System Example + Interplay with the CAN Demo: + + .. parsed-literal:: + + # Registry (if not already running): + |Registry| + + # Monitor (optional): + |Monitor| + + # CAN Reader: + |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanReader + + # CAN Writer: + |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanWriter + + # System Controller: + |SystemController| CanReader CanWriter NetworkSimulator + + # Network Simulator Demo: + |DemoDir|/SilKitDemoNetSim ./SilKit-Demos/NetworkSimulator/DemoNetSim.silkit.silkit.yaml NetworkSimulator + +Notes + * The CAN Reader and Writer configure their controller on the network "CAN1", which is simulated by the network simulator demo. + * In the simple bus logic of the network simulation demo (see ``Demos\NetworkSimulator\src\Can\MySimulatedCanController.cpp``), the acknowledgment (CanFrameTransmitEvent) is sent directly to the CAN Writer. + The frame itself (CanFrameEvent) is sent with a delay of 2ms. + diff --git a/docs/faq/faq.rst b/docs/faq/faq.rst index 892e6cb87..cd2029b58 100644 --- a/docs/faq/faq.rst +++ b/docs/faq/faq.rst @@ -1,11 +1,14 @@ +.. include:: /substitutions.rst + ========================== Frequently Asked Questions ========================== .. contents:: + :local: :depth: 3 -This section provides frequently asked questions concerning SIL Kit and the corresponding answers. +This section provides frequently asked questions concerning |ProductName| and the corresponding answers. Data Generation & Transmission ============================== @@ -13,57 +16,57 @@ Data Generation & Transmission Is there a maximum payload size for Ethernet frames? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The size of the payload of Ethernet frames is not limited by SIL Kit. -Nonetheless, the maximum payload size might be constrained by the system resources available on the system on which SIL Kit is executed. +The size of the payload of Ethernet frames is not limited by |ProductName|. +Nonetheless, the maximum payload size might be constrained by the system resources available on the system on which |ProductName| is executed. Is there a maximum payload size for Publish/Subscribe or RPC data? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The size of the data payload of the Publish Subscribe and RPC service are not limited by SIL Kit. -Nonetheless, the maximum payload size might be constrained by the system resources available on the system on which SIL Kit is executed. +The size of the data payload of the Publish Subscribe and RPC service are not limited by |ProductName|. +Nonetheless, the maximum payload size might be constrained by the system resources available on the system on which |ProductName| is executed. Can I use a DBC file to generate CAN frames? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Within SIL Kit, there is no included support for DBC files. -You can use SIL Kit enabled tools that have support for DBC files, or you will need to implement DBC support within your implementation yourself. +Within |ProductName|, there is no included support for DBC files. +You can use |ProductName| enabled tools that have support for DBC files, or you will need to implement DBC support within your implementation yourself. Setup ===== -Is it possible to use statically configured ports for SIL Kit peer-to-peer communication between participants? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Is it possible to use statically configured ports for |ProductName| peer-to-peer communication between participants? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since version 4.0.16 users can specify which port the participant opens for communication between participants by using the ``AcceptorUris`` field within the :ref:`Middeware section of the participant configuration`. By doing so, a firewall can be configured to allow these static ports for communication. -The port used by the SIL Kit registry can be specified through its :ref:`CLI`. +The port used by the |ProductName| registry can be specified through its :ref:`CLI`. What is the sil-kit-registry? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The SIL Kit registry is a central utility that is necessary for running a SIL Kit simulation. +The |ProductName| registry is a central utility that is necessary for running a |ProductName| simulation. At the start, each participant connects to the registry and retrieves the connection information to all other participants. -In this sense, the registry acts as a phone book that tells the user the contact information to all other participants of a SIL Kit simulation. +In this sense, the registry acts as a phone book that tells the user the contact information to all other participants of a |ProductName| simulation. The registry does not partake in the simulation itself. It especially does not route messages between participants. -Please note that it is mandatory that all SIL Kit simulation participants can reach the SIL Kit registry for a proper simulation setup. +Please note that it is mandatory that all |ProductName| simulation participants can reach the |ProductName| registry for a proper simulation setup. -Can I use Vector SIL Kit together with real hardware/in a Hardware-in-the-Loop setup? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Can I use Vector |ProductName| together with real hardware/in a Hardware-in-the-Loop setup? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Vector SIL Kit was designed deliberately with Software-in-the-Loop environments in mind. +Vector |ProductName| was designed deliberately with Software-in-the-Loop environments in mind. Many aspects of it are designed for SIL settings (especially the virtual time synchronization, that adapts its speed to the execution speed of the participants) and not HIL settings. -These aspects might imply that SIL Kit does not fit the needs of your hardware setup. -Furthermore, SIL Kit itself does not provide capabilities to connect it to a hardware setup. +These aspects might imply that |ProductName| does not fit the needs of your hardware setup. +Furthermore, |ProductName| itself does not provide capabilities to connect it to a hardware setup. -Nonetheless, some SIL Kit enabled tools may allow you to bridge a SIL Kit simulation and a HIL setup. +Nonetheless, some |ProductName| enabled tools may allow you to bridge a |ProductName| simulation and a HIL setup. -How can I interoperate a SIL Kit simulation that is distributed between Windows and Linux clients? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How can I interoperate a |ProductName| simulation that is distributed between Windows and Linux clients? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For SIL Kit it does not matter whether all simulation participants are running on the same kind of operating system. -All SIL Kit simulation participants must be able to connect to the SIL Kit registry, and they must be able to establish a connection to all other simulation participants. -In such a distributed setting, the SIL Kit registry must be started such that it is reachable through the network by other hosts. +For |ProductName| it does not matter whether all simulation participants are running on the same kind of operating system. +All |ProductName| simulation participants must be able to connect to the |ProductName| registry, and they must be able to establish a connection to all other simulation participants. +In such a distributed setting, the |ProductName| registry must be started such that it is reachable through the network by other hosts. You might do so by running the command below: @@ -81,26 +84,26 @@ All simulation participants must now specify a URI so that they connect to this Other ===== -How is the performance/latency/throughput of the SIL Kit? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How is the performance/latency/throughput of the |ProductName|? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The specific performance (latency, throughput, animation factor, etc.) of your SIL Kit simulation depends on a set of parameters that highly depend on your use case. +The specific performance (latency, throughput, animation factor, etc.) of your |ProductName| simulation depends on a set of parameters that highly depend on your use case. The number of simulation participants, whether virtual time synchronization is used, the size of simulation steps, the size and frequency of messages being exchanged, and many other aspects highly influence the performance for you use case. Finally, the hardware being used, the network infrastructure and the distribution of simulation participants over different hosts affect the performance as well. -To get a first impression of the performance that can be expected of the SIL Kit in your use case, refer to the :ref:`Benchmark Demo` where you can specify a set of relevant parameters and get real performance measurements for your setup. +To get a first impression of the performance that can be expected of the |ProductName| in your use case, refer to the :ref:`Benchmark Demo` where you can specify a set of relevant parameters and get real performance measurements for your setup. Can I control the order in which simulation participants execute their simulation steps, in case they occur at the same time? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ No, the order simulation step execution of synchronized participants can not be controlled. -How can I configure a SIL Kit participant to write a trace log file? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How can I configure a |ProductName| participant to write a trace log file? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A trace log file can be used in debugging scenarios to get a detailed insight into the execution of a SIL Kit participant. +A trace log file can be used in debugging scenarios to get a detailed insight into the execution of a |ProductName| participant. -The :ref:`participant configuration` is a YAML file which enables you to modify some aspects of the runtime behavior of SIL Kit simulation participants. +The :ref:`participant configuration` is a YAML file which enables you to modify some aspects of the runtime behavior of |ProductName| simulation participants. In particular, you can also use it to let a participant generate a trace log file. For example, by adding the following configuration: @@ -117,43 +120,43 @@ For example, by adding the following configuration: If your participant configuration already contains a logging section, you must only add the sink. -This will tell SIL Kit to write all log messages of Level trace and above to a file in the process working directory of the SIL Kit participant. +This will tell |ProductName| to write all log messages of Level trace and above to a file in the process working directory of the |ProductName| participant. The file name will be ``TraceLogFile`` with a time-specific suffix. The ``LogName`` field also supports an absolute path, e.g., ``LogName: C:\Temp\SimulationLog``. -How can I use unicode characters with SIL Kit? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How can I use unicode characters with |ProductName|? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -SIL Kit expects strings passed via the C and C++ API to be encoded as UTF-8. +|ProductName| expects strings passed via the C and C++ API to be encoded as UTF-8. This is particularly important for paths, e.g., the path to the participant configuration. -This can lead to some confusion when SIL Kit is used on the Windows operating system. +This can lead to some confusion when |ProductName| is used on the Windows operating system. The utility executables (``sil-kit-registry``, ``sil-kit-system-controller``, and ``sil-kit-monitor``), and all demo applications are compiled using a manifest, that automatically activates the UTF-8 codepage. This allows the correct handling of paths containing Unicode characters. Even in modern Windows systems, UTF-8 is usually not used as the default codepage, in order to be compatible with old applications. -Unfortunately this can lead to strange characters in the command line output of SIL Kit tools, when, e.g., the participant name contains non-ASCII characters. +Unfortunately this can lead to strange characters in the command line output of |ProductName| tools, when, e.g., the participant name contains non-ASCII characters. As an example, when the participant name is set to ``🚗`` (car emoji), if the output codepage is not changed to UTF-8, the output might look like this: .. figure:: ../_static/faq-example-bad-output-codepage.png - :alt: : Mangled output from SIL Kit when the output codepage is not UTF-8, and the participant name contains Unicode characters + :alt: : Mangled output from |ProductName| when the output codepage is not UTF-8, and the participant name contains Unicode characters :align: center :width: 1000 - : Mangled output from SIL Kit when the output codepage is not UTF-8, and the participant name contains Unicode characters + : Mangled output from |ProductName| when the output codepage is not UTF-8, and the participant name contains Unicode characters If the output codepage is changed to UTF-8 (see below), the output should look like this: .. figure:: ../_static/faq-example-good-output-codepage.png - :alt: : Correct output from SIL Kit when the output codepage is set to UTF-8, and the participant name contains Unicode characters + :alt: : Correct output from |ProductName| when the output codepage is set to UTF-8, and the participant name contains Unicode characters :align: center :width: 1000 - : Correct output from SIL Kit when the output codepage is set to UTF-8, and the participant name contains Unicode characters + : Correct output from |ProductName| when the output codepage is set to UTF-8, and the participant name contains Unicode characters -If you use ``cmd.exe``, run the command ``chcp 65001`` before invoking any SIL Kit utilities or demos. +If you use ``cmd.exe``, run the command ``chcp 65001`` before invoking any |ProductName| utilities or demos. This command changes the output codepage of the console window to UTF-8, which is required to correctly decode the text output of the executables for presentation in the console window. -If you use PowerShell, run ``[console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding`` before invoking any SIL Kit utilities or demos to achieve the same effect. +If you use PowerShell, run ``[console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding`` before invoking any |ProductName| utilities or demos to achieve the same effect. diff --git a/docs/for-developers/developers.rst b/docs/for-developers/developers.rst index 2b0b1fa19..383eafdc1 100644 --- a/docs/for-developers/developers.rst +++ b/docs/for-developers/developers.rst @@ -1,10 +1,9 @@ +.. include:: /substitutions.rst + ============================= Developer Guide ============================= -.. |ProductName| replace:: SIL Kit - - The following sections explain, how to consume the Vector |ProductName| library in your own application and how to use the |ProductName| API to communicate with other participants of a simulation. .. contents:: @@ -53,7 +52,7 @@ From CMake this can be consumed via the ``find_package(SilKit CONFIG)`` mechanis For example, the following CMakeLists.txt imports the |ProductName| library based on its file system path. .. literalinclude:: - ../usage/sample_silkit/CMakeLists.txt + ../code-samples/simple/CMakeLists.txt :language: cmake :lines: 22-31 @@ -64,11 +63,11 @@ If you use another method to build your software you can directly use the ``SilK A simple Publish / Subscribe application ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -We'll create a simple, self-contained |ProductName| application that uses :doc:`Publish/Subscribe<../api/pubsub>` to exchange user-defined data between two participants. +We'll create a simple, self-contained |ProductName| application that uses :doc:`Publish/Subscribe` to exchange user-defined data between two participants. In our C++ file ``simple.cpp``, we include the headers and define namespaces and constants: .. literalinclude:: - ../usage/sample_silkit/simple.cpp + ../code-samples/simple/simple.cpp :language: cpp :lines: 22-31 @@ -84,7 +83,7 @@ This can be done by loading an existing :ref:`YAML file Here, we use the configuration file ``simple.yaml`` to configure a logger that logs all error messages to a file: .. literalinclude:: - ../usage/sample_silkit/simple.yaml + ../code-samples/simple/simple.yaml :language: yaml We load it in the main function of our code:: @@ -99,12 +98,12 @@ The application will run two participants concurrently, each in its own thread. One thread will act as a publisher by sending a test string to its subscribers: .. literalinclude:: - ../usage/sample_silkit/simple.cpp + ../code-samples/simple/simple.cpp :language: cpp :lines: 33-69 Initially, the simulation is joined by creating the participant called "PublisherParticipant". -This properly initializes the |ProductName| library; enables the instantiation of :doc:`Services<../api/api>` and offers access to the :doc:`Lifecycle Service<../api/lifecycleService>`, which controls the orchestration of our simulation. +This properly initializes the |ProductName| library; enables the instantiation of :doc:`Services` and offers access to the :doc:`Lifecycle Service`, which controls the orchestration of our simulation. Next, we create a :cpp:class:`publisher` for the ``DataService`` topic. Later, we subscribe to the same topic name in our subscriber to enable communication between the participants. The actual simulation is performed in the simulation task. @@ -115,7 +114,7 @@ We hand over the publisher object in the capture list of our simulation task and The subscriber runs in its own thread, too: .. literalinclude:: - ../usage/sample_silkit/simple.cpp + ../code-samples/simple/simple.cpp :language: cpp :lines: 71-102 @@ -127,7 +126,7 @@ We extend our main function to spawn both threads and join them again once finis Also, we use a try-catch block here to get proper error handling e.g., if the configuration file cannot be loaded. .. literalinclude:: - ../usage/sample_silkit/simple.cpp + ../code-samples/simple/simple.cpp :language: cpp :lines: 104-127 @@ -157,6 +156,6 @@ The final simulation setup can be run through the following commands: # Make sure that the SilKit.dll and simple.yaml are available ./SampleSilKit.exe -The complete source code of this sample can be found here: :download:`CMakeLists.txt<../usage/sample_silkit/CMakeLists.txt>` -:download:`simple.cpp<../usage/sample_silkit/simple.cpp>` :download:`simple.yaml<../usage/sample_silkit/simple.yaml>` +The complete source code of this sample can be found here: :download:`CMakeLists.txt<../code-samples/simple/CMakeLists.txt>` +:download:`simple.cpp<../code-samples/simple/simple.cpp>` :download:`simple.yaml<../code-samples/simple/simple.yaml>` diff --git a/docs/for-users/users.rst b/docs/for-users/users.rst index b73f46cbc..7c8a2dd87 100644 --- a/docs/for-users/users.rst +++ b/docs/for-users/users.rst @@ -1,14 +1,9 @@ +.. include:: /substitutions.rst + ============================== User Guide ============================== -.. - macros for internal use -.. - General macros -.. |ProductName| replace:: SIL Kit -.. - The following section explains how to bring together Vector |ProductName| enabled applications and how to successfully run a simulation. .. contents:: @@ -64,7 +59,7 @@ The following steps are required to set up a simulation and run it: 2. Start the |ProductName| enabled application(s) with the desired arguments. Participants without a lifecycle and autonomous participants will start directly. For example, the applications to start in :numref:`Figure %s ` are both `SilKitDemoCan`` with their respective participant name `CanWriter` and `CanReader` as arguments. - See :doc:`demo applications<../usage/demos>` for informatio of how to build and start the sample applications. + See :doc:`demo applications<../demos/demos>` for informatio of how to build and start the sample applications. If you have access to the registry's log, you should see log entries stating that the participant(s) connected. 3. Depending of the needs of your SIL Kit simulation, it may be necessary to start the :ref:`System Controller Utility` (see :ref:`Configuring the Lifecycle Service` for more information). Once all required simulation participants have joined the simulation, the coordinated participants within the simulation will start. @@ -72,7 +67,7 @@ The following steps are required to set up a simulation and run it: .. admonition:: Note - If you encounter any problems during the initial setup (e.g., you started the registry and the participants but nothing happens), refer to :doc:`Troubleshooting<../usage/troubleshooting>`. + If you encounter any problems during the initial setup (e.g., you started the registry and the participants but nothing happens), refer to :doc:`Troubleshooting<../troubleshooting/troubleshooting>`. .. _sec:users-participants: diff --git a/docs/index.rst b/docs/index.rst index 8623befdc..71d6044c9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1 +1 @@ -.. include:: overview/overview.inc \ No newline at end of file +.. include:: overview/overview.rst \ No newline at end of file diff --git a/docs/licenses/license.rst b/docs/licenses/license.rst index 7d5359a88..a922105a4 100644 --- a/docs/licenses/license.rst +++ b/docs/licenses/license.rst @@ -1,13 +1,15 @@ -.. Self-defined html directives: - -.. role:: raw-html(raw) - :format: html +.. include:: /substitutions.rst -=============== -SIL Kit License -=============== +======== +Licenses +======== -The SIL Kit itself is licensed with minimal restrictions (referred to as *MIT License*): +|ProductName| License +--------------------- + +The |ProductName| itself is licensed with minimal restrictions (referred to as *MIT License*): + +.. code-block:: text Copyright (c) 2022 Vector Informatik GmbH @@ -30,372 +32,367 @@ The SIL Kit itself is licensed with minimal restrictions (referred to as *MIT Li OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -==================== Third-Party Licenses -==================== +-------------------- -The SIL Kit uses third party software components. The full and -unmodified license of each component is printed below. +The |ProductName| uses third party software components. +The full and unmodified license of each component is printed below. -.. contents:: :local: - :depth: 3 +.. contents:: + :local: + :depth: 1 -\1. Google Test: ----------------- +Google Test +~~~~~~~~~~~ -Copyright 2008, Google Inc. -All rights reserved. +.. code-block:: text -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: + Copyright 2008, Google Inc. + All rights reserved. -\* Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: -\* Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following disclaimer + in the documentation and/or other materials provided with the + distribution. -\* Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. + * Neither the name of Google Inc. nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -| -| +Yaml-cpp +~~~~~~~~ -\2. Yaml-cpp: -------------- +.. code-block:: text -Copyright (c) 2008-2015 Jesse Beder. + Copyright (c) 2008-2015 Jesse Beder. + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. +Asio C++ Library +~~~~~~~~~~~~~~~~ -| -| +.. code-block:: text -\3. Asio C++ Library --------------------- + Boost Software License - Version 1.0 - August 17th, 2003 + + Permission is hereby granted, free of charge, to any person or organization + obtaining a copy of the software and accompanying documentation covered by + this license (the "Software") to use, reproduce, display, distribute, + execute, and transmit the Software, and to prepare derivative works of the + Software, and to permit third-parties to whom the Software is furnished to + do so, all subject to the following: + + The copyright notices in the Software and this entire statement, including + the above license grant, this restriction and the following disclaimer, + must be included in all copies of the Software, in whole or in part, and + all derivative works of the Software, unless such copies or derivative + works are solely in the form of machine-executable object code generated by + a source language processor. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT + SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE + FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, + ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + +Spdlog +~~~~~~ + +.. code-block:: text -Boost Software License - Version 1.0 - August 17th, 2003 + The MIT License (MIT) -Permission is hereby granted, free of charge, to any person or organization -obtaining a copy of the software and accompanying documentation covered by -this license (the "Software") to use, reproduce, display, distribute, -execute, and transmit the Software, and to prepare derivative works of the -Software, and to permit third-parties to whom the Software is furnished to -do so, all subject to the following: - -The copyright notices in the Software and this entire statement, including -the above license grant, this restriction and the following disclaimer, -must be included in all copies of the Software, in whole or in part, and -all derivative works of the Software, unless such copies or derivative -works are solely in the form of machine-executable object code generated by -a source language processor. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT -SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE -FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE. - -| -| - -\4. Spdlog ----------------------- - -The MIT License (MIT) - -Copyright (c) 2016 Gabi Melman. - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - -| -| - -\5. Fmtlib ----------------------- - -Copyright (c) 2012 - 2016, Victor Zverovich - -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -| -| - -\6. Oat++ ----------------------- - -Apache License -Version 2.0, January 2004 -http://www.apache.org/licenses/ - -TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - -1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. + Copyright (c) 2016 Gabi Melman. + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + +Fmtlib +~~~~~~ + +.. code-block:: text + + Copyright (c) 2012 - 2016, Victor Zverovich + + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + + 1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR + ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Oat++ +~~~~~ + +.. code-block:: text + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - -2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - -3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - -4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - -5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - -6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - -7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - -8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - -9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - -END OF TERMS AND CONDITIONS - -APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - -Copyright [yyyy] [name of copyright owner] - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - -| -| + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + diff --git a/docs/overview/overview.inc b/docs/overview/overview.rst similarity index 94% rename from docs/overview/overview.inc rename to docs/overview/overview.rst index 990f08630..545cdfa00 100644 --- a/docs/overview/overview.inc +++ b/docs/overview/overview.rst @@ -1,9 +1,9 @@ -======================= +.. include:: substitutions.rst + +======================= Vector SIL Kit Overview ======================= -.. |ProductName| replace:: SIL Kit -.. |NetSim| replace:: Network Simulator .. |_| unicode:: 0xA0 :trim: .. |CAN-API| replace:: :ref:`CAN / CAN FD` @@ -34,13 +34,14 @@ It provides: Supported Services ------------------ -The services currently supported by the |ProductName| consist of the following categories: +The |ProductName| supports the following services: * **Vehicle Network Controllers:** |CAN-API|, |Ethernet-API|, |Flexray-API|, and |LIN-API| * **Data Publish/Subscribe:** topic-based :ref:`publish/subscribe` mechanism to exchange arbitrary data * **RPC Servers/Clients:** for dynamic :ref:`remote procedure execution` * **Orchestration:** for |Lifecycle-API| and |Timesync-API| control * **Logging:** for |Logging-API| messages into a file, standard output, or to other participants +* **Custom Network Simulator:** takes control over the message flow to simulate network details Vehicle Networks ---------------- @@ -79,11 +80,6 @@ A similar configuration file is available for the |ProductName| Registry as well * For getting started operating/orchestrating a |ProductName| simulation, see the :doc:`User Guide <../for-users/users>`. * For getting started developing with the |ProductName|, see the :doc:`Developer Guide <../for-developers/developers>`. - -.. - TODO add links to the corresponding sections once they are revamped - - .. _sec:overview-ecosystem: The |ProductName| Ecosystem @@ -149,8 +145,8 @@ Terminology - A participant is a communication node in the distributed simulation that provides access to the |ProductName| services. * - :ref:`Services` - Participants interact with each other through the means of services. - These can be communication services, e.g., a :doc:`CAN Controller<../api/can>` and orchestration services, such as the the Lifecycle Service, Time Synchronization Service, and the Logging Service. - * - :doc:`Configuration` + These can be communication services, e.g., a :doc:`CAN Controller` and orchestration services, such as the the Lifecycle Service, Time Synchronization Service, and the Logging Service. + * - :doc:`Configuration<../configuration/configuration>` - The optional participant configuration file allows easy configuration of a participant and its interconnection within the simulation. It can be used to change a participant's behavior without recompiling its sources. * - Registry @@ -159,7 +155,7 @@ Terminology * - Registry URI - The registry's URI specifies where the registry can be reached. It defaults to ``silkit://localhost:8500``, that is, the registry is reachable via TCP/IP on the 'localhost' on port 8500. - * - :doc:`Middleware` + * - :doc:`Middleware<../configuration/middleware-configuration>` - The concrete distributed communication implementation. That is, the software layer implementing the distributed message passing mechanism. * - Network Connection @@ -184,7 +180,7 @@ Further Reading --------------- More real-world examples involving time synchronization and simulated automotive networks, can be found in the :doc:`API sections<../api/api>`. -Also, studying the source code of the bundled :doc:`demo applications<../usage/demos>` is a good start. +Also, studying the source code of the bundled :doc:`demo applications<../demos/demos>` is a good start. The simulation lifecycle and supported simulation time synchronization are discussed in :doc:`../simulation/simulation`. Additionally, :doc:`../configuration/configuration` describes how the participant configuration file can be used to change the behavior of participants. diff --git a/docs/simulation/simulation.rst b/docs/simulation/simulation.rst index 9577c14ef..067bcdd45 100644 --- a/docs/simulation/simulation.rst +++ b/docs/simulation/simulation.rst @@ -1,12 +1,9 @@ +.. include:: /substitutions.rst + +=================== +Simulation Concepts +=================== -========== -Simulation -========== -.. - macros for internal use -.. - General macros -.. |ProductName| replace:: SIL Kit .. API references .. |ILifecycleService| replace:: :cpp:class:`ILifecycleService` @@ -142,7 +139,7 @@ System Controller The |ISystemController| interface allows users to set system-wide simulation parameters, such as which participants are required for a simulation, as well as signal commands that are processed by all participants with a -lifecycle (see :doc:`System Controller<../api/systemcontroller>` for details). +lifecycle (see :doc:`System Controller` for details). .. admonition:: Note diff --git a/docs/substitutions.rst b/docs/substitutions.rst new file mode 100644 index 000000000..f73cd613a --- /dev/null +++ b/docs/substitutions.rst @@ -0,0 +1,3 @@ +.. |ProductName| replace:: SIL Kit +.. |NetSim| replace:: Network Simulator + diff --git a/docs/troubleshooting/connection-guides.rst b/docs/troubleshooting/connection-guides.rst new file mode 100644 index 000000000..e7782780a --- /dev/null +++ b/docs/troubleshooting/connection-guides.rst @@ -0,0 +1,53 @@ +.. include:: /substitutions.rst + +Connection Guides +================= + +This chapter provides instructions for specific connection scenarios between various host. + +.. contents:: + :local: + :depth: 2 + + +Windows and WSL +~~~~~~~~~~~~~~~ + +Registry running in WSL ++++++++++++++++++++++++ + +#. If needed, get the precompiled registry from a Ubuntu build of the |ProductName| at https://github.com/vectorgrp/sil-kit/releases. +#. On WSL, use ``ip addr show eth0`` and note down the IP address displayed at ``inet``, e.g., ``172.19.71.101``. + You WSL network should be reachable under this IP address. +#. Start the registry on the WSL side with this IP address and a port:: + + ./sil-kit-registry --listen-uri silkit://172.19.71.101:8500 + +#. On Windows, launch a |ProductName| participant with the same connect URI. + For testing purposes, the SIL Kit Monitor utility can be used:: + + .\sil-kit-monitor.exe --connect-uri silkit://172.19.71.101:8500 + +#. The registry should report the successful connection with a log output like:: + + [SilKitRegistry] [info] Sending known participant message to SystemMonitor, protocol version 3.1 + +Registry running in Windows ++++++++++++++++++++++++++++ + +This setup is possible but requires either + +- network mirroring mode for WSL (available for WSL2) or +- reconfiguration of the WSL and Windows network adapters and possible adaption of firewall settings. + +However, the configuration is error-prone and out of scope for this documentation. +The more convenient setup is to run the registry in the WSL instance, as described in the previous section. + +.. TODO + Windows and Linux VM + Windows and Docker + Linux and Docker + Windows and OpenSSH-Server + + + diff --git a/docs/troubleshooting/connectivity.rst b/docs/troubleshooting/connectivity.rst new file mode 100644 index 000000000..794a32415 --- /dev/null +++ b/docs/troubleshooting/connectivity.rst @@ -0,0 +1,106 @@ +.. include:: /substitutions.rst + +Connectivity +============ + +Connectivity Issues with the |ProductName| Registry +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A |ProductName| simulation needs a running :ref:`sec:util-registry` to establish the connection between the participants. +All participants and the registry must use a common URI to establish the connection. +For the participants, this is called the `connect URI`, for the registry process, this is called the `listen URI`. +The participant logs the following messages if it can't connect to the registry: + +.. code-block:: console + + [yyyy-mm-dd hh:mm:ss] [CanWriter] [error] Failed to connect to SIL Kit Registry (number of attempts: 1) + [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] Make sure that the SIL Kit Registry is up and running and is listening on the following URIs: silkit://localhost:8500, local://.silkit. + [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] If a registry is unable to open a listening socket it will only be reachable via local domain sockets, which depend on the working directory and the middleware configuration ('enableDomainSockets'). + [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] Make sure that the hostname can be resolved and is reachable. + [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] You can configure the SIL Kit Registry hostname and port via the SilKitConfig. + [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] The SIL Kit Registry executable can be found in your SIL Kit installation folder: + [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] INSTALL_DIR/bin/sil-kit-registry[.exe] + Something went wrong: ERROR: Failed to connect to SIL Kit Registry + +Step-by-step Solution +--------------------- + +#. Find out the connect URI the participant is using + This can be found in + + * The :cpp:func:`CreateParticipant()` call + * The ``RegistryUri`` provided in the Participant Configuration file. + This takes precedence over the previously mentioned API call. + * The log message ``Make sure that the SIL Kit Registry is up and running and is listening on the following URIs: `` + +#. Double check if the registry process is running and listens on the correct connect URI + + a. If you have started the registry yourself, check if the provided ``--listen-uri`` is correct. + The registry can also use a configuration file which specify the listen URI. + The configuration file takes precedence over the previously mentioned command line argument. + b. If you have used the |ProductName| MSI installer, check if the Windows service `VectorSilKitRegistry` is running. + +#. Check if ``localhost`` in the connect URI makes sense + + By default, a |ProductName| registry will bind to ``silkit://localhost:8500``. + Out of the box, 'localhost' cannot be resolved between virtualized networks (e.g., Windows connecting to VM, WSL, Docker). + In this case, you have to bind the |ProductName| registry to a publicly reachable URI, such as ``silkit://0.0.0.0:8501``. + Please note that this opens a public listening port and may not be suitable for your work environment. + Consult your system administrator when in doubt. + +#. Check if the connection between the network of the participant and the registry is possible + + Often, issues within your network will lead to this error message. + Test if your host running the |ProductName| participant is able to establish a TCP connection to the registry. + + .. code-block:: powershell + + # Use your IP (here 172.19.71.101) and port (here 8501) of the registry + Test-NetConnection -ComputerName 172.19.71.101 -Port 8501 + + If Telnet does not print that it established a connection, you are having networking issues. + + .. code-block:: powershell + + Trying ... + Connected to . + Escape character is '^]'. + + In this case your network configuration prevents a connection to the registry. + Refer to your network administrator for further assistance. + Some potential issues might be firewalls, VM network configuration (if using a VM), NATs, Docker network configuration (if using Docker). + + .. admonition:: Note + + Telnet can be terminated with the key combination Ctrl+C. + + +Using the Registry as a Proxy for Participant-to-Participant Connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: powershell + + [yyyy-mm-dd hh:mm:ss.sss] [EthernetReader] [info] Connected to registry at 'tcp://127.0.0.1:8501' via 'tcp://127.0.0.1:63107' (silkit://127.0.0.1:8501) + [yyyy-mm-dd hh:mm:ss.sss] [EthernetReader] [warning] VAsioConnection: Failed to connect directly to EthernetWriter, trying to proxy messages through the registry: Failed to connect to host URIs: "tcp://127.0.0.1:37117," + +When a |ProductName| participant joins a simulation, it first connects to the |ProductName| registry (:ref:`sec:util-registry`), which informs the participant about all other participants, that have already joined the simulation. +The participant then tries to connect to all the other participants. + +If another participant cannot be connected to directly, as a last resort, it tries to use the registry as a proxy for participant-to-participant communication. +The warning is issued, since sending the participant-to-participant messages via the registry will add latency and overhead. + +A |ProductName| participant will only attempt to use the registry as a proxy if the remote participant, that could not be connected to directly, supports receiving messages via the registry. + +Connectivity issues between participants +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: powershell + + [yyyy-mm-dd hh:mm:ss] [CanReader] [info] Connected to registry at 'tcp://192.168.1.12:8500' via 'tcp://192.168.1.12:8500' (silkit://192.168.1.12:8500) + [yyyy-mm-dd hh:mm:ss] [CanReader] [error] Timeout during connection setup. The participant was able to connect to the registry, but not to all participants. + There might be network issues. Check network settings and firewall configuration. Was not able to connect to the following participant(s): + CanWriter(local://D:\TEMP\\CanWriterd81c9d2684952765.silkit, tcp://192.168.1.12:52125) + +When a |ProductName| participant joins a simulation, it first connects to the |ProductName| registry (:ref:`sec:util-registry`), to be informed of the other simulation participants and how they can be reached. +This error message is shown if this second step of a simulation setup fails. It occurs when the peer to peer connection between the observed participant and one or more other participants was not possible. +Usually, this problem occurs when a network configuration does not allow for said connections. Check your network setup and firewall configuration. diff --git a/docs/usage/interoperability.rst b/docs/troubleshooting/interoperability.rst similarity index 88% rename from docs/usage/interoperability.rst rename to docs/troubleshooting/interoperability.rst index d7afc4b9e..73c5d9284 100644 --- a/docs/usage/interoperability.rst +++ b/docs/troubleshooting/interoperability.rst @@ -1,20 +1,17 @@ +.. include:: /substitutions.rst Interoperability ================ -.. contents:: - :local: - :depth: 1 - -SIL Kit provides interoperability between participants and utilities from different released versions of SIL Kit. -This section documents known issues and potentially misleading messages reported by SIL Kit participants in certain cases. +|ProductName| provides interoperability between participants and utilities from different released versions of |ProductName|. +This section documents known issues and potentially misleading messages reported by |ProductName| participants in certain cases. Duplicate Participant Names ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Multiple participants with the same name connect to a single registry instance. -The SIL Kit Registry with version 4.0.7 or lower just drops the connection in this case. +The |ProductName| Registry with version 4.0.7 or lower just drops the connection in this case. The participant is not informed and eventually times out. Scenario A diff --git a/docs/usage/lifecycle.rst b/docs/troubleshooting/lifecycle.rst similarity index 91% rename from docs/usage/lifecycle.rst rename to docs/troubleshooting/lifecycle.rst index e0461ca2c..e96b607b7 100644 --- a/docs/usage/lifecycle.rst +++ b/docs/troubleshooting/lifecycle.rst @@ -1,12 +1,9 @@ +.. include:: /substitutions.rst Lifecycle ========= -.. contents:: - :local: - :depth: 1 - -SIL Kit provides a lifecycle service and time synchronization service, that allow to coordinate simulation execution between participants. +|ProductName| provides a lifecycle service and time synchronization service, that allow to coordinate simulation execution between participants. Coordinated required participants ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -16,7 +13,7 @@ Coordinated required participants This participant is in OperationMode::Coordinated, but is not among the participants that are reported to the system controller as "required". If participants of a SIL Kit simulation want to start the simulation together as soon as all necessary participants have joined the simulation, -these SIL Kit participants specify that their lifecycle service is operated in coordinated mode. +these |ProductName| participants specify that their lifecycle service is operated in coordinated mode. When executing such a SIL Kit Simulation, it is important to tell the SIL Kit simulation which participants are considered necessary for the coordinated start. You do this by calling ``sil-kit-system-controller`` with a whitespace separated list of diff --git a/docs/troubleshooting/troubleshooting.rst b/docs/troubleshooting/troubleshooting.rst new file mode 100644 index 000000000..bf349be67 --- /dev/null +++ b/docs/troubleshooting/troubleshooting.rst @@ -0,0 +1,40 @@ +.. include:: /substitutions.rst + +================ +Troubleshooting +================ + +This section provides in-depth troubleshooting information about common problems of |ProductName| simulations. +Most issues can be identified based on log messages by the application. + +.. admonition:: Note + + To troubleshoot any problem involving the |ProductName|, activate the built-in :ref:`logging` on all involved applications. + It is recommended to write the participant log to a file with the most detailed log level ``Trace``: + + .. code-block:: yaml + + Logging: + Sinks: + - Type: File + Level: Trace + LogName: ParticipantLog + +.. + .. contents:: + :local: + :depth: 2 + +.. toctree:: + :maxdepth: 2 + + connectivity.rst + lifecycle.rst + interoperability.rst + connection-guides.rst + +.. + .. include:: connectivity.rst + .. include:: lifecycle.rst + .. include:: interoperability.rst + .. include:: connection-guides.rst diff --git a/docs/usage/connectivity.rst b/docs/usage/connectivity.rst deleted file mode 100644 index e560c3229..000000000 --- a/docs/usage/connectivity.rst +++ /dev/null @@ -1,99 +0,0 @@ -Connectivity -============ - -.. contents:: - :local: - :depth: 1 - -SIL Kit provides interoperability between participants and utilities from different released versions of SIL Kit. -This section documents known issues and potentially misleading messages reported by SIL Kit participants in certain cases. - -Connectivity Issues with Registry -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: console - :caption: Example error message - - [yyyy-mm-dd hh:mm:ss] [CanWriter] [error] Failed to connect to SIL Kit Registry (number of attempts: 1) - [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] Make sure that the SIL Kit Registry is up and running and is listening on the following URIs: silkit://localhost:8500, local://.silkit. - [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] If a registry is unable to open a listening socket it will only be reachable via local domain sockets, which depend on the working directory and the middleware configuration ('enableDomainSockets'). - [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] Make sure that the hostname can be resolved and is reachable. - [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] You can configure the SIL Kit Registry hostname and port via the SilKitConfig. - [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] The SIL Kit Registry executable can be found in your SIL Kit installation folder: - [yyyy-mm-dd hh:mm:ss] [CanWriter] [info] INSTALL_DIR/bin/sil-kit-registry[.exe] - Something went wrong: ERROR: Failed to connect to SIL Kit Registry - -This error message is based on the fact, that your SIL Kit simulation participant was not able to connect to the :ref:`sec:util-registry` with the specified registry URI. -A SIL Kit simulation needs a running :ref:`sec:util-registry` that will tell new simulation participants where to find other participants. -For connecting to a simulation, a SIL Kit participant will use the registry URI specified in its -:cpp:func:`CreateParticipant()` call or if specified, the ``RegistryUri`` provided in the Participant Configuration file. -To find out where your participant is trying to connect to, refer to the printed error message. In this case, it is looked up by hostname `localhost` and TCP port `8500`, with a value of `silkit://localhost:8500` in the log output. - -The registry not being reachable for a participant might have two reasons: There is no registry running under the specified URI, -or the registry is not reachable for this specific participant because of networking issues. - -.. admonition:: Note - - By default, a SIL Kit registry will bind to ``silkit://localhost:8500``. If you want to reach a registry from somewhere where this 'localhost' is not reachable (VM, WSL, Docker), - you have to bind the SIL Kit registry to a publicly reachable URI, such as ``silkit://0.0.0.0:8501``. Make sure that the chosen port is not conflicting to the one of another SIL Kit registry instance. - Please note that this opens a public listening port and may not be suitable for your work environment. - Consult your system administrator when in doubt. - -When starting a registry, you can provide a `--listen-uri` under which the registry will be reachable. -Make sure that a :ref:`sec:util-registry` is running and that it binds to the address and port specified for your connecting participant. - -Often, issues within your network will lead to this error message. To verify, that you are not having networking issues, you can verify that -your host running the SIL Kit participant is able to establish a TCP connection to the registry. One way of doing so, is to use the Telnet utility: - -.. code-block:: powershell - - # Use your IP (here 192.168.1.12) and port (here 8500) of the registry - telnet 192.168.1.12 8500 - -If Telnet does not print that it established a connection, you are having networking issues. - -.. code-block:: powershell - - Trying ... - Connected to . - Escape character is '^]'. - -In this case your network configuration prevents a connection to the registry. -Refer to your network administrator for further assistance. -Some potential issues might be firewalls, VM network configuration (if using a VM), NATs, Docker network configuration (if using Docker). - -.. admonition:: Note - - Telnet can be terminated with the key combination Ctrl+C. - -Using the Registry as a Proxy for Participant-to-Participant Connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: powershell - :caption: Example warning - - [yyyy-mm-dd hh:mm:ss.sss] [EthernetReader] [info] Connected to registry at 'tcp://127.0.0.1:8501' via 'tcp://127.0.0.1:63107' (silkit://127.0.0.1:8501) - [yyyy-mm-dd hh:mm:ss.sss] [EthernetReader] [warning] VAsioConnection: Failed to connect directly to EthernetWriter, trying to proxy messages through the registry: Failed to connect to host URIs: "tcp://127.0.0.1:37117," - -When a SIL Kit participant joins a simulation, it first connects to the SIL Kit registry (:ref:`sec:util-registry`), which informs the participant about all other participants, that have already joined the simulation. -The participant then tries to connect to all the other participants. - -If another participant cannot be connected to directly, as a last resort, it tries to use the registry as a proxy for participant-to-participant communication. -The warning is issued, since sending the participant-to-participant messages via the registry will add latency and overhead. - -A SIL Kit participant will only attempt to use the registry as a proxy if the remote participant, that could not be connected to directly, supports receiving messages via the registry. - -Connectivity issues between participants -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: powershell - :caption: Example error message - - [yyyy-mm-dd hh:mm:ss] [CanReader] [info] Connected to registry at 'tcp://192.168.1.12:8500' via 'tcp://192.168.1.12:8500' (silkit://192.168.1.12:8500) - [yyyy-mm-dd hh:mm:ss] [CanReader] [error] Timeout during connection setup. The participant was able to connect to the registry, but not to all participants. - There might be network issues. Check network settings and firewall configuration. Was not able to connect to the following participant(s): - CanWriter(local://D:\TEMP\\CanWriterd81c9d2684952765.silkit, tcp://192.168.1.12:52125) - -When a SIL Kit participant joins a simulation, it first connects to the SIL Kit registry (:ref:`sec:util-registry`), to be informed of the other simulation participants and how they can be reached. -This error message is shown if this second step of a simulation setup fails. It occurs when the peer to peer connection between the observed participant and one or more other participants was not possible. -Usually, this problem occurs when a network configuration does not allow for said connections. Check your network setup and firewall configuration. diff --git a/docs/usage/demos.rst b/docs/usage/demos.rst deleted file mode 100644 index 07b6e688e..000000000 --- a/docs/usage/demos.rst +++ /dev/null @@ -1,632 +0,0 @@ -====================== -Demos -====================== - -This document describes the usage of the demo projects that are -included with the Vector SIL Kit project and what their -expected output and or results are. All demo source code is located in -the Git repository in the folder Demos. - -.. |UtilDir| replace:: ./SilKit/bin -.. |DemoDir| replace:: ./SilKit/bin -.. |Monitor| replace:: |UtilDir|/sil-kit-monitor -.. |Registry| replace:: |UtilDir|/sil-kit-registry -.. |SystemController| replace:: |UtilDir|/sil-kit-system-controller - -.. admonition:: Note - - All paths on this page are relative to the top level of - the pre-built Vector SIL Kit packages. - - -To build the demos, please refer to :ref:`sec:build-demos`. - - -.. _sec:build-demos: - -Building the Demos -~~~~~~~~~~~~~~~~~~ - -This descriptions refers to the package structures as provided within the `pre-built Vector SIL Kit releases `_. -It is not directly applicable for building the demos from source. - -For building the demos, cmake has to be installed on your system and a corresponding cpp compiler has to be available. - -Building the demos from a pre-built Vector SIL Kit is straight forward, -just run the following commands from within the "SilKit-Demos" directory:: - - mkdir build - cd build - cmake .. - cmake --build . - -The individual demos are then built into ./SilKit/bin in the root directory of the package. - -.. admonition:: Note - - The distributed Demos, as packaged by CPack, are preconfigured to build against - a copy of the SIL Kit binaries in ``../SilKit/``. - This can be overridden by providing your own ``SilKit`` CMake target library, - before the demos are configured by CMake. - Or by changing the ``find_package(SilKit ... PATHS path/to/SilKit)`` statement directly - in the ``./SilKit-Demos/CMakeLists.txt`` directory. - - -.. _sec:util-can-demo: - -CAN Demo -~~~~~~~~ - -.. list-table:: - :widths: 17 205 - :stub-columns: 1 - - * - Abstract - - CAN Reader/Writer with or without network simulator - * - Source location - - ./SilKit-Demos/Can - * - Requirements - - * :ref:`sil-kit-registry` - * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) - * :ref:`sil-kit-monitor` (optional) - * SIL Kit Network Simulator (optional) - * - Parameters - - - File name of the participant configuration to be used; - use ``DemoCan.silkit.yaml`` for an example configuration. - - The name of the participant within the simulation; must either be ``CanWriter`` or - ``CanReader``. - [RegistryUri] - The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). - [\-\-async] - If async flag is set, the participant will join the simulation unsynchronized and it will not need - the |SystemController| to start. - * - Parameter Example - - .. parsed-literal:: - - # Creates a CAN Writer Process with the registry's default URI - |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanWriter - * - System Example - - For synchronized execution: - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Monitor (optional): - |Monitor| - - # CAN Reader: - |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanReader - - # CAN Writer: - |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanWriter - - # System Controller: - |SystemController| CanReader CanWriter - - For unsynchronized execution: - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # CAN Reader: - |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanReader --async - - # CAN Writer: - |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanWriter --async - - * - Notes - - | \- The writer sends CAN frames at a fixed rate of one frame per simulation step (1ms). - | \- Both reader and writer sleep for 1 second per quantum to slow down execution. - -Ethernet Demo -~~~~~~~~~~~~~ - -.. list-table:: - :widths: 17 220 - :stub-columns: 1 - - * - Abstract - - Ethernet Reader / Writer with or without network simulator - * - Source location - - ./SilKit-Demos/Ethernet - * - Requirements - - * :ref:`sil-kit-registry` - * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) - * :ref:`sil-kit-monitor` (optional) - * SIL Kit Network Simulator (optional) - * - Parameters - - - File name of the participant configuration to be used; - use ``DemoEthernet.silkit.yaml`` for an example configuration. - - The name of the participant within the simulation; must either be ``EthernetWriter`` or - ``EthernetReader``. - [RegistryUri] - The ``silkit://`` URI of the registry to connect to; defaults to ``silkit://localhost:8500`` (optional). - [\-\-async] - If async flag is set, the participant will join the simulation unsynchronized and it will not need - the |SystemController| to start. - * - Parameter Example - - .. parsed-literal:: - - # Creates an Ethernet Writer Process with the registry's default URI: - |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetWriter - * - System Example - - For synchronized execution: - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Monitor (optional): - |Monitor| - - # Ethernet Reader: - |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetReader - - # Ethernet Writer: - |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetWriter - - # System Controller: - |SystemController| EthernetReader EthernetWriter - - For unsynchronized execution: - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Ethernet Reader: - |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetReader --async - - # Ethernet Writer: - |DemoDir|/SilKitDemoEthernet ./SilKit-Demos/Ethernet/DemoEthernet.silkit.yaml EthernetWriter --async - - * - Notes - - | \- The writer sends Ethernet frames at a fixed rate of one frame per simulation step (1ms). - | \- Both reader and writer sleep for 1 second per simulation step to slow down execution. - - -LIN Demo -~~~~~~~~ - -.. list-table:: - :widths: 17 220 - :stub-columns: 1 - - * - Abstract - - LIN Master and Slave demo. The master sends and requests messages from a LIN slave. - * - Source location - - ./SilKit-Demos/Lin - * - Requirements - - * :ref:`sil-kit-registry` - * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) - * :ref:`sil-kit-monitor` (optional) - * SIL Kit Network Simulator (optional) - * - Parameters - - - File name of the participant configuration to be used; - use ``DemoLin.silkit.yaml`` for an example configuration. - - The name of the participant within the simulation; must either be ``EthernetWriter`` or - ``EthernetReader``. - [RegistryUri] - The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). - [\-\-async] - If async flag is set, the participant will join the simulation unsynchronized and it will not need - the |SystemController| to start. - * - Parameter Example - - .. parsed-literal:: - - # Creates a LIN Master Process with the registry's default URI: - |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinMaster - * - System Example - - For synchronized execution: - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Monitor (optional): - |Monitor| - - # LIN Master: - |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinMaster - - # LIN Slave: - |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinSlave - - # System Controller: - |SystemController| LinSlave LinMaster - - For unsynchronized execution: - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # LIN Master: - |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinMaster --async - - # LIN Slave: - |DemoDir|/SilKitDemoLin ./SilKit-Demos/Lin/DemoLin.silkit.yaml LinSlave --async - - * - Notes - - | Both Master and Slave sleep for a hort duration per simulation step to slow down execution. - - -FlexRay Demo -~~~~~~~~~~~~ - -.. list-table:: - :widths: 17 220 - :stub-columns: 1 - - * - Abstract - - FlexRay Demo for a FlexRay cluster containing two nodes - * - Source location - - ./SilKit-Demos/FlexRay - * - Requirements - - * :ref:`sil-kit-registry` - * :ref:`sil-kit-system-controller` - * SIL Kit Network Simulator (mandatory) - * :ref:`sil-kit-monitor` (optional) - * - Parameters - - - File name of the participant configuration to be used; - use ``DemoFlexRay.silkit.yaml`` for an example configuration. - - The name of the participant within the simulation; must either be ``Node0`` or - ``Node1``. - [RegistryUri] - The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). - - * - Parameter Example - - .. parsed-literal:: - - # Creates a FlexRay Process for Node 0 with the registry's default URI: - |DemoDir|/SilKitDemoFlexRay ./SilKit-Demos/FlexRay/DemoFlexRay.silkit.yaml Node0 - * - System Example - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Network Simulator (assumed to be in PATH, necessary): - sil-kit-network-simulator ./SilKit-Demos/FlexRay/NetworkSimulatorConfig.yaml - - # Monitor (optional): - |Monitor| - - # Node 0: - |DemoDir|/SilKitDemoFlexRay ./SilKit-Demos/FlexRay/DemoFlexRay.silkit.yaml Node0 - - # Node 1: - |DemoDir|/SilKitDemoFlexRay ./SilKit-Demos/FlexRay/DemoFlexRay.silkit.yaml Node1 - - # System Controller: - |SystemController| Node0 Node1 NetworkSimulator - * - Notes - - Starting the FlexRay cycle takes quite some time, which is accurately modeled by the SIL Kit Network Simulator. - It takes somewhat between 50 and 100 ms until the first FlexRay messages are transmitted. - - -.. _sec:util-pubsub-demo: - -Publish/Subscribe Demo -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 17 220 - :stub-columns: 1 - - * - Abstract - - Data Message Publish/Subscribe Demo for a set of Publishers/Subscribers - * - Source location - - ./SilKit-Demos/PubSub - * - Requirements - - * :ref:`sil-kit-registry` - * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) - * :ref:`sil-kit-monitor` (optional) - * - Parameters - - - File name of the participant configuration to be used; - use ``DemoPubSub.silkit.yaml`` for an example configuration. - - The name of the participant within the simulation; must either be ``Publisher`` or - ``Subscriber``. - [RegistryUri] - The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). - [\-\-async] - If async flag is set, the participant will join the simulation unsynchronized and it will not need - the |SystemController| to start. - - * - Parameter Example - - .. parsed-literal:: - - # Creates a publisher with the registry's default URI: - |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Publisher - * - System Example - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Monitor (optional): - |Monitor| - - # Publisher: - |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Publisher - - # Subscriber: - |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Subscriber - - # System Controller: - |SystemController| Publisher Subscriber - - For unsynchronized execution: - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Publisher: - |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Publisher --async - - # Subscriber: - |DemoDir|/SilKitDemoPubSub ./SilKit-Demos/PubSub/DemoPubSub.silkit.yaml Subscriber --async - - * - Notes - - The publisher and subscriber show how to serialize/deserialize different kinds of data with the built-in :doc:`Data Serialization API`. - -RPC Demo -~~~~~~~~~~~~~~~~~~~~ - - -.. list-table:: - :widths: 17 220 - :stub-columns: 1 - - * - Abstract - - Remote Procedure Call Demo. The client triggers remote procedure calls on the server. - * - Source location - - ./SilKit-Demos/Rpc - * - Requirements - - * :ref:`sil-kit-registry` - * :ref:`sil-kit-system-controller` (not needed for unsynchronized execution) - * :ref:`sil-kit-monitor` (optional) - * - Parameters - - - File name of the participant configuration to be used; - use ``DemoRpc.silkit.yaml`` for an example configuration. - - The name of the participant within the simulation; must either be ``Server`` or - ``Client``. - [RegistryUri] - The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). - [\-\-async] - If async flag is set, the participant will join the simulation unsynchronized and it will not need - the |SystemController| to start. - - * - Parameter Example - - .. parsed-literal:: - - # Creates an RPC server process with the registry's default URI: - |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Server - * - System Example - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Monitor (optional): - |Monitor| - - # Server: - |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Server - - # Client: - |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Client - - # System Controller: - |SystemController| Server Client - - For unsynchronized execution: - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Server: - |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Server --async - - # Client: - |DemoDir|/SilKitDemoRpc ./SilKit-Demos/Rpc/DemoRpc.silkit.yaml Client --async - - * - Notes - - ``Client`` participant has two RPC clients which call the ``Add100`` and ``Sort`` functions on the ``Server`` participant's two RPC servers. - -.. _sec:util-benchmark-demo: - -Benchmark Demo -~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 17 220 - :stub-columns: 1 - - * - Abstract - - Benchmark Demo. Used for evaluating SIL Kit performance of publish/subscribe communication. - * - Source location - - ./SilKit-Demos/Benchmark - * - Requirements - - None (The demo starts its own instance of the registry and system controller). - * - Positional parameters - - [numberOfSimulationRuns] - Sets the number of simulation runs to perform. - [simulationDuration] - Sets the virtual simulation duration . - [numberOfParticipants] - Sets the number of simulation participants . - [messageCount] - Sets the number of messages to be send in each simulation step. - [messageSizeInBytes] - Sets the message size . - [registryURi] - The URI of the registry to start. - * - Optional parameters - - --help - Show the help message. - --registry-uri - The URI of the registry to start. Default: silkit://localhost:8500 - --message-size - Sets the message size in bytes. Default: 1000 - --message-count - Sets the number of messages to be send in each simulation step. Default: 50 - --number-participants - Sets the number of simulation participants . Default: 2 - --number-simulation-runs - Sets the number of simulation runs to perform. Default: 4 - --simulation-duration - Sets the simulation duration (virtual time). Default: 1s - --configuration - Path and filename of the participant configuration YAML file. Default: empty - --write-csv - Path and filename of CSV file with benchmark results. Default: empty - * - Parameter Example - - .. parsed-literal:: - # Launch the benchmark demo with default arguments but 3 participants and a non default registry URI to avoid collisions: - |DemoDir|/SilKitDemoBenchmark --number-participants 3 --registry-uri silkit://localhost:8501 - - # Launch the benchmark demo with positional arguments, a specified configuration file: - |DemoDir|/SilKitDemoBenchmark 4 1 2 1 10 --configuration ./SilKit-Demos/Benchmark/DemoBenchmarkDomainSocketsOff.silkit.yaml - - * - Notes - - | This benchmark demo produces timings of a configurable simulation setup. participants exchange of bytes per simulation step with a fixed simulation step size of 1ms and run for seconds (virtual time). - | - | This simulation run is repeated times and averages over all runs are calculated. Results for average runtime, speedup (virtual time/runtime), throughput (data size/runtime), message rate (count/runtime) including the standard deviation are printed. - | - | The demo uses publish/subscribe controllers with the same topic for the message exchange, so each participant broadcasts the messages to all other participants. The configuration file ``DemoBenchmarkDomainSocketsOff.silkit.yaml`` can be used to disable domain socket usage for more realistic timings of TCP/IP traffic. With ``DemoBenchmarkTCPNagleOff.silkit.yaml``, Nagle's algorithm and domain sockets are switched off. - | - | The demo can be wrapped in helper scripts to run parameter scans, e.g., for performance analysis regarding different message sizes. See ``.\SilKit-Demos\Benchmark\msg-size-scaling\Readme.md`` and ``.\SilKit-Demos\Benchmark\performance-diff\Readme.md`` for further information. - - -Latency Demo -~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 17 220 - :stub-columns: 1 - - * - Abstract - - Latency Demo. Used for evaluating SIL Kit performance of publish/subscribe communication. - * - Source location - - ./SilKit-Demos/Benchmark - * - Requirements - - * :ref:`sil-kit-registry` - * - Positional parameters - - [messageCount] - Sets the number of messages to be send in each simulation step. - [messageSizeInBytes] - Sets the message size. - [registryURi] - The URI of the registry to start. - * - Optional parameters - - --help - Show the help message. - --isReceiver - This process is the receiving counterpart of the latency measurement. Default: false - --registry-uri - The URI of the registry to start. Default: silkit://localhost:8500 - --message-size - Sets the message size. Default: 1000 - --message-count - Sets the number of messages to be send in each simulation step. Default: 1000 - --configuration - Path and filename of the participant configuration YAML file. Default: empty - --write-csv - Path and filename of csv file with benchmark results. Default: empty - * - Parameter Example - - .. parsed-literal:: - # Launch the two LatencyDemo instances with positional arguments and a specified configuration file: - |DemoDir|/SilKitDemoLatency 100 1000 - |DemoDir|/SilKitDemoLatency 100 1000 --isReceiver - - # Launch the LatencyDemo with positional arguments and a specified configuration file: - |DemoDir|/SilKitDemoLatency 100 1000 --configuration ./SilKit-Demos/Benchmark/DemoBenchmarkDomainSocketsOff.silkit.yaml - * - Notes - - | This latency demo produces timings of a configurable simulation setup. Two participants exchange messages of bytes without time synchronization. - | - | The demo uses publish/subscribe controllers performing a message roundtrip (ping-pong) to calculate latency and throughput timings. - | - | Note that the two participants must use the same parameters for valid measurement and one participant must use the ``--isReceiver`` flag. - - -.. _sec:util-netsim-demo: - -Network Simulator Demo -~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 17 205 - :stub-columns: 1 - - * - Abstract - - Demo usage of the Network Simulation API - * - Source location - - ./SilKit-Demos/NetworkSimulator - * - Requirements - - * :ref:`sil-kit-registry` - * :ref:`sil-kit-system-controller` - * :ref:`sil-kit-monitor` (optional) - * - Parameters - - - File name of the participant configuration to be used; - use ``DemoNetSim.silkit.yaml`` for an example configuration. - - The name of the participant within the simulation. - [RegistryUri] - The silkit:// URI of the registry to connect to; defaults to silkit://localhost:8500 (optional). - * - Parameter Example - - .. parsed-literal:: - - # Start the Network Simulator Demo with the given config and participant name - |DemoDir|/SilKitDemoNetSim ./SilKit-Demos/NetworkSimulator/DemoNetSim.silkit.silkit.yaml NetworkSimulator - * - System Example - - Interplay with CAN Demo: - - .. parsed-literal:: - - # Registry (if not already running): - |Registry| - - # Monitor (optional): - |Monitor| - - # CAN Reader: - |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanReader - - # CAN Writer: - |DemoDir|/SilKitDemoCan ./SilKit-Demos/Can/DemoCan.silkit.yaml CanWriter - - # System Controller: - |SystemController| CanReader CanWriter NetworkSimulator - - # Network Simulator Demo: - |DemoDir|/SilKitDemoNetSim ./SilKit-Demos/NetworkSimulator/DemoNetSim.silkit.silkit.yaml NetworkSimulator - - * - Notes - - * The CAN Reader and Writer configure their controller on the network "CAN1", which is simulated by the network simulator demo. - * In the simple bus logic of the network simulation demo (see ``Demos\NetworkSimulator\src\Can\MySimulatedCanController.cpp``), the acknowledgement (CanFrameTransmitEvent) is sent directly to the CAN Writer. The frame itself (CanFrameEvent) is sent with a delay of 2ms. \ No newline at end of file diff --git a/docs/usage/troubleshooting.rst b/docs/usage/troubleshooting.rst deleted file mode 100644 index ea8b611e0..000000000 --- a/docs/usage/troubleshooting.rst +++ /dev/null @@ -1,13 +0,0 @@ -================ -Troubleshooting -================ - -.. contents:: - :depth: 3 - -This section provides troubleshooting information and answers to frequently asked questions about performing -SIL Kit simulations. - -.. include:: connectivity.rst -.. include:: lifecycle.rst -.. include:: interoperability.rst diff --git a/docs/usage/utilities.rst b/docs/usage/utilities.rst deleted file mode 100644 index f53bede5e..000000000 --- a/docs/usage/utilities.rst +++ /dev/null @@ -1,133 +0,0 @@ -============== -Utilities -============== - -.. contents:: - :local: - :depth: 1 - -Running a Vector SIL Kit system is supported by several utilities. -The Registry is a mandatory part of the SIL Kit integrated middleware -- it is needed to establish the connections between simulation participants at the start of a simulation. -The Monitor and System Controller are provided for convenience. They implement -a simulation-wide state tracking and system command handling which is required -in every simulation. However, using these utilities is not mandatory -- users -of the SIL Kit are free to implement their own system and state handling. - -.. _sec:util-registry: - -sil-kit-registry -~~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 17 205 - :stub-columns: 1 - - * - Abstract - - The ``sil-kit-registry`` enables discovery between SIL Kit participants. It is needed for Vector SIL Kit simulations. - - * - Source location - - ``Utilities/SilKitRegistry`` - * - Requirements - - None - * - Parameters - - -v, --version Get version info. - -h, --help Show the help of the SIL Kit Registry. - -u, --listen-uri The ``silkit://`` URI the registry should listen on. Defaults to ``silkit://localhost:8500``. - -g, --generate-configuration Generate a configuration file which includes the URI the registry listens on. - -d, --dashboard-uri The ``http://`` URI of the SIL Kit Dashboard to which data is sent. - -l, --log Log to stdout with level ``off``, ``critical``, ``error``, ``warn``, ``info``, ``debug``, or ``trace``. Defaults to ``info``. - -c, --registry-configuration The configuration read from this file overrides the values specified on the command line. - -s, --use-signal-handler Terminate when an OS signal is received. **Deprecated:** Since v4.0.53, this is the default behavior. - - * - Usage Example - - .. code-block:: powershell - - # Start the SIL Kit Registry - sil-kit-registry - * - Notes - - * The SIL Kit Registry is packaged in the ``SilKit/bin`` directory. - * The SIL Kit Registry must be started before other SIL Kit participants, - either with this process or using the :cpp:func:`StartListening()` API. - * When the port ``0`` is specified in the URI (``--listen-uri``) the operating system will choose a random port for the registry. - This port is used in the generated configuration file (``--generate-configuration``) for use in CI environments. - * When the file specified by ``--generate-configuration`` was created by the registry, it is guaranteed that the registry process - has completed initialization and is ready to accept incoming connections of SIL Kit participants. - * The registry will run if either binding to the TCP socket, or the Domain socket, or both succeeds. - If only TCP or Domain sockets are used, because one of the bindings failed for some reason, a warning will be logged. - It will exit with an error if neither is available. - * The SIL Kit Dashboard is experimental and might be changed or removed in future versions of the SIL Kit. - - -.. _sec:util-system-controller: - -sil-kit-system-controller -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 17 205 - :stub-columns: 1 - - * - Abstract - - The ``sil-kit-system-controller`` defines which participants are required for a simulation. - Coordinated participants will wait until all required participants joined a simulation before they progress their state. - * - Source location - - ``Utilities/SilKitSystemController`` - * - Requirements - - The ``sil-kit-system-controller`` needs a running ``sil-kit-registry`` to connect to. - Furthermore, it requires a list of synchronized participants that are needed to start the simulation as input. - * - Parameters - - -v, --version Get version info. - -h, --help Show the help of the SIL Kit System Controller. - -u, --connect-uri The registry URI to connect to. Defaults to ``silkit://localhost:8500``. - -n, --name The participant name used to take part in the simulation. Defaults to ``SystemController``. - -c, --configuration Path to the Participant configuration YAML or JSON file. Note that the format was changed in v3.6.11. Cannot be used together with the ``--log`` option. - -l, --log Log to stdout with level ``trace``, ``debug``, ``warn``, ``info``, ``error``, ``critical`` or ``off``. Defaults to ``info`` if the ``--configuration`` option is not specified. Cannot be used together with the ``--configuration`` option. - -ni, --non-interactive Never prompt the user. *Deprecated:* Since v4.0.53, this is the default behavior. - - | **, ...** - | Names of participants to wait for before starting simulation. - - * - Usage Example - - .. code-block:: powershell - - # Start the SIL Kit System Controller and wait for 'Participant1' and 'Participant2': - sil-kit-system-controller Participant1 Participant2 - * - Notes - - * The distribution package contains the ``sil-kit-system-controller`` in the - ``SilKit/bin/`` directory. - - -.. _sec:util-monitor: - -sil-kit-monitor -~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 17 205 - :stub-columns: 1 - - * - Abstract - - The ``sil-kit-monitor`` visualizes the states of the participants of a - SIL Kit simulation. - * - Source location - - ``Utilities/SilKitMonitor`` - * - Requirements - - Requires a running ``sil-kit-registry`` to connect to. - * - Parameters - - -v, --version Get version info. - -h, --help Show the help of the SIL Kit Monitor. - -u, --connect-uri The registry URI to connect to. Defaults to ``silkit://localhost:8500``. - -n, --name The participant name used to take part in the simulation. Defaults to ``SystemMonitor``. - -c, --configuration Path to the Participant configuration YAML or JSON file. - -a, --autonomous Run with an autonomous lifecycle. - -r, --coordinated Run with a coordinated lifecycle. - -s, --sync Run with virtual time synchronization. - - * - Usage Example - - .. code-block:: powershell - - # Start the SIL Kit Monitor - sil-kit-monitor - * - Notes - - * The distribution package contains the ``sil-kit-monitor`` in the ``SilKit/bin/`` directory. - * The ``sil-kit-monitor`` represents a passive participant in a SIL Kit system. It can therefore be (re)started at any time. diff --git a/docs/utilities/utilities.rst b/docs/utilities/utilities.rst new file mode 100644 index 000000000..50b9f81a4 --- /dev/null +++ b/docs/utilities/utilities.rst @@ -0,0 +1,148 @@ +.. include:: /substitutions.rst + +============== +Utilities +============== + +.. contents:: + :local: + :depth: 1 + +Running a Vector |ProductName| system is supported by several utilities. +The **Registry** is a mandatory part of the |ProductName| integrated middleware. +It is needed to establish the connections between simulation participants at the start of a simulation. +The **System Controller** implements a simulation-wide state handling. +It allows to provide the participant names that are required for the simulation to start via command-line arguments. +The **Monitor** is provided for convenience. +It implements a simulation-wide state tracking and prints this information to the console. +The System Controller and the Monitor serve as reference implementations for their respective usage scenarios. +Users are free to implement their own versions of these utilities. + +.. _sec:util-registry: + +sil-kit-registry +~~~~~~~~~~~~~~~~ + +Abstract + The ``sil-kit-registry`` enables discovery between |ProductName| participants. + It is needed for Vector |ProductName| simulations. +Source location + ``Utilities/SilKitRegistry`` +Requirements + None +Parameters + * ``-v, --version`` + Get version info. + * ``-h, --help`` + Show the help of the |ProductName| Registry. + * ``-u, --listen-uri `` + The ``silkit://`` URI the registry should listen on. Defaults to ``silkit://localhost:8500``. + * ``-g, --generate-configuration `` + Generate a configuration file which includes the URI the registry listens on. + * ``-d, --dashboard-uri `` + The ``http://`` URI of the |ProductName| Dashboard to which data is sent. + * ``-l, --log `` + Log to stdout with level ``off``, ``critical``, ``error``, ``warn``, ``info``, ``debug``, or ``trace``. Defaults to ``info``. + * ``-c, --registry-configuration `` + The configuration read from this file overrides the values specified on the command line. + * ``-s, --use-signal-handler`` + Terminate when an OS signal is received. **Deprecated:** Since v4.0.53, this is the default behavior. +Usage Example + .. code-block:: powershell + + # Start the SIL Kit Registry + sil-kit-registry +Notes + * The |ProductName| Registry is packaged in the ``SilKit/bin`` directory. + * The |ProductName| Registry must be started before other |ProductName| participants, + either with this process or using the :cpp:func:`StartListening()` API. + * When the port ``0`` is specified in the URI (``--listen-uri``) the operating system will choose a random port for the registry. + This port is used in the generated configuration file (``--generate-configuration``) for use in CI environments. + * When the file specified by ``--generate-configuration`` was created by the registry, it is guaranteed that the registry process + has completed initialization and is ready to accept incoming connections of |ProductName| participants. + * The registry will run if either binding to the TCP socket, or the Domain socket, or both succeeds. + If only TCP or Domain sockets are used, because one of the bindings failed for some reason, a warning will be logged. + It will exit with an error if neither is available. + * The |ProductName| Dashboard is experimental and might be changed or removed in future versions of the |ProductName|. + +.. _sec:util-system-controller: + +sil-kit-system-controller +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Abstract + The ``sil-kit-system-controller`` defines which participants are required for a simulation. + Coordinated participants will wait until all required participants joined a simulation before they progress their state. + Autonomous participants progress their state without any dependencies to other participants. +Source location + ``Utilities/SilKitSystemController`` +Requirements + The ``sil-kit-system-controller`` needs a running ``sil-kit-registry`` to connect to. + Furthermore, it requires a list of participant names that are needed to start the simulation as input. +Parameters + * ``-v, --version`` + Get version info. + * ``-h, --help`` + Show the help of the |ProductName| System Controller. + * ``-u, --connect-uri `` + The registry URI to connect to. Defaults to ``silkit://localhost:8500``. + * ``-n, --name `` + The participant name used to take part in the simulation. Defaults to ``SystemController``. + * ``-c, --configuration `` + Path to the Participant configuration YAML or JSON file. + Note that the format was changed in v3.6.11. + Cannot be used together with the ``--log`` option. + * ``-l, --log `` + Log to stdout with level ``trace``, ``debug``, ``warn``, ``info``, ``error``, ``critical`` or ``off``. + Defaults to ``info`` if the ``--configuration`` option is not specified. + Cannot be used together with the ``--configuration`` option. + * ``-ni, --non-interactive`` + Never prompt the user. *Deprecated:* Since v4.0.53, this is the default behavior. + * ``, ...`` + Names of participants to wait for before starting the simulation. +Usage Example + .. code-block:: powershell + + # Start the SIL Kit System Controller and wait for 'Participant1' and 'Participant2': + sil-kit-system-controller Participant1 Participant2 +Notes + * The distribution package contains the ``sil-kit-system-controller`` in the ``SilKit/bin/`` directory. + +.. _sec:util-monitor: + +sil-kit-monitor +~~~~~~~~~~~~~~~ + +Abstract + The ``sil-kit-monitor`` visualizes the states of the participants of a |ProductName| simulation. +Source location + ``Utilities/SilKitMonitor`` +Requirements + Requires a running ``sil-kit-registry`` to connect to. +Parameters + * ``-v, --version`` + Get version info. + * ``-h, --help`` + Show the help of the |ProductName| Monitor. + * ``-u, --connect-uri `` + The registry URI to connect to. Defaults to ``silkit://localhost:8500``. + * ``-n, --name `` + The participant name used to take part in the simulation. Defaults to ``SystemMonitor``. + * ``-c, --configuration `` + Path to the Participant configuration YAML or JSON file. + * ``-a, --autonomous`` + Run with an autonomous lifecycle. + * ``-r, --coordinated`` + Run with a coordinated lifecycle. + * ``-s, --sync`` + Run with virtual time synchronization. +Usage Example + .. code-block:: powershell + + # Start the SIL Kit Monitor + sil-kit-monitor +Notes + * The distribution package contains the ``sil-kit-monitor`` in the ``SilKit/bin/`` directory. + * The ``sil-kit-monitor`` represents a passive participant in a |ProductName| system. + It can therefore be (re)started at any time. +