OTA_Firmware_Update.h

Go to the documentation of this file.

#ifndef OTA_Firmware_Update_h
#define OTA_Firmware_Update_h
 
// Local includes.
#include "Attribute_Request.h"
#include "Shared_Attribute_Update.h"
#include "OTA_Handler.h"
#include "IAPI_Implementation.h"
 
 
uint8_t constexpr MAX_FW_TOPIC_SIZE = 33U;
uint8_t constexpr OTA_ATTRIBUTE_KEYS_AMOUNT = 5U;
char constexpr NO_FW_REQUEST_RESPONSE[] = "Did not receive requested shared attribute firmware keys. Ensure keys exist and device is connected";
// Firmware topics.
char constexpr FIRMWARE_RESPONSE_TOPIC[] = "v2/fw/response/%u/chunk/";
char constexpr FIRMWARE_REQUEST_TOPIC[] = "v2/fw/request/%u/chunk/%u";
// Firmware data keys.
char constexpr CURR_FW_TITLE_KEY[] = "current_fw_title";
char constexpr CURR_FW_VER_KEY[] = "current_fw_version";
char constexpr FW_ERROR_KEY[] = "fw_error";
char constexpr FW_STATE_KEY[] = "fw_state";
char constexpr FW_VER_KEY[] = "fw_version";
char constexpr FW_TITLE_KEY[] = "fw_title";
char constexpr FW_CHKS_KEY[] = "fw_checksum";
char constexpr FW_CHKS_ALGO_KEY[] = "fw_checksum_algorithm";
char constexpr FW_SIZE_KEY[] = "fw_size";
char constexpr CHECKSUM_AGORITM_MD5[] = "MD5";
char constexpr CHECKSUM_AGORITM_SHA256[] = "SHA256";
char constexpr CHECKSUM_AGORITM_SHA384[] = "SHA384";
char constexpr CHECKSUM_AGORITM_SHA512[] = "SHA512";
// Log messages.
char constexpr NUMBER_PRINTF[] = "%u";
char constexpr NO_FW[] = "Missing shared attribute firmware keys. Ensure you assigned an OTA update with binary";
char constexpr EMPTY_FW[] = "Received shared attribute firmware keys were NULL";
char constexpr FW_NOT_FOR_US[] = "Received firmware title (%s) is different and not meant for this device (%s)";
char constexpr FW_CHKS_ALGO_NOT_SUPPORTED[] = "Received checksum algorithm (%s) is not supported";
char constexpr NOT_ENOUGH_RAM[] = "Temporary allocating more internal client buffer failed, decrease OTA chunk size or decrease overall heap usage";
char constexpr RESETTING_FAILED[] = "Preparing for OTA firmware updates failed, attributes might be NULL";
#if THINGSBOARD_ENABLE_DEBUG
char constexpr PAGE_BREAK[] = "=================================";
char constexpr NEW_FW[] = "A new Firmware is available:";
char constexpr FROM_TOO[] = "(%s) => (%s)";
char constexpr DOWNLOADING_FW[] = "Attempting to download over MQTT...";
#endif // THINGSBOARD_ENABLE_DEBUG
 
 
template <typename Logger = DefaultLogger>
class OTA_Firmware_Update : public IAPI_Implementation {
#if THINGSBOARD_ENABLE_DYNAMIC
    using Request_Callback_Value = Attribute_Request_Callback;
    using Request_Callback_Container = Attribute_Request<Logger>;
    using Update_Callback_Value = Shared_Attribute_Callback;
    using Update_Callback_Container = Shared_Attribute_Update<Logger>;
#else
    using Request_Callback_Value = Attribute_Request_Callback<OTA_ATTRIBUTE_KEYS_AMOUNT>;
    using Request_Callback_Container = Attribute_Request<1U, OTA_ATTRIBUTE_KEYS_AMOUNT, Logger>;
    using Update_Callback_Value = Shared_Attribute_Callback<OTA_ATTRIBUTE_KEYS_AMOUNT>;
    using Update_Callback_Container = Shared_Attribute_Update<1U, OTA_ATTRIBUTE_KEYS_AMOUNT, Logger>;
#endif // THINGSBOARD_ENABLE_DYNAMIC
 
