1 /******************************************************************************
3 @file oad_protocol.h
5 @brief OAD Protocol Header
7 Group: WCS LPC
8 $Target Devices: Linux: AM335x, Embedded Devices: CC1310, CC1350, CC1352$
10 ******************************************************************************
11 $License: BSD3 2016 $
13 Copyright (c) 2015, Texas Instruments Incorporated
14 All rights reserved.
16 Redistribution and use in source and binary forms, with or without
17 modification, are permitted provided that the following conditions
18 are met:
20 * Redistributions of source code must retain the above copyright
21 notice, this list of conditions and the following disclaimer.
23 * Redistributions in binary form must reproduce the above copyright
24 notice, this list of conditions and the following disclaimer in the
25 documentation and/or other materials provided with the distribution.
27 * Neither the name of Texas Instruments Incorporated nor the names of
28 its contributors may be used to endorse or promote products derived
29 from this software without specific prior written permission.
31 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
32 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
33 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
34 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
35 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
36 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
37 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
38 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
39 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
40 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
41 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42 ******************************************************************************
43 $Release Name: TI-15.4Stack Linux x64 SDK$
44 $Release Date: Sept 27, 2017 (2.04.00.13)$
45 *****************************************************************************/
46 /*!*****************************************************************************
47 * @file oad_protocol.h
48 *
49 * @brief Wireless Sensor Network Protocol
50 *
51 * The OADProtocol interface provides device independent APIs, data types,
52 * and macros.
53 *
54 * # Overview #
55 *
56 * The Over the Air Download Protocol module provides protocol
57 * functionality on top of the RF protocol.
58 *
59 * The APIs in this module serve as an interface to a TIRTOS
60 * application and offers functionality for a OAD messaging protocol between
61 * OAD Sever and the OAD Client. The module handles formating / parsing of
62 * messages.
63 *
64 * # Usage #
65 *
66 * To use the OADProtocol module to format/parse OAD messages, the application
67 * calls the following APIs:
68 * - OADProtocol_init(): Initialize the OADProtocol module/task.
69 * - OADProtocol_Params_init(): Initialize a OADProtocol_Params structure
70 * with default values. Then change the parameters from non-default
71 * values as needed.
72 * - OADProtocol_open(): Open an instance of the OADProtocol module,
73 * passing the initialized parameters.
74 * - OADProtocol_sendFwRequest(): This is an example of an OAD message that
75 * is formated and sent.
76 *
77 * The following code example opens OADProtocol, sends a FW version request
78 * and processes the response.
79 *
80 * @code
81 *
82 * OADProtocol_packetCBs_t OADProtocolCbs = {
83 * NULL, //Incoming FW Req
84 * fwVersionReqCb, //Incoming FW Version Rsp
85 * NULL, //Incoming Image Identify Req
86 * NULL, //Incoming Image Identify Rsp
87 * NULL, //Incoming OAD Block Req
88 * NULL, //Incoming OAD Block Rsp
89 * };
90 *
91 * static void fwVersionRspCb(void* pSrcAddr, char *fwVersionStr)
92 * {
93 * //Do something with srcAddr and fwVersionStr
94 * }
95 *
96 * void someTaskInit(void)
97 * {
98 * OADProtocol_init();
99 * }
100 *
101 * void someTaskFxn(void)
102 * {
103 * // Set Default parameters structure
104 * static OADProtocol_Params_t OADProtocol_params;
105 *
106 * // Initialize and open the Wsn Protocol Task
107 * OADProtocol_Params_init(&OADProtocol_params);
108 * OADProtocol_params.pCallbacks = &OADProtocolCbs;
109 * OADProtocol_open(&OADProtocol_params);
110 *
111 * OADProtocol_sendFwVersionReq(nodeAddress);
112 *
113 * }
114 * @endcode
115 *
116 *
117 * ## OADProtocol Configuration ##
118 *
119 * In order to use the OADProtocol APIs, the application is required
120 * to provide application specific configuration and callbacks.
121 *
122 * @code
123 * OADProtocol_Params_t OADProtocol_Params = {
124 * pCallbacks; // Application Callbacks for pressing packets
125 * };
126 * @endcode
127 *
128 *
129 * ## Initializing the OADProtocol Module ##
130 *
131 * OADProtocol_init() must be called before any other OADProtocol APIs.
132 * This function
133 * iterates through the elements of the SPI_config[] array, calling
134 * the element's device implementation SPI initialization function.
135 *
136 *
137 * ## Over the Air Download packets ##
138 *
139 * The OADProtocol supports OAD messages used to update the FW of a sensor
140 * node. The OAD is instigated by the concentrator sending
141 * OADProtocol_PACKET_TYPE_OAD_IMG_IDENTIFY_REQ packet containing the image
142 * header. The sensor node checks the image header and sends a
143 * OADProtocol_PACKET_TYPE_OAD_IMG_IDENTIFY_RSP containing the status, which
144 * is true f the age header is accepted or false if it is rejected. If the
145 * image header is accepted the sensor node requests the FW image blocks with
146 * the OADProtocol_PACKET_TYPE_OAD_BLOCK_REQ and the concentrator sends the
147 * image blocks with OADProtocol_PACKET_TYPE_OAD_BLOCK_RSP.
148 *
149 * The message flow is:
150 *
151 * Server Client
152 *
153 * (Optional FW version Req)
154 * FW_VERSION_REQ ----------------------->
155 * <-------------------------- FW_VERSION_RSP("rfWsnNode v03.01.00")
156 *
157 * OAD_IMG_IDENTIFY_REQ ----------------->
158 * <-------------------------- OAD_IMG_IDENTIFY_RSP(status=1)
159 * <-------------------------- OAD_BLOCK_REQ(block=0)
160 * OAD_BLOCK_RSP(Block 0) --------------->
161 * <-------------------------- OAD_BLOCK_REQ(block=1)
162 * OAD_BLOCK_RSP(Block 1) --------------->
163 * ...
164 * <-------------------------- OAD_BLOCK_REQ(block=n)
165 * OAD_BLOCK_RSP(Block n) --------------->
166 *
167 *
168 *******************************************************************************
169 */
170 #ifndef OADProtocol_H_
171 #define OADProtocol_H_
173 #include "stdint.h"
174 #include "common/native_oad/oad_target.h"
176 /**
177 * @defgroup OADProtocol_PACKET packet defines
178 * @{
179 */
181 /*!
182 * retry timeouts and max number or retries
183 */
184 #define OADProtocol_DEFAULT_MAX_RETRIES 2 ///< Max number of retries for timed out packets
185 /**
186 * @defgroup Other OADProtocol defines
187 * @{
188 */
189 #define OADProtocol_FW_VERSION_STR_LEN 32 ///< Max Length of the FW version string
191 #define OADProtocol_PKT_CMDID_OFFSET 0 ///< Offset to packet type files in packet header
193 #define OADProtocol_IMAGE_ID_LEN 16
195 /*!
196 * Req/Rsp Packet Types
197 */
198 #define OADProtocol_PACKET_TYPE_FW_VERSION_REQ 0x00 ///< Firmware version request
199 #define OADProtocol_PACKET_TYPE_FW_VERSION_REQ_LEN 1 ///< Firmware version request size
201 #define OADProtocol_PACKET_TYPE_FW_VERSION_RSP 0x01 ///< Firmware version response
202 #define OADProtocol_PACKET_TYPE_FW_VERSION_RSP_LEN 1 + OADProtocol_FW_VERSION_STR_LEN ///< Firmware version response
203 #define OADProtocol_VER_RSP_VERSIONSTRING_OFFSET 1 ///< Offset to version string in FW Ver Response
205 #define OADProtocol_PACKET_TYPE_OAD_IMG_IDENTIFY_REQ 0x02 ///< OAD update image identify request
206 #define OADProtocol_PACKET_TYPE_OAD_IMG_IDENTIFY_REQ_LEN 1 + 1 + 16 ///< OAD update image identify request
207 #define OADProtocol_IMG_IDENTIFY_REQ_IMG_ID_OFFSET 1 ///< Offset to status in Image Identify Response
208 #define OADProtocol_IMG_IDENTIFY_REQ_IMG_HDR_OFFSET 2 ///< Offset to status in Image Identify Response
210 #define OADProtocol_PACKET_TYPE_OAD_IMG_IDENTIFY_RSP 0x03 ///< OAD update image identify response
211 #define OADProtocol_PACKET_TYPE_OAD_IMG_IDENTIFY_RSP_LEN 1 + 1 ///< OAD update image identify response
212 #define OADProtocol_IMG_IDENTIFY_RSP_STATUS_OFFSET 1 ///< Offset to status in Image Identify Response
214 #define OADProtocol_PACKET_TYPE_OAD_BLOCK_REQ 0x04 ///< OAD update image block request
215 #define OADProtocol_PACKET_TYPE_OAD_BLOCK_REQ_LEN 1 + 1 + 2 + 2 ///< OAD update image block request
216 #define OADProtocol_BLOCK_REQ_IMG_ID_OFFSET 1 ///< Offset to 16B block num in Block Request
217 #define OADProtocol_BLOCK_REQ_BLOCK_NUM_OFFSET 2 ///< Offset to 16B block num in Block Request
218 #define OADProtocol_BLOCK_REQ_MULTI_BLOCK_SIZE_OFFSET 4 ///< Offset to 16B block num in Block Request
220 #define OADProtocol_PACKET_TYPE_OAD_BLOCK_RSP 0x05 ///< OAD update image block request
221 #define OADProtocol_PACKET_TYPE_OAD_BLOCK_RSP_LEN 1 + 1 + 2 + OAD_BLOCK_SIZE ///< OAD update image block request
222 #define OADProtocol_BLOCK_RSP_IMG_ID_OFFSET 1 ///< Offset to 16B block num in Block Request
223 #define OADProtocol_BLOCK_RSP_BLOCK_NUM_OFFSET 2 ///< Offset to 16B block num in Block Request
224 #define OADProtocol_BLOCK_RSP_BLOCK_DATA_OFFSET 4 ///< Offset to block data in Block Response
227 /** @}*/
229 /// OADProtocol status codes
230 typedef enum {
231 OADProtocol_Status_Success, ///< Success
232 OADProtocol_Failed, ///< Fail
233 OADProtocol_FailedTimeout, ///< Acknowledgment or Response Timed out
234 OADProtocol_FailedCanceled, ///< Canceled by application
235 } OADProtocol_Status_t;
237 /** @brief firmware version request packet callback function type
238 *
239 */
240 typedef void (*fwVersionReqCb_t)(void* pSrcAddr);
242 /** @brief firmware version response packet callback function type
243 *
244 */
245 typedef void (*fwVersionRspCb_t)(void* pSrcAddr, char *fwVersionStr);
247 /** @brief OAD image identify request packet callback function type
248 *
249 */
250 typedef void (*oadImgIdentifyReqCb_t)(void* pSrcAddr, uint8_t imgId, uint8_t *imgMetaData);
252 /** @brief OAD image identify response packet callback function type
253 *
254 */
255 typedef void (*oadImgIdentifyRspCb_t)(void* pSrcAddr, uint8_t status);
257 /** @brief OAD image block request packet callback function type
258 *
259 */
260 typedef void (*oadBlockReqCb_t)(void* pSrcAddr, uint8_t imgId, uint16_t blockNum, uint16_t multiBlockSize);
262 /** @brief OAD image block response packet callback function type
263 *
264 */
265 typedef void (*oadBlockRspCb_t)(void* pSrcAddr, uint8_t imgId, uint16_t blockNum, uint8_t *blkData);
267 /** @brief OADProtocol callback table
268 *
269 */
270 typedef struct
271 {
272 fwVersionReqCb_t pfnFwVersionReqCb; ///< Incoming FW Req
273 fwVersionRspCb_t pfnFwVersionRspCb; ///< Incoming FW Version Rsp
274 oadImgIdentifyReqCb_t pfnOadImgIdentifyReqCb; ///< Incoming Image Identify Req
275 oadImgIdentifyRspCb_t pfnOadImgIdentifyRspCb; ///< Incoming Image Identify Rsp
276 oadBlockReqCb_t pfnOadBlockReqCb; ///< Incoming OAD Block Req
277 oadBlockRspCb_t pfnOadBlockRspCb; ///< Incoming OAD Block Rsp
278 } OADProtocol_MsgCBs_t;
280 /** @brief function definition for sending message over the radio
281 *
282 */
283 typedef void* (*radioAccessAllocMsg_t)(uint32_t size);
285 /** @brief function definition for sending message over the radio
286 *
287 */
288 typedef OADProtocol_Status_t (*radioAccessPacketSend_t)(void* pDstAddress, uint8_t *payload, uint32_t msgSize);
290 /** @brief OADProtocol radio access functions
291 *
292 */
293 typedef struct
294 {
295 radioAccessAllocMsg_t pfnRadioAccessAllocMsg; ///< Function for allocating a message buffer
296 radioAccessPacketSend_t pfnRadioAccessPacketSend; ///< Function for sending message over the radio
297 } OADProtocol_RadioAccessFxns_t;
299 /** @brief RF parameter struct
300 * RF parameters are used with the OADProtocol_open() and OADProtocol_Params_init() call.
301 */
302 typedef struct {
303 OADProtocol_RadioAccessFxns_t *pRadioAccessFxns; ///< Radio access function table
304 OADProtocol_MsgCBs_t *pProtocolMsgCallbacks; ///< Application Callbacks for pressing packets
305 } OADProtocol_Params_t;
307 /** @brief Function to initialize the OADProtocol_Params struct to its defaults
308 *
309 * @param params An pointer to RF_Params structure for
310 * initialization
311 *
312 * Defaults values are:
313 * pRadioAccessFxns = {0}
314 * pCallbacks = {0}
315 */
316 extern void OADProtocol_Params_init(OADProtocol_Params_t *params);
318 /** @brief Function that initializes the Wsn Protocol Task and creates all TI-RTOS objects
319 *
320 */
321 extern void OADProtocol_init(void);
323 /** @brief Function to open the OADProtocol module
324 *
325 * @param params An pointer to RF_Params structure for initialization
326 */
327 extern void OADProtocol_open(OADProtocol_Params_t *params);
329 /** @brief Function to parse OADProtocol packets
330 *
331 * @param srcAddr address of the device that sent the message
332 * @param incomingPacket pointer to packet to be parsed
333 * @param packetLen length of the message
334 */
335 extern OADProtocol_Status_t OADProtocol_ParseIncoming(void* pSrcAddr, uint8_t* incomingPacket);
338 /** @brief Function to send a FW version request packet
339 *
340 * @param dstAddress Address to send the request to
341 *
342 * @return Status
343 */
344 extern OADProtocol_Status_t OADProtocol_sendFwVersionReq(void* pDstAddress);
346 /** @brief Function to send a FW version response packet
347 *
348 * @param dstAddress Address to send the response to
349 * @param fwVersion Firmware version string to send
350 *
351 * @return Status
352 */
353 extern OADProtocol_Status_t OADProtocol_sendFwVersionRsp(void* pDstAddress, char *fwVersion);
355 /** @brief Function to send an OAD image identify request packet
356 *
357 * @param dstAddress Address to send the request to
358 * @param imgId image ID used for requesting image blocks
359 * @param pImgInfoData Image header
360 *
361 * @return Status
362 */
363 extern OADProtocol_Status_t OADProtocol_sendImgIdentifyReq(void* pDstAddress, uint8_t imgId, uint8_t *pImgInfoData);
365 /** @brief Function to send an OAD image identify request packet
366 *
367 * @param dstAddress Address to send the response to
368 * @param status status to send
369 *
370 * @return Status
371 */
372 extern OADProtocol_Status_t OADProtocol_sendOadIdentifyImgRsp(void* pDstAddress, uint8_t status);
374 /** @brief Function to send an OAD block request packet
375 *
376 * @param dstAddress Address to send the request to
377 * @param imgId image ID of image blocks
378 * @param blockNum block Number to request
379 * @param multiBlockSize Numer of blocks in the multi Block transfer (0 or 1 for none-multiblock)
380 *
381 * @return Status
382 *
383 */
384 extern OADProtocol_Status_t OADProtocol_sendOadImgBlockReq(void* pDstAddress, uint8_t imgId, uint16_t blockNum, uint16_t multiBlockSize);
386 /** @brief Function to send an OAD block response packet
387 *
388 * @param dstAddress Address to send the response to
389 * @param imgId image ID of image blocks
390 * @param blockNum Block number
391 * @param block pointer to image block
392 *
393 * @return Status
394 *
395 */
396 extern OADProtocol_Status_t OADProtocol_sendOadImgBlockRsp(void* pDstAddress, uint8_t imgId, uint16_t blockNum, uint8_t *block);
398 #endif /* OADProtocol_H_ */