ucs2-lib/inc/ucs_nodedis.h

   1 /*------------------------------------------------------------------------------------------------*/
   2 /* UNICENS V2.1.0-3491                                                                            */
   3 /* Copyright (c) 2017 Microchip Technology Germany II GmbH & Co. KG.                              */
   4 /*                                                                                                */
   5 /* This program is free software: you can redistribute it and/or modify                           */
   6 /* it under the terms of the GNU General Public License as published by                           */
   7 /* the Free Software Foundation, either version 2 of the License, or                              */
   8 /* (at your option) any later version.                                                            */
   9 /*                                                                                                */
  10 /* This program is distributed in the hope that it will be useful,                                */
  11 /* but WITHOUT ANY WARRANTY; without even the implied warranty of                                 */
  12 /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                                  */
  13 /* GNU General Public License for more details.                                                   */
  14 /*                                                                                                */
  15 /* You should have received a copy of the GNU General Public License                              */
  16 /* along with this program.  If not, see <http://www.gnu.org/licenses/>.                          */
  17 /*                                                                                                */
  18 /* You may also obtain this software under a propriety license from Microchip.                    */
  19 /* Please contact Microchip for further information.                                              */
  20 /*------------------------------------------------------------------------------------------------*/
  21
  22 /*!
  23  * \file
  24  * \brief Internal header file of class CNodeDiscovery.
  25  *
  26  * \cond UCS_INTERNAL_DOC
  27  */
  28 #ifndef UCS_NODEDIS_H
  29 #define UCS_NODEDIS_H
  30
  31 /*------------------------------------------------------------------------------------------------*/
  32 /* Includes                                                                                       */
  33 /*------------------------------------------------------------------------------------------------*/
  34 #include "ucs_exc.h"
  35
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #endif
  41
  42
  43 #define ND_NUM_NODES            40U     /*!< \brief max number of nodes */
  44
  45
  46
  47 /*! \brief Function signature of node evaluation callback used by Node Discovery service.
  48  *
  49  *  The Node Discovery service announces the signature of each node it has found to the
  50  *  application via the evaluation function. In this function the application
  51  *  decides how the Node Discovery service shall proceed with the node.
  52  *  The application maintains two lists:
  53  *
  54  *  <dl>
  55  *      <dt> *set_list* </dt>
  56  *      <dd> Contains the signatures of the nodes the system shall contain
  57  *
  58  *      <dt> *device_list* </dt>
  59  *      <dd> Contains the signatures of the nodes detected in the system
  60  *  </dl>
  61  *
  62  *  The evaluation has to follow these rules:
  63  *  - If the node is not part of the *set_list*, it is regarded as unknown (\ref UCS_ND_CHK_UNKNOWN)
  64  *    and will be ignored.
  65  *  - If the node is part of the *set_list* and is not yet in the *device_list*, the Node Discovery
  66  *    Service shall try to add the node to network (\ref UCS_ND_CHK_WELCOME).
  67  *  - If the node is already part of the *device_list*, there are two possibilities: the node in the
  68  *    *device_list* experienced a reset or there are two nodes with the same signature. Evaluation
  69  *    result is \ref UCS_ND_CHK_UNIQUE. The Node Discovery service will perform further tests.
  70  *
  71  *  \param    self         The instance
  72  *  \param    signature    Signature of the respective node
  73  *  \returns  UCS_ND_CHK_WELCOME  Node is ok, try to add it to the network.
  74  *  \returns  UCS_ND_CHK_UNIQUE   Test if this node is unique.
  75  *  \returns  UCS_ND_CHK_UNKNOWN  Node is unknown, no further action.
  76  *  \ingroup G_UCS_NODE_DISCOVERY
  77  */
  78 typedef Ucs_Nd_CheckResult_t (*Nd_EvalCb_t)(void *self, Ucs_Signature_t *signature);
  79
  80 /*! \brief Function signature of result callback used by Node Discovery service.
  81  *
  82  *  The Node Discovery service reports the result of each node and some system events by
  83  *  this callback function.
  84  *
  85  *  \note The parameter <b>signature</b> will be NULL, if parameter <b>code</b> is
  86  *  \ref UCS_ND_RES_STOPPED, \ref UCS_ND_RES_NETOFF or \ref UCS_ND_RES_ERROR.
  87  *
  88  *  \param   self         The instance
  89  *  \param   code         Result code
  90  *  \param   signature    Signature of the respective node
  91  *  \ingroup G_UCS_NODE_DISCOVERY
  92  */
  93 typedef void (*Nd_ReportCb_t)(void *self, Ucs_Nd_ResCode_t code, Ucs_Signature_t *signature);
  94
  95
  96 /*------------------------------------------------------------------------------------------------*/
  97 /* Structures                                                                                     */
  98 /*------------------------------------------------------------------------------------------------*/
  99 /*! \brief   Structure decribing a node. */
 100 typedef struct Nd_Node_
 101 {
 102     /*bool               available; */      /*!< \brief node available? *//*! i todo RWI:  */
 103     /*uint16_t           node_address; */   /*!< \brief node address used for welcome command */
 104     /*uint8_t            result;     */     /*!< \brief result parameter of Welcome.Result message */
 105     /*uint8_t            version;  */       /*!< \brief version parameter of Hello and Welcome messages */
 106     Ucs_Signature_t    signature;           /*!< \brief signature of the node */
 107     CDlNode            node;                /*!< \brief enables listing */
 108
 109 } Nd_Node;
 110
 111
 112 /*! \brief  Initialization structure of the Node Discovery service. */
 113 typedef struct Nd_InitData_
 114 {
 115     void               *inst_ptr;           /*!< \brief The instance used when invoking the callback functions */
 116     Nd_ReportCb_t       report_fptr;        /*!< \brief Report callback function */
 117     Nd_EvalCb_t         eval_fptr;          /*!< \brief Evaluation callback function */
 118
 119 } Nd_InitData_t;
 120
 121
 122
 123
 124 /*! \brief   Structure of class CNodeDiscovery. */
 125 typedef struct CNodeDiscovery_
 126 {
 127     CInic   *inic;                      /*!< \brief Reference to CInic object */
 128     CExc    *exc;                       /*!< \brief Reference to CExc object */
 129     CBase   *base;                      /*!< \brief Reference to CBase object */
 130
 131     bool    running;                    /*!< \brief Indicates th Node Discovery is running. */
 132     CSingleObserver nd_hello;           /*!< \brief Observes the Hello  result */
 133     CSingleObserver nd_welcome;         /*!< \brief Observes the Welcome result */
 134     CSingleObserver nd_signature;       /*!< \brief Observes the Signature result */
 135     CSingleObserver nd_init;            /*!< \brief Observes the DeviceInit result */
 136
 137     CMaskedObserver nd_terminate;       /*!< \brief Observes events leading to termination */
 138
 139     CObserver       nd_nwstatus;        /*!< \brief Observes the MOST Network status */
 140
 141     CFsm     fsm;                       /*!< \brief Node Discovery state machine  */
 142     CService service;                   /*!< \brief Service instance for the scheduler */
 143
 144     CTimer   timer;                     /*!< \brief timer for monitoring messages */
 145
 146
 147     CDlList  new_list;                  /*!< \brief list of detected nodes */
 148     CDlList  unused_list;               /*!< \brief list of unused node elements */
 149     Nd_Node  nodes[ND_NUM_NODES];       /*!< \brief device nodes */
 150     Ucs_Signature_t  current_sig;       /*!< \brief node which is checked currently */
 151
 152     Exc_WelcomeResult_t   welcome_result;       /*!< \brief buffer for welcome result */
 153     Exc_SignatureStatus_t signature_status;     /*!< \brief buffer for signature status */
 154
 155     bool stop_request;                  /*!< \brief indicates a request to stop node discovery */
 156     bool hello_mpr_request;             /*!< \brief indicates an Hello.Get request due to an MPR event*/
 157     bool hello_neton_request;           /*!< \brief indicates an Hello.Get request due to an NetOn event*/
 158     bool neton;                         /*!< \brief indicates Network availability */
 159
 160     void *cb_inst_ptr;                  /*!< \brief Instance required for callback functions */
 161     Nd_ReportCb_t report_fptr;          /*!< \brief Report callback function */
 162     Nd_EvalCb_t eval_fptr;              /*!< \brief Node evaluation callback function */
 163
 164 }CNodeDiscovery;
 165
 166
 167
 168 /*------------------------------------------------------------------------------------------------*/
 169 /* Prototypes                                                                                     */
 170 /*------------------------------------------------------------------------------------------------*/
 171 void Nd_Ctor(CNodeDiscovery *self,
 172              CInic *inic,
 173              CBase *base,
 174              CExc *exc,
 175              Nd_InitData_t *init_ptr);
 176
 177
 178 extern Ucs_Return_t Nd_Start(CNodeDiscovery *self);
 179 extern Ucs_Return_t Nd_Stop(CNodeDiscovery *self);
 180 extern void Nd_InitAll(CNodeDiscovery *self);
 181
 182
 183
 184
 185 #ifdef __cplusplus
 186 }   /* extern "C" */
 187 #endif
 188
 189 #endif /* UCS_NODEDIS_H */
 190 /*!
 191  * \endcond
 192  */
 193
 194 /*------------------------------------------------------------------------------------------------*/
 195 /* End of file                                                                                    */
 196 /*------------------------------------------------------------------------------------------------*/
 197