Skip to content

Document CAN message size handling #288

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
KonradBreitsprecherBkd wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document CAN message size handling #288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 22 additions & 13 deletions docs/api/services/can.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,12 @@ CAN controllers will only communicate within the same network.
Sending CAN Frames
~~~~~~~~~~~~~~~~~~

Data is transferred in the form of a |CanFrame| and received as a |CanFrameEvent|. To send a |CanFrame|, it must be setup
with a CAN ID and the data to be transmitted. Furthermore, valid |CanFrameFlag| have to be set::
Data is transferred in the form of a |CanFrame| and received as a |CanFrameEvent|.
To send a |CanFrame|, it must be set up with a CAN ID and the data to be transmitted.
Furthermore, valid |CanFrameFlag| must be set.
The |CanFrame| struct allows any payload size via its dataField member, messages that exceed CAN/CAN FD limits are
passed through unchanged.
The following snippet shows how to send a CAN FD frame::

// Prepare a CAN message with id 0x17
CanFrame canFrame;
Expand All @@ -91,14 +95,14 @@ To be notified of the success or failure of the transmission, a ``FrameTransmitH
};
canController->AddFrameTransmitHandler(frameTransmitHandler);

An optional second parameter of |AddFrameTransmitHandler| allows to specify the status (|Transmitted|, ...) of the
An optional second parameter of |AddFrameTransmitHandler| allows specifying the status (|Transmitted|, ...) of the
|CanFrameTransmitEvent| to be received. By default, each status is enabled.

.. admonition:: Note

In a simple simulation without the network simulator, the |CanTransmitStatus| of the |CanFrameTransmitEvent| will
always be |Transmitted|. If a detailed simulation is used, it is possible that the transmit queue overflows
causing the handler to be called with |TransmitQueueFull| signaling a transmission failure.
which causes the handler to be called with |TransmitQueueFull|, signaling a transmission failure.

Receiving CAN Frame Events
~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -112,8 +116,9 @@ frame, a timestamp and the actual |CanFrame|. The handler is called whenever a |
};
canController->AddFrameHandler(frameHandler);

An optional second parameter of |AddFrameHandler| allows to specify the direction (TX, RX, TX/RX) of the CAN frames to be
received. By default, only frames of RX direction are handled.
An optional second parameter of |AddFrameHandler| allows specifying the direction (TX, RX, TX/RX) of the CAN frames to
be received.
By default, only frames of RX direction are handled.

Receiving State Change Events
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -137,16 +142,18 @@ Then, the controller must be started explicitly by calling |Start|. Now the cont
Additional control commands are |Stop| and |Reset|.

The following example configures a CAN controller with a baud rate of 10'000 baud for regular CAN messages and a baud
rate of 1'000'000 baud for CAN |_| FD messages and 1'000'000 baud for CAN |_| XL, respectively. Then, the controller is started::
rate of 1'000'000 baud for CAN |_| FD messages and 1'000'000 baud for CAN |_| XL, respectively. Then, the controller
is started::

canController->SetBaudRate(10000, 1000000, 1000000);
canController->Start();

.. admonition:: Note

Both |SetBaudRate| and |Start| should not be called earlier than in the lifecycle service's
:cpp:func:`communication ready handler<SilKit::Core::synd::ILifecycleService::SetCommunicationReadyHandler()>`. Otherwise, it is not guaranteed
that all participants are already connected, which can cause the call to have no effect.
Both |SetBaudRate| and |Start| should be called in the lifecycle service's
:cpp:func:`communication ready handler<SilKit::Core::synd::ILifecycleService::SetCommunicationReadyHandler()>`.
Otherwise, it is not guaranteed that all participants are already connected, which can cause the call to have no
effect.

Managing the Event Handlers
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -189,9 +196,11 @@ Enumerations and Typedefs
Usage Examples
--------------

This section contains complete examples that show the usage of the CAN controller and the interaction of two or more
controllers. Although the CAN controllers would typically belong to different participants and reside in different
processes, their interaction is shown sequentially to demonstrate cause and effect.
This section contains complete examples that demonstrate the usage of the CAN controller and the interaction between
two or more controllers.

Although the CAN controllers would typically belong to different participants and reside in different
processes, their interaction is shown sequentially here to demonstrate cause and effect.

Assumptions:

Expand Down
26 changes: 16 additions & 10 deletions docs/overview/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ It provides:

* Implemented in C++ w/o platform dependencies

* Interoperability between Windows, Linux, and other UNIX derivates​
* Interoperability between Windows, Linux, and other UNIX derivatives​

