LibItsDenm_Functions.ttcn

/**
 *    @author     ETSI / STF449 / STF484 / STF517
 *    @version    $Url: https://oldforge.etsi.org/svn/LibIts/tags/20170222_STF527_Final/ttcn/DENM/LibItsDenm_Functions.ttcn $
 *                $Id: LibItsDenm_Functions.ttcn,v 1.5 2018/05/31 15:57:07 dte Exp $
 *    @desc       Module containing functions for DENM
 *    @copyright   ETSI Copyright Notification
 *                 No part may be reproduced except as authorized by written permission.
 *                 The copyright and the foregoing restriction extend to reproduction in all media.
 *                 All rights reserved.
 *
 */
module LibItsDenm_Functions {
    
    // LibCommon
    import from LibCommon_Sync all;
    import from LibCommon_VerdictControl all;
    import from LibCommon_Time { modulepar PX_TNOAC ; function f_sleep };
    
    // LibIts
    import from ITS_Container language "ASN.1:1997" all;
    import from DENM_PDU_Descriptions language "ASN.1:1997" all;
    
    // LibItsCommon
    import from LibItsCommon_Templates all;
    import from LibItsCommon_TypesAndValues all;
    import from LibItsCommon_Functions all;
    import from LibItsCommon_Pixits all;
    
    // LibIts
    import from LibItsDenm_TestSystem all;
    import from LibItsDenm_TypesAndValues all; 
    import from LibItsDenm_Templates all; 
//    import from LibItsDenm_Pixits all; 
    import from LibItsDenm_Pics all; 
    