  public:
    OTA_Firmware_Update()
      : m_subscribe_api_callback()
      , m_send_json_callback()
      , m_send_json_string_callback()
      , m_subscribe_topic_callback()
      , m_unsubscribe_topic_callback()
      , m_get_receive_size_callback()
      , m_get_send_size_callback()
      , m_set_buffer_size_callback()
      , m_get_request_id_callback()
      , m_fw_callback()
      , m_previous_buffer_size(0U)
      , m_changed_buffer_size(false)
#if THINGSBOARD_ENABLE_STL
      , m_ota(std::bind(&OTA_Firmware_Update::Publish_Chunk_Request, this, std::placeholders::_1, std::placeholders::_2), std::bind(&OTA_Firmware_Update::Firmware_Send_State, this, std::placeholders::_1, std::placeholders::_2), std::bind(&OTA_Firmware_Update::Firmware_OTA_Unsubscribe, this))
#else
      , m_ota(OTA_Firmware_Update::staticPublishChunk, OTA_Firmware_Update::staticFirmwareSend, OTA_Firmware_Update::staticUnsubscribe)
#endif // THINGSBOARD_ENABLE_STL
      , m_response_topic()
      , m_fw_attribute_update()
      , m_fw_attribute_request()
    {
        // Can be ignored, because the topic is set correctly once we start an update anyway, therefore we simply insert 0 as the request id for now.
        // It just has to be set to an actual value that is not an empty string, because that would make the internal callback receive all other responses from the server as well,
        // even if they are not meant for this class and we are not currently updating the device
        (void)snprintf(m_response_topic, sizeof(m_response_topic), FIRMWARE_RESPONSE_TOPIC, 0U);
#if !THINGSBOARD_ENABLE_STL
        m_subscribedInstance = nullptr;
#endif // !THINGSBOARD_ENABLE_STL
    }
 
    ~OTA_Firmware_Update() override = default;
 
    bool Start_Firmware_Update(OTA_Update_Callback const & callback) {
        if (!Prepare_Firmware_Settings(callback))  {
            Logger::printfln(RESETTING_FAILED);
            return false;
        }
 
        auto & request_timeout = m_fw_callback.Get_Request_Timeout();
        constexpr char const * array[OTA_ATTRIBUTE_KEYS_AMOUNT] = {FW_CHKS_KEY, FW_CHKS_ALGO_KEY, FW_SIZE_KEY, FW_TITLE_KEY, FW_VER_KEY};
#if THINGSBOARD_ENABLE_STL
        Request_Callback_Value const fw_request_callback(std::bind(&OTA_Firmware_Update::Firmware_Shared_Attribute_Received, this, std::placeholders::_1), request_timeout.Get_Timeout(), std::bind(&OTA_Firmware_Update::Request_Timeout, this), array + 0U, array + OTA_ATTRIBUTE_KEYS_AMOUNT);
#else
        Request_Callback_Value const fw_request_callback(OTA_Firmware_Update::onStaticFirmwareReceived, request_timeout.Get_Timeout(), OTA_Firmware_Update::onStaticRequestTimeout, array + 0U, array + OTA_ATTRIBUTE_KEYS_AMOUNT);
#endif // THINGSBOARD_ENABLE_STL
        return m_fw_attribute_request.Shared_Attributes_Request(fw_request_callback);
    }
 
    void Stop_Firmware_Update() {
        m_ota.Stop_Firmware_Update();
    }
 
