m2mb API docs  30.00.007
m2mb API sets documentation
m2mb_fota.h
Go to the documentation of this file.
1 /*===============================================================================================*/
2 /* >>> Copyright (C) Telit Communications S.p.A. Italy All Rights Reserved. <<< */
21 #ifndef M2M_M2MB_FOTA_H
22 #define M2M_M2MB_FOTA_H
23 
24 
25 /* Global declarations ==========================================================================*/
26 #define M2MB_LOAD_UPDATED_APPS 0xAABB
27 #define M2MB_SKIP_BACKUP_RESTORE_PARAM 0xCCDD
28 #define M2MB_DEFAULT_LOAD_UPDATED_APPS 0xFFFF
29 #define M2MB_PARAM_LEN (255+1)
30 
31 /* Global typedefs ==============================================================================*/
32 typedef enum
33 {
34  M2MB_FOTA_STATE_UPDATE_START = 0,
35  M2MB_FOTA_STATE_UPDATE_PHASE_LAST = 0xF000,
36  M2MB_FOTA_STATE_UPDATE_CHECK_IN_AGENT = 0xF800,
37  M2MB_FOTA_STATE_CHECK_VERSION = 0xFF00,
38  M2MB_FOTA_STATE_UPDATED = 0xFF10,
39  M2MB_FOTA_STATE_UPDATED_NO_BACKUP_PARAMETERS = 0xFF15,
40  M2MB_FOTA_STATE_BACKUP_PARAMETERS = 0xFF20,
41  M2MB_FOTA_STATE_AFTER_BACKUP_PARAMETERS = 0xFF23,
42  M2MB_FOTA_STATE_RESTORE_PARAMETERS = 0xFF30,
43  M2MB_FOTA_STATE_AFTER_RESTORE_PARAMETERS = 0xFF33,
44  M2MB_FOTA_STATE_URC_PURGE = 0xFF40,
45  M2MB_FOTA_STATE_AFTER_PURGE = 0xFF50,
46  M2MB_FOTA_STATE_SPECIAL_CASE = 0xFF60,
47  M2MB_FOTA_STATE_IDLE = 0xFFFF
48 } M2MB_FOTA_STATE_E;
49 
50 typedef enum
51 {
52  M2MB_XQCN_STATE_BACKUPED = 0,
53  M2MB_XQCN_STATE_WRITTEN = 0x1000,
54  M2MB_XQCN_STATE_ERASED = 0x1500,
55  M2MB_XQCN_STATE_END = 0x2000,
56  M2MB_XQCN_STATE_READY = 0xFFFF
57 } M2MB_XQCN_STATE_E;
58 
59 typedef enum
60 {
61  M2MB_Q6ZIP_STATE_READY = 0xFFFF,
62  M2MB_Q6ZIP_STATE_ERASING = 0xFFFE,
63  M2MB_Q6ZIP_STATE_END = 0xFFFD
64 } M2MB_Q6ZIP_STATE_E;
65 
66 typedef enum
67 {
68  M2MB_CLADE_STATE_READY = 0xFFFF,
69  M2MB_CLADE_STATE_BACKUP_START = 0xFFFE,
70  M2MB_CLADE_STATE_BACKUP_END = 0xFFFD
71 } M2MB_CLADE_STATE_E;
72 
73 typedef enum
74 {
75  M2MB_FOTA_TRACE_VERBOSE_LEVEL_0,
76  M2MB_FOTA_TRACE_VERBOSE_LEVEL_1,
77  M2MB_FOTA_TRACE_VERBOSE_LEVEL_2,
78  M2MB_FOTA_TRACE_VERBOSE_LEVEL_ALL,
79  M2MB_FOTA_TRACE_VERBOSE_LEVEL_NO_CHANGE,
80  M2MB_FOTA_TRACE_VERBOSE_LEVEL_PRINT = 0xFFF0,
81  M2MB_FOTA_TRACE_VERBOSE_LEVEL_NUM = 0xFFFF
82 } M2MB_FOTA_TRACE_VERBOSE_LEVEL_E;
83 
84 typedef enum
85 {
86  M2MB_FOTA_TRACE_SPEED_NO_CHANGE,
87  M2MB_FOTA_TRACE_SPEED_4800,
88  M2MB_FOTA_TRACE_SPEED_9600,
89  M2MB_FOTA_TRACE_SPEED_115200,
90  M2MB_FOTA_TRACE_SPEED_230400,
91  M2MB_FOTA_TRACE_SPEED_460800,
92  M2MB_FOTA_TRACE_SPEED_921600,
93  M2MB_FOTA_TRACE_SPEED_BAUD_NUMBER,
94  M2MB_FOTA_TRACE_SPEED_NUM = 0xFFFF
95 } M2MB_FOTA_TRACE_SPEED_E;
96 
97 typedef enum
98 {
99  M2MB_FOTA_RESULT_CODE_UNDEF,
100  M2MB_FOTA_RESULT_CODE_OK,
101  M2MB_FOTA_RESULT_CODE_ERROR_GET_STATE,
102  M2MB_FOTA_RESULT_CODE_READ_ERROR,
103  M2MB_FOTA_RESULT_CODE_WRITE_ERROR,
104  M2MB_FOTA_RESULT_CODE_GET_INFO_ERROR,
105  M2MB_FOTA_RESULT_CODE_INVALID_TRACE_VERBOSE_LEVEL,
106  M2MB_FOTA_RESULT_CODE_INVALID_TRACE_SPEED,
107  M2MB_FOTA_RESULT_CODE_GET_PARTITION_FAIL,
108  M2MB_FOTA_RESULT_CODE_BAD_MALLOC,
109  M2MB_FOTA_RESULT_CODE_ERROR_NO_TAG,
110  M2MB_FOTA_RESULT_CODE_ERROR_MD5_CALCULATE,
111  M2MB_FOTA_RESULT_CODE_ERROR_MD5_CHECK,
112  M2MB_FOTA_RESULT_CODE_ERROR_BAD_ACTION,
113  M2MB_FOTA_RESULT_CODE_ERROR_PARTITION_COPY,
114  M2MB_FOTA_RESULT_CODE_ERROR_GET_FW_CNV_ELEMENTS,
115  M2MB_FOTA_RESULT_CODE_ERROR_CHECK_FW_DELTA_CNV_ELEMENTS,
116  M2MB_FOTA_RESULT_CODE_ERROR_ERASE_FW_CNV_ELEMENTS,
117  M2MB_FOTA_RESULT_CODE_INVALID_HANDLE,
118  M2MB_FOTA_RESULT_CODE_TASK_ERROR,
119  M2MB_FOTA_RESULT_CODE_ERROR_SHA256_CALCULATE,
120  M2MB_FOTA_RESULT_CODE_ERROR_SHA256_CHECK,
121  M2MB_FOTA_RESULT_CODE_ERROR_FOTA_IN_PROGRESS,
122  M2MB_FOTA_RESULT_CODE_NUM
123 } M2MB_FOTA_RESULT_CODE_E;
124 
125 typedef enum
126 {
127  M2MB_FOTA_CHECK_SETUP_SOURCE,
128  M2MB_FOTA_CHECK_SETUP_DESTINATION,
129  M2MB_FOTA_CHECK_SETUP_NUM
130 } M2MB_FOTA_CHECK_SETUP_E;
131 
132 typedef enum
133 {
134  M2MB_FOTA_DOWNLOAD_TYPE_HTTP,
135  M2MB_FOTA_DOWNLOAD_TYPE_HTTPS,
136  M2MB_FOTA_DOWNLOAD_TYPE_FTP,
137  M2MB_FOTA_DOWNLOAD_TYPE_FTPS,
138  M2MB_FOTA_DOWNLOAD_TYPE_COAP,
139  M2MB_FOTA_DOWNLOAD_TYPE_COAPS,
140  M2MB_FOTA_DOWNLOAD_TYPE_MAX_NUM
141 } M2MB_FOTA_DOWNLOAD_TYPE_E;
142 
143 typedef enum
144 {
145  M2MB_FOTA_DOWNLOAD_SUCCESS,
146  M2MB_FOTA_DOWNLOAD_TASK_INTERNAL_ERROR,
147  M2MB_FOTA_DOWNLOAD_NOT_RESOLVED,
148  M2MB_FOTA_DOWNLOAD_CONN_SOCKET_ERROR,
149  M2MB_FOTA_DOWNLOAD_CONN_CONTEXT_ERROR,
150  M2MB_FOTA_DOWNLOAD_ACCESS_DENIED,
151  M2MB_FOTA_DOWNLOAD_FILE_NOT_FOUND,
152  M2MB_FOTA_DOWNLOAD_SESSION_ERROR,
153  M2MB_FOTA_DOWNLOAD_MEMORY_ERROR
154 } M2MB_FOTA_DOWNLOAD_RESULT_E;
155 
156 typedef enum
157 {
158  M2MB_FOTA_EXTENDED_FTP_PROTOCOL,
159  M2MB_FOTA_BASIC_FTP_PROTOCOL
160 } M2MB_FOTA_FTP_PROTOCOL_E;
161 
162 typedef enum
163 {
164  M2MB_FOTA_EVENT_HTTP_DELTA_TRANSFER_END,
165  M2MB_FOTA_EVENT_FTP_DELTA_TRANSFER_END
166 } M2MB_FOTA_IND_E;
167 
168 typedef void *M2MB_FOTA_HANDLE;
169 
170 typedef struct
171 {
172  UINT8 cid;
173  CHAR server_addr[256]; // es.: "lwm2m.devicewise.com" or "34.200.145.8"
174  UINT16 port; // HTTP port
175  CHAR resource[256]; // HTTP resource path, es.: "/pubfile/lwm2m/MOTDATA_N.txt"
176  CHAR user[M2MB_PARAM_LEN]; // username (empty if not present)
177  CHAR psw[M2MB_PARAM_LEN]; // password (empty if not present)
178  UINT32 timeout; // milliseconds
179  BOOLEAN HTTPSEn; // secure HTTP ( on = TRUE /off = FALSE )
180  void *sslConfig; // the M2MB_SSL_CONFIG_T type must be used to create the sslConfig object. If sslConfig is NULL, the default SSL configuration will be used.
181 } M2MB_FOTA_HTTP_SESSION_CFG_T;
182 
183 typedef struct
184 {
185  CHAR URI[256]; /* hostName/[pathName/]fileName */
186  CHAR user[M2MB_PARAM_LEN];
187  CHAR psw[M2MB_PARAM_LEN];
188  BOOLEAN passiveMode;
189  UINT32 timeout;
190  BOOLEAN IPPignoring;
191  BOOLEAN FTPSEn;
192  M2MB_FOTA_FTP_PROTOCOL_E protocol;
193 } M2MB_FOTA_FTP_SESSION_CFG_T;
194 
195 typedef struct
196 {
197  UINT8 connID;
198  UINT8 cid;
199  BOOLEAN cid_active;
200  UINT16 pktSize;
201  UINT16 inactivityTimeout;
202  UINT16 connectionTimeout;
203  UINT16 dataSendingTimeout;
204 } M2MB_FOTA_SOCKET_CFG_T;
205 
206 typedef struct
207 {
208  M2MB_FOTA_FTP_SESSION_CFG_T sessionCfg;
209  M2MB_FOTA_SOCKET_CFG_T socketCfg;
210 } M2MB_FOTA_FTP_CFG_T;
211 
212 // Callback resp_struct for M2MB_FOTA_EVENT_HTTP_DELTA_TRANSFER_END and M2MB_FOTA_EVENT_FTP_DELTA_TRANSFER_END events
213 typedef struct
214 {
215  M2MB_FOTA_DOWNLOAD_RESULT_E result;
216  UINT32 packageSize;
217 } M2MB_FOTA_CB_RESP_DELTA_TRANSFER_END_T;
218 
219 // Callback for FOTA events
220 // Params: h -> handle
221 // fota_event -> event type
222 // resp_size -> size of resp_struct
223 // resp_struct -> pointer to M2MB_FOTA_CB_RESP_DELTA_TRANSFER_END_T, in case of
224 // M2MB_FOTA_EVENT_HTTP_DELTA_TRANSFER_END and M2MB_FOTA_EVENT_FTP_DELTA_TRANSFER_END events
225 // userdata -> generic user data returned as it is in the callback.
226 typedef void ( *m2mb_fota_ind_callback )( M2MB_FOTA_HANDLE h, M2MB_FOTA_IND_E fota_event, UINT16 resp_size, void *resp_struct, void *userdata );
227 
228 
229 /* Global functions =============================================================================*/
230 /*-----------------------------------------------------------------------------------------------*/
295 /*-----------------------------------------------------------------------------------------------*/
296 M2MB_RESULT_E m2mb_fota_init
297 (
298  M2MB_FOTA_HANDLE *pHandle,
299  m2mb_fota_ind_callback callback,
300  void *userdata
301 );
302 
303 /*-----------------------------------------------------------------------------------------------*/
325 /*-----------------------------------------------------------------------------------------------*/
326 M2MB_RESULT_E m2mb_fota_deinit
327 (
328  M2MB_FOTA_HANDLE handle
329 );
330 
331 /*-----------------------------------------------------------------------------------------------*/
362 /*-----------------------------------------------------------------------------------------------*/
363 M2MB_RESULT_E m2mb_fota_get_delta
364 (
365  M2MB_FOTA_HANDLE handle,
366  M2MB_FOTA_DOWNLOAD_TYPE_E type,
367  void *settings
368 );
369 
370 /*-----------------------------------------------------------------------------------------------*/
392 /*-----------------------------------------------------------------------------------------------*/
393 M2MB_RESULT_E m2mb_fota_reset
394 (
395  M2MB_FOTA_HANDLE handle
396 );
397 
398 /*-----------------------------------------------------------------------------------------------*/
424 /*-----------------------------------------------------------------------------------------------*/
425 M2MB_RESULT_E m2mb_fota_result_code_get
426 (
427  M2MB_FOTA_HANDLE handle,
428  M2MB_FOTA_RESULT_CODE_E *pResultCode
429 );
430 
431 /*-----------------------------------------------------------------------------------------------*/
460 /*-----------------------------------------------------------------------------------------------*/
461 M2MB_RESULT_E m2mb_fota_config_set
462 (
463  M2MB_FOTA_HANDLE handle,
464  M2MB_FOTA_TRACE_VERBOSE_LEVEL_E TraceVerboseLevel,
465  M2MB_FOTA_TRACE_SPEED_E TraceSpeed
466 );
467 
468 /*-----------------------------------------------------------------------------------------------*/
498 /*-----------------------------------------------------------------------------------------------*/
499 M2MB_RESULT_E m2mb_fota_config_get
500 (
501  M2MB_FOTA_HANDLE handle,
502  M2MB_FOTA_TRACE_VERBOSE_LEVEL_E *pTraceVerboseLevel,
503  M2MB_FOTA_TRACE_SPEED_E *pTraceSpeed
504 );
505 
506 /*-----------------------------------------------------------------------------------------------*/
536 /*-----------------------------------------------------------------------------------------------*/
537 M2MB_RESULT_E m2mb_fota_update_package_info_get
538 (
539  M2MB_FOTA_HANDLE handle,
540  UINT32 *pBlockSize,
541  UINT32 *pPartitionSize
542 );
543 
544 /*-----------------------------------------------------------------------------------------------*/
581 /*-----------------------------------------------------------------------------------------------*/
582 M2MB_RESULT_E m2mb_fota_update_package_write
583 (
584  M2MB_FOTA_HANDLE handle,
585  UINT32 BlockAddress,
586  UINT8 *pBuffer
587 );
588 
589 /*-----------------------------------------------------------------------------------------------*/
615 /*-----------------------------------------------------------------------------------------------*/
616 M2MB_RESULT_E m2mb_fota_update_package_check_setup
617 (
618  M2MB_FOTA_HANDLE handle,
619  M2MB_FOTA_CHECK_SETUP_E Action
620 );
621 
622 /*-----------------------------------------------------------------------------------------------*/
644 /*-----------------------------------------------------------------------------------------------*/
645 M2MB_RESULT_E m2mb_fota_start
646 (
647  M2MB_FOTA_HANDLE handle
648 );
649 
650 /*-----------------------------------------------------------------------------------------------*/
675 /*-----------------------------------------------------------------------------------------------*/
676 M2MB_RESULT_E m2mb_fota_end
677 (
678  M2MB_FOTA_HANDLE handle
679 );
680 
681 /*-----------------------------------------------------------------------------------------------*/
707 /*-----------------------------------------------------------------------------------------------*/
708 M2MB_RESULT_E m2mb_fota_state_get
709 (
710  M2MB_FOTA_HANDLE handle,
711  M2MB_FOTA_STATE_E *pState
712 );
713 
714 
715 #endif /* M2M_M2MB_FOTA_H */
716 
m2mb_fota_update_package_write
M2MB_RESULT_E m2mb_fota_update_package_write(M2MB_FOTA_HANDLE handle, UINT32 BlockAddress, UINT8 *pBuffer)
Write update package data to flash.
m2mb_fota_update_package_info_get
M2MB_RESULT_E m2mb_fota_update_package_info_get(M2MB_FOTA_HANDLE handle, UINT32 *pBlockSize, UINT32 *pPartitionSize)
Get FOTA update package partition info.
M2MB_FOTA_FTP_SESSION_CFG_T
Definition: m2mb_fota.h:183
m2mb_fota_config_get
M2MB_RESULT_E m2mb_fota_config_get(M2MB_FOTA_HANDLE handle, M2MB_FOTA_TRACE_VERBOSE_LEVEL_E *pTraceVerboseLevel, M2MB_FOTA_TRACE_SPEED_E *pTraceSpeed)
Get FOTA configuration.
M2MB_FOTA_SOCKET_CFG_T
Definition: m2mb_fota.h:195
m2mb_fota_start
M2MB_RESULT_E m2mb_fota_start(M2MB_FOTA_HANDLE handle)
Start FOTA process.
m2mb_fota_state_get
M2MB_RESULT_E m2mb_fota_state_get(M2MB_FOTA_HANDLE handle, M2MB_FOTA_STATE_E *pState)
Get FOTA process state.
M2MB_FOTA_HTTP_SESSION_CFG_T
Definition: m2mb_fota.h:170
m2mb_fota_update_package_check_setup
M2MB_RESULT_E m2mb_fota_update_package_check_setup(M2MB_FOTA_HANDLE handle, M2MB_FOTA_CHECK_SETUP_E Action)
Check update package integrity, applicability and prepare for FOTA update.
m2mb_fota_get_delta
M2MB_RESULT_E m2mb_fota_get_delta(M2MB_FOTA_HANDLE handle, M2MB_FOTA_DOWNLOAD_TYPE_E type, void *settings)
Get FOTA delta.
M2MB_FOTA_FTP_CFG_T
Definition: m2mb_fota.h:206
m2mb_fota_init
M2MB_RESULT_E m2mb_fota_init(M2MB_FOTA_HANDLE *pHandle, m2mb_fota_ind_callback callback, void *userdata)
FOTA system open.
m2mb_fota_end
M2MB_RESULT_E m2mb_fota_end(M2MB_FOTA_HANDLE handle)
End FOTA process.
m2mb_fota_deinit
M2MB_RESULT_E m2mb_fota_deinit(M2MB_FOTA_HANDLE handle)
FOTA system close.
m2mb_fota_config_set
M2MB_RESULT_E m2mb_fota_config_set(M2MB_FOTA_HANDLE handle, M2MB_FOTA_TRACE_VERBOSE_LEVEL_E TraceVerboseLevel, M2MB_FOTA_TRACE_SPEED_E TraceSpeed)
Set FOTA configuration.
m2mb_fota_reset
M2MB_RESULT_E m2mb_fota_reset(M2MB_FOTA_HANDLE handle)
Base FOTA system initialization.
m2mb_fota_result_code_get
M2MB_RESULT_E m2mb_fota_result_code_get(M2MB_FOTA_HANDLE handle, M2MB_FOTA_RESULT_CODE_E *pResultCode)
Get last FOTA result code.
M2MB_FOTA_CB_RESP_DELTA_TRANSFER_END_T
Definition: m2mb_fota.h:213