Zigbee Protocol Controller 1.6.0
ota.hpp
Go to the documentation of this file.
1/******************************************************************************
2 * # License
3 * <b>Copyright 2021 Silicon Laboratories Inc. www.silabs.com</b>
4 ******************************************************************************
5 * The licensor of this software is Silicon Laboratories Inc. Your use of this
6 * software is governed by the terms of Silicon Labs Master Software License
7 * Agreement (MSLA) available at
8 * www.silabs.com/about-us/legal/master-software-license-agreement. This
9 * software is distributed to you in Source Code format and is governed by the
10 * sections of the MSLA applicable to Source Code.
11 *
12 *****************************************************************************/
13#ifndef OTA_H
14#define OTA_H
15
16// Unify Components
17#include "uic_typedefs.h"
18#include "sl_status.h"
19
20// Standard library imports
21#include <functional>
22#include <string>
23#include <ctime>
24
25constexpr uint16_t DEFAULT_CLUSTER_REVISION = 1;
26
121namespace uic_ota
122{
127enum class status_t {
128 IDLE, /*< Means the device is not currently
129 * participating in any part of an OTA process. */
130 DOWNLOAD_IN_PROGRESS, /*< One ore more firmware fragments
131 * has been sent but the transfer is not complete. */
132 WAITING_TO_UPGRADE, /*< Indicates that device has
133 * transferred the image but has not yet updated. Possibly
134 * because of the ApplyAfter timestamp has not yet passed.*/
136 * external/manual activation to complete the update.*/
137 WAIT_FOR_MORE, /*< Indicates that the client is still
138 * waiting to receive more OTA upgrade image files from
139 * the server. This is true for a client device that is
140 * composed of multiple processors and each processor
141 * requires different image or a system which requires
142 * multiple images. The client SHALL be in this
143 * state until it has received all necessary OTA
144 * upgrade images, then it SHALL transition to Download
145 * complete state.*/
146};
147
153enum class last_error_t {
154 SUCCESS = 0, /* The operation was successful. */
155 ABORT = 1, /*< Failed case when a client or a server decides
156 * to abort the upgrade process.*/
157 NOT_AUTHORIZED = 2,
158 INVALID_IMAGE = 3, /*< Invalid OTA upgrade image (ex. failed
159 * signature validation or signer information check or CRC
160 * check) */
161 REQUIRE_MORE_IMAGE = 4, /*< The client still requires more OTA
162 * upgrade image files in order to successfully upgrade */
163 NOT_SUPPORTED = 5,
164};
165
171 OK,
172 TIMED_OUT, /*< image provider can be reached. however it took too long to
173 receive and return the response. Request it dropped */
174 ERROR,
175};
176
186struct meta_t {
187 std::string uiid;
188 std::string unid;
190 std::string version;
191 std::string filename;
192};
193
201using image_available_func_t = std::function<void(const meta_t &)>;
202
209 = std::function<void(const image_ready_result_t, const std::string &)>;
210
226sl_status_t init(const image_available_func_t &image_available_cb,
227 const std::string &image_base_path,
228 unsigned long int cache_size,
229 uint32_t timeout_s,
230 uint16_t cluster_revision = DEFAULT_CLUSTER_REVISION);
231
239void subscribe_unid(const std::string &unid, const std::string &uiid);
240
249void unsubscribe_unid(const std::string &unid, const std::string &uiid);
250
258void unsubscribe_all_unids_uiid(const std::string &unid);
259
273void get_by_unid(const std::string &unid,
274 const std::string &uiid,
275 const image_ready_funct_t &get_ready_cb);
276
291 const dotdot_endpoint_id_t &endpoint,
292 const ota_uiid_t &uiid,
293 const status_t status);
294
308void update_size(const dotdot_unid_t &unid,
309 const dotdot_endpoint_id_t &endpoint,
310 const ota_uiid_t &uiid,
311 const size_t size_file);
312
327 const dotdot_endpoint_id_t &endpoint,
328 const ota_uiid_t &uiid,
329 const size_t offset);
330
345 const dotdot_endpoint_id_t &endpoint,
346 const ota_uiid_t &uiid,
347 const last_error_t last_error);
348
363 const dotdot_endpoint_id_t &endpoint,
364 const ota_uiid_t &uiid,
365 const time_t apply_after);
366
381 const dotdot_endpoint_id_t &endpoint,
382 const ota_uiid_t &uiid,
383 const std::string &current_version);
384
399 const dotdot_endpoint_id_t &endpoint,
400 const ota_uiid_t &uiid,
401 const std::string &target_version);
402
407
415
423
424}; // namespace uic_ota
426#endif
uint32_t sl_status_t
Definition: sl_status.h:139
Definition: ota.hpp:122
last_error_t
Structure used to indicate the last error status. Used by protocol controllers to report firmware dow...
Definition: ota.hpp:153
@ NOT_AUTHORIZED
no permission to download image
status_t
Structure used to indicate the firmware upload status. used in function ota::status_update.
Definition: ota.hpp:127
@ WAITING_TO_UPGRADE_VIA_EXTERNAL_EVENT
void update_target_version(const dotdot_unid_t &unid, const dotdot_endpoint_id_t &endpoint, const ota_uiid_t &uiid, const std::string &target_version)
Target version update of firmware upgrade OTA MQTT for the image_listener component specific for a UI...
void subscribe_unid(const std::string &unid, const std::string &uiid)
Listen for images that match the UNID + UIID pair/ when changes to this key is detected,...
void unretain_ota_status()
Clean up MQTT status for UNIDs and endpoints.
void unsubscribe_all_unids_uiid(const std::string &unid)
Stop watching all images for unid and unretain MQTT messages.
void clear_cache()
Utility function to clear the internal cache.
image_ready_result_t
Result enum that describes if an image is ready for the caller to be used to donwload its clients.
Definition: ota.hpp:170
@ ERROR
mqtt client error. the mqtt transport could not get images
void update_apply_after(const dotdot_unid_t &unid, const dotdot_endpoint_id_t &endpoint, const ota_uiid_t &uiid, const time_t apply_after)
Apply after update of firmware upgrade OTA MQTT for the image_listener component specific for a UIID,...
void update_current_version(const dotdot_unid_t &unid, const dotdot_endpoint_id_t &endpoint, const ota_uiid_t &uiid, const std::string &current_version)
Current version update of firmware upgrade OTA MQTT for the image_listener component specific for a U...
sl_status_t init(const image_available_func_t &image_available_cb, const std::string &image_base_path, unsigned long int cache_size, uint32_t timeout_s, uint16_t cluster_revision=DEFAULT_CLUSTER_REVISION)
initialize ota_listener
void update_offset(const dotdot_unid_t &unid, const dotdot_endpoint_id_t &endpoint, const ota_uiid_t &uiid, const size_t offset)
Offset update of firmware upgrade OTA MQTT for the image_listener component specific for a UIID,...
void update_status(const dotdot_unid_t &unid, const dotdot_endpoint_id_t &endpoint, const ota_uiid_t &uiid, const status_t status)
Status update of firmware upgrade OTA MQTT for the image_listener component specific for a UIID,...
void update_size(const dotdot_unid_t &unid, const dotdot_endpoint_id_t &endpoint, const ota_uiid_t &uiid, const size_t size_file)
Size file of firmware upgrade OTA MQTT for the image_listener component specific for a UIID,...
void update_last_error(const dotdot_unid_t &unid, const dotdot_endpoint_id_t &endpoint, const ota_uiid_t &uiid, const last_error_t last_error)
Last error update of firmware upgrade OTA MQTT for the image_listener component specific for a UIID,...
std::function< void(const image_ready_result_t, const std::string &)> image_ready_funct_t
this callback is returned when the actually firmware image is downloaded and stored to disk,...
Definition: ota.hpp:209
void unsubscribe_unid(const std::string &unid, const std::string &uiid)
Stop watching specific images.
std::function< void(const meta_t &)> image_available_func_t
Callback function that is triggered when an new firmware image is detected on the image provider.
Definition: ota.hpp:201
void unretain_ota_status_by_unid(const dotdot_unid_t &unid)
Clean up MQTT status for a UNID and related endpoints.
void get_by_unid(const std::string &unid, const std::string &uiid, const image_ready_funct_t &get_ready_cb)
After an image_available call is triggered.
constexpr uint16_t DEFAULT_CLUSTER_REVISION
Definition: ota.hpp:25
SL Status Codes.
Struct that describes meta for a new available image.
Definition: ota.hpp:186
time_t apply_after
Definition: ota.hpp:189
std::string uiid
Definition: ota.hpp:187
std::string filename
Definition: ota.hpp:191
std::string version
Definition: ota.hpp:190
std::string unid
Definition: ota.hpp:188
Generic type definitions for Unify.
const char * ota_uiid_t
Definition: uic_typedefs.h:40
uint8_t dotdot_endpoint_id_t
Definition: uic_typedefs.h:38
const char * dotdot_unid_t
Definition: uic_typedefs.h:39