esphome 2024.12.4__py3-none-any.whl → 2025.2.0b1__py3-none-any.whl

esphome/components/mixer/speaker/mixer_speaker.h

@@ -0,0 +1,207 @@
+#pragma once
+
+#ifdef USE_ESP32
+
+#include "esphome/components/audio/audio.h"
+#include "esphome/components/audio/audio_transfer_buffer.h"
+#include "esphome/components/speaker/speaker.h"
+
+#include "esphome/core/component.h"
+
+#include <freertos/event_groups.h>
+#include <freertos/FreeRTOS.h>
+
+namespace esphome {
+namespace mixer_speaker {
+
+/* Classes for mixing several source speaker audio streams and writing it to another speaker component.
+ *  - Volume controls are passed through to the output speaker
+ *  - Directly handles pausing at the SourceSpeaker level; pause state is not passed through to the output speaker.
+ *  - Audio sent to the SourceSpeaker's must have 16 bits per sample.
+ *  - Audio sent to the SourceSpeaker can have any number of channels. They are duplicated or ignored as needed to match
+ *    the number of channels required for the output speaker.
+ *  - In queue mode, the audio sent to the SoureSpeakers can have different sample rates.
+ *  - In non-queue mode, the audio sent to the SourceSpeakers must have the same sample rates.
+ *  - SourceSpeaker has an internal ring buffer. It also allocates a shared_ptr for an AudioTranserBuffer object.
+ *  - Audio Data Flow:
+ *      - Audio data played on a SourceSpeaker first writes to its internal ring buffer.
+ *      - MixerSpeaker task temporarily takes shared ownership of each SourceSpeaker's AudioTransferBuffer.
+ *      - MixerSpeaker calls SourceSpeaker's `process_data_from_source`, which tranfers audio from the SourceSpeaker's
+ *        ring buffer to its AudioTransferBuffer. Audio ducking is applied at this step.
+ *      - In queue mode, MixerSpeaker prioritizes the earliest configured SourceSpeaker with audio data. Audio data is
+ *        sent to the output speaker.
+ *      - In non-queue mode, MixerSpeaker adds all the audio data in each SourceSpeaker into one stream that is written
+ *        to the output speaker.
+ */
+
+class MixerSpeaker;
+
+class SourceSpeaker : public speaker::Speaker, public Component {
+ public:
+  void dump_config() override;
+  void setup() override;
+  void loop() override;
+
+  size_t play(const uint8_t *data, size_t length, TickType_t ticks_to_wait) override;
+  size_t play(const uint8_t *data, size_t length) override { return this->play(data, length, 0); }
+
+  void start() override;
+  void stop() override;
+  void finish() override;
+
+  bool has_buffered_data() const override;
+
+  /// @brief Mute state changes are passed to the parent's output speaker
+  void set_mute_state(bool mute_state) override;
+
+  /// @brief Volume state changes are passed to the parent's output speaker
+  void set_volume(float volume) override;
+
+  void set_pause_state(bool pause_state) override { this->pause_state_ = pause_state; }
+  bool get_pause_state() const override { return this->pause_state_; }
+
+  /// @brief Transfers audio from the ring buffer into the transfer buffer. Ducks audio while transferring.
+  /// @param ticks_to_wait FreeRTOS ticks to wait while waiting to read from the ring buffer.
+  /// @return Number of bytes transferred from the ring buffer.
+  size_t process_data_from_source(TickType_t ticks_to_wait);
+
+  /// @brief Sets the ducking level for the source speaker.
+  /// @param decibel_reduction (uint8_t) The dB reduction level. For example, 0 is no change, 10 is a reduction by 10 dB
+  /// @param duration (uint32_t) The number of milliseconds to transition from the current level to the new level
+  void apply_ducking(uint8_t decibel_reduction, uint32_t duration);
+
+  void set_buffer_duration(uint32_t buffer_duration_ms) { this->buffer_duration_ms_ = buffer_duration_ms; }
+  void set_parent(MixerSpeaker *parent) { this->parent_ = parent; }
+  void set_timeout(uint32_t ms) { this->timeout_ms_ = ms; }
+
+  std::weak_ptr<audio::AudioSourceTransferBuffer> get_transfer_buffer() { return this->transfer_buffer_; }
+
+ protected:
+  friend class MixerSpeaker;
+  esp_err_t start_();
+  void stop_();
+
+  /// @brief Ducks audio samples by a specified amount. When changing the ducking amount, it can transition gradually
+  /// over a specified amount of samples.
+  /// @param input_buffer buffer with audio samples to be ducked in place
+  /// @param input_samples_to_duck number of samples to process in ``input_buffer``
+  /// @param current_ducking_db_reduction pointer to the current dB reduction
+  /// @param ducking_transition_samples_remaining pointer to the total number of samples left before the the
+  ///         transition is finished
+  /// @param samples_per_ducking_step total number of samples per ducking step for the transition
+  /// @param db_change_per_ducking_step the change in dB reduction per step
+  static void duck_samples(int16_t *input_buffer, uint32_t input_samples_to_duck, int8_t *current_ducking_db_reduction,
+                           uint32_t *ducking_transition_samples_remaining, uint32_t samples_per_ducking_step,
+                           int8_t db_change_per_ducking_step);
+
+  MixerSpeaker *parent_;
+
+  std::shared_ptr<audio::AudioSourceTransferBuffer> transfer_buffer_;
+  std::weak_ptr<RingBuffer> ring_buffer_;
+
+  uint32_t buffer_duration_ms_;
+  uint32_t last_seen_data_ms_{0};
+  optional<uint32_t> timeout_ms_;
+  bool stop_gracefully_{false};
+
+  bool pause_state_{false};
+
+  int8_t target_ducking_db_reduction_{0};
+  int8_t current_ducking_db_reduction_{0};
+  int8_t db_change_per_ducking_step_{1};
+  uint32_t ducking_transition_samples_remaining_{0};
+  uint32_t samples_per_ducking_step_{0};
+
+  uint32_t accumulated_frames_read_{0};
+
+  uint32_t pending_playback_ms_{0};
+};
+
+class MixerSpeaker : public Component {
+ public:
+  void dump_config() override;
+  void setup() override;
+  void loop() override;
+
+  void add_source_speaker(SourceSpeaker *source_speaker) { this->source_speakers_.push_back(source_speaker); }
+
+  /// @brief Starts the mixer task. Called by a source speaker giving the current audio stream information
+  /// @param stream_info The calling source speakers audio stream information
+  /// @return ESP_ERR_NOT_SUPPORTED if the incoming stream is incompatible due to unsupported bits per sample
+  ///         ESP_ERR_INVALID_ARG if the incoming stream is incompatible to be mixed with the other input audio stream
+  ///         ESP_ERR_NO_MEM if there isn't enough memory for the task's stack
+  ///         ESP_ERR_INVALID_STATE if the task fails to start
+  ///         ESP_OK if the incoming stream is compatible and the mixer task starts
+  esp_err_t start(audio::AudioStreamInfo &stream_info);
+
+  void stop();
+
+  void set_output_channels(uint8_t output_channels) { this->output_channels_ = output_channels; }
+  void set_output_speaker(speaker::Speaker *speaker) { this->output_speaker_ = speaker; }
+  void set_queue_mode(bool queue_mode) { this->queue_mode_ = queue_mode; }
+  void set_task_stack_in_psram(bool task_stack_in_psram) { this->task_stack_in_psram_ = task_stack_in_psram; }
+
+  speaker::Speaker *get_output_speaker() const { return this->output_speaker_; }
+
+ protected:
+  /// @brief Copies audio frames from the input buffer to the output buffer taking into account the number of channels
+  /// in each stream. If the output stream has more channels, the input samples are duplicated. If the output stream has
+  /// less channels, the extra channel input samples are dropped.
+  /// @param input_buffer
+  /// @param input_stream_info
+  /// @param output_buffer
+  /// @param output_stream_info
+  /// @param frames_to_transfer number of frames (consisting of a sample for each channel) to copy from the input buffer
+  static void copy_frames(const int16_t *input_buffer, audio::AudioStreamInfo input_stream_info, int16_t *output_buffer,
+                          audio::AudioStreamInfo output_stream_info, uint32_t frames_to_transfer);
+
+  /// @brief Mixes the primary and secondary streams taking into account the number of channels in each stream. Primary
+  /// and secondary samples are duplicated or dropped as necessary to ensure the output stream has the configured number
+  /// of channels. Output samples are clamped to the corresponding int16 min or max values if the mixed sample
+  /// overflows.
+  /// @param primary_buffer (int16_t *) samples buffer for the primary stream
+  /// @param primary_stream_info stream info for the primary stream
+  /// @param secondary_buffer (int16_t *) samples buffer for secondary stream
+  /// @param secondary_stream_info stream info for the secondary stream
+  /// @param output_buffer (int16_t *) buffer for the mixed samples
+  /// @param output_stream_info stream info for the output buffer
+  /// @param frames_to_mix number of frames in the primary and secondary buffers to mix together
+  static void mix_audio_samples(const int16_t *primary_buffer, audio::AudioStreamInfo primary_stream_info,
+                                const int16_t *secondary_buffer, audio::AudioStreamInfo secondary_stream_info,
+                                int16_t *output_buffer, audio::AudioStreamInfo output_stream_info,
+                                uint32_t frames_to_mix);
+
+  static void audio_mixer_task(void *params);
+
+  /// @brief Starts the mixer task after allocating memory for the task stack.
+  /// @return ESP_ERR_NO_MEM if there isn't enough memory for the task's stack
+  ///         ESP_ERR_INVALID_STATE if the task didn't start
+  ///         ESP_OK if successful
+  esp_err_t start_task_();
+
+  /// @brief If the task is stopped, it sets the task handle to the nullptr and deallocates its stack
+  /// @return ESP_OK if the task was stopped, ESP_ERR_INVALID_STATE otherwise.
+  esp_err_t delete_task_();
+
+  EventGroupHandle_t event_group_{nullptr};
+
+  std::vector<SourceSpeaker *> source_speakers_;
+  speaker::Speaker *output_speaker_{nullptr};
+
+  uint8_t output_channels_;
+  bool queue_mode_;
+  bool task_stack_in_psram_{false};
+
+  bool task_created_{false};
+
+  TaskHandle_t task_handle_{nullptr};
+  StaticTask_t task_stack_;
+  StackType_t *task_stack_buffer_{nullptr};
+
+  optional<audio::AudioStreamInfo> audio_stream_info_;
+};
+
+}  // namespace mixer_speaker
+}  // namespace esphome
+
+#endif

