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, ImageFormat format, image::ImageType type, image::Transparency transparency, uint32_t buffer_size, bool is_big_endian)
	Construct a new OnlineImage object.

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

void	update () override

void	loop () override

void	map_chroma_key (Color &color)

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	set_placeholder (image::Image *placeholder)
	Set the image that needs to be shown as long as the downloaded image is not available.

void	release ()
	Release the buffer storing the image.

size_t	resize_download_buffer (size_t size)
	Resize the download buffer.

void	add_on_finished_callback (std::function< void(bool)> &&callback)

void	add_on_error_callback (std::function< void()> &&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.

virtual 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)

virtual float	get_loop_priority () const
	priority of loop().

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.

virtual void	mark_failed ()
	Mark this component as failed.

	ESPDEPRECATED ("Use mark_failed(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary " "strings. Will stop working in 2026.6.0", "2025.12.0") void mark_failed(const char *message)

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 (const char *message=nullptr)

void	status_set_warning (const LogString *message)

void	status_set_error ()

	ESPDEPRECATED ("Use status_set_error(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary " "strings. Will stop working in 2026.6.0", "2025.12.0") void status_set_error(const char *message)

void	status_set_error (const LogString *message)

void	status_clear_warning ()

void	status_clear_error ()

void	status_momentary_warning (const char *name, uint32_t length=5000)
	Set warning status flag and automatically clear it after a timeout.

void	status_momentary_error (const char *name, uint32_t length=5000)
	Set error status flag and automatically clear it after a timeout.

bool	has_overridden_loop () const

void	set_component_source (const LogString *source)
	Set where this component was loaded from for some debug messages.

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

bool	should_warn_of_blocking (uint32_t blocking_time)

Public Member Functions inherited from esphome::image::Image
	Image (const uint8_t *data_start, int width, int height, ImageType type, Transparency transparency)

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_img_dsc_t *	get_lv_img_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)

uint32_t	get_buffer_size_ () const

int	get_buffer_size_ (int width, int height) const

int	get_position_ (int x, int y) const

ESPHOME_ALWAYS_INLINE bool	is_auto_resize_ () const

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

void	draw_pixel_ (int x, int y, Color color)
	Draw a pixel into the buffer.

void	end_connection_ ()

Protected Member Functions inherited from esphome::Component
virtual void	call_loop ()

virtual void	call_dump_config ()

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

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 (uint32_t id)

bool	cancel_interval (InternalSchedulerID id)

ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std	ESPDEPRECATED ("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const char *name

	ESPDEPRECATED ("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(uint32_t id

	ESPDEPRECATED ("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(uint32_t initial_wait_time

ESPDEPRECATED("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0") bool cancel_retry(const std	ESPDEPRECATED ("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0") bool cancel_retry(const char *name)

	ESPDEPRECATED ("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0") bool cancel_retry(uint32_t id)

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 (uint32_t id)

bool	cancel_timeout (InternalSchedulerID id)

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 (uint32_t id)

Protected Member Functions inherited from esphome::image::Image
bool	get_binary_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
RAMAllocator< uint8_t >	allocator_ {}

CallbackManager< void(bool)>	download_finished_callback_ {}

CallbackManager< void()>	download_error_callback_ {}

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

std::unique_ptr< ImageDecoder >	decoder_ {nullptr}

uint8_t *	buffer_

DownloadBuffer	download_buffer_

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

const ImageFormat	format_

image::Image *	placeholder_ {nullptr}

std::string	url_ {""}

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

const int	fixed_width_
	width requested on configuration, or 0 if non specified.

const int	fixed_height_
	height requested on configuration, or 0 if non specified.

bool	is_big_endian_
	Whether the image is stored in big-endian format.

int	buffer_width_
	Actual width of the current image.

int	buffer_height_
	Actual height of the current image.

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.

time_t	start_time_

Protected Attributes inherited from esphome::PollingComponent
uint32_t	update_interval_

Protected Attributes inherited from esphome::Component
ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") void set_interval(const std voi	set_interval )(const char *name, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a unique name.

ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") bool cancel_interval(const std boo	cancel_interval )(const char *name)
	Cancel an interval function.

ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t	initial_wait_time

ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t uint8_t	max_attempts

ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t uint8_t std::function< RetryResult(uint8_t)> &&	f

ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t uint8_t std::function< RetryResult(uint8_t)> float	backoff_increase_factor = 1.0f)

uint32_t	initial_wait_time

uint32_t uint8_t	max_attempts

uint32_t uint8_t std::function< RetryResult(uint8_t)> &&	f

uint32_t uint8_t std::function< RetryResult(uint8_t)> float	backoff_increase_factor = 1.0f)

uint8_t	max_attempts

uint8_t std::function< RetryResult(uint8_t)> &&	f

uint8_t std::function< RetryResult(uint8_t)> float	backoff_increase_factor = 1.0f)

ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") void set_timeout(const std voi	set_timeout )(const char *name, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a unique name.

ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") bool cancel_timeout(const std boo	cancel_timeout )(const char *name)
	Cancel a timeout function.

ESPDEPRECATED("Use const char* overload instead. Removed in 2026.7.0", "2026.1.0") void defer(const std voi	defer )(const char *name, std::function< void()> &&f)
	Defer a callback to the next loop() call.

ESPDEPRECATED("Use const char* overload instead. Removed in 2026.7.0", "2026.1.0") bool cancel_defer(const std boo	cancel_defer )(const char *name)
	Cancel a defer callback using the specified name, name must not be empty.

const LogString *	component_source_ {nullptr}

uint16_t	warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_MS}
	Warn if blocked for this many ms (max 65.5s)

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 Bits 5-7: Unused - reserved for future expansion.

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

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

