esphome matrix clock

esphome/.device-builder.json

@@ -306,6 +306,114 @@
     "mac_address": "88:13:BF:68:39:2C"
   },
   "_firmware_jobs": [
+    {
+      "job_id": "3d7f83abae00",
+      "configuration": "esp-ledmatrix1.yaml",
+      "job_type": "install",
+      "status": "completed",
+      "created_at": "2026-05-24T06:00:04.161447+00:00",
+      "started_at": "2026-05-24T06:00:04.161684+00:00",
+      "completed_at": "2026-05-24T06:00:46.473420+00:00",
+      "exit_code": 0,
+      "output": [
+        "\\033[32mINFO ESPHome 2026.5.0\\033[0m\n",
+        "\\033[32mINFO Reading configuration /config/esphome/esp-ledmatrix1.yaml...\\033[0m\n",
+        "\\033[33mWARNING GPIO8 is a strapping PIN and should only be used for I/O with care.\n",
+        "Attaching external pullup/down resistors to strapping pins can cause unexpected failures.\n",
+        "See https://esphome.io/guides/faq/#why-am-i-getting-a-warning-about-strapping-pins\\033[0m\n",
+        "\\033[33mWARNING GPIO9 is a strapping PIN and should only be used for I/O with care.\n",
+        "Attaching external pullup/down resistors to strapping pins can cause unexpected failures.\n",
+        "See https://esphome.io/guides/faq/#why-am-i-getting-a-warning-about-strapping-pins\\033[0m\n",
+        "\\033[32mINFO Generating C++ source...\\033[0m\n",
+        "\\033[32mINFO Setting CONFIG_LWIP_MAX_SOCKETS to 18 (TCP=12 [api=3, captive_portal=3, mqtt=1, web_server=5], UDP=3 [captive_portal=1, mdns=2], TCP_LISTEN=3 [api=1, ota=1, web_server_base=1])\\033[0m\n",
+        "\\033[32mINFO Compiling app... Build path: /data/build/esp-ledmatrix1\\033[0m\n",
+        "Processing \u001b[36m\u001b[1mesp-ledmatrix1\u001b[0m (board: esp32-c3-devkitm-1; framework: espidf; platform: https://github.com/pioarduino/platform-espressif32/releases/download/55.03.38-1/platform-espressif32.zip)\n",
+        "\u001b[1m--------------------------------------------------------------------------------\u001b[0m\n",
+        "\u001b[0mHARDWARE: ESP32C3 160MHz, 320KB RAM, 4MB Flash\n",
+        "\u001b[0m - contrib-piohome @ 3.4.4 \n",
+        "\u001b[0m - framework-espidf @ 3.50504.0 (5.5.4) \n",
+        "\u001b[0m - tool-cmake @ 4.0.3 \n",
+        "\u001b[0m - tool-esp-rom-elfs @ 2024.10.11 \n",
+        "\u001b[0m - tool-esptoolpy @ 5.2.0 \n",
+        "\u001b[0m - tool-ninja @ 1.13.1 \n",
+        "\u001b[0m - tool-riscv32-esp-elf-gdb @ 16.3.0+20250913 \n",
+        "\u001b[0m - tool-scons @ 4.40801.0 (4.8.1) \n",
+        "\u001b[0m - toolchain-riscv32-esp @ 14.2.0+20260121\n",
+        "\u001b[33m\u001b[2mUsing Python 3.12.10 environment at: /root/.platformio/penv/.espidf-5.5.4\u001b[0m\n",
+        "\u001b[0mReading CMake configuration...\n",
+        "\u001b[0mDependency Graph\n",
+        "\u001b[0m|-- noise-c @ 0.1.11\n",
+        "\u001b[0mCompiling .pioenvs/esp-ledmatrix1/src/main.cpp.o\n",
+        "\u001b[0mLinking .pioenvs/esp-ledmatrix1/firmware.elf\n",
+        "\u001b[0m\u001b[3m                            Memory Type Usage Summary                             \u001b[0m\n",
+        "\u001b[0m┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓\n",
+        "┃\u001b[1m \u001b[0m\u001b[1mMemory Type/Section\u001b[0m\u001b[1m \u001b[0m┃\u001b[1m \u001b[0m\u001b[1mUsed [bytes]\u001b[0m\u001b[1m \u001b[0m┃\u001b[1m \u001b[0m\u001b[1mUsed [%]\u001b[0m\u001b[1m \u001b[0m┃\u001b[1m \u001b[0m\u001b[1mRemain [bytes]\u001b[0m\u001b[1m \u001b[0m┃\u001b[1m \u001b[0m\u001b[1mTotal [bytes]\u001b[0m\u001b[1m \u001b[0m┃\n",
+        "\u001b[0m┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩\n",
+        "│\u001b[91m \u001b[0m\u001b[91mFlash Code         \u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m      948010\u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m        \u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m              \u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m             \u001b[0m\u001b[91m \u001b[0m│\n",
+        "\u001b[0m│\u001b[94m \u001b[0m\u001b[94m   .text           \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m      948010\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m        \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m              \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m             \u001b[0m\u001b[94m \u001b[0m│\n",
+        "\u001b[0m│\u001b[91m \u001b[0m\u001b[91mFlash Data         \u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m      188404\u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m        \u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m              \u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m             \u001b[0m\u001b[91m \u001b[0m│\n",
+        "\u001b[0m│\u001b[94m \u001b[0m\u001b[94m   .rodata         \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m      188148\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m        \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m              \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m             \u001b[0m\u001b[94m \u001b[0m│\n",
+        "\u001b[0m│\u001b[94m \u001b[0m\u001b[94m   .appdesc        \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m         256\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m        \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m              \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m             \u001b[0m\u001b[94m \u001b[0m│\n",
+        "\u001b[0m│\u001b[91m \u001b[0m\u001b[91mDRAM               \u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m      112432\u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m   34.99\u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m        208864\u001b[0m\u001b[91m \u001b[0m│\u001b[91m \u001b[0m\u001b[91m       321296\u001b[0m\u001b[91m \u001b[0m│\n",
+        "\u001b[0m\u001b[33mTotal image size: \u001b[1;36m1211550\u001b[0m bytes \u001b[1m(\u001b[0m.bin may be padded larger\u001b[1m)\u001b[0m\n",
+        "\u001b[0m\u001b[33m\u001b[33mNote: The reported total sizes may be smaller than those in the technical reference manual due to reserved memory and application configuration. The total flash size available for the application is not included by default, as it cannot be reliably determined due to the presence of other data like the bootloader, partition table, and application partition size.\u001b[0m\n",
+        "\u001b[0m│\u001b[94m \u001b[0m\u001b[94m   .text           \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m       62676\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m   19.51\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m              \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m             \u001b[0m\u001b[94m \u001b[0m│\n",
+        "\u001b[0m│\u001b[94m \u001b[0m\u001b[94m   .bss            \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m       37208\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m   11.58\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m              \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m             \u001b[0m\u001b[94m \u001b[0m│\n",
+        "\u001b[0m│\u001b[94m \u001b[0m\u001b[94m   .data           \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m       12460\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m    3.88\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m              \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m             \u001b[0m\u001b[94m \u001b[0m│\n",
+        "\u001b[0m│\u001b[94m \u001b[0m\u001b[94m   .noinit         \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m          88\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m    0.03\u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m              \u001b[0m\u001b[94m \u001b[0m│\u001b[94m \u001b[0m\u001b[94m             \u001b[0m\u001b[94m \u001b[0m│\n",
+        "\u001b[0m└─────────────────────┴──────────────┴──────────┴────────────────┴───────────────┘\n",
+        "\u001b[0mRAM:   [==        ]  15.2% (used 49756 bytes from 327680 bytes)\n",
+        "\u001b[0mFlash: [=======   ]  66.0% (used 1211294 bytes from 1835008 bytes)\n",
+        "Building .pioenvs/esp-ledmatrix1/firmware.bin\n",
+        "\u001b[0mCreating ESP32-C3 image...\n",
+        "\u001b[0mSuccessfully created ESP32-C3 image.\n",
+        "\u001b[0mCreating binary \"firmware.factory.bin\" with:\n",
+        "\u001b[0m    Offset   | File\n",
+        "\u001b[0m -  0x0      | bootloader.bin\n",
+        "\u001b[0m -  0x8000   | partitions.bin\n",
+        "\u001b[0m -  0x9000   | ota_data_initial.bin\n",
+        "\u001b[0m -  0x10000  | firmware.bin\n",
+        "Successfully created combined binary image.\n",
+        "\u001b[0msign_firmware([\".pioenvs/esp-ledmatrix1/firmware.bin\"], [\".pioenvs/esp-ledmatrix1/firmware.elf\"])\n",
+        "\u001b[0mmerge_factory_bin([\".pioenvs/esp-ledmatrix1/firmware.bin\"], [\".pioenvs/esp-ledmatrix1/firmware.elf\"])\n",
+        "\u001b[0mInfo: bootloader.bin not found - skipping\n",
+        "\u001b[0mInfo: partition-table.bin not found - skipping\n",
+        "\u001b[0mInfo: ota_data_initial.bin not found - skipping\n",
+        "\u001b[0mInfo: esp-ledmatrix1.bin not found - skipping\n",
+        "\u001b[0mUsing FLASH_EXTRA_IMAGES from PlatformIO environment\n",
+        "\u001b[0mMerging binaries into /data/build/esp-ledmatrix1/.pioenvs/esp-ledmatrix1/firmware.factory.bin\n",
+        "\u001b[0mMerging binaries with esptool\n",
+        "\u001b[0mSHA digest in image updated.\n",
+        "\u001b[0mWrote 0x137d30 bytes to file '/data/build/esp-ledmatrix1/.pioenvs/esp-ledmatrix1/firmware.factory.bin', ready to flash to offset 0x0.\n",
+        "\u001b[0mSuccessfully created /data/build/esp-ledmatrix1/.pioenvs/esp-ledmatrix1/firmware.factory.bin\n",
+        "\u001b[0mesp32_copy_ota_bin([\".pioenvs/esp-ledmatrix1/firmware.bin\"], [\".pioenvs/esp-ledmatrix1/firmware.elf\"])\n",
+        "\u001b[0mCopied firmware to /data/build/esp-ledmatrix1/.pioenvs/esp-ledmatrix1/firmware.ota.bin\n",
+        "\u001b[0m========================= [\u001b[32m\u001b[1mSUCCESS\u001b[0m] Took 27.91 seconds =========================\u001b[0m\n",
+        "\\033[32mINFO Build Info: config_hash=0xf445aeee build_time_str=2026-05-24 15:15:37 +1200\\033[0m\n",
+        "\\033[32mINFO Successfully compiled program.\\033[0m\n",
+        "\\033[32mINFO Connecting to 172.31.11.185 port 3232...\\033[0m\n",
+        "\\033[32mINFO Connected to 172.31.11.185\\033[0m\n",
+        "\\033[32mINFO Uploading /data/build/esp-ledmatrix1/.pioenvs/esp-ledmatrix1/firmware.bin (1211696 bytes)\\033[0m\n",
+        "Uploading: [============================================================] 100% Done...\r\n",
+        "\n",
+        "\\033[32mINFO Upload took 6.26 seconds, waiting for result...\\033[0m\n",
+        "\\033[32mINFO OTA successful\\033[0m\n",
+        "\\033[32mINFO Successfully uploaded program.\\033[0m\n"
+      ],
+      "error": null,
+      "port": "OTA",
+      "new_name": "",
+      "progress": 100,
+      "remote_peer": "",
+      "remote_job_id": "",
+      "remote_peer_label": "",
+      "device_name": "",
+      "device_friendly_name": "",
+      "source": "local",
+      "source_pin_sha256": "",
+      "source_label": "",
+      "source_esphome_version": ""
+    },
     {
       "job_id": "126762467ae7",
       "configuration": "esp-nspanel1masterbdrm.yaml",
@@ -647,6 +755,45 @@
       "source_label": "",
       "source_esphome_version": ""
     },
+    {
+      "job_id": "5ed4f57830a1",
+      "configuration": "esp-ledmatrix1.yaml",
+      "job_type": "clean",
+      "status": "completed",
+      "created_at": "2026-05-24T03:37:56.768112+00:00",
+      "started_at": "2026-05-24T03:37:56.768278+00:00",
+      "completed_at": "2026-05-24T03:37:58.596073+00:00",
+      "exit_code": 0,
+      "output": [
+        "\\033[32mINFO ESPHome 2026.5.0\\033[0m\n",
+        "\\033[32mINFO Reading configuration /config/esphome/esp-ledmatrix1.yaml...\\033[0m\n",
+        "\\033[33mWARNING GPIO8 is a strapping PIN and should only be used for I/O with care.\n",
+        "Attaching external pullup/down resistors to strapping pins can cause unexpected failures.\n",
+        "See https://esphome.io/guides/faq/#why-am-i-getting-a-warning-about-strapping-pins\\033[0m\n",
+        "\\033[33mWARNING GPIO9 is a strapping PIN and should only be used for I/O with care.\n",
+        "Attaching external pullup/down resistors to strapping pins can cause unexpected failures.\n",
+        "See https://esphome.io/guides/faq/#why-am-i-getting-a-warning-about-strapping-pins\\033[0m\n",
+        "\\033[32mINFO Deleting /data/build/esp-ledmatrix1/.pioenvs\\033[0m\n",
+        "\\033[32mINFO Deleting /data/build/esp-ledmatrix1/.piolibdeps\\033[0m\n",
+        "\\033[32mINFO Deleting /data/build/esp-ledmatrix1/dependencies.lock\\033[0m\n",
+        "\\033[32mINFO Deleting /data/build/esp-ledmatrix1/managed_components\\033[0m\n",
+        "\\033[32mINFO Deleting PlatformIO cache /data/cache/platformio/cache\\033[0m\n",
+        "\\033[32mINFO Done!\\033[0m\n"
+      ],
+      "error": null,
+      "port": "",
+      "new_name": "",
+      "progress": null,
+      "remote_peer": "",
+      "remote_job_id": "",
+      "remote_peer_label": "",
+      "device_name": "",
+      "device_friendly_name": "",
+      "source": "local",
+      "source_pin_sha256": "",
+      "source_label": "",
+      "source_esphome_version": ""
+    },
     {
       "job_id": "e4433a434baf",
       "configuration": "esp-nspanel1masterbdrm.yaml",
@@ -727,6 +874,6 @@
   },
   "esp-ledmatrix1.yaml": {
     "board_id": "generic-esp8266",
-    "mac_address": "5C:CF:7F:A0:36:73"
+    "mac_address": "64:E8:33:84:FD:C8"
   }
 }

