FlexRay Service API

Using the FlexRay Controller
API and Data Type Reference

Using the FlexRay Controller 

The FlexRay Service API provides an FlexRay bus abstraction through the IFlexrayController interface. A FlexRay controller is created by calling CreateFlexrayController given a controller name and network name:

auto* flexrayController = participant->CreateFlexrayController("FlexRay1", "PowerTrain1");

FlexRay controllers will only communicate within the same network.

Note

The FlexRay service needs a detailed simulation based on the network simulator. Because of the intrinsic complexity within FlexRay, no trivial simulation exists.

Initialization 

Before the FlexRay controller can be used and participate in FlexRay communication cycles, it must be configured, and a startup phase must take place at the beginning of the simulation.

Configuration 

The configuration is performed by setting up a FlexrayControllerConfig and passing it to Configure(). Furthermore, Configure() switches the controller to FlexrayPocState::Ready signaling that it is ready for startup.

The FlexrayControllerConfig consists of global FlexrayClusterParameters and node-specific FlexrayNodeParameters, which are both best set in the participant configuration (see config section FlexrayControllers). Furthermore, the FlexrayControllerConfig contains one or more FlexrayTxBufferConfig instances, which can either be specified in the participant configuration or added manually at runtime. Tx buffers are used to initiate a transmission from one FlexRay controller to another.

The following example configures a FlexRay controller with two FlexrayTxBufferConfig instances specifying two FlexrayFrameEvent instances, which will be sent during simulation. The FlexrayClusterParameters and the FlexrayNodeParameters are assumed to be set in the participant configuration:

std::vector<FlexrayTxBufferConfig> bufferConfigs;
FlexrayTxBufferConfig txConfig;
txConfig.channels = FlexrayChannel::AB;
txConfig.slotId = 10;
txConfig.offset = 0;
txConfig.repetition = 1;
txConfig.hasPayloadPreambleIndicator = false;
txConfig.headerCrc = 5;
txConfig.transmissionMode = FlexrayTransmissionMode::SingleShot;
bufferConfigs.push_back(txConfig);

txConfig.channels = FlexrayChannel::A;
txConfig.slotId = 20;
bufferConfigs.push_back(txConfig);

FlexrayControllerConfig controllerConfig;
controllerConfig.bufferConfigs = bufferConfigs;
controllerConfig.clusterParams = participantConfig.flexrayControllers[0].clusterParameters;
controllerConfig.nodeParams = participantConfig.flexrayControllers[0].nodeParameters;

flexrayController->Configure(controllerConfig);

Note that Configure() should be called in the CommunicationReadyHandler of the LifecycleService.

Startup 

At least two FlexRay controllers are always required for a successful startup in a FlexRay cluster. The two participants responsible for startup are also called cold start nodes. The “leading” cold start node (normally the first node that is in FlexrayPocState::Ready) has to send the Wakeup() command to the other “following” cold start node(s):

leadingColdStartNode->Wakeup();
// The leading controllers FlexrayPocState will change from
// Ready to Wakeup triggering the PocStatusHandler.

The response of the following cold start node must be the AllowColdstart() and Run() command that can be sent in the WakeupHandler callback:

void WakeupHandler(IFlexrayController* controller, const FlexraySymbolEvent& symbol)
{
    followingColdStartNode->AllowColdstart();
    followingColdStartNode->Run();
}

Finally, the leading cold start node has also to respond by sending the same commands after the FlexrayPocState changed from FlexrayPocState::Wakeup to FlexrayPocState::Ready:

if (oldState == FlexrayPocState::Wakeup
    && newState == FlexrayPocState::Ready)
{
    leadingColdStartNode->AllowColdstart();
    leadingColdStartNode->Run();
}

Note that the leading cold start node must send these commands in the next FlexRay cycle and not directly in a handler like the PocStatusHandler.

Tx Buffer Update (Sending FlexRay Messages)

In each FlexRay cycle, data can be sent by using the UpdateTxBuffer(). For this, an existing txBufferIndex, a payload and the payloadDataValid flag must be provided:

