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

Add configuration parameters to Bus Terminal definition (low-cut) #221

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
57971d3
Add configuration parameters to Bus Terminal definition (low-cut)
Dec 6, 2024
b7e330b
Remove obsolete reference to FlexRay iteration argument
Dec 9, 2024
5650d4c
Reorganizing CAN network parameters within Bus Terminals
Dec 9, 2024
a8c723d
Clarifications on low-cut Bus Terminal definition
Dec 9, 2024
61b99ca
Adapt causality and name of BusNotification parameter (CAN part)
Dec 10, 2024
399567c
Add possible constant variability for BusNotification parameters
Dec 10, 2024
ee49f12
Fixed typo
Dec 10, 2024
6e86afa
Add review fixes
Dec 10, 2024
3f821dd
Adapt FlexRay chapter to new configuration params concept
Dec 10, 2024
66023e7
Fixed typos
Dec 11, 2024
d9127f2
Fixed some text
Dec 11, 2024
6e38ed9
Fixed sentence
Dec 11, 2024
98e58b6
Fixed issue #219
Dec 12, 2024
e094cfb
Reordering sentences
Dec 17, 2024
70ea62a
Fixed missing "or omitted"
Dec 17, 2024
2908900
Reordered bus notification section (FlexRay)
Dec 17, 2024
e2c4542
Integrate review comments
Dec 19, 2024
60d973c
Fixed configuration parameter description listing
Dec 19, 2024
7605115
Rewrite text regarding BusNotifications parameter for CAN
klausschuch Dec 18, 2024
393db7f
Use when instead of while
klausschuch Dec 19, 2024
94c0665
Remove Configuration to not confuse it with Configuration Operation
klausschuch Dec 19, 2024
a209cca
Change BusNotifications text for Bus Simulation FMUs
klausschuch Dec 19, 2024
61ef8f0
Fix typo
klausschuch Dec 20, 2024
b57cf85
Fixed review comments
Dec 20, 2024
ec17409
Fixed typo
Dec 20, 2024
d07bb86
Fixed text
Dec 20, 2024
e34c471
Fixed text again
Dec 20, 2024
492da4d
Fixed typos
Dec 20, 2024
50da157
Remove obsolete exclusion
klausschuch Dec 20, 2024
3d5390c
Improve consistent use of <Terminal> vs Terminal
klausschuch Dec 20, 2024
6ef9751
Explicitly define Configuration Terminal
klausschuch Dec 20, 2024
d62eb86
Use Configuration Terminal in examples
klausschuch Dec 20, 2024
dbaa050
Use links for Configuration Terminals
Dec 20, 2024
19b79e4
Fixed text
Dec 20, 2024
338239b
Fixed syntax of start values
Dec 20, 2024
70e3f94
Fixed spaces
Dec 20, 2024
13e5b1d
Fixed example
Dec 20, 2024
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
10 changes: 3 additions & 7 deletions docs/3____physical_signal_abstraction.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -69,17 +69,16 @@ 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
The attribute `name` of the `<Terminal>` element 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`]_.
In any case, the attribute `name` of the `<Terminal>` must be consistent with the `BusName` component of all its corresponding signal, frame and Clock variables.
In any case, the attribute `name` of the `<Terminal>` element must be consistent with the `BusName` component of all its corresponding signal, frame and Clock variables.

Attribute definitions::
* `terminalKind` must be set to `org.fmi-ls-bus.network-terminal`.
* `matchingRule` must be set to `bus`.
* `name` is the network name, e.g., `Powertrain`, see <<high-cut-example, example>> and constraints above.

Element definitions::
* There must be no `<TerminalStreamMemberVariable>` element.
* There must be one `<Terminal>` element per network frame described in the <<high-cut-network-description-files>>, if their signal and Clock variables are present in the `modelDescription.xml`.

Annotation element::
Expand All @@ -97,7 +96,6 @@ Attribute definitions::
* `name` must match the frame name as defined in the <<high-cut-network-description-files>> in `/extra/org.fmi-standard.fmi-ls-bus`.

Element definitions::
* There must be no `<TerminalStreamMemberVariable>` element.
* There must be one <<high-cut-pdu-terminal>> element per PDU of this frame.
* There must be one `<TerminalMemberVariable>` for the Clock this frame is connected to.
The `memberName` of this variable must be "Clock".
Expand All @@ -114,8 +112,6 @@ Attribute definitions::
For network types not natively referencing a "PDU", like CAN, a synthetic PDU with the same name as its frame is inserted.

Element definitions::
* There must be no `<TerminalStreamMemberVariable>` element.
* There must be no `<Terminal>` element.
* There must be one `<TerminalMemberVariable>` per <<high-cut-terminal-member-variable-for-signals,signal>> of this PDU.

All <<high-cut-terminal-member-variable-for-signals,`TerminalMemberVariables`>> must have the same `causality` of either `input` or `output`.
Expand Down Expand Up @@ -169,7 +165,7 @@ The `modelDescription.xml` excerpt listed below shows which variables would exis
include::examples/X_network4FMI_modelDescription_highCut.xml[]
----

The following file shows the `<Terminal>` definition representing the network and frame structure defined with `Powertrain.dbc` above.
The following file shows the <<high-cut-bus-terminal,Bus Terminal>> definition representing the network and frame structure defined with `Powertrain.dbc` above.

.Example terminalsAndIcons.xml file.
[#terminalsAndIconHighCut.xml]
Expand Down
79 changes: 45 additions & 34 deletions docs/4_4_1_can.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ The ID must be considered here as a purely numerical value.
This means that there is no need for separate segmentation between the 11-bit base CAN identifier and an 18-bit CAN identifier extension information that is known from the CAN protocol.
Additional information such as Ide is also not part of the ID, but is treated separately.
| Ide | 1 byte | Specified whether the ID should be transmitted as standard (11-bit) or extended (29-bit) message identifier.
For specification the boolean values `TRUE` and `FALSE` (see <<table-boolean-value-kinds>>) shall be used.
For specification the boolean values `TRUE` and `FALSE` (see <<table-boolean-value-kinds>>) shall be used.
| Rtr | 1 byte | Specifies whether the given frame represents a Remote Transmission Request frame.
For specification the boolean values `TRUE` and `FALSE` (see <<table-boolean-value-kinds>>) shall be used.
| Data Length | 2 byte | Specifies the length of the Data argument in bytes.
Expand All @@ -178,7 +178,7 @@ h|Behavior
3+|The <<low-cut-can-transmit-operation, `CAN Transmit`>> operation shall be provided by Network FMUs to initiate the transmission of a CAN frame.
In case of directly connected Network FMUs (see <<common-concepts-direct-communication>>), the FMU importer forwards the operation directly to the receiving Network FMUs.
If a Bus Simulation is involved (see <<common-concepts-composition-with-dedicated-bus-simulation-fmu>> and <<common-concepts-importer-with-integrated-bus-simulation>>), the FMU importer forwards the operation initially to the Bus Simulation, where the operation is distributed with respect to the simulated bus behavior.
Depending on the simulation details, the Bus Simulation might response with a <<low-cut-can-confirm-operation, `Confirm`>>, <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>>, <<low-cut-can-bus-error-operation, `Bus Error`>> or <<low-cut-can-format-error-operation, `Format Error`>> operation.
Depending on the simulation details, the Bus Simulation might respond with a <<low-cut-can-confirm-operation, `Confirm`>>, <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>>, <<low-cut-can-bus-error-operation, `Bus Error`>> or <<low-cut-can-format-error-operation, `Format Error`>> operation.
Depending on the <<low-cut-can-status-operation, status>> of the specified Network FMU further restrictions for <<low-cut-can-transmit-operation, `CAN Transmit`>> operations <<table-can-status-values, exist>>.

|====
Expand Down Expand Up @@ -268,9 +268,9 @@ The following applies for this operation: `Length = 12`.
|The ID of the confirmed CAN message.

h|Behavior
3+|The specified operation shall be produced by the Bus Simulation and consumed by Network FMUs.
If the structural parameter <<low-cut-can-bus-notification-parameter, `org.fmi_standard.fmi_ls_bus.Can_BusNotifications`>> of a Network FMU is set to `false`, the Network FMU does not wait for any responses from a Bus Simulation, i.e., potentially received <<low-cut-can-confirm-operation, `Confirm`>> operations are discarded by the Network FMU.
Depending on the <<low-cut-can-status-operation, status>> of the specified Network FMU further restrictions for <<low-cut-can-confirm-operation, `Confirm`>> operations <<table-can-status-values, exist>>.
3+|This operation shall be produced by the Bus Simulation and consumed by Network FMUs. +
Only Network FMUs with the corresponding optionally exposed <<low-cut-can-bus-notification-parameter, `BusNotifications`>> parameter set to `fmi3True` might wait for this operation.
Depending on the <<low-cut-can-status-operation, status>> of the receiving Network FMU further restrictions for <<low-cut-can-confirm-operation, `Confirm`>> operations <<table-can-status-values, exist>>.

|====

Expand Down Expand Up @@ -310,8 +310,8 @@ h|Behavior
3+|During simulation, several <<low-cut-can-transmit-operation, `Transmit`>> operations can be sent by Network FMUs to a Bus Simulation at the same time.
In such case, the Bus Simulation has to decide which <<low-cut-can-transmit-operation, `Transmit`>> operation should be processed first.
Depending on the configuration (see the `Arbitration Lost Behavior` argument of the <<low-cut-can-configuration-operation, `Configuration`>> operation), the deferred <<low-cut-can-transmit-operation, `Transmit`>> operations shall either be buffered or they shall be discarded and the <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>> operation shall be sent back to the respective Network FMUs.
A Network FMU receiving the <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>> operation can decide to provide the <<low-cut-can-transmit-operation, `Transmit`>> operation again or e.g., to raise an internal transmit timeout failure after a while.
If the structural parameter <<low-cut-can-bus-notification-parameter, `org.fmi_standard.fmi_ls_bus.Can_BusNotifications`>> of a Network FMU is set to `false`, the Network FMU does not wait for any responses from a Bus Simulation, i.e., potentially received <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>> operations are discarded by the Network FMU.
A Network FMU receiving the <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>> operation can decide to provide the <<low-cut-can-transmit-operation, `Transmit`>> operation again or e.g., to raise an internal transmit timeout failure after a while. +
Only Network FMUs with the corresponding optionally exposed <<low-cut-can-bus-notification-parameter, `BusNotifications`>> parameter set to `fmi3True` might wait for this operation and respond accordingly.

|====

Expand Down Expand Up @@ -357,14 +357,15 @@ For specification the boolean values `PRIMARY_ERROR_FLAG` and `SECONDARY_ERROR_F
For specification the boolean values `TRUE` and `FALSE` (see <<table-boolean-value-kinds>>) shall be used.

