[runtime_image] Improve format logs (#19903)

Co-authored-by: J. Nick Koston <nick@koston.org>

esphome/components/online_image/online_image.cpp

@@ -122,11 +122,11 @@ void OnlineImage::update() {
       return;
     }
   }
-  ESP_LOGD(TAG, "Using image format: %d", format);
+  ESP_LOGD(TAG, "Using image format: %s", LOG_STR_ARG(runtime_image::get_format_name(format)));
 
   // Initialize decoder with the known format
   if (!this->begin_decode(total_size, format)) {
-    ESP_LOGE(TAG, "Failed to initialize decoder for format %d", format);
+    ESP_LOGE(TAG, "Failed to initialize decoder for format %s", LOG_STR_ARG(runtime_image::get_format_name(format)));
     this->end_connection_();
     this->download_error_callback_.call();
     return;

esphome/components/runtime_image/image_format.cpp

@@ -1,5 +1,6 @@
 #include "esphome/core/defines.h"
 #include "esphome/core/helpers.h"
+#include "esphome/core/progmem.h"
 #include "image_format.h"
 
 namespace esphome::runtime_image {
@@ -26,6 +27,8 @@ static constexpr MimeLookup MIME_LOOKUP_TABLE[] = {
 #endif
 };
 
+PROGMEM_STRING_TABLE(ImageFormatStrings, "AUTO", "BMP", "JPEG", "PNG", "QOI", "UNKNOWN");
+
 const char *get_mime_type_for_format(ImageFormat format) {
   for (const auto &entry : MIME_LOOKUP_TABLE) {
     if (entry.format == format) {
@@ -44,4 +47,8 @@ std::optional<ImageFormat> get_format_for_mime_type(const char *mime_type) {
   return std::nullopt;
 }
 
+const LogString *get_format_name(ImageFormat format) {
+  return ImageFormatStrings::get_log_str(static_cast<uint8_t>(format), ImageFormatStrings::LAST_INDEX);
+}
+
 }  // namespace esphome::runtime_image

esphome/components/runtime_image/image_format.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <optional>
+#include "esphome/core/log.h"
 
 namespace esphome::runtime_image {
 
@@ -25,5 +26,7 @@ enum ImageFormat {
 const char *get_mime_type_for_format(ImageFormat format);
 /// Case-insensitive substring match of known media types; nullopt if none found
 std::optional<ImageFormat> get_format_for_mime_type(const char *mime_type);
+/// Human-readable name for a format; "UNKNOWN" if not recognized
+const LogString *get_format_name(ImageFormat format);
 
 }  // namespace esphome::runtime_image

esphome/components/runtime_image/runtime_image.cpp

@@ -186,14 +186,15 @@ bool RuntimeImage::begin_decode(size_t expected_size, ImageFormat format) {
 
   // An idle decoder for a different format cannot be reused
   if (this->decoder_ != nullptr && this->decoder_->get_format() != format) {
-    ESP_LOGD(TAG, "Decoder format mismatch: current: %d, new: %d", this->decoder_->get_format(), format);
+    ESP_LOGD(TAG, "Decoder format mismatch: current: %s, new: %s",
+             LOG_STR_ARG(get_format_name(this->decoder_->get_format())), LOG_STR_ARG(get_format_name(format)));
     this->decoder_ = nullptr;
   }
 
   if (!this->decoder_) {
     this->decoder_ = this->create_decoder_(format);
     if (!this->decoder_) {
-      ESP_LOGE(TAG, "Failed to create decoder for format %d", format);
+      ESP_LOGE(TAG, "Failed to create decoder for format %s", LOG_STR_ARG(get_format_name(format)));
       return false;
     }
   }
@@ -357,7 +358,7 @@ size_t RuntimeImage::get_buffer_size(int width, int height) const {
 int RuntimeImage::get_position_(int x, int y) const { return (x + y * this->buffer_width_) * this->get_bpp() / 8; }
 
 std::unique_ptr<ImageDecoder> RuntimeImage::create_decoder_(ImageFormat format) {
-  ESP_LOGV(TAG, "Creating decoder for format %d", format);
+  ESP_LOGV(TAG, "Creating decoder for format %s", LOG_STR_ARG(get_format_name(format)));
   switch (format) {
 #ifdef USE_RUNTIME_IMAGE_BMP
     case BMP:
@@ -379,7 +380,7 @@ std::unique_ptr<ImageDecoder> RuntimeImage::create_decoder_(ImageFormat format)
       ESP_LOGE(TAG, "Image format could not be determined; set `format:` explicitly in the configuration");
       return nullptr;
     default:
-      ESP_LOGE(TAG, "Unsupported image format: %d", format);
+      ESP_LOGE(TAG, "Unsupported image format: %s", LOG_STR_ARG(get_format_name(format)));
       return nullptr;
   }
 }

tests/components/runtime_image/test_format_names.cpp

@@ -0,0 +1,19 @@
+#include <gtest/gtest.h>
+
+#include "esphome/components/runtime_image/image_format.h"
+
+namespace esphome::runtime_image::testing {
+
+TEST(RuntimeImageFormatNames, FormatNames) {
+  EXPECT_STREQ(LOG_STR_ARG(get_format_name(AUTO)), "AUTO");
+  EXPECT_STREQ(LOG_STR_ARG(get_format_name(BMP)), "BMP");
+  EXPECT_STREQ(LOG_STR_ARG(get_format_name(JPEG)), "JPEG");
+  EXPECT_STREQ(LOG_STR_ARG(get_format_name(PNG)), "PNG");
+  EXPECT_STREQ(LOG_STR_ARG(get_format_name(QOI)), "QOI");
+}
+
+TEST(RuntimeImageFormatNames, OutOfRangeName) {
+  EXPECT_STREQ(LOG_STR_ARG(get_format_name(static_cast<ImageFormat>(254))), "UNKNOWN");
+}
+
+}  // namespace esphome::runtime_image::testing

tests/components/runtime_image/test_mime_types.cpp

@@ -2,7 +2,7 @@
 
 #include <optional>
 
-#include "esphome/components/runtime_image/runtime_image.h"
+#include "esphome/components/runtime_image/image_format.h"
 
 namespace esphome::runtime_image::testing {