esphome/components/mpr121/mpr121.h

@@ -117,6 +117,8 @@ class MPR121GPIOPin : public GPIOPin {
   void set_inverted(bool inverted) { this->inverted_ = inverted; }
   void set_flags(gpio::Flags flags) { this->flags_ = flags; }
 
+  gpio::Flags get_flags() const override { return this->flags_; }
+
  protected:
   MPR121Component *parent_;
   uint8_t pin_;

esphome/components/mqtt/__init__.py

@@ -373,7 +373,7 @@ async def to_code(config):
             )
         )
 
-    cg.add(var.set_topic_prefix(config[CONF_TOPIC_PREFIX]))
+    cg.add(var.set_topic_prefix(config[CONF_TOPIC_PREFIX], CORE.name))
 
     if config[CONF_USE_ABBREVIATIONS]:
         cg.add_define("USE_MQTT_ABBREVIATIONS")

esphome/components/mqtt/mqtt_client.cpp

@@ -606,7 +606,13 @@ void MQTTClientComponent::set_log_level(int level) { this->log_level_ = level; }
 void MQTTClientComponent::set_keep_alive(uint16_t keep_alive_s) { this->mqtt_backend_.set_keep_alive(keep_alive_s); }
 void MQTTClientComponent::set_log_message_template(MQTTMessage &&message) { this->log_message_ = std::move(message); }
 const MQTTDiscoveryInfo &MQTTClientComponent::get_discovery_info() const { return this->discovery_info_; }
