Over the air firmware update callback wrapper. More...

#include <OTA_Update_Callback.h>

Inheritance diagram for OTA_Update_Callback:

Collaboration diagram for OTA_Update_Callback:

Public Member Functions
	OTA_Update_Callback ()=default
	Constructs empty callbacks, will result in never being called. Internals are simply default constructed as nullptr. More...

	OTA_Update_Callback (char const current_fw_title, char const current_fw_version, IUpdater *updater, function finished_callback, Callback< void, size_t const &, size_t const & >::function progress_callback=nullptr, Callback< void >::function update_starting_callback=nullptr, uint8_t chunk_retries=CHUNK_RETRIES, uint16_t chunk_size=CHUNK_SIZE, uint64_t const &timeout_microseconds=REQUEST_TIMEOUT_MS)
	Constructs callbacks that will be called to inform about the OTA firmware update process. More...

	~OTA_Update_Callback () override=default

char const *	Get_Firmware_Title () const
	Gets the current firmware title. More...

void	Set_Firmware_Title (const char *current_fw_title)
	Sets the current firmware title. More...

char const *	Get_Firmware_Version () const
	Gets the current firmware version. More...

void	Set_Firmware_Version (const char *current_fw_version)
	Sets the current firmware version. More...

IUpdater *	Get_Updater () const
	Gets the updater implementation, used to write the actual firmware data into the needed memory location, so it can be used to reboot the given device with that new flashed firmware. More...

void	Set_Updater (IUpdater *updater)
	Sets the updater implementation, used to write the actual firmware data into the needed memory location, so it can be used to reboot the given device with that new flashed firmware. More...

size_t const &	Get_Request_ID () const
	Gets the unique request identifier that is connected to the original request. More...

void	Set_Request_ID (size_t const &request_id)
	Sets the unique request identifier that is connected to the original request. More...

void	Call_Progress_Callback (size_t const &current, size_t const &total) const
	Calls the progress callback that was subscribed, when this class instance was initally created. More...

void	Set_Progress_Callback (Callback< void, size_t const &, size_t const & >::function progress_callback)
	Sets the progress callback method. More...

void	Call_Update_Starting_Callback () const
	Calls the update starting callback that was subscribed, when this class instance was initally created. More...

void	Set_Update_Starting_Callback (Callback< void >::function update_starting_callback)
	Sets the update starting callback method. More...

uint8_t	Get_Chunk_Retries () const
	Gets the amount of times we attempt to download each chunk of the OTA firmware binary file. More...

void	Set_Chunk_Retries (uint8_t chunk_retries)
	Sets the amount of times we attempt to download each chunk of the OTA firmware binary file. More...

uint16_t	Get_Chunk_Size () const
	Gets the size of the chunks that the firmware binary data will be split into. More...

void	Set_Chunk_Size (uint16_t chunk_size)
	Sets the size of the chunks that the firmware binary data will be split into. More...

Timeoutable_Request &	Get_Request_Timeout ()
	Gets the request timeout callback. More...

Public Member Functions inherited from Callback< void, bool const & >
	Callback ()=default
	Constructs empty callback, will result in never being called. Internals are simply default constructed as nullptr. More...

	Callback (function callback)
	Constructor. More...

virtual	~Callback ()=default
	Virtual default destructor, created to ensure that if a pointer to this class is used and deleted, we will also call the derived base class destructor. More...

void	Call_Callback (argument_types const &... arguments) const
	Calls the callback that was subscribed, when this class instance was initally created. More...

void	Set_Callback (function callback)
	Sets the callback method that will be called upon data arrival with the given data that was received. If nullptr is passed the callback will never be called and instead return with a defaulted instance of the requested return variable. More...

Additional Inherited Members
Public Types inherited from Callback< void, bool const & >
using	function = std::function< void(argument_types... arguments)>
	Callback signature. More...

Detailed Description

Over the air firmware update callback wrapper.