esphome/esp-ledmatrix1.yaml

@@ -2,12 +2,19 @@
 # TITLE: LED MATRIX 1
 # zorruno.com layout v1.1 2026
 # ESP32-C3 SuperMini MAX7219 LED matrix clock and scroll display.
+#:########################################################################################:#
+# REFERENCES:
 # Original Project Reference https://github.com/RealDeco/matrixclock-esphome
+# Fonts: https://github.com/RealDeco/matrixclock-esphome/tree/main/fonts
+# 3D Printed Case (includes project notes in the 3mf files) 
+#      https://github.com/RealDeco/matrixclock-esphome/tree/main/3DPrint
 #:########################################################################################:#
 # REPO:
 # https://home.fox.co.nz/gitea/zorruno/zorruno-homeassistant/src/branch/master/esphome/esp-ledmatrix1.yaml
 #:########################################################################################:#
 # VERSIONS:
+# V1.3 2026-05-24 Added native API action for Home Assistant direct scroll text commands.
+# V1.2 2026-05-24 Added 1-15 brightness level slider and improved operation notes.
 # V1.1 2026-05-23 Updated yaml to zorruno layout V1.1, cleaned comments, fixed SNTP time IDs,
 #                  added current_mins fallback display, removed unused MQTT topic, and fixed
 #                  blank scroll handling.