std::string payloadString{"FlexRay message"};

FlexrayTxBufferUpdate update;
update.payload.resize(payloadString.size());
update.payloadDataValid = true;
update.txBufferIndex = 0;

std::copy(payloadString.begin(), payloadString.end(), update.payload.begin());

controller->UpdateTxBuffer(update);

To be notified for the success or failure of the transmission, a FrameTransmitHandler should be added:

// Add FrameTransmitHandler to receive FlexRay transmit events from other FlexRay controllers.
auto frameTransmitHandler =
    [](IFlexrayController*, const FlexrayFrameTransmitEvent& ack) {};
flexrayController->AddFrameTransmitHandler(frameTransmitHandler);

Receiving FlexRay Messages 

To receive data from other FlexRay controller, a FrameHandler must be added via AddFrameHandler(), which is called by the FlexRay controller whenever a FlexrayFrameEvent is received:

// Add FrameHandler to receive FlexRay messages from other FlexRay controller.
auto frameHandler =
    [](IFlexrayController*, const FlexrayFrameEvent& msg) {};
flexrayController->AddFrameHandler(frameHandler);

Note

For a successful startup, also the PocStatusHandler, the WakeupHandler, the SymbolHandler and the SymbolTransmitHandler should be added to invoke the different necessary commands.

Receiving POC Status Changes 

The protocol operation control (POC) status is a structure consisting of status variables, sub-states and flags. It is modelled by the FlexrayPocStatusEvent structure. Updates to the controller’s POC status can be monitored using handlers added with a call to AddPocStatusHandler():

// Add a FlexrayPocStatusEvent handler, and handle status changes
flexrayController->AddPocStatusHandler([&oldPoc](IFlexrayController* ctrl, const FlexrayPocStatusEvent& poc) {
    // we might get called even if poc.state was not changed
    if (poc.state != oldPoc.state)
    {
        switch (poc.state)
        {
        case FlexrayPocState::Halt:
            //handle halt
            break;
        case FlexrayPocState::Config:
            // etc.
            break;
        //case FlexrayPocState::...
            //...
        }
    }

    if (poc.freeze)
    {
      //handle freeze
    }

    if (poc.chiHaltRequest)
    {
      //deferred halt was requested ...
    }

    //if(poc....) handle other status changes

    // retain state for next handler invocation
    oldPoc = poc
});

The handler will be invoked whenever the controller’s POC status is updated.

Managing the Event Handlers 

Adding a handler will return a HandlerId which can be used to remove the handler via:

RemoveFrameHandler()
RemoveFrameTransmitHandler()
RemoveWakeupHandler()
RemovePocStatusHandler()
RemoveSymbolHandler()
RemoveSymbolTransmitHandler()
RemoveCycleStartHandler()

API and Data Type Reference 

FlexRay Controller API 

class IFlexrayController

Abstract FlexRay Controller API to be used by vECUs.

Public Types

using CallbackT = std::function<void(IFlexrayController *controller, const MsgT &msg)>: Generic FleyRay callback method.

using FrameHandler = CallbackT<FlexrayFrameEvent>: Callback type to indicate that a FlexRay message has been received. Cf. AddFrameHandler();

using FrameTransmitHandler = CallbackT<FlexrayFrameTransmitEvent>: Callback type to indicate that a FlexrayFrameTransmitEvent has been received. Cf. AddFrameTransmitHandler();

using WakeupHandler = CallbackT<FlexrayWakeupEvent>: Callback type to indicate that a wakeup has been received. Should be answered by a call to Run(). Cf. AddWakeupHandler();

using PocStatusHandler = CallbackT<FlexrayPocStatusEvent>: Callback type to indicate that the POC status (including state variables, modes and error codes) has changed.

using SymbolHandler = CallbackT<FlexraySymbolEvent>: Callback type to indicate that the controller has received a symbol. Cf. AddSymbolHandler();

using SymbolTransmitHandler = CallbackT<FlexraySymbolTransmitEvent>: Callback type to indicate that the controller has sent a symbol. Cf. AddSymbolTransmitHandler();

