2 * Unicens Integration Helper Component
4 * Copyright (C) 2017 Microchip Technology Germany II GmbH & Co. KG
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.
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.
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/>.
19 * You may also obtain this software under a propriety license from Microchip.
20 * Please contact Microchip for further information.
30 #include "ucs_config.h"
31 #include "ucs-xml/UcsXml.h"
33 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
35 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
37 // Fulup interface added to support ucs2vol
38 typedef const struct {
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);
50 * \brief Initializes Unicens Integration module.
51 * \note Must be called before any other function of this component
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
58 void UCSI_Init(UCSI_Data_t *pPriv, void *pTag);
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"
67 * \param pPriv - private data section of this instance
68 * \param ucsConfig - UCS config handle
69 * \return true, configuration successfully enqueued, false otherwise
71 bool UCSI_NewConfig(UCSI_Data_t *pPriv, UcsXmlVal_t *ucsConfig);
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
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.
88 bool UCSI_ProcessRxData(UCSI_Data_t *pPriv, const uint8_t *pBuffer, uint16_t len);
91 * \brief Gives Unicens Integration module time to do its job
92 * \note Call this function only from single context (not from ISR)
94 * \param pPriv - private data section of this instance
96 void UCSI_Service(UCSI_Data_t *pPriv);
100 * \brief Call after timer set by UCSI_CB_OnSetServiceTimer
102 * \note Call this function only from single context (not from ISR)
104 * \param pPriv - private data section of this instance
106 void UCSI_Timeout(UCSI_Data_t *pPriv);
108 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
109 /* CALLBACK SECTION */
110 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
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
118 extern uint16_t UCSI_CB_OnGetTime(void *pTag);
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)
129 extern void UCSI_CB_OnSetServiceTimer(void *pTag, uint16_t timeout);
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 "..."
140 extern void UCSI_CB_OnUserMessage(void *pTag, const char format[],
141 uint16_t vargsCnt, ...);
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
150 extern void UCSI_CB_OnServiceRequired(void *pTag);
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
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);
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
171 extern void UCSI_CB_SendMostMessage(void *pTag,
172 const uint8_t *pPayload, uint32_t payloadLen);
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
181 extern void UCSI_CB_OnStop(void *pTag);
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
191 extern void UCSI_CB_OnMgrReport(void *pTag, Ucs_MgrReport_t code, uint16_t nodeAddress, Ucs_Rm_Node_t *pNode);