ucs2-interface/ucs_interface.h

   1 /*------------------------------------------------------------------------------------------------*/
   2 /* UNICENS Integration Helper Component                                                           */
   3 /* Copyright 2017, Microchip Technology Inc. and its subsidiaries.                                */
   4 /*                                                                                                */
   5 /* Redistribution and use in source and binary forms, with or without                             */
   6 /* modification, are permitted provided that the following conditions are met:                    */
   7 /*                                                                                                */
   8 /* 1. Redistributions of source code must retain the above copyright notice, this                 */
   9 /*    list of conditions and the following disclaimer.                                            */
  10 /*                                                                                                */
  11 /* 2. Redistributions in binary form must reproduce the above copyright notice,                   */
  12 /*    this list of conditions and the following disclaimer in the documentation                   */
  13 /*    and/or other materials provided with the distribution.                                      */
  14 /*                                                                                                */
  15 /* 3. Neither the name of the copyright holder nor the names of its                               */
  16 /*    contributors may be used to endorse or promote products derived from                        */
  17 /*    this software without specific prior written permission.                                    */
  18 /*                                                                                                */
  19 /* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"                    */
  20 /* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE                      */
  21 /* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE                 */
  22 /* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE                   */
  23 /* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL                     */
  24 /* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR                     */
  25 /* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER                     */
  26 /* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,                  */
  27 /* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE                  */
  28 /* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
  29 /*------------------------------------------------------------------------------------------------*/
  30 #ifndef UCSI_H_
  31 #define UCSI_H_
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 #include "ucs_config.h"
  38 #include "ucs-xml/UcsXml.h"
  39
  40 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
  41 /*                            Public API                                */
  42 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
  43
  44 /**
  45  * \brief Initializes UNICENS Integration module.
  46  * \note Must be called before any other function of this component
  47  *
  48  * \param pPriv - External allocated memory area for this particular
  49  *                instance (static allocated or allocated with malloc)
  50  * \param pTag - Pointer given by the integrator. This pointer will be
  51  *               returned by any callback function of this component
  52  */
  53 void UCSI_Init(UCSI_Data_t *pPriv, void *pTag);
  54
  55
  56 /**
  57  * \brief Executes the given configuration. If already started, all
  58  *        existing local and remote INIC resources will be destroyed
  59  * \note All given pointers must stay valid until this callback is
  60  *       raised: "UCSI_CB_OnStop"
  61  *
  62  * \param pPriv - private data section of this instance
  63  * \param ucsConfig - UCS config handle
  64  * \return true, configuration successfully enqueued, false otherwise
  65  */
  66 bool UCSI_NewConfig(UCSI_Data_t *pPriv, UcsXmlVal_t *ucsConfig);
  67
  68 /**
  69  * \brief Offer the received control data from LLD to Unicens
  70  * \note Call this function only from single context (not from ISR)
  71  * \note This function can be called repeated until it return false
  72  *
  73  * \param pPriv - private data section of this instance
  74  * \param pBuffer - Received bytes from MOST control channel
  75  * \param len - Length of the received data array
  76  * \return true, if the data could be enqueued for processing, remove
  77  *         the data from LLD queue in this case.
  78  *         false, data could not be processed due to lag of resources.
  79  *         In this case do not discard the data. Offer the same
  80  *         data again after UCSI_CB_OnServiceRequired was
  81  *         raised or any time later.
  82  */
  83 bool UCSI_ProcessRxData(UCSI_Data_t *pPriv, const uint8_t *pBuffer, uint16_t len);
  84
  85 /**
  86  * \brief Gives UNICENS Integration module time to do its job
  87  * \note Call this function only from single context (not from ISR)
  88  *
  89  * \param pPriv - private data section of this instance
  90  */
  91 void UCSI_Service(UCSI_Data_t *pPriv);
  92
  93
  94 /**
  95  * \brief Call after timer set by UCSI_CB_OnSetServiceTimer
  96  *        expired.
  97  * \note Call this function only from single context (not from ISR)
  98  *
  99  * \param pPriv - private data section of this instance
 100  */
 101 void UCSI_Timeout(UCSI_Data_t *pPriv);
 102
 103 /**
 104  * \brief Sends an AMS message to the control channel
 105  *
 106  * \note Call this function only from single context (not from ISR)
 107  *
 108  * \param pPriv - private data section of this instance
 109  * \param msgId - The AMS message id
 110  * \param targetAddress - The node / group target address
 111  * \param pPayload - The AMS payload to be sent
 112  * \param payloadLen - The length of the AMS payload
 113  *
 114  * \return true, if operation was successful. false if the message could not be sent.
 115  */
 116 bool UCSI_SendAmsMessage(UCSI_Data_t *my, uint16_t msgId, uint16_t targetAddress, uint8_t *pPayload, uint32_t payloadLen);
 117
 118 /**
 119  * \brief Gets the queued AMS message from UNICENS stack
 120  *
 121  * \note Call this function only from single context (not from ISR)
 122  * \note This function may be called cyclic or when UCSI_CB_OnAmsMessageReceived was raised
 123  *
 124  * \param pPriv - private data section of this instance
 125  * \param pMsgId - The received AMS message id will be written to this pointer
 126  * \param pSourceAddress - The received AMS source address will be written to this pointer
 127  * \param pPayload - The received AMS payload will be written to this pointer
 128  * \param pPayloadLen - The received AMS payload length will be written to this pointer
 129  *
 130  * \return true, if operation was successful. false if no message got be retrieved.
 131  */
 132 bool UCSI_GetAmsMessage(UCSI_Data_t *my, uint16_t *pMsgId, uint16_t *pSourceAddress, uint8_t **pPayload, uint32_t *pPayloadLen);
 133
 134 /**
 135  * \brief Releases the message memory returned by UCSI_GetAmsMessage.
 136  *
 137  * \note Call this function only from single context (not from ISR)
 138  * \note This function must be called when the data of UCSI_GetAmsMessage has been processed.
 139  *       If this function is not called, UCSI_GetAmsMessage will return always the reference to the same data.
 140  * \note UCSI_Service may also free the data returned by UCSI_GetAmsMessage!
 141  *
 142  * \param pPriv - private data section of this instance
 143  */
 144 void UCSI_ReleaseAmsMessage(UCSI_Data_t *my);
 145
 146 /**
 147  * \brief Enables or disables a route by the given routeId
 148  * \note Call this function only from single context (not from ISR)
 149  *
 150  * \param pPriv - private data section of this instance
 151  * \param routeId - identifier as given in XML file along with MOST socket (unique)
 152  * \param isActive - true, route will become active. false, route will be deallocated
 153  *
 154  * \return true, if route was found and the specific command was enqueued to UNICENS.
 155  */
 156 bool UCSI_SetRouteActive(UCSI_Data_t *pPriv, uint16_t routeId, bool isActive);
 157
 158 /**
 159  * \brief Enables or disables a route by the given routeId
 160  * \note Call this function only from single context (not from ISR)
 161  *
 162  * \param pPriv - private data section of this instance
 163  * \param targetAddress - targetAddress - The node / group target address
 164  * \param isBurst - true, write blockCount I2C telegrams dataLen with a single call. false, write a single I2C message.
 165  * \param blockCount - amount of blocks to write. Only used when isBurst is set to true.
 166  * \param slaveAddr - The I2C address.
 167  * \param timeout - Timeout in milliseconds.
 168  * \param dataLen - Amount of bytes to send via I2C
 169  * \param pData - The payload to be send.
 170  * \param result_fptr - Callback function notifying the asynchronous result.
 171  * \param request_ptr - User reference which is provided for the asynchronous result.
 172  *
 173  * \return true, if route command was enqueued to UNICENS.
 174  */
 175 bool UCSI_I2CWrite(UCSI_Data_t *pPriv, uint16_t targetAddress, bool isBurst, uint8_t blockCount,
 176     uint8_t slaveAddr, uint16_t timeout, uint8_t dataLen, uint8_t *pData,
 177     Ucsi_ResultCb_t result_fptr, void *request_ptr);
 178
 179 /**
 180  * \brief Enables or disables a route by the given routeId
 181  * \note Call this function only from single context (not from ISR)
 182  *
 183  * \param pPriv - private data section of this instance
 184  * \param targetAddress - targetAddress - The node / group target address
 185  * \param gpioPinId - INIC GPIO PIN starting with 0 for the first GPIO.
 186  * \param isHighState - true, high state = 3,3V. false, low state = 0V.
 187  *
 188  * \return true, if GPIO command was enqueued to UNICENS.
 189  */
 190 bool UCSI_SetGpioState(UCSI_Data_t *pPriv, uint16_t targetAddress, uint8_t gpioPinId, bool isHighState);
 191
 192 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
 193 /*                        CALLBACK SECTION                              */
 194 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
 195
 196 /**
 197  * \brief Callback when ever a timestamp is needed
 198  * \note This function must be implemented by the integrator
 199  * \param pTag - Pointer given by the integrator by UCSI_Init
 200  * \return timestamp in milliseconds
 201  */
 202 extern uint16_t UCSI_CB_OnGetTime(void *pTag);
 203
 204
 205 /**
 206  * \brief Callback when the implementer needs to arm a timer.
 207  * \note This function must be implemented by the integrator
 208  * \note After timer expired, call the UCSI_Timeout from service
 209  *       Thread. (Not from callback!)
 210  * \param pTag - Pointer given by the integrator by UCSI_Init
 211  * \param timeout - milliseconds from now on to call back. (0=disable)
 212  */
 213 extern void UCSI_CB_OnSetServiceTimer(void *pTag, uint16_t timeout);
 214
 215
 216 /**
 217  * \brief Callback when ever an UNICENS forms a human readable message.
 218  *        This can be error events or when enabled also debug messages.
 219  * \note This function must be implemented by the integrator
 220  * \param pTag - Pointer given by the integrator by UCSI_Init
 221  * \param isError - true, if this message is an important error message. false, user/debug message, not important.
 222  * \param format - Zero terminated format string (following printf rules)
 223  * \param vargsCnt - Amount of parameters stored in "..."
 224  */
 225 extern void UCSI_CB_OnUserMessage(void *pTag, bool isError, const char format[],
 226     uint16_t vargsCnt, ...);
 227
 228 /**
 229  * \brief Callback when ever this instance needs to be serviced.
 230  * \note Call UCSI_Service by your scheduler at the next run
 231  * \note This function must be implemented by the integrator
 232  * \param pTag - Pointer given by the integrator by UCSI_Init
 233  */
 234 extern void UCSI_CB_OnServiceRequired(void *pTag);
 235
 236 /**
 237  * \brief Callback when ever this instance of UNICENS wants to send control data to the LLD.
 238  * \note This function must be implemented by the integrator
 239  * \param pTag - Pointer given by the integrator by UCSI_Init
 240  * \param pPayload - Byte array to be sent on the INIC control channel
 241  * \param payloadLen - Length of pPayload in Byte
 242  */
 243 extern void UCSI_CB_OnTxRequest(void *pTag,
 244     const uint8_t *pPayload, uint32_t payloadLen);
 245
 246 /**
 247  * \brief Callback when UNICENS instance has been stopped.
 248  * \note This event can be used to free memory holding the resources
 249  *       passed with UCSI_NewConfig
 250  * \note This function must be implemented by the integrator
 251  * \param pTag - Pointer given by the integrator by UCSI_Init
 252  */
 253 extern void UCSI_CB_OnStop(void *pTag);
 254
 255 /**
 256  * \brief Callback when UNICENS instance has received an AMS message
 257  * \note This function must be implemented by the integrator
 258  * \note After this callback, call UCSI_GetAmsMessage indirect by setting a flag
 259  * \param pTag - Pointer given by the integrator by UCSI_Init
 260  */
 261 extern void UCSI_CB_OnAmsMessageReceived(void *pTag);
 262
 263 /**
 264  * \brief Callback when a route become active / inactive.
 265  * \note This function must be implemented by the integrator
 266  * \param pTag - Pointer given by the integrator by UCSI_Init
 267  * \param routeId - identifier as given in XML file along with MOST socket (unique)
 268  * \param isActive - true, if the route is now in use. false, the route is not established.
 269  */
 270 extern void UCSI_CB_OnRouteResult(void *pTag, uint16_t routeId, bool isActive);
 271
 272 /**
 273  * \brief Callback when a INIC GPIO changes its state
 274  * \note This function must be implemented by the integrator
 275  * \param pTag - Pointer given by the integrator by UCSI_Init
 276  * \param nodeAddress - Node Address of the INIC sending the update.
 277  * \param gpioPinId - INIC GPIO PIN starting with 0 for the first GPIO.
 278  * \param isHighState - true, high state = 3,3V. false, low state = 0V.
 279  */
 280 extern void UCSI_CB_OnGpioStateChange(void *pTag, uint16_t nodeAddress, uint8_t gpioPinId, bool isHighState);
 281
 282 /**
 283  * \brief Callback when nodes are discovered or disappear
 284  * \note This function must be implemented by the integrator
 285  * \param pTag - Pointer given by the integrator by UCSI_Init
 286  * \param code - Report code
 287  * \param nodeAddress - Node Address of the INIC sending the update.
 288  * \param pNode - Reference to the node structure or NULL.
 289  */
 290 extern void UCSI_CB_OnMgrReport(void *pTag, Ucs_MgrReport_t code, uint16_t nodeAddress, Ucs_Rm_Node_t *pNode);
 291
 292 #ifdef __cplusplus
 293 }
 294 #endif
 295
 296 #endif /* UCSI_H_ */