int	height_

ImageType	type_

const uint8_t *	data_start_

Transparency	transparency_

size_t	bpp_ {}

size_t	stride_ {}

lv_img_dsc_t	dsc_ {}

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

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 39 of file online_image.h.

Constructor & Destructor Documentation

◆ OnlineImage()

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

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: ImageFormat).

Parameters

buffer_size Size of the buffer used to download the image.

Definition at line 37 of file online_image.cpp.

Member Function Documentation

◆ add_on_error_callback()

void esphome::online_image::OnlineImage::add_on_error_callback ( std::function< void()> && callback )

Definition at line 364 of file online_image.cpp.

◆ add_on_finished_callback()

void esphome::online_image::OnlineImage::add_on_finished_callback ( std::function< void(bool)> && callback )

Definition at line 360 of file online_image.cpp.

◆ 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 71 of file online_image.h.

◆ draw()

void esphome::online_image::OnlineImage::draw	(	int	x,
		int	y,
		display::Display *	display,
		Color	color_on,
		Color	color_off )

overridevirtual

Reimplemented from esphome::image::Image.

Definition at line 50 of file online_image.cpp.

◆ draw_pixel_()

void esphome::online_image::OnlineImage::draw_pixel_	(	int	x,
		int	y,
		Color	color )

protected

Draw a pixel into the buffer.

This is used by the decoder to fill the buffer that will later be displayed by the draw method. This will internally convert the supplied 32 bit RGBA color into the requested image storage format.

Parameters

x	Horizontal pixel position.
y	Vertical pixel position.
color	32 bit color to put into the pixel.

Definition at line 273 of file online_image.cpp.

◆ end_connection_()

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

protected

Definition at line 343 of file online_image.cpp.

◆ get_buffer_size_() [1/2]

uint32_t esphome::online_image::OnlineImage::get_buffer_size_ ( ) const

inlineprotected

Definition at line 104 of file online_image.h.

◆ get_buffer_size_() [2/2]

int esphome::online_image::OnlineImage::get_buffer_size_	(	int	width,
		int	height ) const

inlineprotected

Definition at line 105 of file online_image.h.

◆ get_position_()

int esphome::online_image::OnlineImage::get_position_	(	int	x,
		int	y ) const

inlineprotected

Definition at line 107 of file online_image.h.

◆ is_auto_resize_()

ESPHOME_ALWAYS_INLINE bool esphome::online_image::OnlineImage::is_auto_resize_ ( ) const

inlineprotected

Definition at line 109 of file online_image.h.

◆ loop()

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

overridevirtual

Reimplemented from esphome::Component.

Definition at line 216 of file online_image.cpp.

◆ map_chroma_key()

void esphome::online_image::OnlineImage::map_chroma_key ( Color & color )

Definition at line 260 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 58 of file online_image.cpp.

◆ resize_()

size_t esphome::online_image::OnlineImage::resize_	(	int	width,
		int	height )

protected

Resize the image buffer to the requested dimensions.

The buffer will be allocated if not existing. If the dimensions have been fixed in the yaml config, the buffer will be created with those dimensions and not resized, even on request. Otherwise, the old buffer will be deallocated and a new buffer with the requested allocated

Parameters

width
height

Returns: 0 if no memory could be allocated, the size of the new buffer otherwise.

Definition at line 74 of file online_image.cpp.

◆ resize_download_buffer()

size_t esphome::online_image::OnlineImage::resize_download_buffer ( size_t size )

inline

Resize the download buffer.

