Download an image from a given URL, and decode it using the specified decoder. More...

#include <online_image.h>

Inheritance diagram for esphome::online_image::OnlineImage:

Public Member Functions
	OnlineImage (const std::string &url, int width, int height, runtime_image::ImageFormat format, image::ImageType type, image::Transparency transparency, image::Image *placeholder, uint32_t buffer_size, bool is_big_endian=false)
	Construct a new OnlineImage object.

void	update () override

void	update_if (bool update)
	Download now when `update` is true (the `update` flag of `online_image.set_url`).

void	loop () override

void	set_url (const std::string &url)
	Set the URL to download the image from.

template<typename V >
void	add_request_header (const std::string &header, V value)
	Add the request header.

void	release ()
	Release the buffer storing the image.

template<typename F >
void	add_on_download_started_callback (F &&callback)
	Called when the server has accepted the request and the image starts to download.

template<typename F >
void	add_on_finished_callback (F &&callback)

template<typename F >
void	add_on_progress_callback (F &&callback)
	Called with the percentage downloaded (NAN when the server did not send the size) and the bytes read so far.

template<typename F >
void	add_on_error_callback (F &&callback)

Public Member Functions inherited from esphome::PollingComponent
	PollingComponent ()

	PollingComponent (uint32_t update_interval)
	Initialize this polling component with the given update interval in ms.

void	set_update_interval (uint32_t update_interval)
	Manually set the update interval in ms for this polling object.

void	call_setup () override

virtual uint32_t	get_update_interval () const
	Get the update interval in ms of this sensor.

void	start_poller ()

void	stop_poller ()

Public Member Functions inherited from esphome::Component
virtual void	setup ()
	Where the component's initialization should happen.

virtual void	dump_config ()

virtual float	get_setup_priority () const
	priority of setup().

float	get_actual_setup_priority () const

void	set_setup_priority (float priority)

void	call ()

virtual void	on_shutdown ()

virtual void	on_safe_shutdown ()

virtual bool	teardown ()
	Called during teardown to allow component to gracefully finish operations.

virtual void	on_powerdown ()
	Called after teardown is complete to power down hardware.

uint8_t	get_component_state () const

void	reset_to_construction_state ()
	Reset this component back to the construction state to allow setup to run again.

bool	is_in_loop_state () const
	Check if this component has completed setup and is in the loop state.

bool	is_idle () const
	Check if this component is idle.

void	mark_failed ()
	Mark this component as failed.

void	mark_failed (const LogString *message)

void	disable_loop ()
	Disable this component's loop.

void	enable_loop ()
	Enable this component's loop.

void	enable_loop_soon_any_context ()
	Thread and ISR-safe version of enable_loop() that can be called from any context.

bool	is_failed () const

bool	is_ready () const

virtual bool	can_proceed ()

bool	status_has_warning () const

bool	status_has_error () const

void	status_set_warning ()

void	status_set_warning (const char *message)

void	status_set_warning (const LogString *message)

bool	status_comm_result (bool ok)
	Clears the warning when `ok`, else sets it with `message` (default "Communication failed"); returns `ok`.

bool	status_comm_result (bool ok, const LogString *message)

void	status_set_error ()

void	status_set_error (const LogString *message)

void	status_clear_warning ()