    bool Subscribe_Firmware_Update(OTA_Update_Callback const & callback) {
        if (!Prepare_Firmware_Settings(callback))  {
            Logger::printfln(RESETTING_FAILED);
            return false;
        }
 
        char const * array[OTA_ATTRIBUTE_KEYS_AMOUNT] = {FW_CHKS_KEY, FW_CHKS_ALGO_KEY, FW_SIZE_KEY, FW_TITLE_KEY, FW_VER_KEY};
#if THINGSBOARD_ENABLE_STL
        Update_Callback_Value const fw_update_callback(std::bind(&OTA_Firmware_Update::Firmware_Shared_Attribute_Received, this, std::placeholders::_1), array + 0U, array + OTA_ATTRIBUTE_KEYS_AMOUNT);
#else
        Update_Callback_Value const fw_update_callback(OTA_Firmware_Update::onStaticFirmwareReceived, array + 0U, array + OTA_ATTRIBUTE_KEYS_AMOUNT);
#endif // THINGSBOARD_ENABLE_STL
        return m_fw_attribute_update.Shared_Attributes_Subscribe(fw_update_callback);
    }
 
    API_Process_Type Get_Process_Type() const override {
        return API_Process_Type::RAW;
    }
 
    void Process_Response(char const * topic, uint8_t * payload, uint32_t length) override {
        auto const & request_id = m_fw_callback.Get_Request_ID();
        auto const chunk = Helper::Split_Topic_Into_Request_ID(topic, Helper::Calculate_Print_Size(FIRMWARE_RESPONSE_TOPIC, request_id));
        m_ota.Process_Firmware_Packet(chunk, payload, length);
    }
 
    void Process_Json_Response(char const * topic, JsonDocument const & data) override {
        // Nothing to do
    }
 
    bool Is_Response_Topic_Matching(char const * topic) const override {
        return strncmp(m_response_topic, topic, strlen(m_response_topic)) == 0;
    }
 
    bool Unsubscribe() override {
        Stop_Firmware_Update();
        return true;
    }
 
    bool Resubscribe_Permanent_Subscriptions() override {
        return Firmware_OTA_Subscribe();
    }
 
#if !THINGSBOARD_USE_ESP_TIMER
    void loop() override {
        m_ota.update();
    }
#endif // !THINGSBOARD_USE_ESP_TIMER
 
    void Initialize() override {
        m_subscribe_api_callback.Call_Callback(m_fw_attribute_update);
        m_subscribe_api_callback.Call_Callback(m_fw_attribute_request);
    }
 
    void Set_Client_Callbacks(Callback<void, IAPI_Implementation &>::function subscribe_api_callback, Callback<bool, char const * const, JsonDocument const &>::function send_json_callback, Callback<bool, char const * const, char const * const>::function send_json_string_callback, Callback<bool, char const * const>::function subscribe_topic_callback, Callback<bool, char const * const>::function unsubscribe_topic_callback, Callback<uint16_t>::function get_receive_size_callback, Callback<uint16_t>::function get_send_size_callback, Callback<bool, uint16_t, uint16_t>::function set_buffer_size_callback, Callback<size_t *>::function get_request_id_callback) override {
        m_subscribe_api_callback.Set_Callback(subscribe_api_callback);
        m_send_json_callback.Set_Callback(send_json_callback);
        m_send_json_string_callback.Set_Callback(send_json_string_callback);
        m_subscribe_topic_callback.Set_Callback(subscribe_topic_callback);
        m_unsubscribe_topic_callback.Set_Callback(unsubscribe_topic_callback);
        m_get_receive_size_callback.Set_Callback(get_receive_size_callback);
        m_get_send_size_callback.Set_Callback(get_send_size_callback);
        m_set_buffer_size_callback.Set_Callback(set_buffer_size_callback);
        m_get_request_id_callback.Set_Callback(get_request_id_callback);
    }
 
  private:
    bool Firmware_Send_Info(char const * current_fw_title, char const * current_fw_version) {
        StaticJsonDocument<JSON_OBJECT_SIZE(2U)> current_firmware_info;
        current_firmware_info[CURR_FW_TITLE_KEY] = current_fw_title;
        current_firmware_info[CURR_FW_VER_KEY] = current_fw_version;
        return m_send_json_callback.Call_Callback(TELEMETRY_TOPIC, current_firmware_info);
    }
 
