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