@@ -20,31 +27,50 @@
 #   - MOSI: GPIO8
 #   - CS:   GPIO9
 #   - SCK:  GPIO10
-# - Power note: 4 MAX7219 modules may need a suitable external 5 V supply.
+# - Power note: 4 MAX7219 modules needs a suitable external 5 V supply.
 # - Keep ESP32-C3 GND and matrix power supply GND connected together.
 #:########################################################################################:#
-# FONTS:
-# Dragon Font: https://www.freebestfonts.com/eight-bit-dragon-font
-# 5x8 Font: https://developer.lasec.com.mx/armando/rpi-rgb-led-matrix/-/blob/master/fonts/5x8.bdf
-#:########################################################################################:#
 # OPERATION NOTES:
-# - Displays the current time from common/sntp_common.yaml using id(sntp_time).
+# - Main display:
-# - If SNTP is invalid, the display falls back to id(current_mins) from common/sntp_common.yaml.
+#   - Shows a 32 x 8 LED matrix clock using the MAX7219 display component.
-# - 12h/24h display mode is selectable from Home Assistant or MQTT.
+#   - Uses common/sntp_common.yaml as the primary time source via id(sntp_time).
-# - Display brightness is exposed as a Home Assistant light entity.
+#   - If SNTP is not valid, uses id(current_mins) as a fallback clock.
-# - Brightness accepts values 0..15 where 0 turns the display off and 1..15 sets intensity.
+#   - In fallback mode the colon stays solid, so it is obvious time is not fully synced.
-# - Scroll Text is exposed as a Home Assistant text entity and clears itself after use.
+#
-# - Before any scroll starts, the clock slides down and off the display.
+# - Clock controls:
-# - After scroll ends, the selected re-entry effect runs: Slide up, Slide down, or Pixel fall.
+#   - Clock format can be selected as 12h or 24h from Home Assistant or MQTT.
-# - Pixel fall hides the clock until the effect finishes, avoiding a clock-under-particles look.
+#   - 12h mode draws a small A or P indicator at the far right of the display.
-# - Scroll speed is adjustable using the Scroll Delay number entity.
+#
+# - Brightness controls:
+#   - The Display light entity can turn the matrix on/off and set proportional brightness.
+#   - The Brightness Level number slider sets the exact MAX7219 intensity from 1 to 15.
+#   - MQTT brightness accepts 0 to turn the display off, or 1-15 to set exact intensity.
+#   - The 1-15 slider keeps the last non-zero brightness value when the display is off.
+#
+# - Scroll text controls:
+#   - Scroll Text is exposed as a Home Assistant text entity.
+#   - Native API action esphome.esp_ledmatrix1_scroll_text can scroll text directly from Home Assistant.
+#   - The text box clears itself after a valid scroll request is accepted.
+#   - Empty scroll requests are ignored and do not replay the previous message.
+#   - Scroll Delay controls the delay in milliseconds between scroll steps.
+#
+# - Scroll transitions:
+#   - Before scrolling, the clock always slides down and off the display.
+#   - After scrolling, the selected re-entry effect runs.
+#   - Available re-entry effects are Slide up, Slide down, and Pixel fall.
+#   - Pixel fall hides the clock until the particle effect finishes.
 #:########################################################################################:#
 # MQTT COMMANDS:
 # - ${mqtt_command_topic}/scroll : Text payload to scroll once across the display.
 # - ${mqtt_command_topic}/mode   : Payload 12 or 24 to select clock format.
