Introduction

The Network Supervisor is a central component of the UNICENS Management Library. It is responsible to run certain network procedures in a commonly defined way. The target is to reduce the complexity of an application by automatically handling the API and dependencies of different internal UNICENS and INIC functionalities.

The different Network Supervisor Modes

The Network Supervisor has different Supervisor Modes, which describe a certain usage scenario during runtime. E.g., the Supervisor Normal Operation Mode defines the typical use case of a UNICENS application. It is responsible to startup the network, discovers and initializes remote nodes and triggers the routing management to build activated routes.

The following listing describes the available Supervisor Modes.

Supervisor Normal Operation Mode
The Supervisor is responsible to start the network, handle the node discovery, remote node configuration and triggers routing management. This is the Default Supervisor Mode after initialization if it is not to another mode by the application.
Supervisor Inactive Mode
The Supervisor is responsible to set the network to the state "NotAvailable.Regular".
Supervisor Diagnosis Mode
The Supervisor is responsible to execute the configured Half or Full Duplex System Diagnosis.
Supervisor Programming Mode
The Supervisor is responsible to run programming sequences as specified by the application.
Supervisor Fallback Mode (experimental feature)
The Supervisor is responsible to force the network to the state "NotAvailable.Fallback".

Initialization

The Network Supervisor provides several parameters the application may set during initialization. The most important parameters are callback functions which are notifying about state changes and the so called network descriptor, which is the list of known nodes and routes in the network.

The network descriptor shall at least list the local node (root node). It is required for Normal Operation Mode as well as for Fallback Mode while you may use Inactive, Diagnosis and Programming Mode without a fully specified network descriptor.

void App_Initialize(void)
{
    Ucs_InitData_t init_data;
    Ucs_SetDefaultConfig(&init_data);
    init_data.supv.mode = UCS_SUPV_MODE_INACTIVE;             /* initial supervisor mode */
    init_data.supv.report_mode_fptr = &App_OnSupvReportMode;  /* notification of mode transitions */
    init_data.supv.report_fptr = &App_OnSupvReport;           /* reporting in normal operation */
    init_data.supv.packet_bw = 52U;                           /* bandwidth in normal operation */
    init_data.supv.nodes_list_ptr = &app_nodes[0];            /* network descriptor: */
    init_data.supv.nodes_list_size = APP_NODES_NUM;           /* configuration of known routes */
    init_data.supv.routes_list_ptr = &app_routes[0];          /* and nodes */
    init_data.supv.routes_list_size = APP_ROUTES_NUM;
    /* ... further initialization ... */
    Ucs_Init(ucs_ptr, &init_data, &App_OnInitResult);
}

Transitions to other Supervisor

Set another Supervisor Mode

During runtime the application can set the Network Supervisor to another operation mode by calling the function Ucs_Supv_SetMode(). An example is listed below.

bool App_SetInactiveMode(void)
{
    boot success = false;
    if (Ucs_Supv_SetMode(ucs_ptr, UCS_SUPV_MODE_INACTIVE) == UCS_RET_SUCCESS)
    {
        success = true;
    }
    return success;
}

The setting of Network Supervisor Modes is restricted to certain transitions which are shown in the picture below. As shown there is a special treatment of the Diagnosis Mode and Programming Mode. While both Supervisor Modes are active it is not possible to change the mode by calling Ucs_Supv_SetMode(). Both modes can be seen as processes that return to the Supervisor Inactive Mode after an error occurs or after successful termination.

Reporting of Operation Modes and States

During initialization the application can assign the supv.report_mode_fptr to receive notifications about the Supervisor Mode changes. This is important because of the following reasons:

When running the Supervisor Programming or Diagnosis Mode the Network Supervisor will return automatically to the Supervisor Inactive Mode after successful termination or when the respective mode is terminated by an error. Hence, the application can choose the next Supervisor Mode to execute.
Besides notifying the current Supervisor Mode the reporting function notifies also the current state of the Network Supervisor. The state can be UCS_SUPV_STATE_BUSY or UCS_SUPV_STATE_READY. While this state just has informational character in most of the Supervisor Modes it is important during the Supervisor Inactive Mode. While the state is "busy" in Supervisor Inactive Mode the application is not allowed to set a new Supervisor Mode. The application must wait until "ready" is notified. See also Ucs_Supv_SetMode().

The following example shows the reporting function printing the current Supervisor Mode and state.

static void App_OnSupvReportMode(Ucs_Supv_Mode_t mode, Ucs_Supv_State_t state, void *user_ptr)
{
    const char * mode_str = "UNKNOWN";
    const char * state_str = "UNKNOWN";
    switch (mode)
    {
        case UCS_SUPV_MODE_NORMAL:
            mode_str = "NORMAL_OPERATION";
            break;
        case UCS_SUPV_MODE_INACTIVE:
            mode_str = "INACTIVE";
            break;
        case UCS_SUPV_MODE_FALLBACK:
            mode_str = "FALLBACK";
            break;
        case UCS_SUPV_MODE_DIAGNOSIS:
            mode_str = "DIAGNOSIS";
            break;
        case UCS_SUPV_MODE_PROGRAMMING:
            mode_str = "PROGRAMMING";
            break;
        default:
            break;
    }
    switch (state)
    {
        case UCS_SUPV_STATE_BUSY:
            state_str = "BUSY";
            break;
        case UCS_SUPV_STATE_READY:
            state_str = "READY";
            break;
        default:
            break;
    }
    printf("App_OnSupvModeReport(): MODE=%s, STATE=%s\n", mode_str, state_str);
}

The following table shows the meaning of the Network Supervisor state in the different Supervisor modes.

Mode	Meaning of BUSY	Meaning of READY
Inactive	The target network state "NotAvailable.Regular" is not reached.	The target network state "NotAvailable.Regular" is reached.
Normal Operation	The target network state "Available" is not reached.	The target network state "Available" is not reached.
Diagnosis	Performing initial checks.	The Supervisor Diagnosis mode is now running.
Programming	Performing initial checks.	The Supervisor Programming mode is now running.
Fallback	The target network state "NotAvailable.Fallback" is not reached.	The target network state "NotAvailable.Fallback" is not reached.

Available API in Supervisor Modes

Depending on the current Supervisor Mode the number of available API functions is restricted for the application. The API function will return UCS_RET_ERR_NOT_SUPPORTED in this case. The following table shows which API functions are restricted to certain Supervisor Modes. Only restricted functions are listed.

API Function	Inactive	Normal Operation	Diagnosis	Programming	Fallback
Ucs_Supv_SetMode()	yes	yes	-	-	yes
Ucs_Supv_ProgramNode()	-	-	-	yes	-
Ucs_Supv_ProgramExit()	-	-	-	yes	-
Ucs_Rm_SetRouteActive()	yes	yes	-	-	yes
Ucs_Rm_GetAtdValue()	-	yes	-	-	-
Ucs_Xrm_Stream_SetPortConfig()	yes	yes	-	-	-
Ucs_Xrm_Stream_GetPortConfig()	yes	yes	-	-	-
Ucs_Network_GetFrameCounter()	-	yes	-	-	-
Ucs_Network_GetNodesCount()	yes	yes	-	yes	-
Ucs_AmsTx_AllocMsg()	yes	yes	-	-	-
Ucs_AmsTx_SendMsg()	yes	yes	-	-	-