m2mb API docs  25.21.002
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_INTEGRITY_CHECK = 0xFFFF,
76  M2MB_FOTA_INTEGRITY_PASS = 0xFFFE,
77  M2MB_FOTA_INTEGRITY_FAIL = 0xFFFD
78 } M2MB_FOTA_INTEGRITY_E;
79 
80 typedef enum
81 {
82  M2MB_FOTA_TRACE_VERBOSE_LEVEL_0,
83  M2MB_FOTA_TRACE_VERBOSE_LEVEL_1,
84  M2MB_FOTA_TRACE_VERBOSE_LEVEL_2,
85  M2MB_FOTA_TRACE_VERBOSE_LEVEL_ALL,
86  M2MB_FOTA_TRACE_VERBOSE_LEVEL_NO_CHANGE,
87  M2MB_FOTA_TRACE_VERBOSE_LEVEL_PRINT = 0xFFF0,
88  M2MB_FOTA_TRACE_VERBOSE_LEVEL_NUM = 0xFFFF
89 } M2MB_FOTA_TRACE_VERBOSE_LEVEL_E;
90 
91 typedef enum
92 {
93  M2MB_FOTA_TRACE_SPEED_NO_CHANGE,
94  M2MB_FOTA_TRACE_SPEED_4800,
95  M2MB_FOTA_TRACE_SPEED_9600,
96  M2MB_FOTA_TRACE_SPEED_115200,
97  M2MB_FOTA_TRACE_SPEED_230400,
98  M2MB_FOTA_TRACE_SPEED_460800,
99  M2MB_FOTA_TRACE_SPEED_921600,
100  M2MB_FOTA_TRACE_SPEED_BAUD_NUMBER,
101  M2MB_FOTA_TRACE_SPEED_NUM = 0xFFFF
102 } M2MB_FOTA_TRACE_SPEED_E;
103 
104 typedef enum
105 {
106  M2MB_FOTA_RESULT_CODE_UNDEF,
107  M2MB_FOTA_RESULT_CODE_OK,
108  M2MB_FOTA_RESULT_CODE_ERROR_GET_STATE,
109  M2MB_FOTA_RESULT_CODE_READ_ERROR,
110  M2MB_FOTA_RESULT_CODE_WRITE_ERROR,
111  M2MB_FOTA_RESULT_CODE_GET_INFO_ERROR,
112  M2MB_FOTA_RESULT_CODE_INVALID_TRACE_VERBOSE_LEVEL,
113  M2MB_FOTA_RESULT_CODE_INVALID_TRACE_SPEED,
114  M2MB_FOTA_RESULT_CODE_GET_PARTITION_FAIL,
115  M2MB_FOTA_RESULT_CODE_BAD_MALLOC,
116  M2MB_FOTA_RESULT_CODE_ERROR_NO_TAG,
117  M2MB_FOTA_RESULT_CODE_ERROR_MD5_CALCULATE,
118  M2MB_FOTA_RESULT_CODE_ERROR_MD5_CHECK,
119  M2MB_FOTA_RESULT_CODE_ERROR_BAD_ACTION,
120  M2MB_FOTA_RESULT_CODE_ERROR_PARTITION_COPY,
121  M2MB_FOTA_RESULT_CODE_ERROR_GET_FW_CNV_ELEMENTS,
122  M2MB_FOTA_RESULT_CODE_ERROR_CHECK_FW_DELTA_CNV_ELEMENTS,
123  M2MB_FOTA_RESULT_CODE_ERROR_ERASE_FW_CNV_ELEMENTS,
124  M2MB_FOTA_RESULT_CODE_INVALID_HANDLE,
125  M2MB_FOTA_RESULT_CODE_TASK_ERROR,
126  M2MB_FOTA_RESULT_CODE_ERROR_SHA256_CALCULATE,
127  M2MB_FOTA_RESULT_CODE_ERROR_SHA256_CHECK,
128  M2MB_FOTA_RESULT_CODE_ERROR_FOTA_IN_PROGRESS,
129  M2MB_FOTA_RESULT_CODE_NUM
130 } M2MB_FOTA_RESULT_CODE_E;
131 
132 typedef enum
133 {
134  M2MB_FOTA_CHECK_SETUP_SOURCE,
135  M2MB_FOTA_CHECK_SETUP_DESTINATION,
136  M2MB_FOTA_CHECK_SETUP_NUM
137 } M2MB_FOTA_CHECK_SETUP_E;
138 
139 typedef enum
140 {
141  M2MB_FOTA_DOWNLOAD_TYPE_HTTP,
142  M2MB_FOTA_DOWNLOAD_TYPE_HTTPS,
143  M2MB_FOTA_DOWNLOAD_TYPE_FTP,
144  M2MB_FOTA_DOWNLOAD_TYPE_FTPS,
145  M2MB_FOTA_DOWNLOAD_TYPE_COAP,
146  M2MB_FOTA_DOWNLOAD_TYPE_COAPS,
147  M2MB_FOTA_DOWNLOAD_TYPE_MAX_NUM
148 } M2MB_FOTA_DOWNLOAD_TYPE_E;
149 
150 typedef enum
151 {
152  M2MB_FOTA_DOWNLOAD_SUCCESS,
153  M2MB_FOTA_DOWNLOAD_TASK_INTERNAL_ERROR,
154  M2MB_FOTA_DOWNLOAD_NOT_RESOLVED,
155  M2MB_FOTA_DOWNLOAD_CONN_SOCKET_ERROR,
156  M2MB_FOTA_DOWNLOAD_CONN_CONTEXT_ERROR,
157  M2MB_FOTA_DOWNLOAD_ACCESS_DENIED,
158  M2MB_FOTA_DOWNLOAD_FILE_NOT_FOUND,
159  M2MB_FOTA_DOWNLOAD_SESSION_ERROR,
160  M2MB_FOTA_DOWNLOAD_MEMORY_ERROR
161 } M2MB_FOTA_DOWNLOAD_RESULT_E;
162 
163 typedef enum
164 {
165  M2MB_FOTA_EXTENDED_FTP_PROTOCOL,
166  M2MB_FOTA_BASIC_FTP_PROTOCOL
167 } M2MB_FOTA_FTP_PROTOCOL_E;
168 
169 typedef enum
170 {
171  M2MB_FOTA_EVENT_HTTP_DELTA_TRANSFER_END,
172  M2MB_FOTA_EVENT_FTP_DELTA_TRANSFER_END
173 } M2MB_FOTA_IND_E;
174 
175 typedef void *M2MB_FOTA_HANDLE;
176 
177 typedef struct
178 {
179  UINT8 cid;
180  CHAR server_addr[256]; // es.: "lwm2m.devicewise.com" or "34.200.145.8"
181  UINT16 port; // HTTP port
182  CHAR resource[256]; // HTTP resource path, es.: "/pubfile/lwm2m/MOTDATA_N.txt"
183  CHAR user[M2MB_PARAM_LEN]; // username (empty if not present)
184  CHAR psw[M2MB_PARAM_LEN]; // password (empty if not present)
185  UINT32 timeout; // milliseconds
186  BOOLEAN HTTPSEn; // secure HTTP ( on = TRUE /off = FALSE )
187  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.
188 } M2MB_FOTA_HTTP_SESSION_CFG_T;
189 
190 typedef struct
191 {
192  CHAR URI[256]; /* hostName/[pathName/]fileName */
193  CHAR user[M2MB_PARAM_LEN];
194  CHAR psw[M2MB_PARAM_LEN];
195  BOOLEAN passiveMode;
196  UINT32 timeout;
197  BOOLEAN IPPignoring;
198  BOOLEAN FTPSEn;
199  M2MB_FOTA_FTP_PROTOCOL_E protocol;
200 } M2MB_FOTA_FTP_SESSION_CFG_T;
201 
202 typedef struct
203 {
204  UINT8 connID;
205  UINT8 cid;
206  BOOLEAN cid_active;
207  UINT16 pktSize;
208  UINT16 inactivityTimeout;
209  UINT16 connectionTimeout;
210  UINT16 dataSendingTimeout;
211 } M2MB_FOTA_SOCKET_CFG_T;
212 
213 typedef struct
214 {
215  M2MB_FOTA_FTP_SESSION_CFG_T sessionCfg;
216  M2MB_FOTA_SOCKET_CFG_T socketCfg;
217 } M2MB_FOTA_FTP_CFG_T;
218 
219 // Callback resp_struct for M2MB_FOTA_EVENT_HTTP_DELTA_TRANSFER_END and M2MB_FOTA_EVENT_FTP_DELTA_TRANSFER_END events
220 typedef struct
221 {
222  M2MB_FOTA_DOWNLOAD_RESULT_E result;
223  UINT32 packageSize;
224 } M2MB_FOTA_CB_RESP_DELTA_TRANSFER_END_T;
225 
226 // Callback for FOTA events
227 // Params: h -> handle
228 // fota_event -> event type
229 // resp_size -> size of resp_struct
230 // resp_struct -> pointer to M2MB_FOTA_CB_RESP_DELTA_TRANSFER_END_T, in case of
231 // M2MB_FOTA_EVENT_HTTP_DELTA_TRANSFER_END and M2MB_FOTA_EVENT_FTP_DELTA_TRANSFER_END events
232 // userdata -> generic user data returned as it is in the callback.
233 typedef void ( *m2mb_fota_ind_callback )( M2MB_FOTA_HANDLE h, M2MB_FOTA_IND_E fota_event, UINT16 resp_size, void *resp_struct, void *userdata );
234 
235 
236 /* Global functions =============================================================================*/
237 /*-----------------------------------------------------------------------------------------------*/
302 /*-----------------------------------------------------------------------------------------------*/
303 M2MB_RESULT_E m2mb_fota_init
304 (
305  M2MB_FOTA_HANDLE *pHandle,
306  m2mb_fota_ind_callback callback,
307  void *userdata
308 );
309 
310 /*-----------------------------------------------------------------------------------------------*/
332 /*-----------------------------------------------------------------------------------------------*/
333 M2MB_RESULT_E m2mb_fota_deinit
334 (
335  M2MB_FOTA_HANDLE handle
336 );
337 
338 /*-----------------------------------------------------------------------------------------------*/
369 /*-----------------------------------------------------------------------------------------------*/
370 M2MB_RESULT_E m2mb_fota_get_delta
371 (
372  M2MB_FOTA_HANDLE handle,
373  M2MB_FOTA_DOWNLOAD_TYPE_E type,
374  void *settings
375 );
376 
377 /*-----------------------------------------------------------------------------------------------*/
400 /*-----------------------------------------------------------------------------------------------*/
401 M2MB_RESULT_E m2mb_fota_reset
402 (
403  M2MB_FOTA_HANDLE handle
404 );
405 
406 /*-----------------------------------------------------------------------------------------------*/
432 /*-----------------------------------------------------------------------------------------------*/
433 M2MB_RESULT_E m2mb_fota_result_code_get
434 (
435  M2MB_FOTA_HANDLE handle,
436  M2MB_FOTA_RESULT_CODE_E *pResultCode
437 );
438 
439 /*-----------------------------------------------------------------------------------------------*/
470 /*-----------------------------------------------------------------------------------------------*/
471 M2MB_RESULT_E m2mb_fota_config_set
472 (
473  M2MB_FOTA_HANDLE handle,
474  M2MB_FOTA_TRACE_VERBOSE_LEVEL_E TraceVerboseLevel,
475  M2MB_FOTA_TRACE_SPEED_E TraceSpeed
476 );
477 
478 /*-----------------------------------------------------------------------------------------------*/
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 /*-----------------------------------------------------------------------------------------------*/
550 /*-----------------------------------------------------------------------------------------------*/
551 M2MB_RESULT_E m2mb_fota_update_package_info_get
552 (
553  M2MB_FOTA_HANDLE handle,
554  UINT32 *pBlockSize,
555  UINT32 *pPartitionSize
556 );
557 
558 /*-----------------------------------------------------------------------------------------------*/
597 /*-----------------------------------------------------------------------------------------------*/
598 M2MB_RESULT_E m2mb_fota_update_package_write
599 (
600  M2MB_FOTA_HANDLE handle,
601  UINT32 BlockAddress,
602  UINT8 *pBuffer
603 );
604 
605 /*-----------------------------------------------------------------------------------------------*/
631 /*-----------------------------------------------------------------------------------------------*/
632 M2MB_RESULT_E m2mb_fota_update_package_check_setup
633 (
634  M2MB_FOTA_HANDLE handle,
635  M2MB_FOTA_CHECK_SETUP_E Action
636 );
637 
638 /*-----------------------------------------------------------------------------------------------*/
660 /*-----------------------------------------------------------------------------------------------*/
661 M2MB_RESULT_E m2mb_fota_start
662 (
663  M2MB_FOTA_HANDLE handle
664 );
665 
666 /*-----------------------------------------------------------------------------------------------*/
693 /*-----------------------------------------------------------------------------------------------*/
694 M2MB_RESULT_E m2mb_fota_end
695 (
696  M2MB_FOTA_HANDLE handle
697 );
698 
699 /*-----------------------------------------------------------------------------------------------*/
727 /*-----------------------------------------------------------------------------------------------*/
728 M2MB_RESULT_E m2mb_fota_state_get
729 (
730  M2MB_FOTA_HANDLE handle,
731  M2MB_FOTA_STATE_E *pState
732 );
733 
734 
735 #endif /* M2M_M2MB_FOTA_H */
736 
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:190
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:202
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:177
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:213
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:220