ucs2-interface/ucs_interface.h

   1 /*
   2  * Unicens Integration Helper Component
   3  *
   4  * Copyright (C) 2017 Microchip Technology Germany II GmbH & Co. KG
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  *
  19  * You may also obtain this software under a propriety license from Microchip.
  20  * Please contact Microchip for further information.
  21  *
  22  */
  23 #ifndef UCSI_H_
  24 #define UCSI_H_
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #include "ucs_config.h"
  31 #include "ucs-xml/UcsXml.h"
  32
  33 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
  34 /*                            Public API                                */
  35 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
  36
  37 // Fulup interface added to support ucs2vol
  38 typedef const struct {
  39     char* name;
  40     int numid;
  41 } UCSI_channelsT;
  42
  43 typedef void (*UCSI_VolumeServiceCB_t)(uint16_t timeout);
  44 UCSI_channelsT *UCSI_Vol_Init (UCSI_Data_t *pPriv, UCSI_VolumeServiceCB_t serviceCB);
  45 uint8_t UCSI_Vol_Set  (UCSI_Data_t *pPriv, int numId, uint8_t volume);
  46 void UCSI_Vol_Service (UCSI_Data_t *pPriv);
  47
  48
  49 /**
  50  * \brief Initializes Unicens Integration module.
  51  * \note Must be called before any other function of this component
  52  *
  53  * \param pPriv - External allocated memory area for this particular
  54  *                instance (static allocated or allocated with malloc)
  55  * \param pTag - Pointer given by the integrator. This pointer will be
  56  *               returned by any callback function of this component
  57  */
  58 void UCSI_Init(UCSI_Data_t *pPriv, void *pTag);
  59
  60
  61 /**
  62  * \brief Executes the given configuration. If already started, all
  63  *        existing local and remote INIC resources will be destroyed
  64  * \note All given pointers must stay valid until this callback is
  65  *       raised: "UCSI_CB_OnStop"
  66  *
  67  * \param pPriv - private data section of this instance
  68  * \param ucsConfig - UCS config handle
  69  * \return true, configuration successfully enqueued, false otherwise
  70  */
  71 bool UCSI_NewConfig(UCSI_Data_t *pPriv, UcsXmlVal_t *ucsConfig);
  72
  73 /**
  74  * \brief Offer the received control data from LLD to Unicens
  75  * \note Call this function only from single context (not from ISR)
  76  * \note This function can be called repeated until it return false
  77  *
  78  * \param pPriv - private data section of this instance
  79  * \param pBuffer - Received bytes from MOST control channel
  80  * \param len - Length of the received data array
  81  * \return true, if the data could be enqueued for processing, remove
  82  *         the data from LLD queue in this case.
  83  *         false, data could not be processed due to lag of resources.
  84  *         In this case do not discard the data. Offer the same
  85  *         data again after UCSI_CB_OnServiceRequired was
  86  *         raised or any time later.
  87  */
  88 bool UCSI_ProcessRxData(UCSI_Data_t *pPriv, const uint8_t *pBuffer, uint16_t len);
  89
  90 /**
  91  * \brief Gives Unicens Integration module time to do its job
  92  * \note Call this function only from single context (not from ISR)
  93  *
  94  * \param pPriv - private data section of this instance
  95  */
  96 void UCSI_Service(UCSI_Data_t *pPriv);
  97
  98
  99 /**
 100  * \brief Call after timer set by UCSI_CB_OnSetServiceTimer
 101  *        expired.
 102  * \note Call this function only from single context (not from ISR)
 103  *
 104  * \param pPriv - private data section of this instance
 105  */
 106 void UCSI_Timeout(UCSI_Data_t *pPriv);
 107
 108 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
 109 /*                        CALLBACK SECTION                              */
 110 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
 111
 112 /**
 113  * \brief Callback when ever a timestamp is needed
 114  * \note This function must be implemented by the integrator
 115  * \param pTag - Pointer given by the integrator by UCSI_Init
 116  * \return timestamp in milliseconds
 117  */
 118 extern uint16_t UCSI_CB_OnGetTime(void *pTag);
 119
 120
 121 /**
 122  * \brief Callback when the implementer needs to arm a timer.
 123  * \note This function must be implemented by the integrator
 124  * \note After timer expired, call the UCSI_Timeout from service
 125  *       Thread. (Not from callback!)
 126  * \param pTag - Pointer given by the integrator by UCSI_Init
 127  * \param timeout - milliseconds from now on to call back. (0=disable)
 128  */
 129 extern void UCSI_CB_OnSetServiceTimer(void *pTag, uint16_t timeout);
 130
 131
 132 /**
 133  * \brief Callback when ever an Unicens forms a human readable message.
 134  *        This can be error events or when enabled also debug messages.
 135  * \note This function must be implemented by the integrator
 136  * \param pTag - Pointer given by the integrator by UCSI_Init
 137  * \param format - Zero terminated format string (following printf rules)
 138  * \param vargsCnt - Amount of parameters stored in "..."
 139  */
 140 extern void UCSI_CB_OnUserMessage(void *pTag, const char format[],
 141     uint16_t vargsCnt, ...);
 142
 143
 144 /**
 145  * \brief Callback when ever this instance needs to be serviced.
 146  * \note Call UCSI_Service by your scheduler at the next run
 147  * \note This function must be implemented by the integrator
 148  * \param pTag - Pointer given by the integrator by UCSI_Init
 149  */
 150 extern void UCSI_CB_OnServiceRequired(void *pTag);
 151
 152
 153 /**
 154  * \brief Callback when ever a MOST error message was received.
 155  * \note This function must be implemented by the integrator
 156  * \param pTag - Pointer given by the integrator by UCSI_Init
 157  * \note All following parameters belong to the usual MOST message
 158  */
 159 extern void UCSI_CB_OnMostError(void *pTag, uint16_t sourceAddr,
 160     uint8_t fblock, uint8_t inst, uint16_t function, uint8_t op,
 161     const uint8_t *pPayload, uint32_t payloadLen);
 162
 163
 164 /**
 165  * \brief Callback when ever this instance wants to send a message to INIC.
 166  * \note This function must be implemented by the integrator
 167  * \param pTag - Pointer given by the integrator by UCSI_Init
 168  * \param pPayload - Byte array to be sent on the INIC control channel
 169  * \param payloadLen - Length of pPayload in Byte
 170  */
 171 extern void UCSI_CB_SendMostMessage(void *pTag,
 172     const uint8_t *pPayload, uint32_t payloadLen);
 173
 174 /**
 175  * \brief Callback when Unicens instance has been stopped.
 176  * \note This event can be used to free memory holding the resources
 177  *       passed with UCSI_NewConfig
 178  * \note This function must be implemented by the integrator
 179  * \param pTag - Pointer given by the integrator by UCSI_Init
 180  */
 181 extern void UCSI_CB_OnStop(void *pTag);
 182
 183 /**
 184  * \brief Callback on Unicens management results.
 185  * \note This function must be implemented by the integrator
 186  * \param pTag - Pointer given by the integrator by UCSI_Init
 187  * \param code - Result code
 188  * \param nodeAddress - Node address of the device causing this event
 189  * \param pNode - Pointer to node structure holding details of changed node
 190  */
 191 extern void UCSI_CB_OnMgrReport(void *pTag, Ucs_MgrReport_t code, uint16_t nodeAddress, Ucs_Rm_Node_t *pNode);
 192
 193 #ifdef __cplusplus
 194 }
 195 #endif
 196
 197 #endif /* UCSI_H_ */