    bool Firmware_Send_State(char const * current_fw_state, char const * fw_error = "") {
        StaticJsonDocument<JSON_OBJECT_SIZE(2U)> current_firmware_state;
        current_firmware_state[FW_ERROR_KEY] = fw_error;
        current_firmware_state[FW_STATE_KEY] = current_fw_state;
        return m_send_json_callback.Call_Callback(TELEMETRY_TOPIC, current_firmware_state);
    }
 
    bool Prepare_Firmware_Settings(OTA_Update_Callback const & callback) {
        char const * current_fw_title = callback.Get_Firmware_Title();
        char const * current_fw_version = callback.Get_Firmware_Version();
 
        if (Helper::String_IsNull_Or_Empty(current_fw_title) || Helper::String_IsNull_Or_Empty(current_fw_version)) {
            return false;
        }
        else if (!Firmware_Send_Info(current_fw_title, current_fw_version)) {
            return false;
        }
 
        size_t * p_request_id = m_get_request_id_callback.Call_Callback();
        if (p_request_id == nullptr) {
            Logger::printfln(REQUEST_ID_NULL);
            return false;
        }
        auto & request_id = *p_request_id;
 
        m_fw_callback = callback;
        m_fw_callback.Set_Request_ID(++request_id);
        (void)snprintf(m_response_topic, sizeof(m_response_topic), FIRMWARE_RESPONSE_TOPIC, request_id);
        return true;
    }
 
    bool Firmware_OTA_Subscribe() {
        return true;
    }
 
    bool Firmware_OTA_Unsubscribe() {
        // Buffer size has been set to another value before the update,
        // to allow to receive ota chunck packets that might be much bigger than the normal
        // buffer size would allow, therefore we return to the previous value to decrease overall memory usage
        if (m_changed_buffer_size) {
            (void)m_set_buffer_size_callback.Call_Callback(m_previous_buffer_size, m_get_send_size_callback.Call_Callback());
        }
        // Reset now not needed private member variables
        m_fw_callback = OTA_Update_Callback();
        return true;
    }
 
    bool Publish_Chunk_Request(size_t const & request_id, size_t const & request_chunck) {
        uint16_t const & chunk_size = m_fw_callback.Get_Chunk_Size();
 
        char size[Helper::Calculate_Print_Size(NUMBER_PRINTF, chunk_size)] = {};
        (void)snprintf(size, sizeof(size), NUMBER_PRINTF, chunk_size);
 
        char topic[Helper::Calculate_Print_Size(FIRMWARE_REQUEST_TOPIC, request_id, request_chunck)] = {};
        (void)snprintf(topic, sizeof(topic), FIRMWARE_REQUEST_TOPIC, request_id, request_chunck);
        return m_send_json_string_callback.Call_Callback(topic, size);
    }
 
    void Request_Timeout() {
        Logger::printfln(NO_FW_REQUEST_RESPONSE);
        Firmware_Send_State(FW_STATE_FAILED, NO_FW_REQUEST_RESPONSE);
    }
 