-# - ${mqtt_command_topic}/bright : Payload 0 turns display off, 1-15 sets brightness.
+# - ${mqtt_command_topic}/bright : Payload 0 turns display off, 1-15 sets exact brightness.
 # - ${mqtt_status_topic}/status  : Publishes online/offline status.
 #:########################################################################################:#
+# HOME ASSISTANT API ACTIONS:
+# - esphome.esp_ledmatrix1_scroll_text
+#   data:
+#     message: "Text to scroll"
+#:########################################################################################:#
 # OFFLINE NOTES:
 # a) Home Assistant offline, but WiFi/network and MQTT online:
 #    - Clock display should continue using SNTP if the NTP servers are reachable.
@@ -75,7 +101,7 @@ substitutions:
 
   # Project Naming
   project_name: "Generic.ESP32 Supermini"
-  project_version: "v1.1"
+  project_version: "v1.3"
 
   # Passwords & Secrets
   api_key: !secret esp-api_key
@@ -103,6 +129,7 @@ substitutions:
   pin_sck: GPIO10
   num_chips: "4"
   scroll_delay_ms: "15" # ms between scroll steps
+  matrix_initial_brightness: "2" # Default MAX7219 intensity, 1-15.
   y_offset: "0"
   y_scroll_offset: "0"
 
