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 // Fulup interface added to support ucs2vol
  45 typedef const struct {
  46     char* name;
  47     int numid;
  48 } UCSI_channelsT;
  49
  50 typedef void (*UCSI_VolumeServiceCB_t)(uint16_t timeout);
  51 UCSI_channelsT *UCSI_Vol_Init (UCSI_Data_t *pPriv, UCSI_VolumeServiceCB_t serviceCB);
  52 uint8_t UCSI_Vol_Set  (UCSI_Data_t *pPriv, int numId, uint8_t volume);
  53 void UCSI_Vol_Service (UCSI_Data_t *pPriv);
  54
  55
  56 /**
  57  * \brief Initializes Unicens Integration module.
  58  * \note Must be called before any other function of this component
  59  *
  60  * \param pPriv - External allocated memory area for this particular
  61  *                instance (static allocated or allocated with malloc)
  62  * \param pTag - Pointer given by the integrator. This pointer will be
  63  *               returned by any callback function of this component
  64  */
  65 void UCSI_Init(UCSI_Data_t *pPriv, void *pTag);
  66
  67
  68 /**
  69  * \brief Executes the given configuration. If already started, all
  70  *        existing local and remote INIC resources will be destroyed
  71  * \note All given pointers must stay valid until this callback is
  72  *       raised: "UCSI_CB_OnStop"
  73  *
  74  * \param pPriv - private data section of this instance
  75  * \param ucsConfig - UCS config handle
  76  * \return true, configuration successfully enqueued, false otherwise
  77  */
  78 bool UCSI_NewConfig(UCSI_Data_t *pPriv, UcsXmlVal_t *ucsConfig);
  79
  80 /**
  81  * \brief Offer the received control data from LLD to Unicens
  82  * \note Call this function only from single context (not from ISR)
  83  * \note This function can be called repeated until it return false
  84  *
  85  * \param pPriv - private data section of this instance
  86  * \param pBuffer - Received bytes from MOST control channel
  87  * \param len - Length of the received data array
  88  * \return true, if the data could be enqueued for processing, remove
  89  *         the data from LLD queue in this case.
  90  *         false, data could not be processed due to lag of resources.
  91  *         In this case do not discard the data. Offer the same
  92  *         data again after UCSI_CB_OnServiceRequired was
  93  *         raised or any time later.
  94  */
  95 bool UCSI_ProcessRxData(UCSI_Data_t *pPriv, const uint8_t *pBuffer, uint16_t len);
  96
  97 /**
  98  * \brief Gives Unicens Integration module time to do its job
  99  * \note Call this function only from single context (not from ISR)
 100  *
 101  * \param pPriv - private data section of this instance
 102  */
 103 void UCSI_Service(UCSI_Data_t *pPriv);
 104
 105
 106 /**
 107  * \brief Call after timer set by UCSI_CB_OnSetServiceTimer
 108  *        expired.
 109  * \note Call this function only from single context (not from ISR)
 110  *
 111  * \param pPriv - private data section of this instance
 112  */
 113 void UCSI_Timeout(UCSI_Data_t *pPriv);
 114
 115 /**
 116  * \brief Sends an AMS message to the control channel
 117  *
 118  * \note Call this function only from single context (not from ISR)
 119  *
 120  * \param pPriv - private data section of this instance
 121  * \param msgId - The AMS message id
 122  * \param targetAddress - The node / group target address
 123  * \param pPayload - The AMS payload to be sent
 124  * \param payloadLen - The length of the AMS payload
 125  *
 126  * \return true, if operation was successful. false if the message could not be sent.
 127  */
 128 bool UCSI_SendAmsMessage(UCSI_Data_t *my, uint16_t msgId, uint16_t targetAddress, uint8_t *pPayload, uint32_t payloadLen);
 129
 130 /**
 131  * \brief Gets the queued AMS message from Unicens stack
 132  *
 133  * \note Call this function only from single context (not from ISR)
 134  * \note This function may be called cyclic or when UCSI_CB_OnAmsMessageReceived was raised
 135  *
 136  * \param pPriv - private data section of this instance
 137  * \param pMsgId - The received AMS message id will be written to this pointer
 138  * \param pSourceAddress - The received AMS source address will be written to this pointer
 139  * \param pPayload - The received AMS payload will be written to this pointer
 140  * \param pPayloadLen - The received AMS payload length will be written to this pointer
 141  *
 142  * \return true, if operation was successful. false if no message got be retrieved.
 143  */
 144 bool UCSI_GetAmsMessage(UCSI_Data_t *my, uint16_t *pMsgId, uint16_t *pSourceAddress, uint8_t **pPayload, uint32_t *pPayloadLen);
 145
 146 /**
 147  * \brief Releases the message memory returned by UCSI_GetAmsMessage.
 148  *
 149  * \note Call this function only from single context (not from ISR)
 150  * \note This function must be called when the data of UCSI_GetAmsMessage has been processed.
 151  *       If this function is not called, UCSI_GetAmsMessage will return always the reference to the same data.
 152  * \note UCSI_Service may also free the data returned by UCSI_GetAmsMessage!
 153  *
 154  * \param pPriv - private data section of this instance
 155  */
 156 void UCSI_ReleaseAmsMessage(UCSI_Data_t *my);
 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 routeId - identifier as given in XML file along with MOST socket
 164  * \param isActive - true, route will become active. false, route will be deallocated
 165  *
 166  * \return true, if route was found and the specific command was enqueued to Unicens.
 167  */
 168 bool UCSI_SetRouteActive(UCSI_Data_t *pPriv, uint16_t routeId, bool isActive);
 169
 170 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
 171 /*                        CALLBACK SECTION                              */
 172 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
 173
 174 /**
 175  * \brief Callback when ever a timestamp is needed
 176  * \note This function must be implemented by the integrator
 177  * \param pTag - Pointer given by the integrator by UCSI_Init
 178  * \return timestamp in milliseconds
 179  */
 180 extern uint16_t UCSI_CB_OnGetTime(void *pTag);
 181
 182
 183 /**
 184  * \brief Callback when the implementer needs to arm a timer.
 185  * \note This function must be implemented by the integrator
 186  * \note After timer expired, call the UCSI_Timeout from service
 187  *       Thread. (Not from callback!)
 188  * \param pTag - Pointer given by the integrator by UCSI_Init
 189  * \param timeout - milliseconds from now on to call back. (0=disable)
 190  */
 191 extern void UCSI_CB_OnSetServiceTimer(void *pTag, uint16_t timeout);
 192
 193
 194 /**
 195  * \brief Callback when ever an Unicens forms a human readable message.
 196  *        This can be error events or when enabled also debug messages.
 197  * \note This function must be implemented by the integrator
 198  * \param pTag - Pointer given by the integrator by UCSI_Init
 199  * \param isError - true, if this message is an important error message. false, user/debug message, not important.
 200  * \param format - Zero terminated format string (following printf rules)
 201  * \param vargsCnt - Amount of parameters stored in "..."
 202  */
 203 extern void UCSI_CB_OnUserMessage(void *pTag, bool isError, const char format[],
 204     uint16_t vargsCnt, ...);
 205
 206
 207 /**
 208  * \brief Callback when ever this instance needs to be serviced.
 209  * \note Call UCSI_Service by your scheduler at the next run
 210  * \note This function must be implemented by the integrator
 211  * \param pTag - Pointer given by the integrator by UCSI_Init
 212  */
 213 extern void UCSI_CB_OnServiceRequired(void *pTag);
 214
 215 /**
 216  * \brief Callback when ever this instance of Unicens wants to send control data to the LLD.
 217  * \note This function must be implemented by the integrator
 218  * \param pTag - Pointer given by the integrator by UCSI_Init
 219  * \param pPayload - Byte array to be sent on the INIC control channel
 220  * \param payloadLen - Length of pPayload in Byte
 221  */
 222 extern void UCSI_CB_OnTxRequest(void *pTag,
 223     const uint8_t *pPayload, uint32_t payloadLen);
 224
 225 /**
 226  * \brief Callback when Unicens instance has been stopped.
 227  * \note This event can be used to free memory holding the resources
 228  *       passed with UCSI_NewConfig
 229  * \note This function must be implemented by the integrator
 230  * \param pTag - Pointer given by the integrator by UCSI_Init
 231  */
 232 extern void UCSI_CB_OnStop(void *pTag);
 233
 234 /**
 235  * \brief Callback when Unicens instance has received an AMS message
 236  * \note This function must be implemented by the integrator
 237  * \note After this callback, call UCSI_GetAmsMessage indirect by setting a flag
 238  * \param pTag - Pointer given by the integrator by UCSI_Init
 239  */
 240 extern void UCSI_CB_OnAmsMessageReceived(void *pTag);
 241
 242 #ifdef __cplusplus
 243 }
 244 #endif
 245
 246 #endif /* UCSI_H_ */