Parameters

size	The new size for the download buffer.

Definition at line 94 of file online_image.h.

◆ set_placeholder()

void esphome::online_image::OnlineImage::set_placeholder ( image::Image * placeholder )

inline

Set the image that needs to be shown as long as the downloaded image is not available.

Parameters

placeholder Pointer to the (to show as placeholder.

Definition at line 81 of file online_image.h.

◆ 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 62 of file online_image.h.

◆ update()

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

overridevirtual

Implements esphome::PollingComponent.

Definition at line 104 of file online_image.cpp.

◆ validate_url_()

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

protected

Definition at line 352 of file online_image.cpp.

Field Documentation

◆ allocator_

RAMAllocator<uint8_t> esphome::online_image::OnlineImage::allocator_ {}

protected

Definition at line 102 of file online_image.h.

◆ buffer_

uint8_t* esphome::online_image::OnlineImage::buffer_

protected

Definition at line 147 of file online_image.h.

◆ buffer_height_

int esphome::online_image::OnlineImage::buffer_height_

protected

Actual height of the current image.

If fixed_height_ is specified, this will be equal to it; otherwise it will be set once the decoding starts and the original size is known. This needs to be separate from "BaseImage::get_height()" because the latter must return 0 until the image has been decoded (to avoid showing partially decoded images).

Definition at line 189 of file online_image.h.

◆ buffer_width_

int esphome::online_image::OnlineImage::buffer_width_

protected

Actual width of the current image.

If fixed_width_ is specified, this will be equal to it; otherwise it will be set once the decoding starts and the original size is known. This needs to be separate from "BaseImage::get_width()" because the latter must return 0 until the image has been decoded (to avoid showing partially decoded images).

Definition at line 180 of file online_image.h.

◆ decoder_

std::unique_ptr<ImageDecoder> esphome::online_image::OnlineImage::decoder_ {nullptr}

protected

Definition at line 145 of file online_image.h.

◆ download_buffer_

DownloadBuffer esphome::online_image::OnlineImage::download_buffer_

protected

Definition at line 148 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 154 of file online_image.h.

◆ download_error_callback_

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

protected

Definition at line 142 of file online_image.h.

◆ download_finished_callback_

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

protected

Definition at line 141 of file online_image.h.

◆ downloader_

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

protected

Definition at line 144 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 193 of file online_image.h.

◆ fixed_height_

const int esphome::online_image::OnlineImage::fixed_height_

protected

height requested on configuration, or 0 if non specified.

Definition at line 166 of file online_image.h.

◆ fixed_width_

const int esphome::online_image::OnlineImage::fixed_width_

protected

width requested on configuration, or 0 if non specified.

Definition at line 164 of file online_image.h.

◆ format_

const ImageFormat esphome::online_image::OnlineImage::format_

protected

Definition at line 156 of file online_image.h.

◆ is_big_endian_

bool esphome::online_image::OnlineImage::is_big_endian_

protected

Whether the image is stored in big-endian format.

This is used to determine how to store 16 bit colors in the buffer.

Definition at line 171 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 197 of file online_image.h.

◆ placeholder_

image::Image* esphome::online_image::OnlineImage::placeholder_ {nullptr}

protected

Definition at line 157 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 161 of file online_image.h.

◆ start_time_

time_t esphome::online_image::OnlineImage::start_time_

protected

Definition at line 199 of file online_image.h.

◆ url_

std::string esphome::online_image::OnlineImage::url_ {""}

protected

Definition at line 159 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

Detailed Description

Constructor & Destructor Documentation

◆ OnlineImage()

Member Function Documentation

◆ add_on_error_callback()

◆ add_on_finished_callback()

◆ add_request_header()

◆ draw()

◆ draw_pixel_()

◆ end_connection_()

◆ get_buffer_size_() [1/2]

◆ get_buffer_size_() [2/2]

◆ get_position_()

◆ is_auto_resize_()

◆ loop()

◆ map_chroma_key()

◆ release()

◆ resize_()

◆ resize_download_buffer()

◆ set_placeholder()

◆ set_url()

◆ update()

◆ validate_url_()

Field Documentation

◆ allocator_

◆ buffer_

◆ buffer_height_

◆ buffer_width_

◆ decoder_

◆ download_buffer_

◆ download_buffer_initial_size_

◆ download_error_callback_

◆ download_finished_callback_

◆ downloader_

◆ etag_

◆ fixed_height_

◆ fixed_width_

◆ format_

◆ is_big_endian_

◆ last_modified_

◆ placeholder_

◆ request_headers_

◆ start_time_

◆ url_