@@ -176,6 +203,11 @@ esp32:
     type: esp-idf
     version: recommended
 
+#esp8266:
+#  board: esp01_1m
+#  early_pin_init: false # Recommended false where switches are involved. Defaults to true.
+#  board_flash_mode: dout # Default is dout.
+
 #:########################################################################################:#
 # LOGGER: ESPHome Logging Enable
 # https://esphome.io/components/logger.html
@@ -186,6 +218,37 @@ logger:
   #esp8266_store_log_strings_in_flash: false
   #tx_buffer_size: 64
 
+#:########################################################################################:#
+# API COMPONENT: Device-specific Home Assistant native API actions
+# https://esphome.io/components/api.html
+#:########################################################################################:#
+api:
+  actions:
+    # Home Assistant action: esphome.esp_ledmatrix1_scroll_text
+    # Example HA data: { message: "Hello from Home Assistant" }
+    - action: scroll_text
+      variables:
+        message: string
+      then:
+        - lambda: |-
+            std::string s = message;
+
+            s.erase(std::remove(s.begin(), s.end(), '\r'), s.end());
+            s.erase(std::remove(s.begin(), s.end(), '\n'), s.end());
+            s.erase(std::remove_if(s.begin(), s.end(),
+              [](unsigned char c){ return c < 0x20; }), s.end());
+
+            // Ignore empty API scroll commands completely.
+            if (s.empty()) return;
+
+            // Keep the HA text entity visually in sync with this direct API action.
+            id(ha_scroll_text).publish_state(s.c_str());
+
+            id(scroll_text) = s;
+            id(scroll_x) = ${num_chips} * 8;
+            id(start_scroll_sequence).execute();
+            id(clear_scroll_text_box).execute();
+
 #:########################################################################################:#
 # GLOBALS:
 # https://esphome.io/components/globals.html