Note: Contains the needed configuration settings to create the request that should be sent to the server. Documentation about the specific use of Over the air updates in ThingsBoard can be found here https://thingsboard.io/docs/user-guide/ota-updates/

Constructor & Destructor Documentation

◆ OTA_Update_Callback() [1/2]

OTA_Update_Callback::OTA_Update_Callback ( )

default

Constructs empty callbacks, will result in never being called. Internals are simply default constructed as nullptr.

◆ OTA_Update_Callback() [2/2]

OTA_Update_Callback::OTA_Update_Callback	(	char const *	current_fw_title,
		char const *	current_fw_version,
		IUpdater *	updater,
		function	finished_callback,
		Callback< void, size_t const &, size_t const & >::function	progress_callback = `nullptr`,
		Callback< void >::function	update_starting_callback = `nullptr`,
		uint8_t	chunk_retries = `CHUNK_RETRIES`,
		uint16_t	chunk_size = `CHUNK_SIZE`,
		uint64_t const &	timeout_microseconds = `REQUEST_TIMEOUT_MS`
	)

Constructs callbacks that will be called to inform about the OTA firmware update process.

Parameters

current_fw_title	Non owning pointer to the firmware title the device has choosen, is used to only allow updates with the same given title, other updates will be canceled. Additionally it has to be kept alive by the user for the runtime of the OTA Update process
current_fw_version	Non owning pointer to the firmware version the device is currently on, is used to only allow updates with a different version, other updates will be canceled. Additionally it has to be kept alive by the user for the runtime of the OTA Update process
updater	Non owning pointer to the updater implementation that writes the given firmware data. Additionally it has to be kept alive by the user for the runtime of the OTA Update process
finished_callback	End callback method that will be called as soon as the OTA firmware update, either finished successfully or failed. Is meant to allow to either restart the device if the udpate was successfull or to restart any stopped services before the update started in the subscribed update_starting_callback
progress_callback	Progress callback method that will be called every time our current progress of downloading the complete firmware data changed, meaning it will be called if the amount of already downloaded chunks increased. Is meant to allow to display a progress bar or print the current progress of the update into the console with the currently already downloaded amount of chunks and the total amount of chunks, default = nullptr
update_starting_callback	Update starting callback method that will be called as soon as the shared attribute firmware keys have been received and processed and the moment before we subscribe the necessary topics for the OTA firmware update. Is meant to give a moment were any additional processes or communication with the cloud can be stopped to ensure the update process runs as smooth as possible. To ensure that calling the ThingsBoardSized::Cleanup_Subscriptions() method can be used which stops any receiving of data over MQTT besides the one for the OTA firmware update, if this method is used ensure to call all subscribe methods again so they can be resubscribed, in the method passed to the finished_callback if the update failed and we do not restart the device, default = nullptr
chunk_retries	Amount of retries the OTA firmware update has to download each seperate chunk with a given size, before the complete download is stopped and registered as failed, default = CHUNK_RETRIES
chunk_size	Size of the chunks that the firmware binary data will be split into, increased chunk size might speed up the process by a little bit, but requires more heap memory,
timeout	Maximum amount of time in microseconds for the OTA firmware update for each seperate chunk, until that chunk counts as a timeout, retries is then subtraced by one and the download is retried, default = REQUEST_TIMEOUT_MS

◆ ~OTA_Update_Callback()

OTA_Update_Callback::~OTA_Update_Callback ( )

overridedefault

Member Function Documentation

◆ Call_Progress_Callback()

void OTA_Update_Callback::Call_Progress_Callback	(	size_t const &	current,
		size_t const &	total
	)		const

Calls the progress callback that was subscribed, when this class instance was initally created.

Parameters

current	Already received and processsed amount of chunks
total	Total amount of chunks we need to receive and process until the update has completed

◆ Call_Update_Starting_Callback()

void OTA_Update_Callback::Call_Update_Starting_Callback ( ) const

Calls the update starting callback that was subscribed, when this class instance was initally created.

◆ Get_Chunk_Retries()