h|Behavior
3+|While transmitting CAN frames, various kinds of bus error may happen.
3+|When transmitting CAN frames, various kinds of bus error may happen.
A Bus Simulation can simulate such errors by providing <<low-cut-can-bus-error-operation, `Bus Error`>> operations to the Network FMUs.
Based on consumed <<low-cut-can-bus-error-operation, `Bus Error`>> operations, Network FMUs shall maintain an internal CAN node state (see <<low-cut-can-error-handling>>).
To determine the CAN node state properly, Network FMUs need the information about their role at the time when the simulated error happened.
For a Network FMU that initiated the <<low-cut-can-transmit-operation, `Transmit`>> operation, the argument `Is Sender` shall be set to `TRUE` in the corresponding <<low-cut-can-bus-error-operation, `Bus Error`>> operation.
For a Network FMU considered to be the one detecting the error first, the argument `Error Flag = PRIMARY_ERROR_FLAG` shall be set.
The arguments `Is Sender = TRUE` and `Error Flag = PRIMARY_ERROR_FLAG` must only be set once per simulated error.
If the structural parameter <<low-cut-can-bus-notification-parameter, `org.fmi_standard.fmi_ls_bus.Can_BusNotifications`>> of a Network FMU is set to `false`, the Network FMU does not wait for any responses from a Bus Simulation, i.e., potentially received <<low-cut-can-bus-error-operation, `Bus Error`>> operations are discarded by the Network FMU.
The arguments `Is Sender = TRUE` and `Error Flag = PRIMARY_ERROR_FLAG` must only be set once per simulated error. +
Only Network FMUs with the corresponding optionally exposed <<low-cut-can-bus-notification-parameter, `BusNotifications`>> parameter set to `fmi3True` might wait for this operation and respond accordingly.