@@ -218,11 +281,18 @@ globals:
     restore_value: true
     initial_value: '${scroll_delay_ms}'
 
-  # MAX7219 intensity: 0=OFF, 1..15=ON. Driven by the HA light entity.
+  # MAX7219 intensity: 0=OFF, 1..15=ON. Driven by the HA light and brightness slider.
   - id: matrix_intensity
     type: int
     restore_value: false
-    initial_value: '2'
+    initial_value: '${matrix_initial_brightness}'
+
+  # Last non-zero brightness level selected by HA, MQTT, or the 1-15 slider.
+  # This allows the exact slider to keep its value when the display is switched off.
+  - id: matrix_last_nonzero_intensity
+    type: int
+    restore_value: true
+    initial_value: '${matrix_initial_brightness}'
 
   # Brightness sync loop protection for HA light <-> MQTT brightness updates.
   - id: suppress_mqtt_bright_sync
@@ -362,6 +432,9 @@ mqtt:
             if (v == 0) {
               id(matrix_light).turn_off().perform();
             } else {
+              id(matrix_last_nonzero_intensity) = v;
+              id(matrix_brightness_number).publish_state((float) v);
+
               auto call = id(matrix_light).turn_on();
               call.set_brightness((float) v / 15.0f);
               call.perform();
@@ -422,12 +495,35 @@ number:
       - lambda: |-
           id(scroll_delay_runtime) = (int) x;
 
+  - platform: template
+    id: matrix_brightness_number
+    name: "${friendly_name} Brightness Level"
+    icon: "mdi:brightness-6"
+    min_value: 1
+    max_value: 15
+    step: 1
+    restore_value: true
+    initial_value: ${matrix_initial_brightness}
+    optimistic: true
+    set_action:
+      - lambda: |-
+          int v = (int) lroundf(x);
+          if (v < 1) v = 1;
+          if (v > 15) v = 15;
+
+          id(matrix_last_nonzero_intensity) = v;
+
+          // Setting the exact brightness slider also turns the display on.
+          auto call = id(matrix_light).turn_on();
+          call.set_brightness((float) v / 15.0f);
+          call.perform();
+
 #:########################################################################################:#
 # OUTPUT COMPONENT:
 # https://esphome.io/components/output/
 #:########################################################################################:#
 output:
-  # Template output lets the HA light slider control MAX7219 intensity.
+  # Template output lets the HA light and brightness slider control MAX7219 intensity.
   - platform: template
     id: matrix_brightness_out
     type: float
@@ -445,6 +541,8 @@ output:
             if (v > 15) v = 15;
 
             id(matrix_intensity) = v;
+            id(matrix_last_nonzero_intensity) = v;
+            id(matrix_brightness_number).publish_state((float) v);
             id(matrix).turn_on_off(true);
             pub = v;
           }

esphome/fonts/README.md

@@ -0,0 +1,5 @@
+fonts found here:
+
+dragon font: https://www.freebestfonts.com/eight-bit-dragon-font
+
+5x8: https://developer.lasec.com.mx/armando/rpi-rgb-led-matrix/-/blob/master/fonts/5x8.bdf