    group utFuntions { 
            
        /**
         * @desc    Requests to bring the IUT in an initial state
         * @param   p_init The initialisation to trigger.
         */
        function f_utInitializeIut(template (value) UtDenmInitialize p_init) runs on ItsDenm {
            
            //deactivate denmPort default alts
            vc_denmDefaultActive := false;
            
            utPort.send(p_init);
            tc_wait.start;
            alt {
                [] utPort.receive(UtDenmResults: { utDenmInitializeResult := true }) {
                    tc_wait.stop;
                    log("*** " & testcasename() & ": INFO: IUT initialized ***");
                }
                [] a_utDefault() {
                  //empty on purpose
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
            
            //activate denmPort default alts
            vc_denmDefaultActive := true;
            
        }
        
        /**
         * @desc    Requests to change the IUT with a new pseudonym
         * @param   p_change The change to trigger.
         */
        function f_utChangePseudonym ( template (value) UtDenmChangePseudonym p_change ) runs on ItsDenm {
            
            //deactivate denmPort default alts
            vc_denmDefaultActive := false;
            
            utPort.send(p_change);
            tc_wait.start;
            alt {
                [] utPort.receive(UtDenmResults: { utDenmChangePseudonymResult := true}) {
                    tc_wait.stop;
                    log("*** " & testcasename() & ": INFO: IUT pseudonym changed ***");
                }
                [] utPort.receive(UtDenmResults: { utDenmChangePseudonymResult := false}) {
                    tc_wait.stop;
                    log("*** " & testcasename() & ": INFO: IUT pseudonym unchanged ***");
                    f_selfOrClientSyncAndVerdict("error", e_error);
                }
                [] a_utDefault() {
                  //empty on purpose
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
            
            //activate denmPort default alts
            vc_denmDefaultActive := true;
            
        }
        
        /**
         * @desc    Triggers an event from the application layer
         * @param   p_event The event to trigger.
         */
        function f_utTriggerEvent(in template (value) UtDenmTrigger p_event) runs on ItsDenm return ActionID {
            var ActionID v_actionId;
            var UtDenmResults v_result;
            
            //deactivate denmPort default alts
            vc_denmDefaultActive := false;
            
            utPort.send(p_event);
            tc_wait.start;
            alt {
	      [] utPort.receive(UtDenmResults: { utDenmTriggerResult := ? }) -> value v_result {
                    tc_wait.stop;
                    v_actionId := v_result.utDenmTriggerResult.actionId;
                    if ( not v_result.utDenmTriggerResult.result ) {
                        f_selfOrClientSyncAndVerdict("DENM Trigger failed", e_error);
                    }
                }
                [] a_utDefault() {
                  //empty on purpose
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
            
            //activate denmPort default alts
            vc_denmDefaultActive := true;
            
            return v_actionId;
        }
        
        /**
         * @desc    Updates an event at the application layer
         * @param   p_event The event to update.
         */
        function f_utUpdateEvent(template (value) UtDenmUpdate p_event) runs on ItsDenm return ActionID {
            var ActionID v_actionId;
            var UtDenmResults v_result;
            
            //deactivate denmPort default alts
            vc_denmDefaultActive := false;
            
            utPort.send(p_event);
            tc_wait.start;
            alt {
	      [] utPort.receive(UtDenmResults: { utDenmUpdateResult := ? }) -> value v_result {
                    tc_wait.stop;
                    v_actionId := v_result.utDenmUpdateResult.actionId;
                }
                [] a_utDefault() {
                  //empty on purpose
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
            
            //activate denmPort default alts
            vc_denmDefaultActive := true;
            
            return v_actionId;
        }
        
        /**
         * @desc    Terminates an event at the application layer
         * @param   p_event The event to terminate.
         */
        function f_utTerminateEvent(template (value) UtDenmTermination p_event) runs on ItsDenm {
            
            //deactivate denmPort default alts
            vc_denmDefaultActive := false;
            
            utPort.send(p_event);
            tc_wait.start;
            alt {
                [] utPort.receive(UtDenmResults: { utDenmTerminationResult := ?}) {
                    tc_wait.stop;
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
                [] a_utDefault() {
                  //empty on purpose
                }
            }
            
            //activate denmPort default alts
            vc_denmDefaultActive := true;
            
        }
        
        /**
         * @desc    Changes the position of the IUT
         * @param   p_latitude
         * @param   p_longitude
         * @param   p_elevation 
         */
        function f_utChangePosition(template (value) UtDenmChangePosition p_position) runs on ItsDenm {
            
            //deactivate denmPort default alts
            vc_denmDefaultActive := false;
            
            utPort.send(p_position);
            tc_wait.start;
            alt {
                [] utPort.receive(UtDenmResults: { utDenmChangePositionResult := ? }) {
                    tc_wait.stop;
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
                [] a_utDefault() {
                  //empty on purpose
                }
            }
            
            //activate denmPort default alts
            vc_denmDefaultActive := true;
            
        }
        
    } // End of group utFunctions

    group adapterControl {
        
        /**
         * @desc Initialise secure mode if required
         */
        function f_initialiseSecuredMode(
                                         in charstring p_certificateId := PX_CERT_FOR_TS
        ) runs on ItsDenm {
            
            if (PICS_IS_IUT_SECURED == true) {
                
                if(e_success != f_acTriggerSecEvent(m_acEnableSecurity(p_certificateId))) { 
                    log("*** INFO: TEST CASE NOW STOPPING ITSELF! ***");
                    stop;
                }
            }
            
        } // End of function f_initialiseSecuredMode()
        
        function f_uninitialiseSecuredMode() runs on ItsDenm {
            
            if (PICS_IS_IUT_SECURED == true) {
                f_acTriggerSecEvent(m_acDisableSecurity);
            }
            
        } // End of function f_initialiseSecuredMode()
        
        /**
         * @desc    Triggers event in the test system adaptation.
         * @param   p_event The event to trigger
         * @return  FncRetCode
         */
        function f_acTriggerSecEvent(
                                     in template (value) AcSecPrimitive p_event
        ) runs on ItsDenm return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            acPort.send(p_event);
            tc_ac.start;
            alt {
                [] acPort.receive(m_acSecResponseSuccess) {
                    tc_ac.stop;
                }
                [] acPort.receive {
                    tc_ac.stop;
                    log("*** " & __SCOPE__ & ": ERROR: Received unexpected message ***");
                    f_selfOrClientSyncAndVerdict("error", e_error);
                }
                [] tc_ac.timeout {
                    log("*** " & __SCOPE__ & ": ERROR: Timeout while waiting for adapter control event result ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
            
            return v_ret;
        }
        
        /**
         * @desc    Triggers event in the test system adaptation.
         * @param   p_event The event to trigger
         * @return  FncRetCode
         */
        function f_acTriggerGnssEvent(template (value) AcGnssPrimitive p_event) runs on ItsDenm return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            acPort.send(p_event);
            tc_ac.start;
            alt {
                [] acPort.receive(m_acGnssResponseSuccess) {
                    tc_ac.stop;
                }
                [] acPort.receive {
                    tc_ac.stop;
                    log("*** " & __SCOPE__ & ": ERROR: Received unexpected message ***");
                    f_selfOrClientSyncAndVerdict("error", e_error);
                }
                [] tc_ac.timeout {
                    log("*** " & __SCOPE__ & ": ERROR: Timeout while waiting for adapter control event result ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
            
            return v_ret;
        }
        
        /**
         * @desc    Loads the given scenario
         * 
         * @param   p_scenario   The scenario to load.
         */
        function f_acLoadScenario(Scenario p_scenario) runs on ItsDenm {
            
            if (PX_GNSS_SCENARIO_SUPPORT==true) {
                f_acTriggerGnssEvent(m_loadScenario(p_scenario));
            }
        } // End of function f_acLoadScenario
        
        /**
         * @desc    Starts a loaded scenario
         */
        function f_acStartScenario() runs on ItsDenm {
            
            if (PX_GNSS_SCENARIO_SUPPORT==true) {
                f_acTriggerGnssEvent(m_startScenario);
                vc_scenarioStarted := true;
            }
        } // End of function f_acStartScenario
        
        /**
         * @desc    Stops a loaded scenario
         */
        function f_acStopScenario() runs on ItsDenm {
            
            if (PX_GNSS_SCENARIO_SUPPORT==true and vc_scenarioStarted==true) {
                f_acTriggerGnssEvent(m_stopScenario);
                vc_scenarioStarted := false;
            }
        } // End of function f_acStopScenario
        
        function f_acAwaitDistanceCovered(float p_distanceToCover) runs on ItsDenm return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            if (PX_GNSS_SCENARIO_SUPPORT==true and vc_scenarioStarted==true) {
                f_acTriggerGnssEvent(m_distanceToCover(p_distanceToCover));
                
                tc_ac.start(PX_T_GNSS_AWAIT_DISTANCE_COVERED);
                alt {
                    [] acPort.receive(m_acGnssDistanceCoveredSuccess) {
                        tc_ac.stop;
                    }
                    [] acPort.receive(m_acGnssDistanceCoveredError) {
                        tc_ac.stop;
                        log("*** " & __SCOPE__ & ": ERROR: Received unexpected message ***");
                        f_selfOrClientSyncAndVerdict("error", e_error);
                    }
                    [] tc_ac.timeout {
                        log("*** " & __SCOPE__ & ": ERROR: Timeout while waiting for covered distance indication ***");
                        f_selfOrClientSyncAndVerdict("error", e_timeout);
                    }
                }
                
            }
            return v_ret;
        } // End of function f_acAwaitDistanceCovered
        
        function f_acAwaitSpeed(float p_speed, SpeedTrend p_speedTrend := e_accelerate) runs on ItsDenm return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            if (PX_GNSS_SCENARIO_SUPPORT==true and vc_scenarioStarted==true) {
                f_acTriggerGnssEvent(m_awaitSpeed(p_speed, p_speedTrend));
                
                tc_ac.start(PX_T_GNSS_AWAIT_SPEED_REACHED);
                alt {
                    [] acPort.receive(m_acGnssSpeedReachedSuccess) {
                        tc_ac.stop;
                    }
                    [] acPort.receive(m_acGnssSpeedReachedError) {
                        tc_ac.stop;
                        log("*** " & __SCOPE__ & ": ERROR: Received unexpected message ***");
                        f_selfOrClientSyncAndVerdict("error", e_error);
                    }
                    [] tc_ac.timeout {
                        log("*** " & __SCOPE__ & ": ERROR: Timeout while waiting for covered distance indication ***");
                        f_selfOrClientSyncAndVerdict("error", e_timeout);
                    }
                }
                
            }
            return v_ret;
        } // End of function f_acAwaitSpeed
        
        function f_acAwaitTimeInRunningScenario(integer p_time) runs on ItsDenm return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            if (PX_GNSS_SCENARIO_SUPPORT==true and vc_scenarioStarted==true) {
                f_acTriggerGnssEvent(m_timeInRunningScenario(p_time));
                
                tc_ac.start(int2float(p_time)*1.1);
                alt {
                    [] acPort.receive(m_acGnssTimeReachedSuccess) {
                        tc_ac.stop;
                    }
                    [] acPort.receive(m_acGnssTimeReachedError) {
                        tc_ac.stop;
                        log("*** " & __SCOPE__ & ": ERROR: Received unexpected message ***");
                        f_selfOrClientSyncAndVerdict("error", e_error);
                    }
                    [] tc_ac.timeout {
                        log("*** " & __SCOPE__ & ": ERROR: Timeout while waiting for time reached indication ***");
                        f_selfOrClientSyncAndVerdict("error", e_timeout);
                    }
                }
                
            }
            return v_ret;
        } // end f_acAwaitTimeInRunningScenario
        
    } // End of group adapterControl

    group denmConfigurationFunctions {
        
        /**
         * @desc    Setups default configuration   
         * @param   p_certificateId The certificate identifier the TA shall use in case of secured IUT
         */
        function f_cfUp(
                        in charstring p_certificateId := PX_CERT_FOR_TS
        ) runs on ItsDenm system ItsDenmSystem {
            
            map(self:acPort, system:acPort);
            map(self:utPort, system:utPort);
            map(self:denmPort, system:denmPort);
            f_connect4SelfOrClientSync();
            
            // Initialise secured mode
            f_initialiseSecuredMode(p_certificateId); 
            
        } // End of function f_cfUp
        
        /**
         * @desc    Deletes default configuration 
         */
        function f_cfDown() runs on ItsDenm system ItsDenmSystem {
            
            // Initialise secured mode
            f_uninitialiseSecuredMode();
            
            unmap(self:acPort, system:acPort);
            unmap(self:utPort, system:utPort);
            unmap(self:denmPort, system:denmPort);
            f_disconnect4SelfOrClientSync();
            
        } // End of function f_cfDown
        
    } //end denmConfigurationFunctions
    
    group altsteps {
        
        /**
         * @desc The base default.
         */
        altstep a_default() runs on ItsDenm {
            [vc_denmDefaultActive] denmPort.receive(mw_denmInd(mw_denmPdu(mw_anyDenm))) { 
                log("*** " & testcasename() & ": INFO: DENM message received in default ***");
                vc_denmReceived := true;
                repeat;
            }
            [vc_denmDefaultActive] denmPort.receive {
                log("*** " & testcasename() & ": ERROR: Received an unexpected message ***");
                f_selfOrClientSyncAndVerdict("error", e_error);
            }
            [] acPort.receive(AdapterControlResults: { acGnssTimeReached := ?}) {
                log("*** a_default: INFO: event received on AC port in default ***");
                repeat;
            }
            [] acPort.receive(AdapterControlResults: { acGnssSpeedReached := ?}) {
                log("*** a_default: INFO: event received on AC port in default ***");
                repeat;
            }
            [] acPort.receive(AdapterControlResults: { acGnssDistanceCovered := ?}) {
                log("*** a_default: INFO: event received on AC port in default ***");
                repeat;
            }
            [] acPort.receive {
                tc_ac.stop;
                log("*** " & __SCOPE__ & ": ERROR: Received unexpected message ***");
                f_selfOrClientSyncAndVerdict("error", e_error);
            }
            [] tc_wait.timeout {
                log("*** " & testcasename() & ": INCONC: Timeout while awaiting reaction of the IUT prior to Upper Tester action ***");
                f_selfOrClientSyncAndVerdict("error", e_timeout);
            }
            [] tc_ac.timeout {
                log("*** " & testcasename() & ": INCONC: Timeout while awaiting the reception of a message ***");
                f_selfOrClientSyncAndVerdict("error", e_timeout);
            }
            [] a_shutdown() {
                f_poDefault();
                f_cfDown();
                log("*** " & testcasename() & ": INFO: TEST COMPONENT NOW STOPPING ITSELF! ***");
                stop;   
            }
        }
        
        /**
         * @desc The default for handling upper tester messages.
         */
        altstep a_utDefault() runs on ItsDenm {
            var UtDenmEventInd v_event;
            [vc_utDefaultActive] utPort.receive(UtDenmEventInd:?) -> value v_event {
                //store every upper tester indication received
                vc_utEvents[lengthof(vc_utEvents)] := v_event;
                repeat;
            }
            [vc_utDefaultActive] utPort.receive {
                log("*** " & testcasename() & ": INFO: Received unhandled/unknown UT message from IUT ***");
                repeat;
            }
        }
        
    } // end group altsteps
    
    group preambles {
        
        /**
         * @desc The default preamble.
         */
        function f_prDefault() runs on ItsDenm {
            vc_default := activate(a_default());
            activate(a_utDefault());
        }
        
        /**
         * @desc Brings the IUT into an initial state.
         * @return FncRetCode 
         */
        function f_prInitialState(
                                  in Scenario p_scenario := e_staticPosition,
                                  in template (value) UtDenmInitialize p_denmInitialize := m_denmInitialize,
                                  in boolean p_awaitTimeInRunningScenario := true
        ) runs on ItsDenm return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            f_utInitializeIut(p_denmInitialize);
            
            f_acLoadScenario(valueof(p_scenario));
            f_acStartScenario();
            if (p_awaitTimeInRunningScenario) {
                f_acAwaitTimeInRunningScenario(f_getTimeForGpsFix());
            }

            f_prDefault();
            
            return v_ret;
        }
        
    } // end group preambles
    
    group postambles {
        
        /**
         * @desc The default postamble.
         */
        function f_poDefault() runs on ItsDenm {
            var FncRetCode v_ret := e_success;
            f_acStopScenario();
        }
        
        /**
         * @desc Postamble including cancellation of an event.
         * @param p_trigger Indicates if the cancellation have to be raised by the test system(e_ets) 
         *                  or at the application layer of the IUT(e_iut).
         * @param p_actionId The action ID of the event to be cancelled
         */
        function f_poCancelEvent(template (value) Trigger p_trigger, template (value) ActionID p_actionId) 
        runs on ItsDenm {
            var FncRetCode v_ret := e_success;
            
            if (valueof(p_trigger) == e_ets) {
                f_sendDenMessage( m_denmCancellation ( p_actionId , f_getTsStationType( ) ) );
                f_sleep(PX_TNOAC);
            }
            else {
                f_utTerminateEvent(m_utEventCancellation(p_actionId));
            }
            
            f_poDefault();
        }
        
    } // end group postambles
    
    group sendFunctions {
        
        /**
         * @desc Sends a DEN message
         * @param p_sendMsg The DEN message to send.
         * @param p_overrideSeqNo Overrides the sequence number with the stored one. 
         */
        function f_sendDenMessage(template (value) DecentralizedEnvironmentalNotificationMessage p_denm, boolean p_overrideSeqNo := true) runs on ItsDenm return ActionID {

            if (p_overrideSeqNo) {
                p_denm.management.actionID.sequenceNumber := vc_sequenceNo;
            }

            denmPort.send(
                m_denmReq(
                    m_denmPdu(
                        p_denm
                    )
                )
            );
                        
            return valueof(p_denm.management.actionID);
        }
        
    } // end sendFunctions
    
    group receiveFunctions {
        
        /**
         * @desc Awaits a DEN message and returns it
         * @param p_rcvMsg The expected message to be received.
         * @param p_rcvdMsg The received message - OUT.
         */
        function f_awaitDenMessage(in template (present) DenmInd p_rcvMsg, out DenmInd p_rcvdMsg) runs on ItsDenm {
            
            tc_ac.start;
            alt {
                [] denmPort.receive(p_rcvMsg) -> value p_rcvdMsg {
                    tc_ac.stop;
                }
                [] tc_ac.timeout {
                    log("*** " & testcasename() & ": INFO: Timeout while awaiting the reception of a message ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }            
        }
        
    } // end receiveFunctions
    
    group miscellaneousFunctions {
        
        /**
         * @desc Increases the sequence number and handles the special case where the 
         *       sequence number reaches the limit of 65535 and will be reset to 0.
         * @param p_sequenceNumber The sequence number to increase.
         * @return The increased sequence number.
         */
        function f_increaseSequenceNumber(in SequenceNumber p_sequenceNumber) return SequenceNumber {
            // if maximum number of 65535 reached, reset it to 0
            return ((p_sequenceNumber + 1) mod 65536);
        }
        
    } // end group miscellaneousFunctions
    
} // end LibItsDenm_Functions