    void Firmware_Shared_Attribute_Received(JsonObjectConst const & data) {
        // Check if firmware is available for our device
        if (!data.containsKey(FW_VER_KEY) || !data.containsKey(FW_TITLE_KEY) || !data.containsKey(FW_CHKS_KEY) || !data.containsKey(FW_CHKS_ALGO_KEY) || !data.containsKey(FW_SIZE_KEY)) {
            Logger::printfln(NO_FW);
            Firmware_Send_State(FW_STATE_FAILED, NO_FW);
            return;
        }
 
        char const * fw_title = data[FW_TITLE_KEY];
        char const * fw_version = data[FW_VER_KEY];
        char const * fw_checksum = data[FW_CHKS_KEY];
        char const * fw_algorithm = data[FW_CHKS_ALGO_KEY];
        auto const fw_size = data[FW_SIZE_KEY];
 
        char const * curr_fw_title = m_fw_callback.Get_Firmware_Title();
        char const * curr_fw_version = m_fw_callback.Get_Firmware_Version();
 
        if (fw_title == nullptr || fw_version == nullptr || curr_fw_title == nullptr || curr_fw_version == nullptr || fw_algorithm == nullptr || fw_checksum == nullptr) {
            Logger::printfln(EMPTY_FW);
            Firmware_Send_State(FW_STATE_FAILED, EMPTY_FW);
            return;
        }
        // If firmware version and title is the same, we do not initiate an update, because we expect the type of binary to be the same one we are currently using
        // and therefore updating would be useless as we have already updated previously
        else if (strncmp(curr_fw_title, fw_title, strlen(curr_fw_title)) == 0U && strncmp(curr_fw_version, fw_version, strlen(curr_fw_version)) == 0U) {
            Firmware_Send_State(FW_STATE_UPDATED);
            return;
        }
        // If firmware title is not the same, we do not initiate an update, because we expect the binary to be for another type of device
        // and downloading it on this device could possibly cause hardware issues or even destroy the device
        else if (strncmp(curr_fw_title, fw_title, strlen(curr_fw_title)) != 0U) {
            char message[strlen(FW_NOT_FOR_US) + strlen(fw_title) + strlen(curr_fw_title) + 3U] = {};
            (void)snprintf(message, sizeof(message), FW_NOT_FOR_US, fw_title, curr_fw_title);
            Logger::printfln(message);
            Firmware_Send_State(FW_STATE_FAILED, message);
            return;
        }
 
        mbedtls_md_type_t fw_checksum_algorithm = mbedtls_md_type_t{};
 
        if (strncmp(CHECKSUM_AGORITM_MD5, fw_algorithm, strlen(CHECKSUM_AGORITM_MD5)) == 0U) {
            fw_checksum_algorithm = mbedtls_md_type_t::MBEDTLS_MD_MD5;
        }
        else if (strncmp(CHECKSUM_AGORITM_SHA256, fw_algorithm, strlen(CHECKSUM_AGORITM_SHA256)) == 0U) {
            fw_checksum_algorithm = mbedtls_md_type_t::MBEDTLS_MD_SHA256;
        }
        else if (strncmp(CHECKSUM_AGORITM_SHA384, fw_algorithm, strlen(CHECKSUM_AGORITM_SHA384)) == 0U) {
            fw_checksum_algorithm = mbedtls_md_type_t::MBEDTLS_MD_SHA384;
        }
        else if (strncmp(CHECKSUM_AGORITM_SHA512, fw_algorithm, strlen(CHECKSUM_AGORITM_SHA512)) == 0U) {
            fw_checksum_algorithm = mbedtls_md_type_t::MBEDTLS_MD_SHA512;
        }
        else {
            char message[strlen(FW_CHKS_ALGO_NOT_SUPPORTED) + strlen(fw_algorithm) + 2U] = {};
            (void)snprintf(message, sizeof(message), FW_CHKS_ALGO_NOT_SUPPORTED, fw_algorithm);
            Logger::printfln(message);
            Firmware_Send_State(FW_STATE_FAILED, message);
            return;
        }
 
        m_fw_callback.Call_Update_Starting_Callback();
        bool const result = Firmware_OTA_Subscribe();
        if (!result) {
            m_fw_callback.Call_Callback(result);
            return;
        }
 
#if THINGSBOARD_ENABLE_DEBUG
        Logger::printfln(PAGE_BREAK);
        Logger::printfln(NEW_FW);
        char firmware[strlen(FROM_TOO) + strlen(curr_fw_version) + strlen(fw_version) + 3U] = {};
        (void)snprintf(firmware, sizeof(firmware), FROM_TOO, curr_fw_version, fw_version);
        Logger::printfln(firmware);
        Logger::printfln(DOWNLOADING_FW);
#endif // THINGSBOARD_ENABLE_DEBUG
 
        const uint16_t& chunk_size = m_fw_callback.Get_Chunk_Size();
 
        // Get the previous buffer size and cache it so the previous settings can be restored after the update has finished.
        m_previous_buffer_size = m_get_receive_size_callback.Call_Callback();
        m_changed_buffer_size = m_previous_buffer_size < (chunk_size + 50U);
 
        // Increase size of receive buffer according to the actual chunk size required for the OTA update to work correctly.
        if (m_changed_buffer_size && !m_set_buffer_size_callback.Call_Callback(chunk_size + 50U, m_get_send_size_callback.Call_Callback())) {
            Logger::printfln(NOT_ENOUGH_RAM);
            Firmware_Send_State(FW_STATE_FAILED, NOT_ENOUGH_RAM);
            m_fw_callback.Call_Callback(false);
            return;
        }
 
        m_ota.Start_Firmware_Update(m_fw_callback, fw_size, fw_checksum, fw_checksum_algorithm);
    }
 
#if !THINGSBOARD_ENABLE_STL
    static void onStaticFirmwareReceived(JsonDocument const & data) {
        if (m_subscribedInstance == nullptr) {
            return;
        }
        m_subscribedInstance->Firmware_Shared_Attribute_Received(data);
    }
 