void	status_clear_error ()

	ESPDEPRECATED ("Use status_momentary_warning() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_warning(const char *name

void	status_momentary_warning (uint32_t length=5000)
	Set warning status flag and clear it after `length` ms.

void	status_momentary_warning (const LogString *message, uint32_t length=5000)

	ESPDEPRECATED ("Use status_momentary_error() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_error(const char *name

void	status_momentary_error (uint32_t length=5000)
	Set error status flag and clear it after `length` ms.

void	status_momentary_error (const LogString *message, uint32_t length=5000)

bool	has_overridden_loop () const

const LogString *	get_component_log_str () const ESPHOME_ALWAYS_INLINE
	Get the integration where this component was declared as a LogString for logging.

bool	should_warn_of_blocking (uint32_t blocking_time, uint32_t &threshold_ms_out)

Public Member Functions inherited from esphome::runtime_image::RuntimeImage
	RuntimeImage (ImageFormat format, image::ImageType type, image::Transparency transparency, image::Image *placeholder=nullptr, bool is_big_endian=false, int fixed_width=0, int fixed_height=0)
	Construct a new RuntimeImage object.

	~RuntimeImage ()

int	resize (int width, int height)
	Resize the image buffer to the requested dimensions.

void	draw_pixel (int x, int y, const Color &color)

void	map_chroma_key (Color &color)

int	get_buffer_width () const

int	get_buffer_height () const

void	draw (int x, int y, display::Display *display, Color color_on, Color color_off) override

bool	begin_decode (size_t expected_size=0, ImageFormat format=AUTO)
	Begin decoding an image.

int	feed_data (uint8_t *data, size_t len)
	Feed data to the decoder.

bool	decoder_supports_source () const
	Whether the active decoder can read a DecodeSource itself (see begin_source()).

int	begin_source (DecodeSource *source)
	Decode from a source the decoder reads itself, in place of feed_data().

int	decode_step ()
	Decode a little more from the source; see ImageDecoder::decode_step().

bool	end_decode ()
	Complete the decoding process.

bool	is_decoding () const
	Check if decoding is currently in progress.

bool	is_decode_finished () const
	Check if the decoder has finished processing all data.

bool	decoder_knows_end () const
	True while decoding and the decoder can tell a complete image from a cut-off one.

bool	is_loaded () const
	Check if an image is currently loaded.

ImageFormat	get_format () const
	Get the image format.

void	release ()
	Release the image buffer and free its memory, ending any decode session.

bool	set_external_buffer (uint8_t *buffer, int width, int height)
	Decode into a buffer the caller owns, instead of one allocated here.

size_t	get_buffer_size (int width, int height) const
	Get the buffer size in bytes needed for a picture of the given dimensions.

void	set_progressive_display (bool progressive)
	Set whether to allow progressive display during decode.

Public Member Functions inherited from esphome::image::Image
	Image (const uint8_t *data_start, int width, int height, ImageType type, Transparency transparency, bool big_endian=false)
	big_endian is the RGB565 byte order; codegen writes little endian unless configured otherwise.

Color	get_pixel (int x, int y, Color color_on=display::COLOR_ON, Color color_off=display::COLOR_OFF) const

int	get_width () const override

int	get_height () const override

const uint8_t *	get_data_start () const

ImageType	get_type () const

int	get_bpp () const

size_t	get_width_stride () const
	Return the stride of the image in bytes, that is, the distance in bytes between two consecutive rows of pixels.

bool	has_transparency () const

lv_image_dsc_t *	get_lv_image_dsc ()

Public Member Functions inherited from esphome::display::BaseImage
Public Member Functions inherited from esphome::Parented< esphome::http_request::HttpRequestComponent >
	Parented ()

	Parented (esphome::http_request::HttpRequestComponent *parent)

esphome::http_request::HttpRequestComponent *	get_parent () const
	Get the parent of this object.

void	set_parent (esphome::http_request::HttpRequestComponent *parent)
	Set the parent of this object.

Protected Member Functions
bool	validate_url_ (const std::string &url)

void	end_connection_ ()

void	finish_download_ ()

void	loop_stream_ ()
	loop() for a JPEG that is decoded as it downloads

void	fail_download_ ()

void	report_progress_ (bool force)
	Reports download progress, at most every PROGRESS_INTERVAL_MS unless force is set.

Protected Member Functions inherited from esphome::Component
friend	void::setup ()

friend	void::original_setup ()

void	set_component_source_ (uint8_t index)
	Set where this component was loaded from for some debug messages.

void	call_dump_config_ ()

void	enable_loop_slow_path_ ()

void	set_component_state_ (uint8_t state)
	Helper to set component state (clears state bits and sets new state)

bool	set_status_flag_ (uint8_t flag)
	Helper to set a status LED flag on both this component and the app.

bool	set_error_flag_ (const LogString *message)
	Set the error flag and log it; true when it was not set before.

void	set_interval (const char *name, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a const char* name.

void	set_interval (uint32_t id, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a numeric ID (zero heap allocation).

void	set_interval (InternalSchedulerID id, uint32_t interval, std::function< void()> &&f)

void	set_interval (uint32_t interval, std::function< void()> &&f)

bool	cancel_interval (const char *name)
	Cancel an interval function.

bool	cancel_interval (uint32_t id)

bool	cancel_interval (InternalSchedulerID id)

void	set_timeout (const char *name, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a const char* name.

void	set_timeout (uint32_t id, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a numeric ID (zero heap allocation).

void	set_timeout (InternalSchedulerID id, uint32_t timeout, std::function< void()> &&f)

void	set_timeout (uint32_t timeout, std::function< void()> &&f)

bool	cancel_timeout (const char *name)
	Cancel a timeout function.

bool	cancel_timeout (uint32_t id)

bool	cancel_timeout (InternalSchedulerID id)

void	defer (const char *name, std::function< void()> &&f)
	Defer a callback to the next loop() call with a const char* name.

void	defer (std::function< void()> &&f)
	Defer a callback to the next loop() call.

void	defer (uint32_t id, std::function< void()> &&f)
	Defer a callback with a numeric ID (zero heap allocation)

bool	cancel_defer (const char *name)
	Cancel a defer callback using the specified name, name must not be empty.

bool	cancel_defer (uint32_t id)

void	status_clear_warning_slow_path_ ()

void	status_clear_error_slow_path_ ()

Protected Member Functions inherited from esphome::runtime_image::RuntimeImage
size_t	resize_buffer_ (int width, int height)
	Resize the image buffer to the requested dimensions.

void	release_buffer_ ()
	Release only the image buffer without resetting the decoder.

int	get_position_ (int x, int y) const
	Get the position in the buffer for a pixel.

std::unique_ptr< ImageDecoder >	create_decoder_ (ImageFormat format)
	Create decoder instance for the requested format.

Protected Member Functions inherited from esphome::image::Image
template<bool ROWS_OUTER>
void	draw_ (int x, int y, display::Display *display, Color color_on, Color color_off, int x_start, int x_end, int y_start, int y_end)
	Per-pixel draw of the clipped range, rows (true) or columns (false) outer.

bool	get_binary_pixel_ (int x, int y) const

Color	get_rgb111_pixel_ (int x, int y) const

Color	get_rgb_pixel_ (int x, int y) const

Color	get_rgb565_pixel_ (int x, int y) const

Color	get_grayscale_pixel_ (int x, int y) const

Protected Attributes
CallbackManager< void(bool)>	download_finished_callback_ {}

CallbackManager< void()>	download_error_callback_ {}

LazyCallbackManager< void()>	download_started_callback_ {}

LazyCallbackManager< void(float, size_t)>	download_progress_callback_ {}

std::shared_ptr< http_request::HttpContainer >	downloader_ {nullptr}

DownloadBuffer	download_buffer_

DownloadSource	source_ {download_buffer_}

size_t	download_buffer_initial_size_
	This is the initial size of the download buffer, not the current size.

std::string	url_

std::vector< std::pair< std::string, TemplatableValue< std::string > > >	request_headers_

std::string	etag_
	The value of the ETag HTTP header provided in the last response.

std::string	last_modified_
	The value of the Last-Modified HTTP header provided in the last response.

uint32_t	start_time_ {0}

uint32_t	last_data_time_ {0}

uint32_t	last_progress_time_ {0}

bool	streaming_ {false}

bool	stream_started_ {false}

Protected Attributes inherited from esphome::PollingComponent
uint32_t	update_interval_

Protected Attributes inherited from esphome::Component
uint8_t	component_source_index_ {0}
	Index into component source PROGMEM lookup table (0 = not set)

uint8_t	warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_CS}
	Warn threshold in centiseconds (max 2550ms)

uint8_t	component_state_ {0x00}
	State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bit 5: Has overridden loop() (set at registration time) Bits 6-7: Unused - reserved for future expansion.

volatile bool	pending_enable_loop_ {false}
	ISR-safe flag for enable_loop_soon_any_context.

ComponentRuntimeStats	runtime_stats_

Protected Attributes inherited from esphome::runtime_image::RuntimeImage
uint8_t *	buffer_ {nullptr}

std::unique_ptr< ImageDecoder >	decoder_ {nullptr}

const ImageFormat	format_
	The image format this RuntimeImage is configured to decode.

int	buffer_width_ {0}
	Actual width of the current image.

int	buffer_height_ {0}
	Actual height of the current image.

size_t	decoded_bytes_ {0}

const int	fixed_width_ {0}
	Fixed width requested on configuration, or 0 if not specified.

const int	fixed_height_ {0}
	Fixed height requested on configuration, or 0 if not specified.

image::Image *	placeholder_ {nullptr}
	Placeholder image to show when the runtime image is not available.

bool	progressive_display_ {false}

bool	external_buffer_ {false}
	Whether buffer_ belongs to the caller, so it must not be freed or resized here.

Protected Attributes inherited from esphome::image::Image
int	width_

int	height_

ImageType	type_

const uint8_t *	data_start_

Transparency	transparency_

bool	big_endian_

uint8_t	bpp_ {}

lv_img_dsc_t	dsc_ {}

Protected Attributes inherited from esphome::Parented< esphome::http_request::HttpRequestComponent >
esphome::http_request::HttpRequestComponent *	parent_

Additional Inherited Members
Data Fields inherited from esphome::Component
uint32_t	length = 5000)

Detailed Description

Download an image from a given URL, and decode it using the specified decoder.

The image will then be stored in a buffer, so that it can be re-displayed without the need to re-download or re-decode.

Definition at line 28 of file online_image.h.

Constructor & Destructor Documentation

◆ OnlineImage()

esphome::online_image::OnlineImage::OnlineImage	(	const std::string &	url,
		int	width,
		int	height,
		runtime_image::ImageFormat	format,
		image::ImageType	type,
		image::Transparency	transparency,
		image::Image *	placeholder,
		uint32_t	buffer_size,
		bool	is_big_endian = false )

Construct a new OnlineImage object.

Parameters

url	URL to download the image from.
width	Desired width of the target image area.
height	Desired height of the target image area.
format	Format that the image is encoded in (

See also: runtime_image::ImageFormat).

Parameters

type	The pixel format for the image.
transparency	The transparency type for the image.
placeholder	Optional placeholder image to show while loading.
buffer_size	Size of the buffer used to download the image.
is_big_endian	Whether the image is stored in big-endian format.

Definition at line 24 of file online_image.cpp.

Member Function Documentation

◆ add_on_download_started_callback()

template<typename F >

void esphome::online_image::OnlineImage::add_on_download_started_callback ( F && callback )

inline

Called when the server has accepted the request and the image starts to download.

Definition at line 78 of file online_image.h.

◆ add_on_error_callback()

template<typename F >

void esphome::online_image::OnlineImage::add_on_error_callback ( F && callback )

inline

Definition at line 88 of file online_image.h.

◆ add_on_finished_callback()

template<typename F >

void esphome::online_image::OnlineImage::add_on_finished_callback ( F && callback )

inline

Definition at line 81 of file online_image.h.

◆ add_on_progress_callback()

template<typename F >

void esphome::online_image::OnlineImage::add_on_progress_callback ( F && callback )

inline

Called with the percentage downloaded (NAN when the server did not send the size) and the bytes read so far.

Definition at line 85 of file online_image.h.

◆ add_request_header()

template<typename V >

void esphome::online_image::OnlineImage::add_request_header	(	const std::string &	header,
		V	value )

inline

Add the request header.

Definition at line 67 of file online_image.h.

◆ end_connection_()

void esphome::online_image::OnlineImage::end_connection_ ( )

protected

Definition at line 429 of file online_image.cpp.

◆ fail_download_()

void esphome::online_image::OnlineImage::fail_download_ ( )

protected

Definition at line 402 of file online_image.cpp.

◆ finish_download_()

void esphome::online_image::OnlineImage::finish_download_ ( )

protected

Definition at line 407 of file online_image.cpp.

◆ loop()

void esphome::online_image::OnlineImage::loop ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 170 of file online_image.cpp.

◆ loop_stream_()

void esphome::online_image::OnlineImage::loop_stream_ ( )

protected

loop() for a JPEG that is decoded as it downloads

Definition at line 299 of file online_image.cpp.

◆ release()

void esphome::online_image::OnlineImage::release ( )

Release the buffer storing the image.

The image will need to be downloaded again to be able to be displayed.

Definition at line 445 of file online_image.cpp.

◆ report_progress_()

void esphome::online_image::OnlineImage::report_progress_ ( bool force )

protected

Reports download progress, at most every PROGRESS_INTERVAL_MS unless force is set.

Definition at line 390 of file online_image.cpp.

◆ set_url()

void esphome::online_image::OnlineImage::set_url ( const std::string & url )

inline

Set the URL to download the image from.

Definition at line 58 of file online_image.h.

◆ update()

void esphome::online_image::OnlineImage::update ( )

overridevirtual

Implements esphome::PollingComponent.

Definition at line 49 of file online_image.cpp.

◆ update_if()

void esphome::online_image::OnlineImage::update_if ( bool update )

inline

Download now when update is true (the update flag of online_image.set_url).

Definition at line 51 of file online_image.h.

◆ validate_url_()

bool esphome::online_image::OnlineImage::validate_url_ ( const std::string & url )

protected

Definition at line 33 of file online_image.cpp.

Field Documentation

◆ download_buffer_

DownloadBuffer esphome::online_image::OnlineImage::download_buffer_

protected

Definition at line 108 of file online_image.h.

◆ download_buffer_initial_size_

size_t esphome::online_image::OnlineImage::download_buffer_initial_size_

protected

This is the initial size of the download buffer, not the current size.

The download buffer can be resized at runtime; the download_buffer_initial_size_ will not change even if the download buffer has been resized.

Definition at line 115 of file online_image.h.

◆ download_error_callback_

CallbackManager<void()> esphome::online_image::OnlineImage::download_error_callback_ {}

protected

Definition at line 103 of file online_image.h.

◆ download_finished_callback_

CallbackManager<void(bool)> esphome::online_image::OnlineImage::download_finished_callback_ {}

protected

Definition at line 102 of file online_image.h.

◆ download_progress_callback_

LazyCallbackManager<void(float, size_t)> esphome::online_image::OnlineImage::download_progress_callback_ {}

protected

Definition at line 105 of file online_image.h.

◆ download_started_callback_

LazyCallbackManager<void()> esphome::online_image::OnlineImage::download_started_callback_ {}

protected

Definition at line 104 of file online_image.h.

◆ downloader_

std::shared_ptr<http_request::HttpContainer> esphome::online_image::OnlineImage::downloader_ {nullptr}

protected

Definition at line 107 of file online_image.h.

◆ etag_

std::string esphome::online_image::OnlineImage::etag_

protected

The value of the ETag HTTP header provided in the last response.

Definition at line 124 of file online_image.h.

◆ last_data_time_

uint32_t esphome::online_image::OnlineImage::last_data_time_ {0}

protected

Definition at line 131 of file online_image.h.

◆ last_modified_

std::string esphome::online_image::OnlineImage::last_modified_

protected

The value of the Last-Modified HTTP header provided in the last response.

Definition at line 128 of file online_image.h.

◆ last_progress_time_

uint32_t esphome::online_image::OnlineImage::last_progress_time_ {0}

protected

Definition at line 132 of file online_image.h.

◆ request_headers_

std::vector<std::pair<std::string, TemplatableValue<std::string> > > esphome::online_image::OnlineImage::request_headers_

protected

Definition at line 119 of file online_image.h.

◆ source_

DownloadSource esphome::online_image::OnlineImage::source_ {download_buffer_}

protected

Definition at line 109 of file online_image.h.

◆ start_time_

uint32_t esphome::online_image::OnlineImage::start_time_ {0}

protected

Definition at line 130 of file online_image.h.

◆ stream_started_

bool esphome::online_image::OnlineImage::stream_started_ {false}

protected

Definition at line 134 of file online_image.h.

◆ streaming_

bool esphome::online_image::OnlineImage::streaming_ {false}

protected

Definition at line 133 of file online_image.h.

◆ url_

std::string esphome::online_image::OnlineImage::url_

protected

Definition at line 117 of file online_image.h.

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

esphome/components/online_image/online_image.h
esphome/components/online_image/online_image.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ OnlineImage()

Member Function Documentation

◆ add_on_download_started_callback()

◆ add_on_error_callback()

◆ add_on_finished_callback()

◆ add_on_progress_callback()

◆ add_request_header()

◆ end_connection_()

◆ fail_download_()

◆ finish_download_()

◆ loop()

◆ loop_stream_()

◆ release()

◆ report_progress_()

◆ set_url()

◆ update()

◆ update_if()

◆ validate_url_()

Field Documentation

◆ download_buffer_

◆ download_buffer_initial_size_

◆ download_error_callback_

◆ download_finished_callback_

◆ download_progress_callback_

◆ download_started_callback_

◆ downloader_

◆ etag_

◆ last_data_time_

◆ last_modified_

◆ last_progress_time_

◆ request_headers_

◆ source_

◆ start_time_

◆ stream_started_

◆ streaming_

◆ url_