aboutsummaryrefslogtreecommitdiffstats
path: root/ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__n_o_d_e__d_i_s.html
blob: 239c315ef536b098f6f411ff04bf4f541fbb0bc6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>UNICENS: Node Discovery</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico">
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="style_html.css" rel="stylesheet" type="text/css" />
<link href="inic.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div class="GlobalWrapper">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr>
  <td><a href="index.html"><img alt="Logo" src="logo.png"/></a></td>
  <td>
   <div id="projectname">UNICENS&#160;<span id="projectnumber">V2.1.0-3491</span></div>
   <div id="projectbrief">User Manual and API Reference</div>
    <div id="searchbox">        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.2 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('_p__u_m__s_t_a_r_t_e_d__n_o_d_e__d_i_s.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Node Discovery </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1>Introduction</h1>
<p>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.</p>
<h1>Initialization</h1>
<p>The application provides the two callback functions of the Node Discovery service.</p>
<div class="fragment"><div class="line"><a class="code" href="struct_ucs___init_data__t.html" title="UNICENS initialization structure used by function Ucs_Init().">Ucs_InitData_t</a> init_data;</div>
<div class="line"></div>
<div class="line"><span class="comment">/* Node Discovery Section */</span>    </div>
<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_a97b13c03602cc54884ae1765c518bd7b.html#a97b13c03602cc54884ae1765c518bd7b" title="The initialization data of the Node Discovery.">nd</a>.<a class="code" href="struct_ucs___nd___init_data__t_a98b9ccad2c6c5fa2edaf472151ee853c.html#a98b9ccad2c6c5fa2edaf472151ee853c" title="Callback function reporting the results of the Node Discovery service.">report_fptr</a> = &amp;App_OnNodeDiscoveryResult;</div>
<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_a97b13c03602cc54884ae1765c518bd7b.html#a97b13c03602cc54884ae1765c518bd7b" title="The initialization data of the Node Discovery.">nd</a>.<a class="code" href="struct_ucs___nd___init_data__t_ab9bc02a84c7daeff234344541d41be62.html#ab9bc02a84c7daeff234344541d41be62" title="Callback function asking for evaluation of the found signature.">eval_fptr</a>   = &amp;App_OnNodeDiscoveryEval;</div>
</div><!-- fragment --><table  class="mns_ic_table">
<tr>
<td id="mns_ic_started">&#160;</td><td>See also <em>Getting Started</em>, section <a class="el" href="_p__u_m__s_t_a_r_t_e_d__i_n_i_t.html">Initialization</a>. </td></tr>
</table>
<dl class="section note"><dt>Note</dt><dd>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.</dd></dl>
<h1>Operation</h1>
<p>The application maintains at least two lists:</p>
<dl>
<dt><em>set_list</em>  </dt>
<dd><p class="startdd">Contains the signatures of the nodes the system shall contain.</p>
<p class="enddd"></p>
</dd>
<dt><em>device_list</em>  </dt>
<dd>Contains the signatures of the nodes detected in the system. </dd>
</dl>
<p>For debuggting purposes it may be useful to have a third list:</p>
<dl>
<dt><em>unknown_list</em>  </dt>
<dd><p class="startdd">Signatures of the nodes which are detected but are not part of the <em>set_list</em>.</p>
<p class="enddd"></p>
</dd>
</dl>
<p>After startup all nodes are initialized and not part of the system. The application starts the Node Discovery service by calling <a class="el" href="group___g___u_c_s___n_o_d_e___d_i_s_c_o_v_e_r_y_ga50a5b00d5bbd1ad324478509dc524eec.html#ga50a5b00d5bbd1ad324478509dc524eec" title="Starts the Node Discovery service.">Ucs_Nd_Start()</a>. It asks every node for its signature (<a class="el" href="struct_ucs___signature__t.html" title="This structure holds the signature of the Hello, Welcome and Signature messages. It supports the sign...">Ucs_Signature_t</a>). 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.</p>
<p>The evaluation has to follow these rules:</p>
<ul>
<li>If the node is not part of the <em>set_list</em>, it is regarded as unknown (<a class="el" href="group___g___u_c_s___n_o_d_e___d_i_s_c_o_v_e_r_y___t_y_p_e_s_gae1f89dbd75e3d76917273450df37ff66.html#ggae1f89dbd75e3d76917273450df37ff66a4ed7307250366668604925bf3650be4c">UCS_ND_CHK_UNKNOWN</a>) and will be ignored.</li>
<li>If the node is part of the <em>set_list</em> and is not yet in the <em>device_list</em>, the Node Discovery Service shall try to add the node to network (<a class="el" href="group___g___u_c_s___n_o_d_e___d_i_s_c_o_v_e_r_y___t_y_p_e_s_gae1f89dbd75e3d76917273450df37ff66.html#ggae1f89dbd75e3d76917273450df37ff66a0c15fbb8aa9ee8dbf0362b9e9a8b6942">UCS_ND_CHK_WELCOME</a>).</li>
<li>If the node is already part of the <em>device_list</em>, there are two possibilities: the node in the <em>device_list</em> experienced a reset or there are two nodes with the same signature. Evaluation result is <a class="el" href="group___g___u_c_s___n_o_d_e___d_i_s_c_o_v_e_r_y___t_y_p_e_s_gae1f89dbd75e3d76917273450df37ff66.html#ggae1f89dbd75e3d76917273450df37ff66acdbc82cdd701e67cdd7520172767ba75">UCS_ND_CHK_UNIQUE</a>. The Node Discovery service will perform further tests.</li>
</ul>
<p>The result of the evaluation is passed as the return value of App_OnNodeDiscoveryEval() (for possible values see <a class="el" href="group___g___u_c_s___n_o_d_e___d_i_s_c_o_v_e_r_y___t_y_p_e_s_gae1f89dbd75e3d76917273450df37ff66.html#gae1f89dbd75e3d76917273450df37ff66">Ucs_Nd_CheckResult_t</a>).</p>
<p>When the Node Discovery process for a certain node is finished, the callback function App_OnNodeDiscoveryResult() is called. Its parameter <b>code</b> informs the application about the result of the node (for possible values see <a class="el" href="group___g___u_c_s___n_o_d_e___d_i_s_c_o_v_e_r_y___t_y_p_e_s_ga6736f9abd905dafe99d1337ac672f94e.html#ga6736f9abd905dafe99d1337ac672f94e">Ucs_Nd_ResCode_t</a>).</p>
<p>The Node Discovery service asks periodically for new nodes. So it will detect nodes which start up slowly and nodes which experienced a reset.</p>
<p>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 <b>signature</b> will be NULL.</p>
<p>If a Netoff event happens, the Node Discovery service stops. It restarts automatically if it detects a NetOn event.</p>
<p>The application can stop the Node Discovery service via <a class="el" href="group___g___u_c_s___n_o_d_e___d_i_s_c_o_v_e_r_y_ga637e441520f7b203e551274f17febfb6.html#ga637e441520f7b203e551274f17febfb6" title="Stops the Node Discovery service.">Ucs_Nd_Stop()</a>.</p>
<p>It is possible to reset all nodes to the initial state they had after startup by calling <a class="el" href="group___g___u_c_s___n_o_d_e___d_i_s_c_o_v_e_r_y_gabab6c431e235fe0211f5f1525f9cff2e.html#gabab6c431e235fe0211f5f1525f9cff2e" title="Initializes all nodes.">Ucs_Nd_InitAll()</a>. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">&copy; 2017 Microchip Technology Inc. All rights reserved. <a href="http://www.microchip.com" target="_blank">www.microchip.com</a></li>
  </ul>
</div>
</body>
<!--
Generated on Mon Apr 3 2017 13:52:59 for UNICENS by
Doxygen 1.8.2
-->
<script language="javascript">
<!--
$('#MSearchResults').wrap('<div style="position: absolute; margin-left: 444px;"></div>');
-->
</script>
</html>