    static void onStaticRequestTimeout() {
        if (m_subscribedInstance == nullptr) {
            return;
        }
        m_subscribedInstance->Request_Timeout();
    }
 
    static bool staticPublishChunk(size_t const & request_id, size_t const & request_chunck) {
        if (m_subscribedInstance == nullptr) {
            return false;
        }
        return m_subscribedInstance->Publish_Chunk_Request(request_id, request_chunck);
    }
 
    static bool staticFirmwareSend(char const * current_fw_state, char const * fw_error = nullptr) {
        if (m_subscribedInstance == nullptr) {
            return false;
        }
        return m_subscribedInstance->Firmware_Send_State(current_fw_state, fw_error);
    }
 
    static bool staticUnsubscribe() {
        if (m_subscribedInstance == nullptr) {
            return false;
        }
        return m_subscribedInstance->Firmware_OTA_Unsubscribe();
    }
 
    static OTA_Firmware_Update                                               *m_subscribedInstance;
#endif // !THINGSBOARD_ENABLE_STL
 
    Callback<void, IAPI_Implementation &>                    m_subscribe_api_callback = {};            // Subscribe additional api callback
    Callback<bool, char const * const, JsonDocument const &> m_send_json_callback = {};                // Send json document callback
    Callback<bool, char const * const, char const * const>   m_send_json_string_callback = {};         // Send json string callback
    Callback<bool, char const * const>                       m_subscribe_topic_callback = {};          // Subscribe mqtt topic client callback
    Callback<bool, char const * const>                       m_unsubscribe_topic_callback = {};        // Unubscribe mqtt topic client callback
    Callback<uint16_t>                                       m_get_receive_size_callback = {};         // Get client receive buffer size callback
    Callback<uint16_t>                                       m_get_send_size_callback = {};            // Get client send buffer size callback
    Callback<bool, uint16_t, uint16_t>                       m_set_buffer_size_callback = {};          // Set client buffer size callback
    Callback<size_t *>                                       m_get_request_id_callback = {};           // Get internal request id callback
 
    OTA_Update_Callback                                      m_fw_callback = {};                       // OTA update response callback
    uint16_t                                                 m_previous_buffer_size = {};              // Previous buffer size of the underlying client, used to revert to the previously configured buffer size if it was temporarily increased by the OTA update
    bool                                                     m_changed_buffer_size = {};               // Whether the buffer size had to be changed, because the previous internal buffer size was to small to hold the firmware chunks
    OTA_Handler<Logger>                                      m_ota = {};                               // Class instance that handles the flashing and creating a hash from the given received binary firmware data
    char                                                     m_response_topic[MAX_FW_TOPIC_SIZE] = {}; // Firmware response topic that contains the specific request ID of the firmware we actually want to download
    Update_Callback_Container                                m_fw_attribute_update = {};               // API implementation to be informed if needed fw attributes have been updated
    Request_Callback_Container                               m_fw_attribute_request = {};              // API implementation to request the needed fw attributes to start updating
};
 
#if !THINGSBOARD_ENABLE_STL
OTA_Firmware_Update *OTA_Firmware_Update::m_subscribedInstance = nullptr;
#endif
 
#endif // OTA_Firmware_Update_h