1 /*------------------------------------------------------------------------------------------------*/
2 /* UNICENS Integration Helper Component */
3 /* Copyright 2017, Microchip Technology Inc. and its subsidiaries. */
5 /* Redistribution and use in source and binary forms, with or without */
6 /* modification, are permitted provided that the following conditions are met: */
8 /* 1. Redistributions of source code must retain the above copyright notice, this */
9 /* list of conditions and the following disclaimer. */
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. */
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. */
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 /*------------------------------------------------------------------------------------------------*/
37 #include "ucs_config.h"
38 #include "ucs-xml/UcsXml.h"
40 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
42 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
45 * \brief Initializes UNICENS Integration module.
46 * \note Must be called before any other function of this component
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
53 void UCSI_Init(UCSI_Data_t *pPriv, void *pTag);
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"
62 * \param pPriv - private data section of this instance
63 * \param ucsConfig - UCS config handle
64 * \return true, configuration successfully enqueued, false otherwise
66 bool UCSI_NewConfig(UCSI_Data_t *pPriv, UcsXmlVal_t *ucsConfig);
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
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.
83 bool UCSI_ProcessRxData(UCSI_Data_t *pPriv, const uint8_t *pBuffer, uint16_t len);
86 * \brief Gives UNICENS Integration module time to do its job
87 * \note Call this function only from single context (not from ISR)
89 * \param pPriv - private data section of this instance
91 void UCSI_Service(UCSI_Data_t *pPriv);
95 * \brief Call after timer set by UCSI_CB_OnSetServiceTimer
97 * \note Call this function only from single context (not from ISR)
99 * \param pPriv - private data section of this instance
101 void UCSI_Timeout(UCSI_Data_t *pPriv);
104 * \brief Sends an AMS message to the control channel
106 * \note Call this function only from single context (not from ISR)
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
114 * \return true, if operation was successful. false if the message could not be sent.
116 bool UCSI_SendAmsMessage(UCSI_Data_t *my, uint16_t msgId, uint16_t targetAddress, uint8_t *pPayload, uint32_t payloadLen);
119 * \brief Gets the queued AMS message from UNICENS stack
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
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
130 * \return true, if operation was successful. false if no message got be retrieved.
132 bool UCSI_GetAmsMessage(UCSI_Data_t *my, uint16_t *pMsgId, uint16_t *pSourceAddress, uint8_t **pPayload, uint32_t *pPayloadLen);
135 * \brief Releases the message memory returned by UCSI_GetAmsMessage.
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!
142 * \param pPriv - private data section of this instance
144 void UCSI_ReleaseAmsMessage(UCSI_Data_t *my);
147 * \brief Enables or disables a route by the given routeId
148 * \note Call this function only from single context (not from ISR)
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
154 * \return true, if route was found and the specific command was enqueued to UNICENS.
156 bool UCSI_SetRouteActive(UCSI_Data_t *pPriv, uint16_t routeId, bool isActive);
159 * \brief Enables or disables a route by the given routeId
160 * \note Call this function only from single context (not from ISR)
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.
173 * \return true, if route command was enqueued to UNICENS.
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);
180 * \brief Enables or disables a route by the given routeId
181 * \note Call this function only from single context (not from ISR)
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.
188 * \return true, if GPIO command was enqueued to UNICENS.
190 bool UCSI_SetGpioState(UCSI_Data_t *pPriv, uint16_t targetAddress, uint8_t gpioPinId, bool isHighState);
192 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
193 /* CALLBACK SECTION */
194 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
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
202 extern uint16_t UCSI_CB_OnGetTime(void *pTag);
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)
213 extern void UCSI_CB_OnSetServiceTimer(void *pTag, uint16_t timeout);
216 * \brief Callback when ever the state of the Network has changed.
217 * \note This function must be implemented by the integrator
218 * \param pTag - Pointer given by the integrator by UCSI_Init
219 * \param isAvailable - true, if the network is operable. false, network is down. No message or stream can be sent or received.
220 * \param packetBandwidth - The amount of bytes per frame reserved for the Ethernet channel. Must match to the given packetBw value passed to UCSI_NewConfig.
221 * \param amountOfNodes - The amount of network devices found in the ring.
223 extern void UCSI_CB_OnNetworkState(void *pTag, bool isAvailable, uint16_t packetBandwidth, uint8_t amountOfNodes);
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 "..."
234 extern void UCSI_CB_OnUserMessage(void *pTag, bool isError, const char format[],
235 uint16_t vargsCnt, ...);
238 * \brief Callback when ever this instance needs to be serviced.
239 * \note Call UCSI_Service by your scheduler at the next run
240 * \note This function must be implemented by the integrator
241 * \param pTag - Pointer given by the integrator by UCSI_Init
243 extern void UCSI_CB_OnServiceRequired(void *pTag);
246 * \brief Callback when ever this instance of UNICENS wants to send control data to the LLD.
247 * \note This function must be implemented by the integrator
248 * \param pTag - Pointer given by the integrator by UCSI_Init
249 * \param pPayload - Byte array to be sent on the INIC control channel
250 * \param payloadLen - Length of pPayload in Byte
252 extern void UCSI_CB_OnTxRequest(void *pTag,
253 const uint8_t *pPayload, uint32_t payloadLen);
256 * \brief Callback when UNICENS instance has been stopped.
257 * \note This event can be used to free memory holding the resources
258 * passed with UCSI_NewConfig
259 * \note This function must be implemented by the integrator
260 * \param pTag - Pointer given by the integrator by UCSI_Init
262 extern void UCSI_CB_OnStop(void *pTag);
265 * \brief Callback when UNICENS instance has received an AMS message
266 * \note This function must be implemented by the integrator
267 * \note After this callback, call UCSI_GetAmsMessage indirect by setting a flag
268 * \param pTag - Pointer given by the integrator by UCSI_Init
270 extern void UCSI_CB_OnAmsMessageReceived(void *pTag);
273 * \brief Callback when a route become active / inactive.
274 * \note This function must be implemented by the integrator
275 * \param pTag - Pointer given by the integrator by UCSI_Init
276 * \param routeId - identifier as given in XML file along with MOST socket (unique)
277 * \param isActive - true, if the route is now in use. false, the route is not established.
278 * \param connectionLabel - The connection label used on the Network. Only valid, if isActive=true
280 extern void UCSI_CB_OnRouteResult(void *pTag, uint16_t routeId, bool isActive, uint16_t connectionLabel);
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.
290 extern void UCSI_CB_OnGpioStateChange(void *pTag, uint16_t nodeAddress, uint8_t gpioPinId, bool isHighState);
293 * \brief Callback when nodes are discovered or disappear
294 * \note This function must be implemented by the integrator
295 * \param pTag - Pointer given by the integrator by UCSI_Init
296 * \param code - Report code
297 * \param nodeAddress - Node Address of the INIC sending the update.
298 * \param pNode - Reference to the node structure or NULL.
300 extern void UCSI_CB_OnMgrReport(void *pTag, Ucs_MgrReport_t code, uint16_t nodeAddress, Ucs_Rm_Node_t *pNode);