espectre::IOtaService Class Reference

The firmware-update seam. More...

#include <ota_service.h>

Public Types
using	StatusCallback = std::function<void(const EspectreOtaStatus &)>
	Update progressed.
using	PrepareForUpdateCallback = std::function<void()>
	Last chance to quiesce before the download starts.

Public Member Functions
virtual	~IOtaService ()=default
virtual void	loop ()=0
	Advance service work from the frontend loop.
virtual void	shutdown ()=0
	Abandon any operation in flight and release resources.
virtual bool	start_check (const std::string &current_version)=0
	Ask whether a newer release exists, without downloading it.
virtual bool	start_check (const std::string &current_version, const std::string &channel)
	Same as start_check(current_version), with an optional release channel.
virtual bool	start_update (const std::string &current_version)=0
	Download and apply an update, then schedule the reboot.
virtual bool	start_update (const std::string &current_version, const std::string &channel)
	Same as start_update(current_version), with an optional release channel.
virtual EspectreOtaStatus	status () const =0
	Current status.
virtual void	set_status_callback (StatusCallback callback)=0
	Install the progress handler.
virtual void	set_prepare_for_update_callback (PrepareForUpdateCallback callback)=0
	Install the pre-download hook.

Detailed Description

The firmware-update seam.

Implement it to drive updates through your own distribution channel, or use the shipped HttpsOtaService (ota_service_https.h), which resolves a release manifest over HTTPS and applies the image with esp_https_ota. Frontends expose the result over their operational transport and never talk to the underlying stack themselves. Native uses MQTT for this surface.

Threading

Deliver status and prepare callbacks from loop(), never from a private worker or stack task. The shipped implementation performs network I/O on a worker, queues progress, and waits for the loop to run the prepare hook before starting the download.

Operation model

start_check() and start_update() are asynchronous and mutually exclusive: only one operation runs at a time, and the second returns false while the first is in flight. Progress arrives through the status callback, and status() is safe to poll at any time.

Definition at line 40 of file ota_service.h.

Member Typedef Documentation

StatusCallback

using espectre::IOtaService::StatusCallback = std::function<void(const EspectreOtaStatus &)>

Update progressed.

The argument is the new status, valid for the call.

Definition at line 43 of file ota_service.h.

PrepareForUpdateCallback

using espectre::IOtaService::PrepareForUpdateCallback = std::function<void()>

Last chance to quiesce before the download starts.

See below.

Definition at line 45 of file ota_service.h.

Constructor & Destructor Documentation

~IOtaService()

virtual espectre::IOtaService::~IOtaService ( )

virtualdefault

Member Function Documentation

loop()

virtual void espectre::IOtaService::loop ( )

pure virtual

Advance service work from the frontend loop.

Implementations may do blocking work on a private task, but loop() owns callback delivery and other interaction with the frontend.

shutdown()

virtual void espectre::IOtaService::shutdown ( )

pure virtual

Abandon any operation in flight and release resources.

Safe to repeat.

start_check() [1/2]

virtual bool espectre::IOtaService::start_check ( const std::string & current_version )

pure virtual

Ask whether a newer release exists, without downloading it.

Parameters

current_version

Version to compare against, normally espectre_firmware_version(). Empty is reported as "unknown".

Returns

false when an operation is already in flight or the worker cannot start. True only means the check began; the answer arrives as UPDATE_AVAILABLE or UP_TO_DATE through the status callback.

start_check() [2/2]

virtual bool espectre::IOtaService::start_check ( const std::string & current_version, const std::string & channel )

inlinevirtual

Same as start_check(current_version), with an optional release channel.

Parameters

current_version	Version to compare against, normally espectre_firmware_version(). Empty is reported as "unknown".
channel	release, preview, or develop. Empty keeps the implementation default.

Returns

false when an operation is already in flight, the channel is invalid, or the worker cannot start.

Definition at line 78 of file ota_service.h.

start_update() [1/2]

virtual bool espectre::IOtaService::start_update ( const std::string & current_version )

pure virtual

Download and apply an update, then schedule the reboot.

Performs its own check first, so calling start_check() beforehand is optional. The prepare callback fires once the target is resolved and before the download begins: that is where you call RuntimeFrontendController::quiesce_for_ota() and stop your own traffic.

Returns

false when an operation is already in flight or the worker cannot start. A successful update ends in REBOOT_SCHEDULED.

start_update() [2/2]

virtual bool espectre::IOtaService::start_update ( const std::string & current_version, const std::string & channel )

inlinevirtual

Same as start_update(current_version), with an optional release channel.

Parameters

current_version	Version to compare against, normally espectre_firmware_version(). Empty is reported as "unknown".
channel	release, preview, or develop. Empty keeps the implementation default.

Returns

false when an operation is already in flight, the channel is invalid, or the worker cannot start.

Definition at line 106 of file ota_service.h.

status()

virtual EspectreOtaStatus espectre::IOtaService::status ( ) const

pure virtual

Current status.

Safe to call from any task, including while an update runs.

set_status_callback()

virtual void espectre::IOtaService::set_status_callback ( StatusCallback callback )

pure virtual

Install the progress handler.

Set it before starting an operation.

set_prepare_for_update_callback()

virtual void espectre::IOtaService::set_prepare_for_update_callback ( PrepareForUpdateCallback callback )

pure virtual

Install the pre-download hook.

Set it before calling start_update().

---

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

• src/cpp/runtime/ota_service.h