+

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().

+