using CycleStartHandler = CallbackT<FlexrayCycleStartEvent>: Callback type to indicate that a new FlexRay cycle did start. Cf. AddCycleStartHandler();

Public Functions

virtual ~IFlexrayController() = default

virtual void Configure(const FlexrayControllerConfig &config) = 0: Configure the controller and switch to Ready state.

virtual void ReconfigureTxBuffer(uint16_t txBufferIdx, const FlexrayTxBufferConfig &config) = 0: Reconfigure a TX Buffer that was previously setup with IFlexrayController::Configure(const FlexrayControllerConfig&)

virtual void UpdateTxBuffer(const FlexrayTxBufferUpdate &update) = 0

Update the content of a previously configured TX buffer.

A FlexRay message will be sent at the time matching to the configured Slot ID. If the buffer was configured with FlexrayTransmissionMode::SingleShot, the content is sent exactly once. If it is configured as FlexrayTransmissionMode::Continuous, the content is sent repeatedly according to the offset and repetition configuration.

Data Structures 

struct FlexrayFrame

Public Members

FlexrayHeader header: Header flags, slot, crc, and cycle indidcators.

Util::Span<const uint8_t> payload: Raw payload containing 0 to 254 bytes.

struct FlexrayHeader

Public Types

enum Flag

Flag BitMask definition for helper methods.

Values:

enumerator SuFIndicator

enumerator SyFIndicator

enumerator NFIndicator

enumerator PPIndicator

using FlagMask = SilKit_FlexrayHeader_Flag 

Public Members

FlagMask flags = 0

Flags bit map according to FlagMask. Description:

[7-5]: unused
[4]: Reserved bit
[3]: PPIndicator: 0, regular payload; 1, NM vector or message ID
[2]: NFIndicator: 0, no valid payload data and PPIndicator = 0; 1, valid payload data
[1]: SyFIndicator: 0, frame not used for synchronization; 1, frame shall be used for sync
[0]: SuFIndicator: 0, not a startup frame; 1, a startup frame

uint16_t frameId = 0: Slot ID in which the frame was sent: 1 - 2047.

uint8_t payloadLength = 0: Payload length, 7 bits.

uint16_t headerCrc = 0: Header CRC, 11 bits.

uint8_t cycleCount = 0: Cycle in which the frame was sent: 0 - 63.

struct FlexrayFrameEvent

Public Members

std::chrono::nanoseconds timestamp: Time at end of frame transmission.

FlexrayChannel channel: FlexRay channel A or B. (Valid values: FlexrayChannel::A, FlexrayChannel::B).

FlexrayFrame frame: Received FlexRay frame.

struct FlexrayFrameTransmitEvent

Acknowledge for the transmit on the FlexRay bus.

Public Members

std::chrono::nanoseconds timestamp: Time at end of frame transmission.

uint16_t txBufferIndex: Tx buffer, that was used for the transmission.

FlexrayChannel channel: FlexRay channel A or B. (Valid values: FlexrayChannel::A, FlexrayChannel::B).

FlexrayFrame frame: Copy of the FlexRay frame that was successfully transmitted.

struct FlexraySymbolEvent

A FlexRay Symbol as received on the FlexRay bus.

Subclassed by SilKit::Services::Flexray::FlexraySymbolTransmitEvent, SilKit::Services::Flexray::FlexrayWakeupEvent

Public Members

std::chrono::nanoseconds timestamp: End time of symbol reception.

FlexrayChannel channel: FlexRay channel A or B (values: FlexrayChannel::A, FlexrayChannel::B).

FlexraySymbolPattern pattern: The received symbol, e.g. wakeup pattern.

struct FlexraySymbolTransmitEvent : public SilKit::Services::Flexray::FlexraySymbolEvent : Acknowledges the transmission of a FlexraySymbolPattern on a particular channel.

struct FlexrayWakeupEvent : public SilKit::Services::Flexray::FlexraySymbolEvent 

A FlexRay WUS or WUDOP symbol was received on the FlexRay bus.