uint8_t OTA_Update_Callback::Get_Chunk_Retries ( ) const

Gets the amount of times we attempt to download each chunk of the OTA firmware binary file.

Note: If the download fails because it times out, the write of the chunk data with the updater implementation fails then the retries are decreased by 1 until we hit 0, if that is the case then we instead stop the OTA firmware update completely

Returns: Amount of retries for each single chunk before we abort the update

◆ Get_Chunk_Size()

uint16_t OTA_Update_Callback::Get_Chunk_Size ( ) const

Gets the size of the chunks that the firmware binary data will be split into.

Note: Increased chunk size might speed up the process, but requires more heap memory, because the whole chunk is saved into the heap before it can be processed and is then overwriten after it has been used by the next chunk. This means the size passed to this method or with the constructor needs to be small enough to be allocated on the heap at runtime

Returns: Size of each single chunk to be downloaded

◆ Get_Firmware_Title()

char const * OTA_Update_Callback::Get_Firmware_Title ( ) const

Gets the current firmware title.

Note: Used to decide if an OTA firmware update is already installed and therefore should not be downloaded, this is only done if the title of the update and the current firmware title are the same because if they are not then this firmware is meant for another device type

Returns: Non owning pointer to the current firmware title of the device. Owned by the user that passed it originally in the constructor or with the Set_Firmware_Title method

◆ Get_Firmware_Version()

char const * OTA_Update_Callback::Get_Firmware_Version ( ) const

Gets the current firmware version.

Note: Used to decide if an OTA firmware update is already installed and therefore should not be downloaded, this is only done if the version of the update and the current firmware version are different, because if they are not then we would download the same firmware as is already on the device

Returns: Non owning pointer to the current firmware version of the device. Owned by the user that passed it originally in the constructor or with the Set_Firmware_Version method

◆ Get_Request_ID()

size_t const & OTA_Update_Callback::Get_Request_ID ( ) const

Gets the unique request identifier that is connected to the original request.

Note: Will be later used to verifiy which OTA_Update_Callback is connected to which received OTA firmware update

Returns: Unique identifier connected to the request to start the OTA firmware update

◆ Get_Request_Timeout()

Timeoutable_Request & OTA_Update_Callback::Get_Request_Timeout ( )

Gets the request timeout callback.

Note: Will be called when no response to the request was received in the expected amount of time, causing the internal watchdog to time out. To achieve this behaviour the internal timer can be started and stopped, and simply calls the subscribed callback if the timer is not stopped before it times out

Returns: Request timeout callback

◆ Get_Updater()

IUpdater * OTA_Update_Callback::Get_Updater ( ) const

Gets the updater implementation, used to write the actual firmware data into the needed memory location, so it can be used to reboot the given device with that new flashed firmware.

Returns: Non owning pointer to the updater implementation that writes the given firmware data. Owned by the user that passed it originally in the constructor or with the Set_Updater method

◆ Set_Chunk_Retries()

void OTA_Update_Callback::Set_Chunk_Retries ( uint8_t chunk_retries )

Sets the amount of times we attempt to download each chunk of the OTA firmware binary file.

Note: If the download fails because it times out, the write of the chunk data with the updater implementation fails then the retries are decreased by 1 until we hit 0, if that is the case then we instead stop the OTA firmware update completely

Parameters

chunk_retries Amount of retries for each single chunk before we abort the update

◆ Set_Chunk_Size()

void OTA_Update_Callback::Set_Chunk_Size ( uint16_t chunk_size )

Sets the size of the chunks that the firmware binary data will be split into.

Note: Increased chunk size might speed up the process, but requires more heap memory, because the whole chunk is saved into the heap before it can be processed and is then overwriten after it has been used by the next chunk This means the size passed to this method or with the constructor needs to be small enough to be allocated on the heap at runtime

Parameters

chunk_size Size of each single chunk to be downloaded

◆ Set_Firmware_Title()

