Networking Management

The UNICENS API provides functions that are used to startup and to shutdown the network. It also provides callback functions to observe MOST network parameters.

Starting Up the Network

For starting up the MOST network out of the off state, function Ucs_Network_Startup() must be called. An optional callback function can be used, to monitor the result of the startup command. The callback must adhere to function signature Ucs_StdResultCb_t. In the following example, the result callback is not used.

if (Ucs_Network_Startup(ucs_inst_ptr, 52U, 0xFFFFU, NULL) != UCS_RET_SUCCESS)
{
    /* Handle synchronous error here... */
}

Shutting Down the Network

For shutting down the MOST network, function Ucs_Network_Shutdown() must be called. It also provides an optional callback function to monitor the result of the shutdown command. The callback must adhere to function signature Ucs_StdResultCb_t. The following example uses Ucs_Network_Shutdown() in combination with the optional result callback.

void foo(void)
{
    ...

    if(Ucs_Network_Shutdown(ucs_inst_ptr, &App_OnNwShutdownResult) != UCS_RET_SUCCESS)
    {
        /* Handle synchronous error here... */
    }
 
    ...
}

void App_OnNwShutdownResult(Ucs_StdResult_t result, void *user_ptr)
{
    if(result.code != UCS_RES_SUCCESS)
    {
        /* Handle asynchronous error here... */
    }
}

Observe Network Information

The UNICENS API provides further information about the Network Status. For this purpose the application has the possibility to register the following callback function during initialization time.

Network Status

Callback function net.cb_fptr() reports information about the Network Status. The function must adhere to signature Ucs_Network_StatusCb_t. The following parameters are reported.

• Events
• Availability
• Availability Information
• Availability Transition Cause
• Node Address
• Node Position
• Max Position
• Packet Bandwidth

Ucs_InitData_t init_data;

/* Register callback function for Network Status */
init_data.network.status.cb_fptr = &App_OnUcsNetworkStatus;

If at least one of the Network Status parameters has been changed, this function is invoked. The first argument of the function is a bitmask. This mask indicates which parameters have been changed since the last function call. If a bit is set the corresponding parameter has been changed since the last update. A simple example implementation is shown below.

void App_OnUcsNetworkStatus(uint16_t change_mask,
                            uint16_t events,
                            Ucs_Network_Availability_t availability,
                            Ucs_Network_AvailInfo_t avail_info,
                            Ucs_Network_AvailTransCause_t avail_trans_cause,
                            uint16_t node_address,
                            uint8_t node_position,
                            uint8_t max_position,
                            uint16_t packet_bw)
{
    /* Check update of third parameter "availability" */
    if((change_mask & UCS_NW_M_AVAIL) != 0U)
    {
        switch(availability)
        {
            case UCS_NW_NOT_AVAILABLE:
                (void)printf("\n\rNetwork Not Available\n\r");
                break;
            case UCS_NW_AVAILABLE:
                (void)printf("\n\rNetwork Available\n\r");
                break;
            default:
                break;
        }
    }
 
    /* Handle other Network Status parameters here! */
}

Notification Bitmasks

Furthermore, it is possible to configure the notifications for Network Status. When initializing the corresponding callback function pointer, the user has the possibility to specify a notification bitmask. This mask indicates for which parameters the notification shall be enabled. If such a bit is set and the corresponding parameter has been changed the notification callback function is invoked.

This is an optional parameter. If the mask is not modified, notifications for all of the parameters are enabled.

The following example shows the usage of the notification bitmask.

Ucs_InitData_t init_data;

/* Register callback function for Network Status */
init_data.network.status.cb_fptr = &App_OnUcsNetworkStatus;
/* Notifications are enabled for parameters "availability" and "node_position" */
init_data.network.status.notification_mask = (UCS_NW_M_AVAIL) | (UCS_NW_M_NODE_POS);

See also API Reference, section Ucs_Network_Status_t.