Skip to content
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.

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

>Fix document entry urls #156

Merged
merged 1 commit into from
Apr 22, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
12 changes: 6 additions & 6 deletions docs/1____introduction.adoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
== Introduction
== Introduction [[introduction]]

=== Intent of This Document
=== Intent of This Document [[introduction-intent-of-this-document]]

Automotive CAN, LIN, FlexRay, CAN FD, CAN XL and Ethernet are network technologies that have been applied successfully over many years by all automotive OEMs world wide.
Virtualizing electronic control units (ECUs) and then simulating multiple such virtual ECUs requires connecting them using a virtual version of these network technologies.
Expand All @@ -27,7 +27,7 @@ Other FMUs that want to emulate bus communication provide and relate network inf
This communication architecture can be operated by a common FMU importer and allows complex and detailed bus simulations.
* Importer with Integrated Bus Simulation: Works analogously to the Composition with dedicated Bus Simulation FMU architecture, whereby the Bus Simulation FMU is directly integrated into an importer or other simulator.

=== System Simulation Effects
=== System Simulation Effects [[introduction-system-simulation-effects]]

This standard allows a highly accurate bus simulation using FMI 3.0 mechanisms.
To profit from such accuracy on a system level to predict system behavior, all system simulation components must provide at least that level of accuracy.
Expand All @@ -41,7 +41,7 @@ With virtual ECUs using the zero-time execution model footnote:[Simulated tasks
More detailed models (like instruction set simulators or even System-C models of the hardware) can narrow the window for these events significantly.
However, current (as of writing this standard) modelling technologies do not allow practical (modelling time and run time) implementations of virtual ECUs that can be used to simulate all realistic bus simulation effects (e.g. collision/arbitration events).

=== How to Read This Document
=== How to Read This Document [[introduction-how-to-read-this-document]]

Conventions used in this document:

Expand All @@ -53,13 +53,13 @@ To keep the standard itself brief, the https://modelica.github.io/fmi-guides/mai
It contains further technical discussions and examples on how to implement certain aspects of the standard for both FMUs and importers.
Contrary to the standard, the FMI LS BUS Implementer’s Guide will be a living document, enhanced with further tips and tricks as the FMI community encounters them.

=== Remarks
=== Remarks [[introduction-remarks]]

This layered standard currently only refers to the FMI for Co-Simulation (CS).
At the current time, Model Exchange (ME) and Scheduled Execution (SE) are not taken into account.
All explanations in this document are therefore to be understood in the context of FMI for Co-Simulation (CS).

== Layered Standard Manifest File
== Layered Standard Manifest File [[layered-standard-manifest-file]]

This layered standard defines requires the use of a layered standard manifest file and <<table-schema-fmi-ls-bus-attributes>> shows the content of `fmi-ls-manifest.xml`.

Expand Down
2 changes: 1 addition & 1 deletion docs/2____common_concepts.adoc
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
== Common Concepts
== Common Concepts [[common-concepts]]

Physical signal abstraction ("high cut") and network abstraction ("low cut") layers represent different levels for the exchange of bus messages.
Physical signal abstraction focuses primarily on the exchange of signal values, while network abstraction provides a complete way of implementing a virtual bus driver.
Expand Down
23 changes: 6 additions & 17 deletions docs/3____physical_signal_abstraction.adoc
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
== Physical Signal Abstraction ("high cut")
== Physical Signal Abstraction ("high cut") [[high-cut]]
This chapter describes the physical signal abstraction or "high cut" in detail.

=== Overview

=== Overview [[high-cut-overview]]
Physical signal abstraction allows an idealized exchange of unit-based variables between FMUs.
Variables representing these physical signals are clocked to reflect the bus timing aspects of the information flow.
Changes to these clocked variables always reach the destination.
Expand All @@ -17,12 +16,10 @@ The respective FMU variables are connected to a Bus Simulation, which emulates t
[#figure-transmission-high-cut-overview]
image::high_cut_network_fmu.svg[width=80%, align="center"]

=== Variables

=== Variables [[high-cut-variables]]
This section explains the different variable types used to carry network traffic through FMI input and output variables.

==== Signal Variables

==== Signal Variables [[high-cut-signal-variables]]
To define the signal abstraction layer (or "high cut"), signal variables are defined.

A signal variable carries the physical value of a network signal normally packaged inside a PDU or frame.
Expand All @@ -36,7 +33,6 @@ Generally, signal variables are optional, but they must either be all missing or

All signal variables are clocked to exactly indicate when they have been sent, see <<high-cut-clock-variables>>.


==== Clock Variables [[high-cut-clock-variables]]
In order to use FMU input and output variables as transport layer for networks, input and output Clocks are used.
Such a Clock is scheduled by the sending FMU to indicate the transmission of the corresponding frame or frames.
Expand All @@ -54,7 +50,6 @@ The importer will then connect and merge output Clock activations, even those of
Signal variables belonging to frame `BusName.FrameName` are triggered by the Clock `BusName.FrameName_Clock` and all these variables and their corresponding Clock must share the same `causality` (`input` or `output`).

=== Network Description Files [[high-cut-network-description-files,network description file]]

Standardized <<high-cut-network-description-files,network description files>> may optionally be shipped with each FMU to describe properties of signals and frames, such as signal units, frame composition and trigger conditions.
If these <<high-cut-network-description-files,network description files>> are shipped, they must be placed into the `/extra/org.fmi-standard.fmi-ls-bus` folder.
DBC, LDF, Fibex and ARXML files are allowed, e.g., `Powertrain.dbc`.
Expand All @@ -69,11 +64,10 @@ This document does not address potential open points of these description format
This document does not address IP protection or copyright issues.
These are technical and legal issues that need attention from standardization bodies of the referenced description formats, tool vendors and end users.

=== Terminal Definitions
=== Terminal Definitions [[high-cut-terminal-definitions]]
This section defines terminals for physical signal abstraction or "high cut".

==== Bus Terminal [[high-cut-bus-terminal,bus terminal]]

Each network connected to the FMU must be described in `icons/terminalsAndIcons.xml` as a `<Terminal>` element of `<fmiTerminalsAndIcons><Terminals>` that wraps all <<high-cut-frame-terminal,frame terminals>>.
The attribute `name` of the `<Terminal>` must match the root name of its <<high-cut-network-description-files>> if it exists
_[e.g., `Powertrain`, if the file is `/extra/org.fmi-standard.fmi-ls-bus/Powertrain.dbc`]_.
Expand All @@ -95,7 +89,6 @@ Receiving such frames must then be handled internally to the FMU.
If no <<high-cut-network-description-files,network description file>> is shipped with the specified FMU the `<Annotation>` shall not exist.

==== Frame Terminal [[high-cut-frame-terminal,frame terminal]]

Each frame listed in the <<high-cut-network-description-files>> must be an element of its corresponding <<high-cut-bus-terminal>>.

Attribute definitions::
Expand All @@ -112,7 +105,6 @@ Element definitions::
The <<high-cut-terminal-member-variable-for-signals>> must have the same `causality` as all variables referenced in the <<high-cut-pdu-terminal,PDU Terminals>> included here.

==== PDU Terminal [[high-cut-pdu-terminal,PDU terminal]]

Each PDU listed in the <<high-cut-network-description-files>> must be an element of its corresponding <<high-cut-frame-terminal>>.

Attribute definitions::
Expand All @@ -129,7 +121,6 @@ Element definitions::
All <<high-cut-terminal-member-variable-for-signals,`TerminalMemberVariables`>> must have the same `causality` of either `input` or `output`.

==== Terminal Member Variable for Signals [[high-cut-terminal-member-variable-for-signals,Terminal Member Variable]]

<<high-cut-pdu-terminal,PDU terminals>> list all the contained signals as `<TerminalMemberVariable>`.

Attribute definitions::
Expand All @@ -140,7 +131,6 @@ Attribute definitions::
* `variableKind` is `signal`.

==== Example [[high-cut-example]]

The following excerpts from files are used throughout this document as examples and should illustrate how the different concepts relate.

The following partial DBC file lists merely the CAN message (frame) structure.
Expand Down Expand Up @@ -186,8 +176,7 @@ The following file shows the `<Terminal>` definition representing the network an
include::examples/X_network4FMI_terminalsAndIcons_highCut.xml[]
----

=== Limitations

=== Limitations [[high-cut-limitations]]
Physical signal abstraction maps several network protocols onto co-simulation variables as transport layer simulating in many ways an ideal network.
Such an ideal network differs from physical networks in the following ways (and potentially others):

Expand Down
16 changes: 8 additions & 8 deletions docs/4_4_1_can.adoc
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
==== CAN, CAN FD, CAN XL
==== CAN, CAN FD, CAN XL [[low-cut-can]]
This chapter describes the <<low-cut-layered-standard-bus-protocol, Layered Standard Bus Protocol>> for CAN, CAN FD and CAN XL.
The various CAN standards CAN, CAN FD and CAN XL are considered together, because they are very similar and can also be combined in certain scenarios.

===== Overview
===== Overview [[low-cut-can-overview]]
To simulate CAN, CAN FD and CAN XL buses, CAN-specific operations are specified based on the <<low-cut-layered-standard-bus-protocol, Layered Standard Bus Protocol>>.
Overall, the following groups of operations exists:

Expand Down Expand Up @@ -146,7 +146,7 @@ h|Length

|====

===== Operations
===== Operations [[low-cut-can-operations]]
This section defines the specified operations for CAN, CAN FD and CAN XL.
The following tables provides an overview of all operations and specifies the position and length of the corresponding arguments, as well as the respective flow direction.

Expand Down Expand Up @@ -637,25 +637,25 @@ _A simple Network FMU might also choose to treat Bus Error or Arbitration operat
This structural parameter is mandatory for Network FMUs.
A Bus Simulation (FMU) does not require this structural parameter.

===== Configuration of Bus Simulation
===== Configuration of Bus Simulation [[low-cut-can-configuration-of-bus-simulation]]
The configuration of the Bus Simulation is done by the Network FMUs itself.
For this purpose, the <<low-cut-can-configuration-operation, `Configuration`>> operation provides several configuration parameters.
<<low-cut-can-configuration-operation, `Configuration`>> operations can be produced multiple times during the runtime of a Network FMU.
Because the Bus Simulation shall choose a default behavior, it might be useful in several scenarios that Network FMUs finish configuration before the production of <<low-cut-can-transmit-operation, `Transmit`>> operations.

====== Baud Rate Handling
====== Baud Rate Handling [[low-cut-can-baud-rate-handling]]
In order to calculate the time required for the transmission of a bus message, it is necessary to inform the Bus Simulation about the specified baud rate from a Network FMU.
This baud rate information can be configured by using `CAN_BAUDRATE`, `CAN_FD_BAUDRATE` and `CAN_XL_BAUDRATE` configuration kind of the <<low-cut-can-configuration-operation, `Configuration`>> operation.
In a CAN FD scenario, both the configuration for `CAN_BAUDRATE` and for `CAN_FD_BAUDRATE` shall be carried out.
The Bus Simulation can derive the required CAN, CAN FD or CAN XL controller type from the baud rate configurations a Network FMU carried out.
If the baud rate information is not adjusted by a specified Network FMU, the Bus Simulation shall choose a default behavior by itself.

====== Buffer Handling
====== Buffer Handling [[low-cut-can-buffer-handling]]
By using the `ARBITRATION_LOST_BEHAVIOR` configuration kind of a <<low-cut-can-configuration-operation, `Configuration`>> operation, the buffer handling within the Bus Simulation can be adjusted.
Using buffer handling is required in arbitration scenarios only and will be described <<low-cut-can-arbitration, within this context>>.
If the buffering is not adjusted by a specified Network FMU, the Bus Simulation shall choose a default behavior by itself.

===== Transmission and Acknowledge
===== Transmission and Acknowledge [[low-cut-can-transmission-and-acknowledge]]
The <<low-cut-can-transmit-operation, `Transmit`>> operation represents the sending of a CAN, CAN FD and CAN XL frame.
With appropriate options, relevant functionalities can be configured and used on a network abstraction level (e.g., Virtual CAN network ID for CAN XL or Bit Rate Switch for CAN FD).
In the real world, flawlessly transmitted CAN frames will be acknowledged by at least one receiver CAN node.
Expand Down Expand Up @@ -722,7 +722,7 @@ To simulate the behavior of the CAN Extra Suspend Transmission Time when a CAN n

The https://modelica.github.io/fmi-guides/main/ls-bus-guide/#low-cut-can-sequence-diagrams[FMI LS BUS Implementer’s Guide] contains examples of the presented arbitration cases and visualizes them using sequence diagrams.

===== Wake Up/Sleep
===== Wake Up/Sleep [[low-cut-can-wakeup-sleep]]
This standard supports wake up and sleep functionality for the CAN bus.
However, the realization of local virtual ECU wake-up and sleeping processes, i.e., the transition to the sleep state as well as the virtual ECU local wake-up process, is considered internal to the FMU implementation.
Therefore, only the bus-related aspects are defined in this document.
Expand Down
20 changes: 10 additions & 10 deletions docs/4_4_2_lin.adoc
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
==== LIN
==== LIN [[low-cut-lin]]
This chapter describes the <<low-cut-layered-standard-bus-protocol, Layered Standard Bus Protocol>> for LIN.

===== Overview
===== Overview [[low-cut-lin-overview]]
To simulate LIN buses, LIN-specific operations are specified based on the <<low-cut-layered-standard-bus-protocol, Layered Standard Bus Protocol>>.
Overall, the following groups of operations exists:

Expand Down Expand Up @@ -102,7 +102,7 @@ h|Length

|====

===== Operations
===== Operations [[low-cut-lin-operations]]
This section defines the allowed operations for LIN.
The following tables provides an overview of all operations and specifies the position and length of the corresponding arguments, as well as the respective flow direction.

Expand Down Expand Up @@ -433,32 +433,32 @@ If a Network FMU does not support wake-up this operation can be ignored on consu

|====

===== Transmission and Reception
===== Transmission and Reception [[low-cut-lin-transmission-and-reception]]
#TODO#

===== Detection of Collisions
===== Detection of Collisions [[low-cut-lin-detection-of-collisions]]
#TODO#

===== Configuration of Bus Simulation
===== Configuration of Bus Simulation [[low-cut-lin-configuration-of-bus-simulation]]
The configuration of the Bus Simulation is done by the Network FMUs itself.
For this purpose, the <<low-cut-lin-configuration-operation, `Configuration`>> operation provides several configuration parameters.
<<low-cut-lin-configuration-operation, `Configuration`>> operations can be produced multiple times during the runtime of a Network FMU.
Because the Bus Simulation shall choose a default behavior, it might be useful in several scenarios that Network FMUs finish configuration before the production of <<low-cut-lin-transmit-operation, `Transmit`>> operations.

====== Baud Rate Handling
====== Baud Rate Handling [[low-cut-lin-baud-rate-handling]]
In order to calculate the time required for the transmission of a bus message, it is necessary to inform the Bus Simulation about the specified baud rate from a Network FMU.
This baud rate information can be configured by using `LIN_BAUDRATE` configuration kind of the <<low-cut-lin-configuration-operation, `Configuration`>> operation.
If the baud rate information is not adjusted by a specified Network FMU, the Bus Simulation shall choose a default behavior by itself.

====== Node Definition
====== Node Definition [[low-cut-lin-node-definition]]
By using the `LIN_NODE_DEFINITION` configuration kind of a <<low-cut-lin-configuration-operation, `Configuration`>> operation, the specified node type `LIN_MASTER` or `LIN_SLAVE` needs to be adjusted.
This configuration must be done before the first exchange of <<low-cut-lin-transmit-operation, `Transmit`>> operations.
A Bus Simulation should stop as soon as more than one LIN Master is configured in a network.

===== Error Handling
===== Error Handling [[low-cut-lin-error-handling]]
#TODO#

===== Wake Up/Sleep
===== Wake Up/Sleep [[low-cut-lin-wakeup-sleep]]
This standard supports wake up and sleep for the LIN bus, whereby only the bus-specific parts are taken into account.
This means that the realization of local virtual ECU wake-up and sleeping processes are internal parts of the respective FMU, which is not covered by this document.
Because entering sleep state is a virtual ECU internal process always within LIN bus, this can be ignored.
Expand Down
11 changes: 5 additions & 6 deletions docs/4____network_abstraction.adoc
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
== Network Abstraction ("low cut") [[network-abstraction]]
== Network Abstraction ("low cut") [[low-cut]]
This chapter describes the network abstraction or "low cut" in detail.

=== Overview
=== Overview [[low-cut-overview]]
The network abstraction allows the implementation of virtual bus drivers within FMUs on the level of the hardware abstraction layer.
Exchanging data in terms of the <<low-cut-layered-standard-bus-protocol, Layered Standard Bus Protocol>> via variables grouped by a dedicated bus terminal (see <<low-cut-variables>>), allows the implementation of bus simulations in a wide range from idealized up to detailed behavior, including e.g., timing, arbitration, error, status and other effects.
During simulation, the network communication is controlled by send and receive Bus Operations.
Expand Down Expand Up @@ -252,7 +252,6 @@ Pending Tx data shall be signaled by returning from `fmi3DoStep` with the `event
[#low-cut-triggered-port-connection]
image::low_cut_communication_with_triggered_tx_clock.svg[width=100%, align="center"]


==== Rx Clock Variables [[low-cut-rx-clock-variables]]
The input Clocks (`Rx_Clock`) shall be `triggered` Clocks.

Expand All @@ -262,14 +261,14 @@ If no Bus Operations shall be sent by a specified Network FMU at a given Bus Com
The senders can choose how many Bus Operations are buffered and/or for how long operations are buffered before activating an output Clock to trigger the actual sending of these operations.
This allows senders to trade accuracy for speed: buffering more and interrupting the simulation less will lead to faster simulations, but less accurate timing of the network communication.

==== Selecting the type of Tx Clock[[low-cut-selecting-tx-variables]]
==== Selecting the type of Tx Clock [[low-cut-selecting-tx-variables]]
Selecting suitable Tx variables allows the FMU (or better the exporting tool) to balance the accuracy and performance of its network communication:

- While `aperiodic` Clocks allow very accurate network simulations, frequently entering `Event Mode` will reduce the network simulation speed.
- Using `periodic` Clocks and queueing the operations to be transmitted reduces the number of `Event Mode` entries and speeds up the simulation at the cost of simulation accuracy.
- One could use (structural) parameters to define the accuracy of `aperiodic` Clocks, allowing control of the simulation accuracy and performance with the same FMU.

==== MIME Types
==== MIME Types [[low-cut-mime-types]]
Within FMI, every binary FMI variable has a `mimeType`, which indicates the type of data passed as a binary.
This type indicates which specific bus type is involved.
It ensures that only bus types of the same type can be interconnected, since FMI only allows the connection of two MIME types of the same binary variables.
Expand Down Expand Up @@ -305,7 +304,7 @@ The version number marks the set of available operations.
Only the major version is included by the specified MIME type.
The versioning follows the rules of semantic versioning, as defined in <<PW13>>.

=== Terminal Definitions
=== Terminal Definitions [[low-cut-terminal-definitions]]
This section defines terminals for network abstraction or "low cut".

==== Bus Terminal [[low-cut-bus-terminal,bus terminal]]
Expand Down
Loading