Monitoring PHY Layer Measurements at Any Module

This section describes how to use API functions to monitor PHY layer measurements at any module, even if the modules are not connected to the PHY module via packet streams.

Note: See an example of the API usage in the coverage_area_tracker process model, in sections init4 state exit executives, function block, header block, next_angle exit executives, high_signal exit executives, and low_signal exit executives.

Procedure 4: Monitoring PHY Layer Measurements at Any Module

  1. Get a handle to the PHY module from the client module.

    1.1 Within the client module call oms_wp_phy_module_handle_get(), providing the actual name of the PHY module.

    *Result:* A local handle to the PHY module is created.
    

    Note: Calling this function does not cause any interrupt/event interaction between the client module and the PHY module.

  2. Install the measurement using oms_wp_phy_measure_register_single(). Note the following:

    • This function needs to be called at the fourth simulation event-phase or later.

      Example from the coverage_area_tracker process model init4 state exit executives:

      /* Register a received power measure. Note that the object ID of the cell 			*/
      /* transmitter is associated to this measurement so only the packets sent 	*/
      /* from that node contribute to this measurement.												*/
      oms_wp_phy_measure_register_single(phy_handle,
      								(int) Transmitter_Node_Objid,
      								OmsC_WP_RCV_Power,
      								OMSC_WP_MEASURE_WNDW_SIZE_NONE,
      							coverage_tracker_phy_rcvd_power_measurement_collect_only_one_node);
      
    • This function must indicate the PHY handle, the measure identification code, measure type (e.g., received power, SNR), and the measure window size (in seconds).

    • This function must also indicate the function callback that decides which packets to include in the measurement (see example in function block of the indicated process). This function callback can make use of the oms_wp_phy_measure_entity_get_from_rx_state() to obtain the actual measurement entity that will be updated, as well as oms_wp_phy_support_measurement_write() to write a new measured value into it.

  3. Subscribe to a notification alert when the measurement is above or below a specified threshold value.

    3.1 Use function oms_wp_phy_measure_notification_subscribe(). Be sure to use the same measurement identification code and measurement type used when the measure was installed (in step 2).

    3.2 Specify the threshold value and threshold direction that should trigger the notification. Optionally, use the sub-client ID to assign a code to this particular notification. This is specially useful when more than one notification is subscribed to the same measure, as it allows arriving alerts to be differentiated. The sub-client string is used for debugging purposes, so it can be an empty string if it is not needed.

  4. Monitor the alert.

    Result: The measurement will notify any alerts to the client module using remote interrupts.

    4.1 Use the function oms_wp_phy_notification_handle_get() to evaluate any interrupt arrival and determine if the interrupt corresponded to a notification alert sent by a measurement. This function will capture the notification information, and will return an alert handle (OmsT_WP_Phy_Alert_Handle).

    The alert handle can be evaluated by `oms_wp_phy_alert_handle_valid()` to determine if the interrupt corresponded to a notification alert, in which case this function will return valid. Otherwise it returns false, which happens when the current event does not match the characteristics of a measure notification event (for example, when the current event is not a remote interrupt).
    
    Evaluating the alert handle using `oms_wp_phy_alert_handle_valid()` is specially important when the process model is expecting any other interrupt besides measurement notifications.
    
    > **Note:** In this case, the client module listed as an example (`coverage_area_tracker.pr.m`) does not check for the validity of the alert as it is not expecting other interrupts.
    

    4.2 Read the alert's information.

    After checking the validity of the alert, as described in the previous step, you can read different properties associated with the alert. For example, `oms_wp_phy_alert_threshold_dir_get()` returns the threshold's direction specified in the current alert, `oms_wp_phy_alert_measure_avg_get()` returns the average measure value that triggered the alert, `oms_wp_phy_alert_subclient_id_get()` returns the sub-client ID specified for the current alert, `oms_wp_phy_alert_measure_type_get()` returns the associated measurement type, and so on.
    

End of Procedure 4