|====

The following Error Codes are specified:
Expand Down Expand Up @@ -607,35 +608,45 @@ If a Network FMU does not support wake up, this operation can be ignored on the
|====

===== Network Parameters [[low-cut-can-network-parameters]]
Using structural parameters, FMUs can be parameterized according to importer specifications.
This chapter specifies the structural parameters that each CAN-specific Network FMU shall provide.
This chapter defines parameters that Network FMU might provide to configure CAN-specific behavior.
bmenne-dspace marked this conversation as resolved.
Show resolved Hide resolved

====== Bus Notification Parameter [[low-cut-can-bus-notification-parameter]]
For a detailed simulation, the CAN bus behavior regarding acknowledgment, bus errors and arbitration losses must be considered.
A Bus Simulation can simulate these effects by sending bus notifications in terms of <<low-cut-can-confirm-operation, `Confirm-`>>, <<low-cut-can-bus-error-operation, `Bus Error-`>> and <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>> operations to the Network FMUs.

However, in scenarios where Network FMUs are connected directly to each other, or where the Bus Simulation does not simulate such effects, it must be possible to configure the Network FMU such that it does not wait for any response after a <<low-cut-can-transmit-operation, `Transmit`>> operation.
Therefore, the <<low-cut-can-bus-notification-parameter, `org.fmi_standard.fmi_ls_bus.Can_BusNotifications`>> parameter is introduced.
If the value of the parameter is set to `false`, the Network FMU must not wait for any response after a <<low-cut-can-transmit-operation, `Transmit`>> operation ("fire-and-forget").
The default value shall be `false` to allow the Network FMU to be run natively in each simulation scenario.
If the Network FMU shall be configured to handle responses in the form of <<low-cut-can-confirm-operation, `Confirm-`>>, <<low-cut-can-bus-error-operation, `Bus Error-`>> and <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>> operations, the <<low-cut-can-bus-notification-parameter, `org.fmi_standard.fmi_ls_bus.Can_BusNotifications`>> parameter shall be set to `true`. +
_[This does not necessarily mean the FMU must fully support CAN error handling or sophisticated arbitration mechanisms._
_A simple Network FMU might also choose to treat Bus Error or Arbitration operations in a simplified manner, e.g., by treating them as a positive confirmation.]_

