[nextion] Review touch_sleep_timeout (#9345)

esphome/components/nextion/display.py

@@ -95,7 +95,9 @@ CONFIG_SCHEMA = (
             cv.Optional(CONF_SKIP_CONNECTION_HANDSHAKE, default=False): cv.boolean,
             cv.Optional(CONF_START_UP_PAGE): cv.uint8_t,
             cv.Optional(CONF_TFT_URL): cv.url,
-            cv.Optional(CONF_TOUCH_SLEEP_TIMEOUT): cv.int_range(min=3, max=65535),
+            cv.Optional(CONF_TOUCH_SLEEP_TIMEOUT): cv.Any(
+                0, cv.int_range(min=3, max=65535)
+            ),
             cv.Optional(CONF_WAKE_UP_PAGE): cv.uint8_t,
         }
     )

esphome/components/nextion/nextion.cpp

@@ -13,14 +13,11 @@ void Nextion::setup() {
   this->is_setup_ = false;
   this->connection_state_.ignore_is_setup_ = true;
 
-  // Wake up the nextion
-  this->send_command_("bkcmd=0");
-  this->send_command_("sleep=0");
+  // Wake up the nextion and ensure clean communication state
+  this->send_command_("sleep=0");  // Exit sleep mode if sleeping
+  this->send_command_("bkcmd=0");  // Disable return data during init sequence
 
-  this->send_command_("bkcmd=0");
-  this->send_command_("sleep=0");
-
-  // Reboot it
+  // Reset device for clean state - critical for reliable communication
   this->send_command_("rest");
 
   this->connection_state_.ignore_is_setup_ = false;
@@ -140,6 +137,7 @@ void Nextion::reset_(bool reset_nextion) {
 
 void Nextion::dump_config() {
   ESP_LOGCONFIG(TAG, "Nextion:");
+
 #ifdef USE_NEXTION_CONFIG_SKIP_CONNECTION_HANDSHAKE
   ESP_LOGCONFIG(TAG, "  Skip handshake: YES");
 #else  // USE_NEXTION_CONFIG_SKIP_CONNECTION_HANDSHAKE
@@ -151,19 +149,17 @@ void Nextion::dump_config() {
 #ifdef USE_NEXTION_CONFIG_EXIT_REPARSE_ON_START
                 "  Exit reparse:   YES\n"
 #endif  // USE_NEXTION_CONFIG_EXIT_REPARSE_ON_START
-                "  Wake On Touch:  %s",
+                "  Wake On Touch:  %s\n"
+                "  Touch Timeout:  %" PRIu16,
                 this->device_model_.c_str(), this->firmware_version_.c_str(), this->serial_number_.c_str(),
-                this->flash_size_.c_str(), YESNO(this->auto_wake_on_touch_));
+                this->flash_size_.c_str(), YESNO(this->connection_state_.auto_wake_on_touch_),
+                this->touch_sleep_timeout_);
 #endif  // USE_NEXTION_CONFIG_SKIP_CONNECTION_HANDSHAKE
 
 #ifdef USE_NEXTION_MAX_COMMANDS_PER_LOOP
   ESP_LOGCONFIG(TAG, "  Max commands per loop: %u", this->max_commands_per_loop_);
 #endif  // USE_NEXTION_MAX_COMMANDS_PER_LOOP
 
-  if (this->touch_sleep_timeout_ != 0) {
-    ESP_LOGCONFIG(TAG, "  Touch Timeout:  %" PRIu16, this->touch_sleep_timeout_);
-  }
-
   if (this->wake_up_page_ != 255) {
     ESP_LOGCONFIG(TAG, "  Wake Up Page:   %u", this->wake_up_page_);
   }
@@ -311,6 +307,10 @@ void Nextion::loop() {
       this->set_wake_up_page(this->wake_up_page_);
     }
 
+    if (this->touch_sleep_timeout_ != 0) {
+      this->set_touch_sleep_timeout(this->touch_sleep_timeout_);
+    }
+
     this->connection_state_.ignore_is_setup_ = false;
   }
 

esphome/components/nextion/nextion.h

@@ -1164,18 +1164,39 @@ class Nextion : public NextionBase, public PollingComponent, public uart::UARTDe
   void update_components_by_prefix(const std::string &prefix);
 
   /**
-   * Set the touch sleep timeout of the display.
-   * @param timeout Timeout in seconds.
+   * Set the touch sleep timeout of the display using the `thsp` command.
+   *
+   * Sets internal No-touch-then-sleep timer to specified value in seconds.
+   * Nextion will auto-enter sleep mode if and when this timer expires.
+   *
+   * @param touch_sleep_timeout Timeout in seconds.
+   *                           Range: 3 to 65535 seconds (minimum 3 seconds, maximum ~18 hours 12 minutes 15 seconds)
+   *                           Use 0 to disable touch sleep timeout.
+   *
+   * @note Once `thsp` is set, it will persist until reboot or reset. The Nextion device
+   *       needs to exit sleep mode to issue `thsp=0` to disable sleep on no touch.
+   *
+   * @note The display will only wake up by a restart or by setting up `thup` (auto wake on touch).
+   *       See set_auto_wake_on_touch() to configure wake behavior.
    *
    * Example:
    * ```cpp
+   * // Set 30 second touch timeout
    * it.set_touch_sleep_timeout(30);
+   *
+   * // Set maximum timeout (~18 hours)
+   * it.set_touch_sleep_timeout(65535);
+   *
+   * // Disable touch sleep timeout
+   * it.set_touch_sleep_timeout(0);
    * ```
    *
-   * After 30 seconds the display will go to sleep. Note: the display will only wakeup by a restart or by setting up
-   * `thup`.
+   * Related Nextion instruction: `thsp=<value>`
+   *
+   * @see set_auto_wake_on_touch() Configure automatic wake on touch
+   * @see sleep() Manually control sleep state
    */
-  void set_touch_sleep_timeout(uint16_t touch_sleep_timeout);
+  void set_touch_sleep_timeout(uint16_t touch_sleep_timeout = 0);
 
   /**
    * Sets which page Nextion loads when exiting sleep mode. Note this can be set even when Nextion is in sleep mode.

esphome/components/nextion/nextion_commands.cpp

@@ -15,14 +15,15 @@ void Nextion::set_wake_up_page(uint8_t wake_up_page) {
   this->add_no_result_to_queue_with_set_internal_("wake_up_page", "wup", wake_up_page, true);
 }
 
-void Nextion::set_touch_sleep_timeout(uint16_t touch_sleep_timeout) {
-  if (touch_sleep_timeout < 3) {
-    ESP_LOGD(TAG, "Sleep timeout out of bounds (3-65535)");
-    return;
+void Nextion::set_touch_sleep_timeout(const uint16_t touch_sleep_timeout) {
+  // Validate range: Nextion thsp command requires min 3, max 65535 seconds (0 disables)
+  if (touch_sleep_timeout != 0 && touch_sleep_timeout < 3) {
+    this->touch_sleep_timeout_ = 3;  // Auto-correct to minimum valid value
+  } else {
+    this->touch_sleep_timeout_ = touch_sleep_timeout;
   }
 
-  this->touch_sleep_timeout_ = touch_sleep_timeout;
-  this->add_no_result_to_queue_with_set_internal_("touch_sleep_timeout", "thsp", touch_sleep_timeout, true);
+  this->add_no_result_to_queue_with_set_internal_("touch_sleep_timeout", "thsp", this->touch_sleep_timeout_, true);
 }
 
 void Nextion::sleep(bool sleep) {