4____network_abstraction.adoc

Network Abstraction ("low cut")

This chapter describes the network abstraction or "low cut" in detail.

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 Layered Standard Bus Protocol via variables grouped by a dedicated Bus Terminal (see 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. Based on these operations, FMUs implementing this layered standard have to react depending on their role as specified in this document. This role can be a Bus Simulation FMU or an importer with bus simulation support on one side, and Network FMUs (e.g., virtual ECUs) on the other side (see System Compositions). To allow importers an easy distinction between these FMU roles, for Bus Simulation FMUs the attribute isBusSimulationFMU shall be set to true in the Manifest file.

In general, the Layered Standard Bus Protocol is bus-type-specific, but there are some similarities among different bus types. Bus communication often follows a Transmit/Confirm pattern, where a Network FMU sends a Transmit operation containing the network message as payload. Depending on the System Composition, the importer forwards the Transmit operation either directly to receiving FMUs or to a dedicated bus simulation. The Bus Simulation then might delay the transfer of the Transmit operation to the receiving FMUs to simulate timing behavior, before sending a bus-specific Confirm operation back to the sending FMU.

Figure 1. Transmission overview.

The point in time at which FMUs will (potentially) send new network messages can be given to the importer in advance with the proper Clock type. Based on these times, the importer has to calculate the next communicationStepSize for all networked FMUs. For simulating bus communication with timing effects, the FMUs should set the Co-Simulation attribute canHandleVariableCommunicationStepSize = "true".

Figure 2. Example for network simulation with timing behavior.

For simplification reasons or if a detailed bus simulation is not desired, fixed-step size FMUs can also be used with network abstraction. However, depending on the chosen simulation step-size, delay effects of the bus simulation have to be taken into account. Compositions with fixed-step size and variable-step size FMUs require the decoupling of the Bus Simulation logic and the Bus Simulation timing. This decoupling is realized by queuing Tx/Rx Bus Operations inside the Bus Simulation as well as queuing Tx Bus Operations inside Network FMUs. By queuing Bus Operations, System Compositions with variable-step size FMUs as well as fixed-step size FMUs can be simulated together without affecting each other.

Layered Standard Bus Protocol

The Layered Standard Bus Protocol allows the transmission of Bus Operations between FMUs in binary form via Clocks and clocked variables (see Variables). Depending on the role (Network or Bus Simulation), FMUs have to respond to received operations as specified by this layered standard. Operations and the reaction on receipt are bus-type-specific and therefore described in the bus-specific chapters. However, the description follows a uniform structure and consists of two parts, an overview table and a detailed description of all operations.

The overview table represents the binary format of operations and is structured as follows:

• OP Code: The operation code defines the unique value of the operation. It consists of four bytes in length.

• Length: A four byte total data length (OP Code + Length + Arguments) field following the OP Code. For operation with variable size arguments, the total length can vary in value at runtime.

• Arguments: The arguments of the respective operation. The number of arguments is defined for each operation within this standard. For arguments with a variable length, an argument pair composed of length and data is used.

The following table shows an example of an operation definition. The name is OperationName and has the OP Code 0x01. The operation has three arguments Arg1 (2 bytes long), Arg2_Length (1 byte long), Arg2_Data (<Arg2Length> bytes long), whereby argument 2 and argument 3 form a coherent variable length argument.

Table 1. Definition of an operation within the Layered Standard Bus Protocol.

Operation Type	Operation Content
	OP Code	Length	Specific Content
OperationName	0x01	10 + <Arg2_Length>	1 byte Arg1	1 byte Arg2_Length	<Arg2_Length> byte Arg2_Data

Additionally, all operations are described separately in detail in the following structure:

Table 2. Operation example within the Layered Standard Bus Protocol.

Name	Name of the operation (e.g., OperationName)
Description	Contains a description of the specified operation.
OP Code [hex]	OP code of the operation (e.g., 0x01)
Content	Argument	Length	Description
	OP Code	4 byte	Contains the OP Code of the specified operation.
	Length	4 byte	Defines the cumulative length of all arguments in bytes. The following applies for this operation: Length = 10 + <Arg2_Length>.
	Arg1	1 byte	The first argument of the operation.
	Arg2_Length	1 byte	Contains the length of the Arg2_Data argument in bytes.
	Arg2_Data	n byte	The second argument of the operation.
Behavior	Describes the behavior of a Network FMU and the Bus Simulation in the context of this operation. e.g., The specified operation shall be produced by a Network FMU and consumed by the Bus Simulation.

Remarks:

• Numbers shall be transmitted with little-endian byte order.

• Since the standard allows to concatenate multiple operations (see Tx/Rx Data Variables), the Length field is introduced to allow the implementation of a generic parser for received operations.

Format Error

The Format Error operation is independent from the bus type and shall be used when encountering a syntax or content error of received operations.

Table 3. Detailed description of the Format Error operation.

Name	Format Error
Description	Represents a generic format operation error, which can be initiated by every operation. This error shall be used when generally encountering a problem with the syntax or content of an operation.
OP Code [hex]	0x01
Content	Argument	Length	Description
	OP Code	4 byte	Contains the OP Code of the specified operation. For this operation, the OP Code always has the value 0x01 within all bus types.
	Length	4 byte	Defines the cumulative length of all arguments in bytes. The following applies for this operation: Length = 10 + Length of Data argument in bytes.
	Data Length	2 byte	Specifies the length of the Data argument in bytes.
	Data	n byte	Stores the complete binary data of the operation that caused the specified Format Error.
Behavior	The specified operation shall be produced and consumed by Network FMUs and the Bus Simulation.

Basic Type Definitions

The following basic types are defined for this standard, which apply to all supported buses. These basic types are used in the bus-specific parts within the operation definitions as operation arguments.

The following values for the boolean basic type are defined:

Table 4. Overview of the available boolean values.

Boolean	Value	Description
FALSE	0x00	Describes the boolean value: False.
TRUE	0x01	Describes the boolean value: True.

Variables

This section explains how layered standard bus protocol operations are sent and received by FMUs using FMI 3.0 Clock and clocked variables ^[1]. While the former (see Tx Clock Variables and Rx Clock Variables) are used for scheduling and time synchronization, the latter (see Tx/Rx Data Variables) are used to carry the layered standard bus protocol operations in binary form. To summarize, four variables with the following characteristics and relations are used:

• The Rx_Data variable is clocked by the Rx_Clock variable, both with causality set to input.

• The Tx_Data variable is clocked by the Tx_Clock variable. The causality for the Tx_Data variable shall be output, but for the Tx_Clock variable it depends on the selected Clock type (see Tx Clock Variables).

Both variable pairs must be listed as member of its corresponding Bus Terminal.

Tx Clock Variables

As described in the FMI 3.0 specification, Clock variables are used to synchronize events between importer and across FMUs. Since Clock variables are strictly related to the Event Mode, networked FMUs shall set the Co-Simulation attribute hasEventMode = "true" in the model description file.

The point in time where Bus Operations are transferred from the Tx_Data to the Rx_Data variables is defined by the Tx_Clock variable. This point is also referred to as the Bus Communication Point. A Bus Communication Point and a regular communication point can take place at the same time, but should be considered as independent by the importer. In contrast to a regular communication point where input/output variables used in step mode are exchanged, only the clocked Tx/Rx data variables needs to be considered by the importer.

For defining the point in time of a Bus Communication Point, time-based or triggered Clocks can be used for the Tx_Clock variable. Hence the Clock type can influence the bus simulation significantly - the differences should be taken into account.

Time-based Tx Clock Variables

A time-based Tx_Clock variable allows networked FMUs to announce a Bus Communication Point for the next simulation step in advance.

Figure 3. Example Bus Communication Points announced by aperiodic time-based Tx_Clock variables.

The announced Tx time however does not mean that a Bus Operation really has to be transferred, but that the connected networked FMUs should enter the Event Mode at that time. An importer has to determine proper communication step sizes to synchronize networked FMUs at the announced Tx time.

[Note: While simulation it can happen that no Tx_Data has to be transferred to the Rx_Data variable at the announced Tx time. In this case the returned 'valueSize' of the Tx_Data variable is 0.]

Although the causality of a time-based Tx_Clock variable and a triggered Rx_Clock variable are each input, it is allowed to connect both, since a time-based Clock variable of an FMU is considered only to be a request to the importer to provide an attendant Clock source.

Figure 4. Consideration of time-base Tx_Clock connections.

Because of the common Clock source however, both Clock variables (Rx/Tx) might get active at the same time. To make sure that the Rx_Data variables is set properly, an importer has to activate the Rx_Clock variable under consideration of Tx_Data and Rx_Data dependency.

[Note: For clarity always a direct connection line between the Tx_Clock and Rx_Clock variables is shown in figures of this document.]

A time-based Clock can be periodic or aperiodic. Both allows to define Bus Communication Points independently from the regular communication points with fixed or variable distances. The difference between the two Clock types is listed in the following table.

Table 5. Time-based Clock properties.

Clock properties	intervalVariability	Description
periodic	constant	The Bus Communication Point interval is defined in the modelDescription.xml.
periodic	fixed	The Bus Communication Point interval is defined in the modelDescription.xml or must be provided in Initialization Mode.
periodic	tunable	The Bus Communication Point interval is defined in the modelDescription.xml or must be provided in Initialization Mode and can be changed in Event Mode.
aperiodic	changing	The Bus Communication Point interval must be provided in Initialization Mode and can be changed in Event Mode if this Clock ticked.
aperiodic	countdown	The Bus Communication Point interval must be provided in Initialization Mode and can be changed in every Event Mode.

Network FMUs using a time-based Tx_Clock variable should set the Co-Simulation attribute canHandleVariableCommunicationStepSize = "true" in the model description file, since fmi3DoStep is typically called with variable communicationStepSize.

Triggered Tx Clock Variables

A triggered Clock basically allows to signal events when returning from fmi3DoStep either by using an Early Return or when the requested communication point at \(t_{i+1}\) was reached. Since signaling Tx_Clock events with an early return at \(t < t_{i+1}\) would require to set connected networked FMUs back in time to reach Bus Communication Points synchronously, a triggered Tx_Clock variable must only be set when returning from fmi3DoStep with the earlyReturn argument set to fmi3False. In consequence, Bus Communication Points and regular communication points coincide and take place at the same time. The time of a Bus Communication Point can therefore not be defined independently, but is given by the importer. Pending Tx data shall be signaled by returning from fmi3DoStep with the eventHandlingNeeded arguments set to fmi3True.

Figure 5. Triggered Tx_Clock/Rx_Clock connection.

Rx Clock Variables

The input Clocks (Rx_Clock) shall be triggered Clocks.

Tx/Rx Data Variables

The Tx/Rx variables are of type fmi3Binary and contain multiple Bus Operations, as sent or receive by the FMU. If no Bus Operations shall be sent by a specified Network FMU at a given Bus Communication Point, the size of the corresponding binary Tx_Data variable shall be set to zero. 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

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

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. The following table lists the MIME types to use for the Tx/Rx data variables within a Bus Terminal:

Table 6. Overview of the available MIME types for the supported several bus types.

MIME type	Description
application/org.fmi-standard.fmi-ls-bus.can; version="1.0.0-beta.1"	Binary variables simulating a CAN network including CAN, CAN FD and CAN XL
application/org.fmi-standard.fmi-ls-bus.lin; version="1.0.0-alpha.1"	Binary variables simulating a LIN network
application/org.fmi-standard.fmi-ls-bus.flexray; version="1.0.0-alpha.1"	Binary variables simulating a FlexRay network
application/org.fmi-standard.fmi-ls-bus.ethernet; version="1.0.0-alpha.1"	Binary variables simulating an Ethernet network

As in the table, above the version of a specified bus type is integrated within the MIME type. The MIME type and the associated versioning ensure that only compatible bus types can be connected to each other. The version number marks the set of available operations for a specified bus type. The versioning follows the rules of semantic versioning, as defined in [PW13].

Terminal Definitions

This section defines terminals for network abstraction or "low cut".

Bus Terminal

Each network connected to the FMU must be described in icons/terminalsAndIcons.xml as a <Terminal> element of <fmiTerminalsAndIcons><Terminals>. The attribute name of the <Terminal> must match the name of the specified network [e.g., the name of the CAN channel: Powertrain] within a "low cut". If the specified FMU is connected to more than one network, there shall be exactly one <Terminal> for each network.

Attribute definitions

• terminalKind must be set to org.fmi-ls-bus.network-terminal.

• matchingRule must be set to org.fmi-ls-bus.transceiver.

• name is the network name, e.g., Powertrain, see example and constraints.

Element definitions

• Every Bus Terminal contains exactly four variables each in the role of: Tx_Data, Tx_Clock, Rx_Data or Rx_Clock.

• Variables in the role of Rx_Data, Tx_Data, Rx_Clock and Tx_Clock are exposed in the modelDescription.xml and must be listed as <TerminalMemberVariable> elements, whereby variableName can be freely chosen.

• <TerminalMemberVariable>.memberName defines the role of the variable within the <Terminal> and shall be set to Tx_Data, Tx_Clock, Rx_Data or Rx_Clock.

• Multiple use of the same variable within different Bus Terminals is not allowed.

• There must be no <TerminalStreamMemberVariable> element.

The matchingRule of type org.fmi-ls-bus.transceiver is specified as: Tx_{Data|Clock} variables shall be connected to Rx_{Data|Clock} variables and vice versa, whereby the variable type shall be equal.

The following figure shows a FMU with four variables Tx_Data, Tx_Clock, Rx_Data, Rx_Clock that are aggregated to a <Terminal> named Bus Terminal:

Figure 6. Frame variables and terminals.

Example

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

Example modelDescription.xml for ECU node.

link:examples/X_network4FMI_modelDescription_lowCut.xml[role=include]

The following file shows the <Terminal> related definition:

Example terminalsAndIcons.xml file.

link:examples/X_network4FMI_terminalsAndIcons_lowCut.xml[role=include]

Bus-Specific Details

For each supported bus type, the Layered Standard Bus Protocol is defined. This chapter describes the operations of the Layered Standard Bus Protocol to enable the simulation of supported bus types.

4_4_1_can.adoc

4_4_2_lin.adoc

4_4_3_flexray.adoc

4_4_4_ethernet.adoc

---

1. For details, refer to Functional Mock-up Interface Specification (fmi-standard.org) chapter 2.2.8 Clocks.