-

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.

-