.FMU parameter for the configuration of bus notifications.
[[figure-fmu-bus-notifications-parameter]]
Therefore, a parameter with `memberName = "BusNotifications"` can be added within the CAN-specific <<low-cut-configuration-terminal,Configuration Terminal>>. +
If a Network FMU supports bus notifications, the <<low-cut-can-bus-notification-parameter, `BusNotifications`>> parameter shall be exposed.
The default value of this parameter shall be `false`. +
_[The default value `false` allows a simple integration of Network FMUs to simulation scenarios where <<low-cut-can-confirm-operation, `Confirm-`>>, <<low-cut-can-bus-error-operation, `Bus Error-`>> or <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>> operations are not used.]_

klausschuch marked this conversation as resolved.
Show resolved Hide resolved
Only Network FMUs with the corresponding optionally exposed <<low-cut-can-bus-notification-parameter, `BusNotifications`>> parameter set to `fmi3True` might wait for <<low-cut-can-confirm-operation, `Confirm-`>>, <<low-cut-can-bus-error-operation, `Bus Error-`>> and <<low-cut-can-arbitration-lost-operation, `Arbitration Lost`>> operations and respond accordingly; otherwise Network FMUs must not wait ("fire-and-forget").
Even if the Network FMU does not expect bus notifications, i.e. <<low-cut-can-bus-notification-parameter, `BusNotifications`>> variable was not set to `fmi3True`, but receives them, it shall ignore them, i.e. it shall not report warnings or errors.

