m2mb API docs  25.30.004.0
m2mb API sets documentation
m2mb_fota.h
Go to the documentation of this file.
1 /* $version: 252203 */
2 /*===============================================================================================*/
3 /* >>> Copyright (C) Telit Communications S.p.A. Italy All Rights Reserved. <<< */
22 #ifndef M2M_M2MB_FOTA_H
23 #define M2M_M2MB_FOTA_H
24 
25 
26 /* Global declarations ==========================================================================*/
27 #define M2MB_LOAD_UPDATED_APPS 0xAABB
28 #define M2MB_SKIP_BACKUP_RESTORE_PARAM 0xCCDD
29 #define M2MB_DEFAULT_LOAD_UPDATED_APPS 0xFFFF
30 #define M2MB_PARAM_LEN (255+1)
31 
32 /* Global typedefs ==============================================================================*/
33 typedef enum
34 {
35  M2MB_FOTA_STATE_UPDATE_START = 0,
36  M2MB_FOTA_STATE_UPDATE_PHASE_LAST = 0xF000,
37  M2MB_FOTA_STATE_UPDATE_CHECK_IN_AGENT = 0xF800,
38  M2MB_FOTA_STATE_CHECK_VERSION = 0xFF00,
39  M2MB_FOTA_STATE_UPDATED = 0xFF10,
40  M2MB_FOTA_STATE_UPDATED_NO_BACKUP_PARAMETERS = 0xFF15,
41  M2MB_FOTA_STATE_UPDATED_AFTER_NO_BACKUP_PARAMETERS = 0xFF17,
42  M2MB_FOTA_STATE_BACKUP_PARAMETERS = 0xFF20,
43  M2MB_FOTA_STATE_AFTER_BACKUP_PARAMETERS = 0xFF23,
44  M2MB_FOTA_STATE_RESTORE_PARAMETERS = 0xFF30,
45  M2MB_FOTA_STATE_AFTER_RESTORE_PARAMETERS = 0xFF33,
46  M2MB_FOTA_STATE_BEFORE_URC_PURGE = 0xFF37,
47  M2MB_FOTA_STATE_URC_PURGE = 0xFF40,
48  M2MB_FOTA_STATE_AFTER_PURGE = 0xFF50,
49  M2MB_FOTA_STATE_SPECIAL_CASE = 0xFF60,
50  M2MB_FOTA_STATE_IDLE = 0xFFFF
51 } M2MB_FOTA_STATE_E;
52 
53 typedef enum
54 {
55  M2MB_XQCN_STATE_BACKUPED = 0,
56  M2MB_XQCN_STATE_WRITTEN = 0x1000,
57  M2MB_XQCN_STATE_ERASED = 0x1500,
58  M2MB_XQCN_STATE_END = 0x2000,
59  M2MB_XQCN_STATE_READY = 0xFFFF
60 } M2MB_XQCN_STATE_E;
61 
62 typedef enum
63 {
64  M2MB_Q6ZIP_STATE_READY = 0xFFFF,
65  M2MB_Q6ZIP_STATE_ERASING = 0xFFFE,
66  M2MB_Q6ZIP_STATE_END = 0xFFFD
67 } M2MB_Q6ZIP_STATE_E;
68 
69 typedef enum
70 {
71  M2MB_CLADE_STATE_READY = 0xFFFF,
72  M2MB_CLADE_STATE_BACKUP_START = 0xFFFE,
73  M2MB_CLADE_STATE_BACKUP_END = 0xFFFD
74 } M2MB_CLADE_STATE_E;
75 
76 typedef enum
77 {
78  M2MB_FOTA_INTEGRITY_CHECK = 0xFFFF,
79  M2MB_FOTA_INTEGRITY_PASS = 0xFFFE,
80  M2MB_FOTA_INTEGRITY_FAIL = 0xFFFD
81 } M2MB_FOTA_INTEGRITY_E;
82 
83 typedef enum
84 {
85  M2MB_FOTA_TRACE_VERBOSE_LEVEL_0,
86  M2MB_FOTA_TRACE_VERBOSE_LEVEL_1,
87  M2MB_FOTA_TRACE_VERBOSE_LEVEL_2,
88  M2MB_FOTA_TRACE_VERBOSE_LEVEL_ALL,
89  M2MB_FOTA_TRACE_VERBOSE_LEVEL_NO_CHANGE,
90  M2MB_FOTA_TRACE_VERBOSE_LEVEL_PRINT = 0xFFF0,
91  M2MB_FOTA_TRACE_VERBOSE_LEVEL_NUM = 0xFFFF
92 } M2MB_FOTA_TRACE_VERBOSE_LEVEL_E;
93 
94 typedef enum
95 {
96  M2MB_FOTA_TRACE_SPEED_NO_CHANGE,
97  M2MB_FOTA_TRACE_SPEED_4800,
98  M2MB_FOTA_TRACE_SPEED_9600,
99  M2MB_FOTA_TRACE_SPEED_115200,
100  M2MB_FOTA_TRACE_SPEED_230400,
101  M2MB_FOTA_TRACE_SPEED_460800,
102  M2MB_FOTA_TRACE_SPEED_921600,
103  M2MB_FOTA_TRACE_SPEED_BAUD_NUMBER,
104  M2MB_FOTA_TRACE_SPEED_NUM = 0xFFFF
105 } M2MB_FOTA_TRACE_SPEED_E;
106 
107 typedef enum
108 {
109  M2MB_FOTA_RESULT_CODE_UNDEF,
110  M2MB_FOTA_RESULT_CODE_OK,
111  M2MB_FOTA_RESULT_CODE_ERROR_GET_STATE,
112  M2MB_FOTA_RESULT_CODE_READ_ERROR,
113  M2MB_FOTA_RESULT_CODE_WRITE_ERROR,
114  M2MB_FOTA_RESULT_CODE_GET_INFO_ERROR,
115  M2MB_FOTA_RESULT_CODE_INVALID_TRACE_VERBOSE_LEVEL,
116  M2MB_FOTA_RESULT_CODE_INVALID_TRACE_SPEED,
117  M2MB_FOTA_RESULT_CODE_GET_PARTITION_FAIL,
118  M2MB_FOTA_RESULT_CODE_BAD_MALLOC,
119  M2MB_FOTA_RESULT_CODE_ERROR_NO_TAG,
120  M2MB_FOTA_RESULT_CODE_ERROR_MD5_CALCULATE,
121  M2MB_FOTA_RESULT_CODE_ERROR_MD5_CHECK,
122  M2MB_FOTA_RESULT_CODE_ERROR_BAD_ACTION,
123  M2MB_FOTA_RESULT_CODE_ERROR_PARTITION_COPY,
124  M2MB_FOTA_RESULT_CODE_ERROR_GET_FW_CNV_ELEMENTS,
125  M2MB_FOTA_RESULT_CODE_ERROR_CHECK_FW_DELTA_CNV_ELEMENTS,
126  M2MB_FOTA_RESULT_CODE_ERROR_ERASE_FW_CNV_ELEMENTS,
127  M2MB_FOTA_RESULT_CODE_INVALID_HANDLE,
128  M2MB_FOTA_RESULT_CODE_TASK_ERROR,
129  M2MB_FOTA_RESULT_CODE_ERROR_SHA256_CALCULATE,
130  M2MB_FOTA_RESULT_CODE_ERROR_SHA256_CHECK,
131  M2MB_FOTA_RESULT_CODE_ERROR_FOTA_IN_PROGRESS,
132  M2MB_FOTA_RESULT_CODE_NUM
133 } M2MB_FOTA_RESULT_CODE_E;
134 
135 typedef enum
136 {
137  M2MB_FOTA_CHECK_SETUP_SOURCE,
138  M2MB_FOTA_CHECK_SETUP_DESTINATION,
139  M2MB_FOTA_CHECK_SETUP_NUM
140 } M2MB_FOTA_CHECK_SETUP_E;
141 
142 typedef enum
143 {
144  M2MB_FOTA_DOWNLOAD_TYPE_HTTP,
145  M2MB_FOTA_DOWNLOAD_TYPE_HTTPS,
146  M2MB_FOTA_DOWNLOAD_TYPE_FTP,
147  M2MB_FOTA_DOWNLOAD_TYPE_FTPS,
148  M2MB_FOTA_DOWNLOAD_TYPE_COAP,
149  M2MB_FOTA_DOWNLOAD_TYPE_COAPS,
150  M2MB_FOTA_DOWNLOAD_TYPE_MAX_NUM
151 } M2MB_FOTA_DOWNLOAD_TYPE_E;
152 
153 typedef enum
154 {
155  M2MB_FOTA_DOWNLOAD_SUCCESS,
156  M2MB_FOTA_DOWNLOAD_TASK_INTERNAL_ERROR,
157  M2MB_FOTA_DOWNLOAD_NOT_RESOLVED,
158  M2MB_FOTA_DOWNLOAD_CONN_SOCKET_ERROR,
159  M2MB_FOTA_DOWNLOAD_CONN_CONTEXT_ERROR,
160  M2MB_FOTA_DOWNLOAD_ACCESS_DENIED,
161  M2MB_FOTA_DOWNLOAD_FILE_NOT_FOUND,
162  M2MB_FOTA_DOWNLOAD_SESSION_ERROR,
163  M2MB_FOTA_DOWNLOAD_MEMORY_ERROR
164 } M2MB_FOTA_DOWNLOAD_RESULT_E;
165 
166 typedef enum
167 {
168  M2MB_FOTA_EXTENDED_FTP_PROTOCOL,
169  M2MB_FOTA_BASIC_FTP_PROTOCOL
170 } M2MB_FOTA_FTP_PROTOCOL_E;
171 
172 typedef enum
173 {
174  M2MB_FOTA_EVENT_HTTP_DELTA_TRANSFER_END,
175  M2MB_FOTA_EVENT_FTP_DELTA_TRANSFER_END
176 } M2MB_FOTA_IND_E;
177 
178 typedef void *M2MB_FOTA_HANDLE;
179 
180 typedef struct
181 {
182  UINT8 cid;
183  CHAR server_addr[256]; // es.: "lwm2m.devicewise.com" or "34.200.145.8"
184  UINT16 port; // HTTP port
185  CHAR resource[256]; // HTTP resource path, es.: "/pubfile/lwm2m/MOTDATA_N.txt"
186  CHAR user[M2MB_PARAM_LEN]; // username (empty if not present)
187  CHAR psw[M2MB_PARAM_LEN]; // password (empty if not present)
188  UINT32 timeout; // milliseconds
189  BOOLEAN HTTPSEn; // secure HTTP ( on = TRUE /off = FALSE )
190  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.
191 } M2MB_FOTA_HTTP_SESSION_CFG_T;
192 
193 typedef struct
194 {
195  CHAR URI[256]; /* hostName/[pathName/]fileName */
196  CHAR user[M2MB_PARAM_LEN];
197  CHAR psw[M2MB_PARAM_LEN];
198  BOOLEAN passiveMode;
199  UINT32 timeout;
200  BOOLEAN IPPignoring;
201  BOOLEAN FTPSEn;
202  M2MB_FOTA_FTP_PROTOCOL_E protocol;
203 } M2MB_FOTA_FTP_SESSION_CFG_T;
204 
205 typedef struct
206 {
207  UINT8 connID;
208  UINT8 cid;
209  BOOLEAN cid_active;
210  UINT16 pktSize;
211  UINT16 inactivityTimeout;
212  UINT16 connectionTimeout;
213  UINT16 dataSendingTimeout;
214 } M2MB_FOTA_SOCKET_CFG_T;
215 
216 typedef struct
217 {
218  M2MB_FOTA_FTP_SESSION_CFG_T sessionCfg;
219  M2MB_FOTA_SOCKET_CFG_T socketCfg;
220 } M2MB_FOTA_FTP_CFG_T;
221 
222 // Callback resp_struct for M2MB_FOTA_EVENT_HTTP_DELTA_TRANSFER_END and M2MB_FOTA_EVENT_FTP_DELTA_TRANSFER_END events
223 typedef struct
224 {
225  M2MB_FOTA_DOWNLOAD_RESULT_E result;
226  UINT32 packageSize;
227 } M2MB_FOTA_CB_RESP_DELTA_TRANSFER_END_T;
228 
229 // Callback for FOTA events
230 // Params: h -> handle
231 // fota_event -> event type
232 // resp_size -> size of resp_struct
233 // resp_struct -> pointer to M2MB_FOTA_CB_RESP_DELTA_TRANSFER_END_T, in case of
234 // M2MB_FOTA_EVENT_HTTP_DELTA_TRANSFER_END and M2MB_FOTA_EVENT_FTP_DELTA_TRANSFER_END events
235 // userdata -> generic user data returned as it is in the callback.
236 typedef void ( *m2mb_fota_ind_callback )( M2MB_FOTA_HANDLE h, M2MB_FOTA_IND_E fota_event, UINT16 resp_size, void *resp_struct, void *userdata );
237 
238 
239 /* Global functions =============================================================================*/
240 /*-----------------------------------------------------------------------------------------------*/
305 /*-----------------------------------------------------------------------------------------------*/
306 M2MB_RESULT_E m2mb_fota_init
307 (
308  M2MB_FOTA_HANDLE *pHandle,
309  m2mb_fota_ind_callback callback,
310  void *userdata
311 );
312 
313 /*-----------------------------------------------------------------------------------------------*/
335 /*-----------------------------------------------------------------------------------------------*/
336 M2MB_RESULT_E m2mb_fota_deinit
337 (
338  M2MB_FOTA_HANDLE handle
339 );
340 
341 /*-----------------------------------------------------------------------------------------------*/
372 /*-----------------------------------------------------------------------------------------------*/
373 M2MB_RESULT_E m2mb_fota_get_delta
374 (
375  M2MB_FOTA_HANDLE handle,
376  M2MB_FOTA_DOWNLOAD_TYPE_E type,
377  void *settings
378 );
379 
380 /*-----------------------------------------------------------------------------------------------*/
402 /*-----------------------------------------------------------------------------------------------*/
403 M2MB_RESULT_E m2mb_fota_reset
404 (
405  M2MB_FOTA_HANDLE handle
406 );
407 
408 /*-----------------------------------------------------------------------------------------------*/
434 /*-----------------------------------------------------------------------------------------------*/
435 M2MB_RESULT_E m2mb_fota_result_code_get
436 (
437  M2MB_FOTA_HANDLE handle,
438  M2MB_FOTA_RESULT_CODE_E *pResultCode
439 );
440 
441 /*-----------------------------------------------------------------------------------------------*/
472 /*-----------------------------------------------------------------------------------------------*/
473 M2MB_RESULT_E m2mb_fota_config_set
474 (
475  M2MB_FOTA_HANDLE handle,
476  M2MB_FOTA_TRACE_VERBOSE_LEVEL_E TraceVerboseLevel,
477  M2MB_FOTA_TRACE_SPEED_E TraceSpeed
478 );
479 
480 /*-----------------------------------------------------------------------------------------------*/
510 /*-----------------------------------------------------------------------------------------------*/
511 M2MB_RESULT_E m2mb_fota_config_get
512 (
513  M2MB_FOTA_HANDLE handle,
514  M2MB_FOTA_TRACE_VERBOSE_LEVEL_E *pTraceVerboseLevel,
515  M2MB_FOTA_TRACE_SPEED_E *pTraceSpeed
516 );
517 
518 /*-----------------------------------------------------------------------------------------------*/
548 /*-----------------------------------------------------------------------------------------------*/
549 M2MB_RESULT_E m2mb_fota_update_package_info_get
550 (
551  M2MB_FOTA_HANDLE handle,
552  UINT32 *pBlockSize,
553  UINT32 *pPartitionSize
554 );
555 
556 /*-----------------------------------------------------------------------------------------------*/
593 /*-----------------------------------------------------------------------------------------------*/
594 M2MB_RESULT_E m2mb_fota_update_package_write
595 (
596  M2MB_FOTA_HANDLE handle,
597  UINT32 BlockAddress,
598  UINT8 *pBuffer
599 );
600 
601 /*-----------------------------------------------------------------------------------------------*/
627 /*-----------------------------------------------------------------------------------------------*/
628 M2MB_RESULT_E m2mb_fota_update_package_check_setup
629 (
630  M2MB_FOTA_HANDLE handle,
631  M2MB_FOTA_CHECK_SETUP_E Action
632 );
633 
634 /*-----------------------------------------------------------------------------------------------*/
656 /*-----------------------------------------------------------------------------------------------*/
657 M2MB_RESULT_E m2mb_fota_start
658 (
659  M2MB_FOTA_HANDLE handle
660 );
661 
662 /*-----------------------------------------------------------------------------------------------*/
687 /*-----------------------------------------------------------------------------------------------*/
688 M2MB_RESULT_E m2mb_fota_end
689 (
690  M2MB_FOTA_HANDLE handle
691 );
692 
693 /*-----------------------------------------------------------------------------------------------*/
719 /*-----------------------------------------------------------------------------------------------*/
720 M2MB_RESULT_E m2mb_fota_state_get
721 (
722  M2MB_FOTA_HANDLE handle,
723  M2MB_FOTA_STATE_E *pState
724 );
725 
726 
727 #endif /* M2M_M2MB_FOTA_H */
728 
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:193
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:205
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:180
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:216
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:223