service interface StateMachineService

The service interface StateMachineService is provided by State Management for each configured state machine so that a SMControlApplication can specifically request state changes via the method RequestTransition [SWS_SM_00600], [SWS_SM_91107]. The service is offered immediately after successful execution of the start step of the state machine and acknowledges requests without fire-and-forget semantics. However, requests are rejected with specific errors if the passed value is invalid, the transition from the current state is not permitted, or an update or recovery session is active at the same time [SWS_SM_91107].

more ›

Role and system context of the service interface

The service interface StateMachineService is provided by the functional cluster State Management (SM) via a standardized service port [SWS_SM_91021]. According to the formal interface definition [SWS_SM_91022], State Management instantiates and offers this ara::com-based service for each individual configured instance of a StateMachine [SWS_SM_00600].

A SMControlApplication acts as the primary consumer of this interface, interacting directly with the state machine via the service to request state changes SWS StateManagement §9.2.2 “StateMachine service”. While notifications about entered states to regular adaptive applications are primarily provided via the separate service interface StateMachineNotification [SWS_SM_00665], StateMachineService constitutes the active control interface for initiating transitions.

Methods and Invocation Semantics

The interface defines the method RequestTransition, which must be called by the SMControlApplication to effect a state change in the referenced StateMachine [SWS_SM_91107]. The method expects the input parameter TransitionRequest of type TransitionRequestType, which represents the requested transition value within the underlying TransitionRequestTable [SWS_SM_91107], SWS StateManagement §7.x “TransitionRequestTable”.

For RequestTransition, the property Fire & Forget is set to false [SWS_SM_91107]. The calling application thus receives a binding acknowledgment of the request. Interpretation: Within the ara::com proxy-skeleton pattern, feedback is typically expected to be provided via a ara::core::Future or a corresponding result object that resolves on success or transmits a specific error status in case of an error. Question Q-41fa67738672c735 (open)

Lifecycle and State Dependencies

Every ara::com service configured for a StateMachine to be started—including StateMachineService—must be available and offered (Offer) as soon as the ActionListItem "StartStateMachine" has been executed successfully [SWS_SM_00618]. This allows the SMControlApplication to request a transition immediately after successful creation of the state machine, even if the state machine is still processing the initial ActionList at this point in time SWS StateManagement §7.x “StateMachine service interfaces - Offer”.

Offering the service is stopped (StopOffer) as soon as processing to stop the respective state machine takes place [SWS_SM_00619]. Invocations are additionally subject to functional preconditions: If an update session is currently running in the system, initiating state changes is prohibited in principle [SWS_SM_91107].

Error handling and Application Errors

During the execution of RequestTransition, specific Application Errors can occur, which are reported back to the caller by State Management [SWS_SM_91107]:

• kInvalidValue: The passed value is not assigned to any transition in the TransitionRequestTable [SWS_SM_91107].
• kTransitionNotAllowed: The requested state transition is not allowed starting from the current state of the StateMachine [SWS_SM_91107].
• kRecoveryTransitionOngoing: The request is discarded because recovery is currently being executed [SWS_SM_91107].
• kTransitionFailed: An error occurred during the execution of the transition to the target state [SWS_SM_91107].
• kOperationCanceled: The request was aborted because it was superseded by a newer request [SWS_SM_91107].
• kUpdateInProgress: The operation is forbidden because an update session is currently active [SWS_SM_91107].

Sequence diagram: Sequence of a transition request via StateMachineService with offering, success acknowledgment, and error handling. Sources: [SWS_SM_91107], [SWS_SM_00618], SWS StateManagement §7.x “StateMachine service interfaces - Offer”.