Skip to content

Commit c50e1b3

Browse files
Benedikt MenneBenedikt Menne
Benedikt Menne
authored and
Benedikt Menne
committed
Add "Getting Started" chapter for FlexRay
1 parent bd0f1c5 commit c50e1b3

File tree

1 file changed

+224
-12
lines changed

1 file changed

+224
-12
lines changed

‎ls-bus-guide/4____network_abstraction.adoc‎

Lines changed: 224 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ This serialization can be done using the provided <<low-cut-can-getting-started-
2727
After the contents of the binary variables have been transferred to another FMU via an FMU importer, they are deserialized again and then processed inside the receiver.
2828

2929
.Create, process and transfer Bus Operations.
30-
[#figure-general-aspects-overview]
30+
[#figure-general-aspects-overview-can]
3131
image::create_process_bus_operations.svg[width=60%, align="center"]
3232

3333
The point in time where Bus Operations are transferred between different FMUs is defined by the usage of `fmi3Clock` variables.
@@ -82,7 +82,7 @@ The further usage of the `fmi3LsBusUtilBufferInfo` variable is discussed later.
8282
====
8383

8484
===== Creating Bus Operations
85-
The header file https://github.com/modelica/fmi-guides/blob/main/ls-bus-guide/headers/fmi3LsBusUtilCan.h[fmi3LsBusUtilCan.h] offers macros for all Bus Operations specified by the layered standard, which minimize the effort required to create and serialize such an operation.
85+
The header file https://github.com/modelica/fmi-ls-bus/blob/main/headers/fmi3LsBusUtilCan.h[fmi3LsBusUtilCan.h] offers macros for all Bus Operations specified by the layered standard, which minimize the effort required to create and serialize such an operation.
8686
The macros are always provided according to the following syntax: `FMI3_LS_BUS_<BusType>_CREATE_OP_<OperationName>`.
8787
Following these rule, the macro for creating a CAN Transmit operation is `FMI3_LS_BUS_CAN_CREATE_OP_CAN_TRANSMIT`.
8888
A macro for creating an operation also assigns it to a buffer described by an `fmi3LsBusUtilBufferInfo` instance.
@@ -423,16 +423,6 @@ Primarily, structures are included here that allow the Bus Operations specified
423423
* https://github.com/modelica/fmi-ls-bus/blob/main/headers/fmi3LsBusUtil.h[fmi3LsBusUtil.h] provides common utility macros and structures for all supported bus types.
424424
* https://github.com/modelica/fmi-ls-bus/blob/main/headers/fmi3LsBusUtilFlexRay.h[fmi3LsBusUtilFlexRay.h] provides FlexRay explicit utility macros.
425425

426-
==== Demos [[low-cut-flexray-demos]]
427-
###TODO###
428-
The following list contains demos, which illustrate both the Bus Simulation as such and Network FMUs of various designs:
429-
430-
* https://github.com/modelica/fmi-guides/tree/main/ls-bus-guide/demos/can-bus-simulation[CAN Bus Simulation]: Represents an exemplary Bus Simulation FMU for CAN.
431-
This Bus Simulation can be used in combination with the other Network FMUs listed below.
432-
433-
* https://github.com/modelica/fmi-guides/tree/main/ls-bus-guide/demos/can-node-triggered-output[CAN Triggered Output]: This demo Network FMU demonstrates sending and receiving multiple CAN Transmit operations using `triggered` output clocks.
434-
435-
436426
===== General Aspects
437427
Bus Operations represent protocol units to be transmitted in the environment of the layered standard based on the https://modelica.github.io/fmi-ls-bus/main/#low-cut-layered-standard-bus-protocol[Layered Standard Bus Protocol].
438428
All FMI variables required for the exchange are grouped by a defined https://modelica.github.io/fmi-ls-bus/main/#low-cut-bus-terminal[Bus Terminal].
@@ -451,3 +441,225 @@ For this reason, the exchange of Bus Operations is always carried out within the
451441
Details about possible entry points regarding the FMI interface will be provided later in this section.
452442
However, it is important to know that due to the resulting decoupling between the generation, processing and transfer of Bus Operations, the need for buffer semantics arises.
453443
This semantics is reflected directly in the structure and handling of the <<low-cut-flexray-getting-started-provided-header-files,header files>> provided.
444+
445+
===== Buffer Handling
446+
For exchanging Bus Operations between FMUs, variables of type `fmi3Binary` type are used.
447+
For this reason, appropriate variables must first be set up within the implementation that represent the content for this exchange.
448+
The buffer variable can be easily initialized in the form of an `fmi3UInt8` array of any size.
449+
It should be noted that the entire buffer size must of course provide enough space for all created Bus Operations during a `fmi3DoStep`.
450+
To simplify our example, the buffers are declared as global variables within the FMU.
451+
452+
Since describing and reading Bus Operations from a simple array can be quite complicated, the common utility headers provide an `fmi3LsBusUtilBufferInfo` entity.
453+
This abstraction represents a kind of view of the underlying buffer array and allows simplified access using additionally provided functionality.
454+
455+
The following program code shows the definition and initialization of a buffer for transmitting (Tx) and receiving (Rx) Bus Operations in the form of an array.
456+
In addition, an `fmi3LsBusUtilBufferInfo` is created for both buffer variables.
457+
Using `FMI3_LS_BUS_BUFFER_INFO_INIT`, the underlying buffer is coupled to the respective `fmi3LsBusUtilBufferInfo` instance.
458+
459+
[source,c]
460+
.Setting up buffering and fmi3LsBusUtilBufferInfo instance
461+
----
462+
#include "fmi3PlatformTypes.h"
463+
#include "fmi3LsBusUtil.h" // <1>
464+
465+
fmi3UInt8 TxBufferFlexRay[2048]; // <2>
466+
fmi3UInt8 RxBufferFlexRay[2048];
467+
fmi3LsBusUtilBufferInfo TxBufferInfoFlexRay; // <3>
468+
fmi3LsBusUtilBufferInfo RxBufferInfoFlexRay;
469+
470+
fmi3Instance fmi3InstantiateCoSimulation(...) {
471+
FMI3_LS_BUS_BUFFER_INFO_INIT(&TxBufferInfoFlexRay, TxBufferFlexRay, sizeof(TxBufferFlexRay)); // <4>
472+
FMI3_LS_BUS_BUFFER_INFO_INIT(&RxBufferInfoFlexRay, RxBufferFlexRay, sizeof(RxBufferFlexRay));
473+
}
474+
----
475+
<1> Necessary include of the fmi3LsBusUtil.h header file.
476+
<2> Definition and initialization of a `fmi3Binary` buffer variable.
477+
<3> Definition of `fmi3LsBusUtilBufferInfo` variable instance.
478+
<4> Coupling of a Buffer and a `fmi3LsBusUtilBufferInfo` variable.
479+
480+
The buffer is always treated by the provided header functionalities using FIFO (First In - First Out) semantics.
481+
The further usage of the `fmi3LsBusUtilBufferInfo` variable is discussed later.
482+
483+
[NOTE]
484+
.Summary
485+
====
486+
* The transfer of Bus Operations must typically be decoupled from creation and processing
487+
* The API provides macros for buffering of Bus Operations in a FIFO manner
488+
====
489+
490+
===== Creating Bus Operations
491+
The header file https://github.com/modelica/fmi-ls-bus/blob/main/headers/fmi3LsBusUtilFlexRay.h[fmi3LsBusUtilFlexRay.h] offers macros for all Bus Operations specified by the layered standard, which minimize the effort required to create and serialize such an operation.
492+
The macros are always provided according to the following syntax: `FMI3_LS_BUS_<BusType>_CREATE_OP_<OperationName>`.
493+
Following these rule, the macro for creating a FlexRay Transmit operation is `FMI3_LS_BUS_FLEXRAY_CREATE_OP_TRANSMIT`.
494+
A macro for creating an operation also assigns it to a buffer described by an `fmi3LsBusUtilBufferInfo` instance.
495+
496+
The following program code shows how to first define the Cycle ID, Slot ID, channel and payload that should be used in the FlexRay Transmit operation.
497+
Afterwards, the `fmi3LsBusUtilBufferInfo` is reset by using `FMI3_LS_BUS_BUFFER_INFO_RESET`.
498+
`FMI3_LS_BUS_BUFFER_INFO_RESET` sets the internal position of the `fmi3LsBusUtilBufferInfo` instance to zero, so that it is essentially emptied and written from the beginning.
499+
This is necessary to ensure that Bus Operations that have already been transmitted are not transmitted again.
500+
`FMI3_LS_BUS_FLEXRAY_CREATE_OP_TRANSMIT` now creates a new FlexRay Transmit operation with the associated parameters such as Cycle ID, Slot ID, channel and payload and adds them directly to the `fmi3LsBusUtilBufferInfo` instance.
501+
Querying the status of a `fmi3LsBusUtilBufferInfo` instance allows you to check whether there is still enough space in the underlying buffer.
502+
In the last step, `FMI3_LS_BUS_BUFFER_LENGTH` is used to check whether there are Bus Operations in the respective `fmi3LsBusUtilBufferInfo` variable that should be transmitted in `Event Mode`.
503+
504+
[source,c]
505+
.Creation of a FlexRay Transmit operation
506+
----
507+
#include "Fmi3LsBusUtilFlexRay.h"
508+
509+
fmi3Status fmi3DoStep(..., eventHandlingNeeded, ...) {
510+
fmi3UInt8 msg[] = "Hey guys"; // <1>
511+
fmi3LsBusFlexRayCycleId cycleId = 1; // <2>
512+
fmi3LsBusFlexRaySlotId slotId = 1; // <2>
513+
514+
/* Reset read/write positions of the BufferInfo variable */
515+
FMI3_LS_BUS_BUFFER_INFO_RESET(&TxBufferInfoFlexRay); // <3>
516+
517+
/* Create a FlexRay Transmit operation to be send */
518+
FMI3_LS_BUS_FLEXRAY_CREATE_OP_TRANSMIT(&TxBufferInfoFlexRay, cycleId,
519+
slotId, FMI3_LS_BUS_FLEXRAY_CHANNEL_A, <options>, sizeof(msg), msg); // <4>
520+
521+
if(!TxBufferInfoFlexRay.status){ // <5>
522+
/* Error: No free buffer space available */
523+
}
524+
525+
...
526+
527+
if(FMI3_LS_BUS_BUFFER_LENGTH(&TxBufferInfoFlexRay) > 0){
528+
*eventHandlingNeeded = fmi3True; // <6>
529+
}
530+
}
531+
----
532+
<1> Creation of FlexRay frame payload.
533+
<2> Definition of Cycle ID and Slot ID.
534+
<3> Resetting of `fmi3LsBusUtilBufferInfo` variable instance.
535+
<4> Creation of a FlexRay Transmit operation and adding it to the specified `fmi3LsBusUtilBufferInfo` variable.
536+
<5> Verify that free buffer space is available.
537+
<6> Signal that `Event Mode` is needed.
538+
539+
According to the same principles, any specified operation can be created using the corresponding macro.
540+
541+
[NOTE]
542+
.Summary
543+
====
544+
* Bus Operations can be created by using the provided FMI3_LS_BUS_<BusType>_CREATE_OP_<OperationName> macros
545+
* The CREATE_OP macros are creating a Bus Operation and updating the given buffer in a single step
546+
====
547+
548+
===== Receiving Bus Operations
549+
The indication whether new operations are pending within the `Rx_Data` variable is done via the `Rx_Clock`.
550+
This clock ticks as soon as new data is available.
551+
The operation-receiving FMU gets the Bus Operations via an `fmi3Binary` variable.
552+
The contents of this variable may then be copied into a buffer described by an `fmi3LsBusUtilBufferInfo` instance using `FMI3_LS_BUS_BUFFER_WRITE`.
553+
554+
The code snipped below shows its usage within the `fmi3SetClock` and `fmi3SetBinary` functions, which an FMU importer calls when setting the concrete `Rx_Data` variable.
555+
556+
[source,c]
557+
.Receiving Bus Operations
558+
----
559+
fmi3Clock RxClock;
560+
fmi3UInt8 RxBufferFlexRay[2048];
561+
fmi3LsBusUtilBufferInfo RxBufferInfoFlexRay;
562+
563+
fmi3Status fmi3SetClock(fmi3Instance instance,
564+
const fmi3ValueReference valueReference[],
565+
size_t nValueReferences,
566+
const fmi3clock values[]) {
567+
...
568+
for (size_t i = 0; i < nValueReferences; i++) {
569+
if (valueReferences[i] == RX_CLOCK_REFERENCE && values[i] == fmi3ClockActive) { // <1>
570+
/* Set an indicator that clock ticked and new Bus Operations arrived */
571+
RxClock = values[i]; // <2>
572+
}
573+
}
574+
...
575+
}
576+
577+
fmi3Status fmi3SetBinary(fmi3Instance instance,
578+
const fmi3ValueReference valueReferences[],
579+
size_t nValueReferences,
580+
const size_t valueSize,
581+
const fmi3Binary value, ...) {
582+
...
583+
for (size_t i = 0; i < nValueReferences; i++) {
584+
if (valueReferences[i] == RX_DATA_REFERENCE && RxClock == fmi3ClockActive) {
585+
FMI3_LS_BUS_BUFFER_WRITE(&RxBufferInfoFlexRay, value[i], valueSize[i]); // <3>
586+
}
587+
}
588+
...
589+
}
590+
----
591+
<1> Check if `Rx_Clock` has ticked.
592+
<2> Store the information for global access within other FMI interface functions.
593+
<3> Create an `fmi3LsBusUtilBufferInfo` instance based on received Bus Operations.
594+
595+
[NOTE]
596+
.Summary
597+
====
598+
* The LS-BUS API provides macros to write received binary data into a given buffer
599+
* The buffer is updated by the `FMI3_LS_BUS_BUFFER_WRITE` macro
600+
* The `FMI3_LS_BUS_BUFFER_WRITE` can be called repeatedly
601+
====
602+
603+
===== Processing of Bus Operations
604+
The Bus Operations must now be processed on the receiving side.
605+
A suitable place for implementation represents `fmi3UpdateDiscreteStates`.
606+
In this case, the `FMI3_LS_BUS_READ_NEXT_OPERATION` macro can be used to successively deserialize all received Bus Operations into the correct operation structure.
607+
After this, they can be further processed.
608+
609+
[source,c]
610+
.Processing received Bus Operations.
611+
----
612+
fmi3Status fmi3UpdateDiscreteStates(...)
613+
{
614+
fmi3LsBusOperationHeader* hdr;
615+
...
616+
if (fmi3ClockActive == RxClock) {
617+
/* Processing of received Bus Operations */
618+
while (FMI3_LS_BUS_READ_NEXT_OPERATION(&RxBufferInfoFlexRay, hdr)) // <1>
619+
{
620+
switch (hdr->type) // <2>
621+
{
622+
case FMI3_LS_BUS_FLEXRAY_OP_TRANSMIT:
623+
fmi3LsBusFlexRayOperationTransmit *receivedTransmitOp // <3>
624+
= (fmi3LsBusFlexRayOperationTransmit*) hdr;
625+
...
626+
}
627+
}
628+
629+
/* Reset clock */
630+
RxClock = fmi3ClockInactive;
631+
632+
/* Reset read/write positions */
633+
FMI3_LS_BUS_BUFFER_INFO_RESET(&RxBufferInfoFlexRay);
634+
}
635+
...
636+
}
637+
638+
----
639+
<1> Read the next operation from the `fmi3LsBusUtilBufferInfo` instance.
640+
<2> Decide which kind of operation needs to be handled.
641+
<3> Cast to the specific operation structure.
642+
643+
[NOTE]
644+
.Summary
645+
====
646+
* Received Bus Operations can be processed by using the `FMI3_LS_BUS_READ_NEXT_OPERATION` macro
647+
* `FMI3_LS_BUS_BUFFER_INFO_RESET` allows to reset the `fmi3LsBusUtilBufferInfo` instance after processing
648+
====
649+
650+
===== Timing [[low-cut-flexray-timing]]
651+
Since FlexRay is a scheduled bus protocol, a time-based approach is essential.
652+
Within the FMI-LS-BUS, a time window has been described in detail for the https://modelica.github.io/fmi-ls-bus/main/#low-cut-flexray-static-segment[static] and the https://modelica.github.io/fmi-ls-bus/main/#low-cut-flexray-dynamic-segment[dynamic segment], indicating when a Network FMU shall provide a Transmit operation.
653+
This means that the Network FMU itself must ensure that a corresponding FlexRay Transmit operation is provided at the correct time.
654+
The function `FMI3_LS_BUS_FLEXRAY_GET_GLOBAL_TIME`, provided via FMI-LS-BUS <<low-cut-flexray-getting-started-provided-header-files,header files>>, offers assistance here.
655+
Using it, the currently pending cycle and macro tick can be calculated based on the current simulation time.
656+
657+
#ToDo: Add a sample for countdown clocks within this chapter#
658+
659+
==== Demos [[low-cut-flexray-demos]]
660+
The following list contains demos, which illustrate both the Bus Simulation as such and Network FMUs of various designs:
661+
662+
* https://github.com/modelica/fmi-guides/tree/main/ls-bus-guide/demos/flexray-bus-simulation[FlexRay Bus Simulation]: Represents an exemplary Bus Simulation FMU for FlexRay.
663+
This Bus Simulation can be used in combination with the other Network FMUs listed below.
664+
665+
* https://github.com/modelica/fmi-guides/tree/main/ls-bus-guide/demos/flexray-node[FlexRay Countdown Clocks]: This demo Network FMU demonstrates startup, sending and receiving multiple Transmit operations using `countdown` clocks.

0 commit comments

Comments
 (0)