LibItsCam_Functions.ttcn

/**
 *    @author   ETSI / STF405 / STF449 / STF484 / STF517
 *    @version  $Url: https://oldforge.etsi.org/svn/LibIts/tags/20170222_STF527_Final/ttcn/CAM/LibItsCam_Functions.ttcn $
 *              $Id: LibItsCam_Functions.ttcn 1318 2017-01-26 10:20:53Z filatov $
 *    @desc     Module containing common functions for ITS CAM
 *    @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 LibItsCam_Functions {
    
    // LibCommon
    import from LibCommon_Time all;
    import from LibCommon_VerdictControl all;
    import from LibCommon_Sync all;
    
    // LibIts
    import from ITS_Container language "ASN.1:1997" all;
    
    // LibItsCommon
    import from LibItsCommon_Pixits all;
    import from LibItsCommon_Templates all;
    import from LibItsCommon_Functions all;
    import from LibItsCommon_TypesAndValues all;
    
    // LibItsCam
    import from LibItsCam_TestSystem all;
    import from LibItsCam_Templates all;
    import from LibItsCam_TypesAndValues all;
    import from LibItsCam_Pics all;
    import from LibItsCam_Pixits 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) UtCamInitialize p_init) runs on ItsCam {
            
            //deactivate camPort default alts
            vc_camDefaultActive := false;
            
            utPort.send(p_init);
            tc_wait.start;
            alt {
                [] utPort.receive(UtCamResults: { utCamInitializeResult := true }) {
                    tc_wait.stop;
                    log("*** f_utInitializeIut: INFO: IUT initialized ***");
                }
                [] utPort.receive {
                    tc_wait.stop;
                    log("*** f_utInitializeIut: INFO: IUT could not be initialized ***");
                    f_selfOrClientSyncAndVerdict("error", e_error);
                }
                [] tc_wait.timeout {
                    log("*** f_utInitializeIut: INFO: IUT could not be initialized in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
            
            //activate camPort default alts
            vc_camDefaultActive := true;
            
        }
        
        /**
         * @desc    Triggers event from the application layer
         * @param   p_event The event to trigger.
         */
        function f_utTriggerEvent(template (value) UtCamTrigger p_event) runs on ItsCam {
           
            //deactivate camPort default alts
            vc_camDefaultActive := false;
            
            utPort.send(p_event);
            tc_wait.start;
            alt {
                [] utPort.receive(UtCamResults: { utCamTriggerResult := true }) {
                    tc_wait.stop;
                }
                [] utPort.receive {
                    tc_wait.stop;
                }
                [] tc_wait.timeout {
                }
            }
            
            //activate camPort default alts
            vc_camDefaultActive := true;
            
        }
        
        /**
         * @desc    Changes the position of the IUT
         * @param   p_position
         */
        function f_utChangePosition(template (value) UtCamChangePosition p_position) runs on ItsCam {
            
            //deactivate camPort default alts
            vc_camDefaultActive := false;
            
            utPort.send(p_position);
            alt {
                [] utPort.receive(UtCamResults: { utCamChangePositionResult := true}) {
                    tc_wait.stop;
                }
                [] utPort.receive(UtCamResults: { utCamChangePositionResult := ? }) {
                    tc_wait.stop;
                    f_selfOrClientSyncAndVerdict("error", e_error);
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
                    
            //activate camPort default alts
            vc_camDefaultActive := 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 ItsCam {
            
            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 ItsCam {
            
            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(template (value) AcSecPrimitive p_event) runs on ItsCam 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 ItsCam 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(m_acGnssResponseError) {
                    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(in Scenario p_scenario) runs on ItsCam {
            
            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 ItsCam {
            
            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 ItsCam {
            
            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 ItsCam 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,
            boolean p_stopCamPort := true,
            boolean p_deactivateCamDefault := false
        ) runs on ItsCam system ItsCamSystem return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            if (PX_GNSS_SCENARIO_SUPPORT==true and vc_scenarioStarted==true) {
                
                if (p_stopCamPort) {
                    unmap(self:camPort, system:camPort);
                }
                
                if (p_deactivateCamDefault) {
                    vc_camDefaultActive := false;
                }
                
                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);
                    }
                }
                
                if (p_stopCamPort) {
                    map(self:camPort, system:camPort);
                }
                
                if (p_deactivateCamDefault) {
                    vc_camDefaultActive := true;
                }
            }
            return v_ret;
        } // End of function f_acAwaitSpeed
        
        function f_acChangeSpeed(SpeedValue p_deltaSpeedValue) runs on ItsCam {
            
            if (PX_GNSS_SCENARIO_SUPPORT==true and vc_scenarioStarted==true) {
//                f_acTriggerGnssEvent(m_changeScenarioSpeed(p_deltaSpeedValue));
            }
        } // End of function f_acChangeSpeed
        
        function f_acChangeHeading(HeadingValue p_deltaHeadingValue) runs on ItsCam {
            
            if (PX_GNSS_SCENARIO_SUPPORT==true and vc_scenarioStarted==true) {
                f_acTriggerGnssEvent(m_changeScenarioHeading(p_deltaHeadingValue));
            }
        } // End of function f_acChangeHeading
        
        function f_acAwaitTimeInRunningScenario(
            integer p_time,
            boolean p_stopOnCamMessage := true
        ) runs on ItsCam 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 {
                    [p_stopOnCamMessage] camPort.check(receive(mw_camInd ( mw_camMsg_any ))) {
                        tc_ac.stop;
                    }
                    [] 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 camConfigurationFunctions {
        
        /**
         * @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 ItsCam system ItsCamSystem {
            
            map(self:utPort, system:utPort);
            map(self:acPort, system:acPort);
            map(self:camPort, system:camPort);
            f_connect4SelfOrClientSync();
            
            // Initialise secured mode
            f_initialiseSecuredMode(p_certificateId); 
            
        } // End of function f_cfUp
        
        /**
         * @desc    Deletes default configuration 
         */
        function f_cfDown() runs on ItsCam system ItsCamSystem {
            
            // Initialise secured mode
            f_uninitialiseSecuredMode();
            
            unmap(self:camPort, system:camPort);
            
            f_acStopScenario();
            unmap(self:utPort, system:utPort);
            unmap(self:acPort, system:acPort);
            f_disconnect4SelfOrClientSync();
            
        } // End of function f_cfDown
        
    } // End of camConfigurationFunctions
    
    group defaults {
    
        /**
         * @desc    basic default behaviour handling
         */    
        altstep a_default() runs on ItsCam {
            
            [vc_camDefaultActive] camPort.receive(mw_camInd ( mw_camMsg_any )){ 
                log("*** a_default: INFO: CAM message received in default ***");
                vc_camReceived := true;
                repeat;
            }
            [vc_camDefaultActive] camPort.receive {
                log("*** a_default: ERROR: event received on CAM port in default ***");
                f_selfOrClientSyncAndVerdict("error", e_error);
            }
            [] acPort.receive(AdapterControlResults: { acGnssTimeReached := ? }) {
                log("*** a_default: INFO: TimeReached event received on AC port in default ***");
                repeat;
            }
            [] acPort.receive(AdapterControlResults: { acGnssSpeedReached := ? }) {
                log("*** a_default: INFO: SpeedReached event received on AC port in default ***");
                repeat;
            }
            [] acPort.receive(AdapterControlResults: { acGnssDistanceCovered := ? }) {
                log("*** a_default: INFO: DistanceCovered event received on AC port in default ***");
                repeat;
            }
            [] acPort.receive {
                tc_ac.stop;
                log("*** " & __SCOPE__ & ": ERROR: Received unexpected message ***");
                f_selfOrClientSyncAndVerdict("error", e_error);
            }
            [] any timer.timeout {
                log("*** a_default: INCONC: a timer expired in default ***"); 
                f_selfOrClientSyncAndVerdict("error", e_timeout);
            }
            [] a_shutdown() {
                f_poDefault();
                f_cfDown();
                log("*** a_default: INFO: TEST COMPONENT NOW STOPPING ITSELF! ***");
                stop;   
            }
        }//end altstep a_basicDefault
        
        /**
         * @desc The default for handling upper tester messages.
         */
        altstep a_utDefault() runs on ItsCam {
            var UtCamEventInd v_event;
            [] utPort.receive(UtCamEventInd:?) -> value v_event {
                //store every upper tester indication received
                vc_utEvents[lengthof(vc_utEvents)] := v_event;
                repeat;
            }
            [] utPort.receive {
                log("*** " & testcasename() & ": INFO: Received unhandled/unknown UT message from IUT ***");
                repeat;
            }
        }
         
    } // End of defaults  
    
    group preambles {
        
        /**
         * @desc The default preamble.
         */
        function f_prDefault() runs on ItsCam {
            vc_default := activate(a_default());
            activate(a_utDefault());
        }
        
        /**
         * @desc    Initialize the IUT
         * @remark  No specific actions specified in the base standard
         */    
        function f_prInitialState(
                                  in Scenario p_scenario := e_staticPosition,
                                  in boolean p_awaitInitialCAM := true,
                                  in template (value) UtCamInitialize p_camInitialize := m_camInitialize,
                                  in boolean p_awaitTimeInRunningScenario := true 
        ) runs on ItsCam {
            
            f_utInitializeIut(p_camInitialize);
            
            f_prDefault();
            
            f_acLoadScenario(p_scenario);
            
            //Allow burst mode at the beginning
            f_sleep(1.0);
            
            camPort.clear;
            
            f_acStartScenario();
            if (p_awaitTimeInRunningScenario) {
                f_acAwaitTimeInRunningScenario(f_getTimeForGpsFix());
            }
            
            if (p_awaitInitialCAM) {
                tc_ac.start;
                alt {
                    [] camPort.receive(mw_camInd ( mw_camMsg_any )){
                        tc_ac.stop;                        
                        log("*** " & testcasename() & ": INFO: Received initial CAM ***");
                    }
                    [] tc_ac.timeout {
                        log("*** " & testcasename() & ": INCONC: Initial CAM not received ***");
                        f_selfOrClientSyncAndVerdictPreamble("error", e_timeout);
                    }
                } // End of 'alt' statement
            }
        
        } // End of function f_prInitialState
    
    } // End of preambles

    group postambles {
        
        /**
         * @desc The default postamble.
         */
        function f_poDefault() runs on ItsCam {
        }
        
    } // End of group postambles
    
    group camPositionFunctions {
        
        /**
         * @desc    Compute a position using a reference position, a distance 
         *          and an orientation 
         * 
         * @param p_referencePosition The base reference position.
         * @param p_offSet Distance to the reference position (in meter).
         * 
         * @return The new reference position.
         */
        function f_computePositionUsingDistance(in ReferencePosition p_referencePosition, in float p_offSet) return ReferencePosition {
            var ReferencePosition v_referencePosition := p_referencePosition;
            
            log("*** f_computePositionUsingDistance: INFO: calling fx_computePositionUsingDistance() ***");
            fx_computePositionUsingDistance(
                p_referencePosition.latitude,
                p_referencePosition.longitude,
                p_offSet,
                p_referencePosition.positionConfidenceEllipse.semiMajorOrientation,
                v_referencePosition.latitude,
                v_referencePosition.longitude
            );
            return v_referencePosition;
        }
        
        /**
         * @desc    Compute distance between two points
         * @param   p_pointA    First point
         * @param   p_pointB    Second point
         * @return  Computed distance in meters
         * @see     fx_computeDistance
         */
        function f_distance(
            in ReferencePosition p_pointA,
            in ReferencePosition p_pointB
        ) return float {
            return fx_computeDistance(p_pointA.latitude, p_pointA.longitude, p_pointB.latitude, p_pointB.longitude);
        }
        
    } // end group camPositionFunctions

    group camAuxilaryFunctions {
        
        function f_changeSpeed(SpeedValue p_deltaSpeedValue) runs on ItsCam {
            if (PX_GNSS_SCENARIO_SUPPORT == false) {
                f_utTriggerEvent(m_changeSpeed(p_deltaSpeedValue));
            }
            else {
                f_acChangeSpeed(p_deltaSpeedValue);
            }
        }
        
        function f_changeHeading(HeadingValue p_deltaHeadingValue) runs on ItsCam {
            if (PX_GNSS_SCENARIO_SUPPORT == false) {
                f_utTriggerEvent(m_changeHeading(p_deltaHeadingValue));
            }
            else {
                f_acChangeHeading(p_deltaHeadingValue);
            }
        }
        
    } // End group camAuxilaryFunctions
    
    group camGenerators {
        function f_generateDefaultCam() 
        return octetstring {
            return bit2oct(
                        encvalue(
                            m_camReq(
                                m_camMsg_vehicle(
                                    f_getTsStationId(),
                                    f_getCurrentTime() mod 65536, // See ETSI EN 302 637-2 V1.3.0 - Clause B.3 generationDelatTime
                                    m_tsPosition
                                )
                            )
                        )
                    );
        }
    } // End of group camGenerators  

} // End of LibItsCam_Functions