* Stable API and ABI as well as long-term network layer compatibility

Expand All @@ -50,14 +50,20 @@ Vehicle Networks
The |ProductName| provides means to simulate |CANBuses|, Ethernet, FlexRay, and LIN networks.
All networks except for FlexRay can be simulated with two different levels of detail: a simple, functional simulation or a detailed simulation.
The simple simulation assumes no delay and unlimited bandwidth.

The detailed simulation is enabled by using an additional |ProductName| |NetSim|, which considers these aspects as well.
The |NetSim| is not part of |ProductName| itself.
Because of its sensitivity regarding time, FlexRay is only supported in a detailed simulation.

Vehicle networks are accessed through their corresponding services (e.g., a CAN controller).
The service interfaces are the same for simple and detailed simulation.
As a result, an application that works in the simple use case also works when switching to a detailed simulation using the |NetSim|.
The section :ref:`sec:api-services` describes how to configure and use vehicle network services in detail.

In general, |ProductName| deliberately avoids imposing restrictions on bus protocols.
This enables user applications to freely determine the desired level of detail for vehicle network simulations.
For example, a test participant can inject faulty frames without being blocked by |ProductName|.

The section :ref:`sec:api-services` describes how to configure and use the vehicle network services in detail.

Simulation Basics
-----------------
Expand All @@ -78,8 +84,8 @@ Furthermore, |ProductName| participants can use a virtual simulation time that i
While participants are first configured in the |ProductName| API by the developer, they can be reconfigured by the user by providing a YAML-based participant configuration file when starting the participant.
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>`.
* To get started operating/orchestrating a |ProductName| simulation, see the :doc:`User Guide <../for-users/users>`.
* To get started developing with the |ProductName|, see the :doc:`Developer Guide <../for-developers/developers>`.

.. _sec:overview-ecosystem:

Expand All @@ -104,10 +110,10 @@ The |ProductName| ecosystem comprises the following turn-key solutions:
can be used to attach a virtual CAN (Controller Area Network) interface (SocketCAN) to a Vector SIL Kit CAN bus.

* The `SIL Kit Adapter for Generic Linux IO <https://github.com/vectorgrp/sil-kit-adapters-generic-linux-io>`_
allows to attach SIL Kit to a generic Linux IO device, such as character devices or GPIOs.
allows attaching SIL Kit to a generic Linux IO device, such as character devices or GPIOs.

* The `SIL Kit FMU Importer <https://github.com/vectorgrp/sil-kit-fmu-importer>`_
allows to import Functional Mockup Units (FMUs) as SIL Kit participants.
can import Functional Mockup Units (FMUs) as SIL Kit participants.

Related Applications
~~~~~~~~~~~~~~~~~~~~
Expand All @@ -127,12 +133,12 @@ Guiding Principles

* **Local view:** Participants do not require knowledge about the overall system setup or other participants.
Communication between participants is made possible by using a common bus network or topic name.
* **Distributed simulation:** Communication between participants is based on a peer-to-peer connections.
* **Distributed simulation:** Communication between participants is based on peer-to-peer connections.
There is no central simulation participant that handles the distribution of messages or controls the virtual time.
* **Stability:** |ProductName| has a stable network layer and provides API and ABI guarantees.
This means that participants of different versions can partake in the same simulation.
Further, the |ProductName| library can be updated to newer versions without having to adapt or recompile already existing |ProductName| applications.
* **Reconfigurability:** Users should be able to provide a configuration file to the SIL Kit application to change the its behavior (e.g., configure logging or change the network a bus controller connects to).
* **Reconfigurability:** Users should be able to provide a configuration file to the SIL Kit application to change its behavior (e.g., configure logging or change the network a bus controller connects to).

.. _sec:overview-terminology:

Expand All @@ -149,7 +155,7 @@ Terminology
- A participant is a communication node in the distributed simulation that provides access to the |ProductName| services.
* - :ref:`Services<sec:api-services>`
- Participants interact with each other through the means of services.
These can be communication services, e.g., a :doc:`CAN Controller</api/services/can>` and orchestration services, such as the the Lifecycle Service, Time Synchronization Service, and the Logging Service.
These can be communication services, e.g., a :doc:`CAN Controller</api/services/can>` and orchestration services, such as 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.
Expand Down Expand Up @@ -183,7 +189,7 @@ Terminology
Further Reading
---------------

More real-world examples involving time synchronization and simulated automotive networks, can be found in the :doc:`API sections<../api/api>`.
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<../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.
Expand Down
Loading