Public Functions

FlexrayWakeupEvent() = default

inline explicit FlexrayWakeupEvent(const FlexraySymbolEvent &flexraySymbolEvent): Construct a FlexrayWakeupEvent from the FlexraySymbolEvent that triggered the wakeup.

struct FlexrayPocStatusEvent

Protocol Operation Control status as available in the AUTOSAR FlexRay driver model.

This enhances the deprecated struct ControllerStatus by adding members that are available through the Controller Host Interface. AUTOSAR Name: Fr_POCStatusType

Public Members

std::chrono::nanoseconds timestamp: SIL Kit timestamp.

FlexrayPocState state: Status of the Protocol Operation Control (POC).

bool chiHaltRequest: indicates whether a halt request was received from the CHI

bool coldstartNoise: indicates noisy channel conditions during coldstart

bool freeze: indicates that the POC entered a halt state due to an error condition requiring immediate halt.

bool chiReadyRequest: indicates that the CHI requested to enter ready state at the end of the communication cycle.

FlexrayErrorModeType errorMode: indicates the error mode of the POC

FlexraySlotModeType slotMode: indicates the slot mode of the POC

FlexrayStartupStateType startupState: indicates states within the STARTUP mechanism

FlexrayWakeupStatusType wakeupStatus: outcome of the execution of the WAKEUP mechanism

struct FlexrayCycleStartEvent

Indicate the start of a FlexRay cycle.

Public Members

std::chrono::nanoseconds timestamp: Cycle starting time.

uint8_t cycleCounter: Counter of FlexRay cycles.

struct FlexrayControllerConfig

Configure the communication parameters of the FlexRay controller.

Public Members

FlexrayClusterParameters clusterParams: FlexRay cluster parameters.

FlexrayNodeParameters nodeParams: FlexRay node parameters.

std::vector<FlexrayTxBufferConfig> bufferConfigs: FlexRay buffer configs.

struct FlexrayClusterParameters

Protocol relevant global cluster parameters.

Cf. ‘FlexRay Protocol Specification Version 3.0.1’ Appendix B.3.1.1 Parameters.

Public Members

uint8_t gColdstartAttempts: Number of attempts for a cold start before giving up (range 2-31).

uint8_t gCycleCountMax: Max cycle count value in a given cluster (range 7-63, must be an odd integer).

uint16_t gdActionPointOffset: Time offset for a static slot in MacroTicks (MT) (range 1-63).

uint16_t gdDynamicSlotIdlePhase: Duration of the idle phase within a dynamic slot in gdMiniSlots (range 0-2).

uint16_t gdMiniSlot: Duration of a mini slot in MacroTicks (MT) (2-63).

uint16_t gdMiniSlotActionPointOffset: Time offset for a mini slot in MacroTicks (MT) (range 1-31).

uint16_t gdStaticSlot: Duration of a static slot in MacroTicks (MT) (3-664).

uint16_t gdSymbolWindow: Duration of the symbol window in MacroTicks (MT) (range 0-162).

uint16_t gdSymbolWindowActionPointOffset: Time offset for a static symbol windows in MacroTicks (MT) (range 1-63).

uint16_t gdTSSTransmitter: Duration of TSS (Transmission Start Sequence) in gdBits (range 1-15).

uint16_t gdWakeupTxActive: Duration of LOW Phase of a wakeup symbol in gdBit (range 15-60).

uint16_t gdWakeupTxIdle: Duration of the idle of a wakeup symbol in gdBit (45-180).

uint8_t gListenNoise: Upper limit for the startup listen timeout and wakeup listen timeout in the presence of noise. Used as a multiplier of pdListenTimeout (range 2-16).

uint16_t gMacroPerCycle: Number of MacroTicks (MT) per cycle, (range 8-16000).

uint8_t gMaxWithoutClockCorrectionFatal: Threshold used for testing the vClockCorrectionFailed counter (range 1-15).

uint8_t gMaxWithoutClockCorrectionPassive: Threshold used for testing the vClockCorrectionFailed counter (range 1-15).

