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 (unique)
 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  * \brief Enables or disables a route by the given routeId
 172  * \note Call this function only from single context (not from ISR)
 173  *
 174  * \param pPriv - private data section of this instance
 175  * \param targetAddress - targetAddress - The node / group target address
 176  * \param isBurst - true, write blockCount I2C telegrams dataLen with a single call. false, write a single I2C message.
 177  * \param blockCount - amount of blocks to write. Only used when isBurst is set to true.
 178  * \param slaveAddr - The I2C address.
 179  * \param timeout - Timeout in milliseconds.
 180  * \param dataLen - Amount of bytes to send via I2C
 181  * \param pData - The payload to be send.
 182  *
 183  * \return true, if route command was enqueued to Unicens.
 184  */
 185 bool UCSI_I2CWrite(UCSI_Data_t *pPriv, uint16_t targetAddress, bool isBurst, uint8_t blockCount,
 186     uint8_t slaveAddr, uint16_t timeout, uint8_t dataLen, uint8_t *pData);
 187
 188 /**
 189  * \brief Enables or disables a route by the given routeId
 190  * \note Call this function only from single context (not from ISR)
 191  *
 192  * \param pPriv - private data section of this instance
 193  * \param targetAddress - targetAddress - The node / group target address
 194  * \param gpioPinId - INIC GPIO PIN starting with 0 for the first GPIO.
 195  * \param isHighState - true, high state = 3,3V. false, low state = 0V.
 196  *
 197  * \return true, if GPIO command was enqueued to Unicens.
 198  */
 199 bool UCSI_SetGpioState(UCSI_Data_t *pPriv, uint16_t targetAddress, uint8_t gpioPinId, bool isHighState);
 200
 201 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
 202 /*                        CALLBACK SECTION                              */
 203 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
 204
 205 /**
 206  * \brief Callback when ever a timestamp is needed
 207  * \note This function must be implemented by the integrator
 208  * \param pTag - Pointer given by the integrator by UCSI_Init
 209  * \return timestamp in milliseconds
 210  */
 211 extern uint16_t UCSI_CB_OnGetTime(void *pTag);
 212
 213
 214 /**
 215  * \brief Callback when the implementer needs to arm a timer.
 216  * \note This function must be implemented by the integrator
 217  * \note After timer expired, call the UCSI_Timeout from service
 218  *       Thread. (Not from callback!)
 219  * \param pTag - Pointer given by the integrator by UCSI_Init
 220  * \param timeout - milliseconds from now on to call back. (0=disable)
 221  */
 222 extern void UCSI_CB_OnSetServiceTimer(void *pTag, uint16_t timeout);
 223
 224
 225 /**
 226  * \brief Callback when ever an Unicens forms a human readable message.
 227  *        This can be error events or when enabled also debug messages.
 228  * \note This function must be implemented by the integrator
 229  * \param pTag - Pointer given by the integrator by UCSI_Init
 230  * \param isError - true, if this message is an important error message. false, user/debug message, not important.
 231  * \param format - Zero terminated format string (following printf rules)
 232  * \param vargsCnt - Amount of parameters stored in "..."
 233  */
 234 extern void UCSI_CB_OnUserMessage(void *pTag, bool isError, const char format[],
 235     uint16_t vargsCnt, ...);
 236
 237
 238 /**
 239  * \brief Callback when ever this instance needs to be serviced.
 240  * \note Call UCSI_Service by your scheduler at the next run
 241  * \note This function must be implemented by the integrator
 242  * \param pTag - Pointer given by the integrator by UCSI_Init
 243  */
 244 extern void UCSI_CB_OnServiceRequired(void *pTag);
 245
 246 /**
 247  * \brief Callback when ever this instance of Unicens wants to send control data to the LLD.
 248  * \note This function must be implemented by the integrator
 249  * \param pTag - Pointer given by the integrator by UCSI_Init
 250  * \param pPayload - Byte array to be sent on the INIC control channel
 251  * \param payloadLen - Length of pPayload in Byte
 252  */
 253 extern void UCSI_CB_OnTxRequest(void *pTag,
 254     const uint8_t *pPayload, uint32_t payloadLen);
 255
 256 /**
 257  * \brief Callback when Unicens instance has been stopped.
 258  * \note This event can be used to free memory holding the resources
 259  *       passed with UCSI_NewConfig
 260  * \note This function must be implemented by the integrator
 261  * \param pTag - Pointer given by the integrator by UCSI_Init
 262  */
 263 extern void UCSI_CB_OnStop(void *pTag);
 264
 265 /**
 266  * \brief Callback when Unicens instance has received an AMS message
 267  * \note This function must be implemented by the integrator
 268  * \note After this callback, call UCSI_GetAmsMessage indirect by setting a flag
 269  * \param pTag - Pointer given by the integrator by UCSI_Init
 270  */
 271 extern void UCSI_CB_OnAmsMessageReceived(void *pTag);
 272
 273 /**
 274  * \brief Callback when a route become active / inactive.
 275  * \note This function must be implemented by the integrator
 276  * \param pTag - Pointer given by the integrator by UCSI_Init
 277  * \param routeId - identifier as given in XML file along with MOST socket (unique)
 278  * \param isActive - true, if the route is now in use. false, the route is not established.
 279  */
 280 extern void UCSI_CB_OnRouteResult(void *pTag, uint16_t routeId, bool isActive);
 281
 282 /**
 283  * \brief Callback when a INIC GPIO changes its state
 284  * \note This function must be implemented by the integrator
 285  * \param pTag - Pointer given by the integrator by UCSI_Init
 286  * \param nodeAddress - Node Address of the INIC sending the update.
 287  * \param gpioPinId - INIC GPIO PIN starting with 0 for the first GPIO.
 288  * \param isHighState - true, high state = 3,3V. false, low state = 0V.
 289  */
 290 extern void UCSI_CB_OnGpioStateChange(void *pTag, uint16_t nodeAddress, uint8_t gpioPinId, bool isHighState);
 291
 292 #ifdef __cplusplus
 293 }
 294 #endif
 295
 296 #endif /* UCSI_H_ */