_[Note that the bus notification parameter just informs the Network FMU if it can expect to receive notification operations or not.
The parameter doesn't define in any way on how to react upon receiving notification operations.]_

.Parameter to configure bus notifications within a CAN Bus Terminal of Network FMUs.
[[figure-fmu--can-bus-notifications-parameter]]
----
org.fmi_standard.fmi_ls_bus.Can_BusNotifications
Description: "Specifies whether the respective Network FMU can rely on a Confirm,
Bus Error or Arbitration Lost operation after sending a message."
Type: Boolean
Causality: structuralParameter
Variability: fixed
Start: "false"
memberName: BusNotifications
type: Boolean
causality: parameter
variability: fixed
start: false
----

This structural parameter is mandatory for Network FMUs only.
A Bus Simulation (FMU) does not require this structural parameter.
A Bus Simulation FMU shall indicate via a variable with `memberName = "BusNotifications"` within the CAN-specific <<low-cut-configuration-terminal,Configuration Terminal>> whether it provides bus notifications or not.
If the provision of bus notifications can be configured (e.g., via a structural parameter), the attributes of the <<low-cut-can-bus-notification-parameter, `BusNotifications`>> variable shall contain `causality = "calculatedParameter"` and `variability = "fixed"`; or `causality = "output"` and `variability = "constant"` otherwise.

.Parameter to configure bus notifications within a CAN Bus Terminal of the Bus Simulation.
[[figure-fmu-can-bus-notifications-parameter-in-bus-simulation]]
----
memberName: BusNotifications
type: Boolean
causality: calculatedParameter/output
variability: fixed/constant
----

===== Configuration of Bus Simulation [[low-cut-can-configuration-of-bus-simulation]]
The configuration of the Bus Simulation is done by the Network FMUs itself.
Expand All @@ -660,11 +671,11 @@ The <<low-cut-can-transmit-operation, `Transmit`>> operation represents the send
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.
To simulate this behavior, the <<low-cut-can-confirm-operation, `Confirm`>> operations are introduced.
In addition, the structural parameter <<low-cut-can-bus-notification-parameter, `org.fmi_standard.fmi_ls_bus.Can_BusNotifications`>> is defined to support lightweight bus simulations and <<common-concepts-direct-communication, directly connected Network FMUs>>.
In addition, the <<low-cut-can-bus-notification-parameter, `BusNotifications`>> parameter is defined to support lightweight bus simulations and <<common-concepts-direct-communication, directly connected Network FMUs>>.

If <<low-cut-can-bus-notification-parameter, `org.fmi_standard.fmi_ls_bus.Can_BusNotifications`>> is set to `false` (default), then Network FMUs must not rely on receiving <<low-cut-can-confirm-operation, `Confirm`>> operations.
If <<low-cut-can-bus-notification-parameter, `BusNotifications`>> is `false` (default), then Network FMUs must not rely on receiving <<low-cut-can-confirm-operation, `Confirm`>> operations for the specified Bus Terminal.
In this case, the bus simulation is idealized and takes place in a "fire-and-forget" manner.
If a specified Network FMU is depending on <<low-cut-can-confirm-operation, `Confirm`>> operations and <<low-cut-can-bus-notification-parameter, `org.fmi_standard.fmi_ls_bus.Can_BusNotifications`>> is set to `false`, the self confirmation shall be realized internally within the respective Network FMU.
If a specified Network FMU is depending on <<low-cut-can-confirm-operation, `Confirm`>> operations and <<low-cut-can-bus-notification-parameter, `BusNotifications`>> is `false`, the self confirmation shall be realized internally within the respective Network FMU for the specified Bus Terminal.

<<#figure-can-direct-communication>> illustrates this communication, whereby FMU 1 transmits network data to FMU 2.
Subsequently, FMU 1 self-confirms the transmission internally.
Expand All @@ -674,7 +685,7 @@ Subsequently, FMU 1 self-confirms the transmission internally.
image::can_direct_confirmation.svg[width=40%, align="center"]

For a detailed simulation, the Bus Simulation has to support <<low-cut-can-confirm-operation, `Confirm`>> operations.
In this case, the <<low-cut-can-bus-notification-parameter, `org.fmi_standard.fmi_ls_bus.Can_BusNotifications`>> parameter of the Network FMUs can be set to `true` as Network FMUs can rely on receiving <<low-cut-can-confirm-operation, `Confirm`>> operations.
In this case, the <<low-cut-can-bus-notification-parameter, `BusNotifications`>> parameter of the Network FMUs can be set to `fmi3True` as Network FMUs can rely on receiving <<low-cut-can-confirm-operation, `Confirm`>> operations for the specified Bus Terminal.

The following <<#figure-can-confirmation-with-bus-simulation-fmu>> illustrates the behavior, whereby FMU 1 transmits network data to FMU 2 via a Bus Simulation.

Expand Down
Loading