uint16_t gNumberOfMiniSlots: Number of mini slots (range 0-7988).

uint16_t gNumberOfStaticSlots: Number of static slots in a cycle (range 2-1023).

uint16_t gPayloadLengthStatic: Length of the payload of a static frame in 16-Bits words (range 0-127).

uint8_t gSyncFrameIDCountMax: Max number of distinct sync frame identifiers present in a given cluster. (range 2-15).

struct FlexrayNodeParameters

Protocol relevant global node parameters.

Cf. ‘FlexRay Protocol Specification Version 3.0.1’ Appendix B.3.2 Parameters.

Public Members

uint8_t pAllowHaltDueToClock: Controls the transition to halt state due to clock synchronization errors. (0,1).

uint8_t pAllowPassiveToActive: Required number of consecutive even / odd cycle pairs for normal passive to normal active (range 0-31).

FlexrayChannel pChannels: Channel(s) to which the controller is connected (values FlexrayChannel::A, FlexrayChannel::B, FlexrayChannel::AB).

uint8_t pClusterDriftDamping: Cluster drift damping factor for rate correction in MicroTicks (range 0-10).

FlexrayMicroTick pdAcceptedStartupRange: Allowed deviation for startup frames during integration in MicroTicks (range 29-2743).

FlexrayMicroTick pdListenTimeout: Duration of listen phase in MicroTicks (range 1926-2567692).

uint16_t pKeySlotId: Slot ID of the key slot (range 0-1023, value 0 means that there is no key slot).

uint8_t pKeySlotOnlyEnabled: Shall the node enter key slot only mode after startup. (values 0, 1) (AUTOSAR pSingleSlotEnabled).

uint8_t pKeySlotUsedForStartup: Key slot is used for startup (range 0, 1).

uint8_t pKeySlotUsedForSync: Key slot is used for sync (range 0, 1).

uint16_t pLatestTx: Last mini slot which can be transmitted (range 0-7988).

uint8_t pMacroInitialOffsetA: Initial startup offset for frame reference point on channel A (rang 2-68 MacroTicks (MT)).

uint8_t pMacroInitialOffsetB: Initial startup offset for frame reference point on channel B (rang 2-68 MacroTicks (MT)).

FlexrayMicroTick pMicroInitialOffsetA: Offset between secondary time reference and MT boundary (range 0-239 MicroTicks).

FlexrayMicroTick pMicroInitialOffsetB: Offset between secondary time reference and MT boundary (range 0-239 MicroTicks).

FlexrayMicroTick pMicroPerCycle: Nominal number of MicroTicks in the communication cycle (range 960-1280000).

FlexrayMicroTick pOffsetCorrectionOut: Maximum permissible offset correction value (range 15-16082 MicroTicks).

uint16_t pOffsetCorrectionStart: Start of the offset correction phase within the NIT, (7-15999 MT).

FlexrayMicroTick pRateCorrectionOut: Maximum permissible rate correction value (range 3-3846 MicroTicks).

FlexrayChannel pWakeupChannel: Channel used by the node to send a wakeup pattern (values FlexrayChannel::A, FlexrayChannel::B).

uint8_t pWakeupPattern: Number of repetitions of the wakeup symbol (range 0-63, value 0 or 1 prevents sending of WUP).

FlexrayClockPeriod pdMicrotick: Duration of a FlexRay MicroTick (12.5ns, 25ns or 50ns).

uint8_t pSamplesPerMicrotick: Number of samples per MicroTick (values 1 or 2).

struct FlexrayTxBufferConfig

Configuration of Tx-Buffer, used in struct FlexrayControllerConfig.

Public Members

FlexrayChannel channels: (values FlexrayChannel::A, FlexrayChannel::B, FlexrayChannel::AB)

uint16_t slotId: The slot Id of frame.

uint8_t offset: Base offset for cycle multiplexing (values 0-63).

uint8_t repetition: Repetition for cycle multiplexing (values 1,2,4,8,16,32,64).

bool hasPayloadPreambleIndicator: Set the PPindicator.