-void MQTTClientComponent::set_topic_prefix(const std::string &topic_prefix) { this->topic_prefix_ = topic_prefix; }
+void MQTTClientComponent::set_topic_prefix(const std::string &topic_prefix, const std::string &check_topic_prefix) {
+  if (App.is_name_add_mac_suffix_enabled() && (topic_prefix == check_topic_prefix)) {
+    this->topic_prefix_ = str_sanitize(App.get_name());
+  } else {
+    this->topic_prefix_ = topic_prefix;
+  }
+}
 const std::string &MQTTClientComponent::get_topic_prefix() const { return this->topic_prefix_; }
 void MQTTClientComponent::set_publish_nan_as_none(bool publish_nan_as_none) {
   this->publish_nan_as_none_ = publish_nan_as_none;

esphome/components/mqtt/mqtt_client.h

@@ -165,7 +165,7 @@ class MQTTClientComponent : public Component {
    *
    * @param topic_prefix The topic prefix. The last "/" is appended automatically.
    */
-  void set_topic_prefix(const std::string &topic_prefix);
+  void set_topic_prefix(const std::string &topic_prefix, const std::string &check_topic_prefix);
   /// Get the topic prefix of this device, using default if necessary
   const std::string &get_topic_prefix() const;
 

esphome/components/mqtt/mqtt_climate.cpp

@@ -72,9 +72,9 @@ void MQTTClimateComponent::send_discovery(JsonObject root, mqtt::SendDiscoveryCo
   // max_temp
   root[MQTT_MAX_TEMP] = traits.get_visual_max_temperature();
   // target_temp_step
-  root[MQTT_TARGET_TEMPERATURE_STEP] = traits.get_visual_target_temperature_step();
+  root[MQTT_TARGET_TEMPERATURE_STEP] = roundf(traits.get_visual_target_temperature_step() * 10) * 0.1;
   // current_temp_step
-  root[MQTT_CURRENT_TEMPERATURE_STEP] = traits.get_visual_current_temperature_step();
+  root[MQTT_CURRENT_TEMPERATURE_STEP] = roundf(traits.get_visual_current_temperature_step() * 10) * 0.1;
   // temperature units are always coerced to Celsius internally
   root[MQTT_TEMPERATURE_UNIT] = "C";
 

esphome/components/network/ip_address.h

@@ -49,6 +49,7 @@ struct IPAddress {
   }
   IPAddress(const std::string &in_address) { inet_aton(in_address.c_str(), &ip_addr_); }
   IPAddress(const ip_addr_t *other_ip) { ip_addr_ = *other_ip; }
+  std::string str() const { return str_lower_case(inet_ntoa(ip_addr_)); }
 #else
   IPAddress() { ip_addr_set_zero(&ip_addr_); }
   IPAddress(uint8_t first, uint8_t second, uint8_t third, uint8_t fourth) {
@@ -119,6 +120,7 @@ struct IPAddress {
   bool is_set() { return !ip_addr_isany(&ip_addr_); }  // NOLINT(readability-simplify-boolean-expr)
   bool is_ip4() { return IP_IS_V4(&ip_addr_); }
   bool is_ip6() { return IP_IS_V6(&ip_addr_); }
+  bool is_multicast() { return ip_addr_ismulticast(&ip_addr_); }
   std::string str() const { return str_lower_case(ipaddr_ntoa(&ip_addr_)); }
   bool operator==(const IPAddress &other) const { return ip_addr_cmp(&ip_addr_, &other.ip_addr_); }
   bool operator!=(const IPAddress &other) const { return !ip_addr_cmp(&ip_addr_, &other.ip_addr_); }

esphome/components/nextion/automation.h

@@ -49,6 +49,23 @@ class TouchTrigger : public Trigger<uint8_t, uint8_t, bool> {
   }
 };
 
+template<typename... Ts> class NextionSetBrightnessAction : public Action<Ts...> {
+ public:
+  explicit NextionSetBrightnessAction(Nextion *component) : component_(component) {}
+
+  TEMPLATABLE_VALUE(float, brightness)
+
+  void play(Ts... x) override {
+    this->component_->set_brightness(this->brightness_.value(x...));
+    this->component_->set_backlight_brightness(this->brightness_.value(x...));
+  }
+
+  void set_brightness(std::function<void(Ts..., float)> brightness) { this->brightness_ = brightness; }
+
+ protected:
+  Nextion *component_;
+};
+
 template<typename... Ts> class NextionPublishFloatAction : public Action<Ts...> {
  public:
   explicit NextionPublishFloatAction(NextionComponent *component) : component_(component) {}

esphome/components/nextion/display.py

@@ -1,30 +1,30 @@
+from esphome import automation
 import esphome.codegen as cg
+from esphome.components import display, esp32, uart
 import esphome.config_validation as cv
-from esphome import automation
-from esphome.components import display, uart
-from esphome.components import esp32
 from esphome.const import (
+    CONF_BRIGHTNESS,
     CONF_ID,
     CONF_LAMBDA,
-    CONF_BRIGHTNESS,
-    CONF_TRIGGER_ID,
     CONF_ON_TOUCH,
+    CONF_TRIGGER_ID,
 )
 from esphome.core import CORE
+
 from . import Nextion, nextion_ns, nextion_ref
 from .base_component import (
+    CONF_AUTO_WAKE_ON_TOUCH,
+    CONF_EXIT_REPARSE_ON_START,
     CONF_ON_BUFFER_OVERFLOW,
+    CONF_ON_PAGE,
+    CONF_ON_SETUP,
     CONF_ON_SLEEP,
     CONF_ON_WAKE,
-    CONF_ON_SETUP,
-    CONF_ON_PAGE,
+    CONF_SKIP_CONNECTION_HANDSHAKE,
+    CONF_START_UP_PAGE,
     CONF_TFT_URL,
     CONF_TOUCH_SLEEP_TIMEOUT,
     CONF_WAKE_UP_PAGE,
-    CONF_START_UP_PAGE,
-    CONF_AUTO_WAKE_ON_TOUCH,
-    CONF_EXIT_REPARSE_ON_START,
-    CONF_SKIP_CONNECTION_HANDSHAKE,
 )
 
 CODEOWNERS = ["@senexcrenshaw", "@edwardtfn"]
@@ -32,6 +32,9 @@ CODEOWNERS = ["@senexcrenshaw", "@edwardtfn"]
 DEPENDENCIES = ["uart"]
 AUTO_LOAD = ["binary_sensor", "switch", "sensor", "text_sensor"]
 
+NextionSetBrightnessAction = nextion_ns.class_(
+    "NextionSetBrightnessAction", automation.Action
+)
 SetupTrigger = nextion_ns.class_("SetupTrigger", automation.Trigger.template())
 SleepTrigger = nextion_ns.class_("SleepTrigger", automation.Trigger.template())
 WakeTrigger = nextion_ns.class_("WakeTrigger", automation.Trigger.template())
@@ -46,7 +49,7 @@ CONFIG_SCHEMA = (
         {
             cv.GenerateID(): cv.declare_id(Nextion),
             cv.Optional(CONF_TFT_URL): cv.url,
-            cv.Optional(CONF_BRIGHTNESS, default=1.0): cv.percentage,
+            cv.Optional(CONF_BRIGHTNESS): cv.percentage,
             cv.Optional(CONF_ON_SETUP): automation.validate_automation(
                 {
                     cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(SetupTrigger),
@@ -92,12 +95,34 @@ CONFIG_SCHEMA = (
 )
 
 
+@automation.register_action(
+    "display.nextion.set_brightness",
+    NextionSetBrightnessAction,
+    cv.maybe_simple_value(
+        {
+            cv.GenerateID(): cv.use_id(Nextion),
+            cv.Required(CONF_BRIGHTNESS): cv.templatable(cv.percentage),
+        },
+        key=CONF_BRIGHTNESS,
+    ),
+)
+async def nextion_set_brightness_to_code(config, action_id, template_arg, args):
+    paren = await cg.get_variable(config[CONF_ID])
+    var = cg.new_Pvariable(action_id, template_arg, paren)
+
+    template_ = await cg.templatable(config[CONF_BRIGHTNESS], args, float)
+    cg.add(var.set_brightness(template_))
+
+    return var
+
+
 async def to_code(config):
     var = cg.new_Pvariable(config[CONF_ID])
     await uart.register_uart_device(var, config)
 
     if CONF_BRIGHTNESS in config:
         cg.add(var.set_brightness(config[CONF_BRIGHTNESS]))
+
     if CONF_LAMBDA in config:
         lambda_ = await cg.process_lambda(
             config[CONF_LAMBDA], [(nextion_ref, "it")], return_type=cg.void
@@ -119,17 +144,17 @@ async def to_code(config):
             cg.add_library("ESP8266HTTPClient", None)
 
     if CONF_TOUCH_SLEEP_TIMEOUT in config:
-        cg.add(var.set_touch_sleep_timeout_internal(config[CONF_TOUCH_SLEEP_TIMEOUT]))
+        cg.add(var.set_touch_sleep_timeout(config[CONF_TOUCH_SLEEP_TIMEOUT]))
 
     if CONF_WAKE_UP_PAGE in config:
-        cg.add(var.set_wake_up_page_internal(config[CONF_WAKE_UP_PAGE]))
+        cg.add(var.set_wake_up_page(config[CONF_WAKE_UP_PAGE]))
 
     if CONF_START_UP_PAGE in config:
-        cg.add(var.set_start_up_page_internal(config[CONF_START_UP_PAGE]))
+        cg.add(var.set_start_up_page(config[CONF_START_UP_PAGE]))
 
-    cg.add(var.set_auto_wake_on_touch_internal(config[CONF_AUTO_WAKE_ON_TOUCH]))
+    cg.add(var.set_auto_wake_on_touch(config[CONF_AUTO_WAKE_ON_TOUCH]))
 
-    cg.add(var.set_exit_reparse_on_start_internal(config[CONF_EXIT_REPARSE_ON_START]))
+    cg.add(var.set_exit_reparse_on_start(config[CONF_EXIT_REPARSE_ON_START]))
 
     cg.add(var.set_skip_connection_handshake(config[CONF_SKIP_CONNECTION_HANDSHAKE]))
 

esphome/components/nextion/nextion.cpp

@@ -40,7 +40,7 @@ bool Nextion::send_command_(const std::string &command) {
 }
 
 bool Nextion::check_connect_() {
-  if (this->get_is_connected_())
+  if (this->is_connected_)
     return true;
 
   // Check if the handshake should be skipped for the Nextion connection
@@ -273,21 +273,15 @@ void Nextion::loop() {
     this->sent_setup_commands_ = true;
     this->send_command_("bkcmd=3");  // Always, returns 0x00 to 0x23 result of serial command.
 
-    this->set_backlight_brightness(this->brightness_);
+    if (this->brightness_.has_value()) {
+      this->set_backlight_brightness(this->brightness_.value());
+    }
 
     // Check if a startup page has been set and send the command
     if (this->start_up_page_ != -1) {
       this->goto_page(this->start_up_page_);
     }
 
-    // This could probably be removed from the loop area, as those are redundant.
-    this->set_auto_wake_on_touch(this->auto_wake_on_touch_);
-    this->set_exit_reparse_on_start(this->exit_reparse_on_start_);
-
-    if (this->touch_sleep_timeout_ != 0) {
-      this->set_touch_sleep_timeout(this->touch_sleep_timeout_);
-    }
-
     if (this->wake_up_page_ != -1) {
       this->set_wake_up_page(this->wake_up_page_);
     }

esphome/components/nextion/nextion.h

@@ -856,76 +856,6 @@ class Nextion : public NextionBase, public PollingComponent, public uart::UARTDe
    */
   void set_backlight_brightness(float brightness);
 
-  /**
-   * Set the touch sleep timeout of the display.
-   * @param timeout Timeout in seconds.
-   *
-   * Example:
-   * ```cpp
-   * it.set_touch_sleep_timeout(30);
-   * ```
-   *
-   * After 30 seconds the display will go to sleep. Note: the display will only wakeup by a restart or by setting up
-   * `thup`.
-   */
-  void set_touch_sleep_timeout(uint16_t timeout);
-
-  /**
-   * Sets which page Nextion loads when exiting sleep mode. Note this can be set even when Nextion is in sleep mode.
-   * @param page_id The page id, from 0 to the lage page in Nextion. Set 255 (not set to any existing page) to
-   * wakes up to current page.
-   *
-   * Example:
-   * ```cpp
-   * it.set_wake_up_page(2);
-   * ```
-   *
-   * The display will wake up to page 2.
-   */
-  void set_wake_up_page(uint8_t page_id = 255);
-
-  /**
-   * Sets which page Nextion loads when connecting to ESPHome.
-   * @param page_id The page id, from 0 to the lage page in Nextion. Set 255 (not set to any existing page) to
-   * wakes up to current page.
-   *
-   * Example:
-   * ```cpp
-   * it.set_start_up_page(2);
-   * ```
-   *
-   * The display will go to page 2 when it establishes a connection to ESPHome.
-   */
-  void set_start_up_page(uint8_t page_id = 255);
-
-  /**
-   * Sets if Nextion should auto-wake from sleep when touch press occurs.
-   * @param auto_wake True or false. When auto_wake is true and Nextion is in sleep mode,
-   * the first touch will only trigger the auto wake mode and not trigger a Touch Event.
-   *
-   * Example:
-   * ```cpp
-   * it.set_auto_wake_on_touch(true);
-   * ```
-   *
-   * The display will wake up by touch.
-   */
-  void set_auto_wake_on_touch(bool auto_wake);
-
-  /**
-   * Sets if Nextion should exit the active reparse mode before the "connect" command is sent
-   * @param exit_reparse True or false. When exit_reparse is true, the exit reparse command
-   * will be sent before requesting the connection from Nextion.
-   *
-   * Example:
-   * ```cpp
-   * it.set_exit_reparse_on_start(true);
-   * ```
-   *
-   * The display will be requested to leave active reparse mode before setup.
-   */
-  void set_exit_reparse_on_start(bool exit_reparse);
-
   /**
    * Sets whether the Nextion display should skip the connection handshake process.
    * @param skip_handshake True or false. When skip_connection_handshake is true,
@@ -1172,15 +1102,75 @@ class Nextion : public NextionBase, public PollingComponent, public uart::UARTDe
 
   void update_components_by_prefix(const std::string &prefix);
 
-  void set_touch_sleep_timeout_internal(uint32_t touch_sleep_timeout) {
-    this->touch_sleep_timeout_ = touch_sleep_timeout;
-  }
-  void set_wake_up_page_internal(uint8_t wake_up_page) { this->wake_up_page_ = wake_up_page; }
-  void set_start_up_page_internal(uint8_t start_up_page) { this->start_up_page_ = start_up_page; }
-  void set_auto_wake_on_touch_internal(bool auto_wake_on_touch) { this->auto_wake_on_touch_ = auto_wake_on_touch; }
-  void set_exit_reparse_on_start_internal(bool exit_reparse_on_start) {
-    this->exit_reparse_on_start_ = exit_reparse_on_start;
-  }
+  /**
+   * Set the touch sleep timeout of the display.
+   * @param timeout Timeout in seconds.
+   *
+   * Example:
+   * ```cpp
+   * it.set_touch_sleep_timeout(30);
+   * ```
+   *
+   * After 30 seconds the display will go to sleep. Note: the display will only wakeup by a restart or by setting up
+   * `thup`.
+   */
+  void set_touch_sleep_timeout(uint32_t touch_sleep_timeout);
+
+  /**
+   * Sets which page Nextion loads when exiting sleep mode. Note this can be set even when Nextion is in sleep mode.
+   * @param wake_up_page The page id, from 0 to the lage page in Nextion. Set 255 (not set to any existing page) to
+   * wakes up to current page.
+   *
+   * Example:
+   * ```cpp
+   * it.set_wake_up_page(2);
+   * ```
+   *
+   * The display will wake up to page 2.
+   */
+  void set_wake_up_page(uint8_t wake_up_page = 255);
+
+  /**
+   * Sets which page Nextion loads when connecting to ESPHome.
+   * @param start_up_page The page id, from 0 to the lage page in Nextion. Set 255 (not set to any existing page) to
+   * wakes up to current page.
+   *
+   * Example:
+   * ```cpp
+   * it.set_start_up_page(2);
+   * ```
+   *
+   * The display will go to page 2 when it establishes a connection to ESPHome.
+   */
+  void set_start_up_page(uint8_t start_up_page = 255) { this->start_up_page_ = start_up_page; }
+
+  /**
+   * Sets if Nextion should auto-wake from sleep when touch press occurs.
+   * @param auto_wake_on_touch True or false. When auto_wake is true and Nextion is in sleep mode,
+   * the first touch will only trigger the auto wake mode and not trigger a Touch Event.
+   *
+   * Example:
+   * ```cpp
+   * it.set_auto_wake_on_touch(true);
+   * ```
+   *
+   * The display will wake up by touch.
+   */
+  void set_auto_wake_on_touch(bool auto_wake_on_touch);
+
+  /**
+   * Sets if Nextion should exit the active reparse mode before the "connect" command is sent
+   * @param exit_reparse_on_start True or false. When exit_reparse_on_start is true, the exit reparse command
+   * will be sent before requesting the connection from Nextion.
+   *
+   * Example:
+   * ```cpp
+   * it.set_exit_reparse_on_start(true);
+   * ```
+   *
+   * The display will be requested to leave active reparse mode before setup.
+   */
+  void set_exit_reparse_on_start(bool exit_reparse_on_start) { this->exit_reparse_on_start_ = exit_reparse_on_start; }
 
   /**
    * @brief Retrieves the number of commands pending in the Nextion command queue.
@@ -1217,6 +1207,25 @@ class Nextion : public NextionBase, public PollingComponent, public uart::UARTDe
    */
   bool is_updating() override;
 
+  /**
+   * @brief Check if the Nextion display is successfully connected.
+   *
+   * This method returns whether a successful connection has been established with
+   * the Nextion display. A connection is considered established when:
+   *
+   * - The initial handshake with the display is completed successfully, or
+   * - The handshake is skipped via skip_connection_handshake_ flag
+   *
+   * The connection status is particularly useful when:
+   * - Troubleshooting communication issues
+   * - Ensuring the display is ready before sending commands
+   * - Implementing connection-dependent behaviors
+   *
+   * @return true if the Nextion display is connected and ready to receive commands
+   * @return false if the display is not yet connected or connection was lost
+   */
+  bool is_connected() { return this->is_connected_; }
+
  protected:
   std::deque<NextionQueue *> nextion_queue_;
   std::deque<NextionQueue *> waveform_queue_;
@@ -1315,8 +1324,6 @@ class Nextion : public NextionBase, public PollingComponent, public uart::UARTDe
 
 #endif  // USE_NEXTION_TFT_UPLOAD
 
-  bool get_is_connected_() { return this->is_connected_; }
-
   bool check_connect_();
 
   std::vector<NextionComponentBase *> touch_;
@@ -1332,7 +1339,7 @@ class Nextion : public NextionBase, public PollingComponent, public uart::UARTDe
   CallbackManager<void()> buffer_overflow_callback_{};
 
   optional<nextion_writer_t> writer_;
-  float brightness_{1.0};
+  optional<float> brightness_;
 
   std::string device_model_;
   std::string firmware_version_;