void OTA_Update_Callback::Set_Firmware_Title ( const char * current_fw_title )

Sets the current firmware title.

Note: Used to decide if an OTA firmware update is already installed and therefore should not be downloaded, this is only done if the title of the update and the current firmware title are the same because if they are not then this firmware is meant for another device type

Parameters

current_fw_title Non owning pointer to the current firmware title of the device. Additionally it has to be kept alive by the user for the runtime of the OTA Update process

◆ Set_Firmware_Version()

void OTA_Update_Callback::Set_Firmware_Version ( const char * current_fw_version )

Sets the current firmware version.

Note: Used to decide if an OTA firmware update is already installed and therefore should not be downloaded, this is only done if the version of the update and the current firmware version are different, because if they are not then we would download the same firmware as is already on the device

Parameters

current_fw_version Non owning pointer to the current firmware version of the device. Additionally it has to be kept alive by the user for the runtime of the OTA Update process

◆ Set_Progress_Callback()

void OTA_Update_Callback::Set_Progress_Callback ( Callback< void, size_t const &, size_t const & >::function progress_callback )

Sets the progress callback method.

Note: Is meant to allow to display a progress bar or print the current progress of the update. With the currently already downloaded and processed amount of chunks and the total amount of chunks to process

Parameters

progress_callback Progress callback method that will be called every time our current progress of downloading and processing the complete firmware data changed, meaning it will be called if the amount of already downloaded chunks increased

◆ Set_Request_ID()

void OTA_Update_Callback::Set_Request_ID ( size_t const & request_id )

Sets the unique request identifier that is connected to the original request.

Note: Will be later used to verifiy which OTA_Update_Callback is connected to which received OTA firmware update. Not meant for external use, because the value is overwritten by internal method calls anyway once the class instance has been passed as a parameter anyway. This is the case because only the internal methods knows the current request id that this callback will be attached too

Parameters

request_id Unique identifier connected to the request to start the OTA firmware update

◆ Set_Update_Starting_Callback()

void OTA_Update_Callback::Set_Update_Starting_Callback ( Callback< void >::function update_starting_callback )

Sets the update starting callback method.

Note: Is meant to give a moment were any additional processes or communication with the cloud can be stopped to ensure the update process runs as smooth as possible. To ensure that calling the ThingsBoardSized::Cleanup_Subscriptions() method can be used which stops any receiving of data over MQTT besides the one for the OTA firmware update, if this method is used ensure to call all subscribe methods again so they can be resubscribed, in the method passed to the finished_callback if the update failed and we do not restart the device

Parameters

update_starting_callback Update starting callback method that will be called as soon as the shared attribute firmware keys have been received and processed and the moment before we subscribe the necessary topics for the OTA firmware update

◆ Set_Updater()

void OTA_Update_Callback::Set_Updater ( IUpdater * updater )

Sets the updater implementation, used to write the actual firmware data into the needed memory location, so it can be used to reboot the given device with that new flashed firmware.

Parameters

updater Updater implementation that writes the given firmware data. Additionally it has to be kept alive by the user for the runtime of the OTA Update process

The documentation for this class was generated from the following files:

src/OTA_Update_Callback.h
src/OTA_Update_Callback.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ OTA_Update_Callback() [1/2]

◆ OTA_Update_Callback() [2/2]

◆ ~OTA_Update_Callback()

Member Function Documentation

◆ Call_Progress_Callback()

◆ Call_Update_Starting_Callback()

◆ Get_Chunk_Retries()

◆ Get_Chunk_Size()

◆ Get_Firmware_Title()

◆ Get_Firmware_Version()

◆ Get_Request_ID()

◆ Get_Request_Timeout()

◆ Get_Updater()

◆ Set_Chunk_Retries()

◆ Set_Chunk_Size()

◆ Set_Firmware_Title()

◆ Set_Firmware_Version()

◆ Set_Progress_Callback()

◆ Set_Request_ID()

◆ Set_Update_Starting_Callback()

◆ Set_Updater()