uint16_t headerCrc: Header CRC, 11 bits.

FlexrayTransmissionMode transmissionMode: FlexrayTransmissionMode::SingleShot or FlexrayTransmissionMode::Continuous.

struct FlexrayTxBufferUpdate

Update the content of a FlexRay TX-Buffer.

Public Members

uint16_t txBufferIndex: Index of the TX Buffers according to the configured buffers (cf. FlexrayControllerConfig).

bool payloadDataValid: Payload data valid flag.

Util::Span<const uint8_t> payload: Raw payload containing 0 to 254 bytes.

Enumerations and Typedefs 

using SilKit::Services::Flexray::FlexrayMicroTick = SilKit_FlexrayMicroTick : FlexRay micro tick.

enum SilKit::Services::Flexray::FlexrayClockPeriod

Period of the clock (used for micro tick period and sample clock period).

Values:

enumerator T12_5NS: 12.5ns / 80MHz

enumerator T25NS: 25ns / 40MHz

enumerator T50NS: 50ns / 20MHz

enum SilKit::Services::Flexray::FlexrayChannel

Type and constants for the FlexRay channel parameter A, B, or AB.

Values:

enumerator None: Invalid Channel.

enumerator A: Channel A.

enumerator B: Channel B.

enumerator AB: Channel AB.

enum SilKit::Services::Flexray::FlexraySymbolPattern

FlexRay symbols patterns.

Values:

enumerator CasMts: Collision avoidance symbol (CAS) OR media access test symbol (MTS).

enumerator Wus: Wakeup symbol (WUS).

enumerator Wudop: Wakeup During Operation Pattern (WUDOP).

enum SilKit::Services::Flexray::FlexrayTransmissionMode

Transmission mode for FlexRay Tx-Buffer.

Values:

enumerator SingleShot: Send TX Buffer only once.

enumerator Continuous: Send TX Buffer repeatedly.

enum SilKit::Services::Flexray::FlexrayPocState

Protocol Operation Control (POC) state of the FlexRay communication controller AUTOSAR Name: Fr_POCStateType.

Values:

enumerator DefaultConfig: CC expects configuration. Initial state after reset.

enumerator Config: CC is in configuration mode for setting communication parameters.

enumerator Ready: intermediate state for initialization process (after Config).

enumerator Startup: FlexRay startup phase.

enumerator Wakeup: FlexRay wakeup phase.

enumerator NormalActive: Normal operating mode.

enumerator NormalPassive: Operating mode with transient or tolerable errors.

enumerator Halt: CC is halted (caused by the application (FlexrayChiCommand::DEFERRED_HALT) or by a fatal error).

enum SilKit::Services::Flexray::FlexraySlotModeType

Indicates what slot mode the POC is in. AUTOSAR Name: Fr_SlotModeType.

Values:

enumerator KeySlot

enumerator AllPending

enumerator All

enum SilKit::Services::Flexray::FlexrayErrorModeType

Indicates what error mode the POC is in. AUTOSAR Name: Fr_ErrorModeType.

Values:

enumerator Active

enumerator Passive

enumerator CommHalt

enum SilKit::Services::Flexray::FlexrayStartupStateType

Indicates the current substate in the startup procedure. AUTOSAR Name: Fr_StartupStateType.

Values:

enumerator Undefined

enumerator ColdStartListen

enumerator IntegrationColdstartCheck

enumerator ColdStartJoin

enumerator ColdStartCollisionResolution

enumerator ColdStartConsistencyCheck

enumerator IntegrationListen

enumerator InitializeSchedule

enumerator IntegrationConsistencyCheck

enumerator ColdStartGap

enumerator ExternalStartup

enum SilKit::Services::Flexray::FlexrayWakeupStatusType

Indicates the outcome of the wake-up mechanism. AUTOSAR Name: Fr_WakeupStateType.

Values:

enumerator Undefined

enumerator ReceivedHeader

enumerator ReceivedWup

enumerator CollisionHeader

enumerator CollisionWup

enumerator CollisionUnknown

enumerator Transmitted