Node Discovery

Introduction

The idea behind the Node Discovery service is that nodes are allowed to use the bus only if they meet certain requirements. A central instance detects all nodes and checks if they fit to the intended system. Nodes passing the check get an explicit "invitation" to join the system.

Initialization

The application provides the two callback functions of the Node Discovery service.

Ucs_InitData_t init_data;

/* Node Discovery Section */    
init_data.nd.report_fptr = &App_OnNodeDiscoveryResult;
init_data.nd.eval_fptr   = &App_OnNodeDiscoveryEval;

See also Getting Started, section Initialization.

Note

The function names App_OnNodeDiscoveryResult() and App_OnNodeDiscoveryEval() are just example names. Nevertheless they will be used in the description below to designate the respective functions.

Operation

The application maintains at least two lists:

set_list

Contains the signatures of the nodes the system shall contain.

device_list

Contains the signatures of the nodes detected in the system.

For debuggting purposes it may be useful to have a third list:

unknown_list

Signatures of the nodes which are detected but are not part of the set_list.

After startup all nodes are initialized and not part of the system. The application starts the Node Discovery service by calling Ucs_Nd_Start(). It asks every node for its signature (Ucs_Signature_t). Each detected node will be presented to the application via the callback function App_OnNodeDiscoveryEval(). In this function the application decides how the Node Discovery service shall proceed with the node.

The evaluation has to follow these rules:

• If the node is not part of the set_list, it is regarded as unknown (UCS_ND_CHK_UNKNOWN) and will be ignored.
• If the node is part of the set_list and is not yet in the device_list, the Node Discovery Service shall try to add the node to network (UCS_ND_CHK_WELCOME).
• If the node is already part of the device_list, there are two possibilities: the node in the device_list experienced a reset or there are two nodes with the same signature. Evaluation result is UCS_ND_CHK_UNIQUE. The Node Discovery service will perform further tests.

The result of the evaluation is passed as the return value of App_OnNodeDiscoveryEval() (for possible values see Ucs_Nd_CheckResult_t).

When the Node Discovery process for a certain node is finished, the callback function App_OnNodeDiscoveryResult() is called. Its parameter code informs the application about the result of the node (for possible values see Ucs_Nd_ResCode_t).

The Node Discovery service asks periodically for new nodes. So it will detect nodes which start up slowly and nodes which experienced a reset.

App_OnNodeDiscoveryResult() informs also about general events like NetOff, unexpected error and stop of the Node Discovery service by application command. In these cases the parameter signature will be NULL.

If a Netoff event happens, the Node Discovery service stops. It restarts automatically if it detects a NetOn event.

The application can stop the Node Discovery service via Ucs_Nd_Stop().

It is possible to reset all nodes to the initial state they had after startup by calling Ucs_Nd_InitAll().