nextion.h

Go to the documentation of this file.

#pragma once
 
#include <list>
#include <vector>
 
#include "esphome/components/display/display.h"
#include "esphome/components/display/display_color_utils.h"
#include "esphome/components/uart/uart.h"
#include "esphome/core/defines.h"
#include "esphome/core/string_ref.h"
#include "esphome/core/time.h"
 
#ifdef USE_NEXTION_WAVEFORM
#include "esphome/core/helpers.h"
#endif  // USE_NEXTION_WAVEFORM
 
#include "nextion_base.h"
#include "nextion_component.h"
 
#ifdef USE_NEXTION_TFT_UPLOAD
#ifdef USE_ESP32
#include <esp_http_client.h>
#elif defined(USE_ESP8266)
#include <ESP8266HTTPClient.h>
#include <WiFiClientSecure.h>
#elif defined(USE_LIBRETINY)
#include <HTTPClient.h>
#endif  // USE_ESP32 vs USE_ESP8266 vs USE_LIBRETINY
#endif  // USE_NEXTION_TFT_UPLOAD
 
namespace esphome::nextion {
 
class Nextion;
class NextionComponentBase;
 
using nextion_writer_t = display::DisplayWriter<Nextion>;
 
#ifdef USE_NEXTION_COMMAND_SPACING
class NextionCommandPacer {
 public:
  explicit NextionCommandPacer(uint8_t initial_spacing = 0) : spacing_ms_(initial_spacing) {}
 
  void set_spacing(uint8_t spacing_ms) { spacing_ms_ = spacing_ms; }
 
  uint8_t get_spacing() const { return spacing_ms_; }
 
  bool can_send(uint32_t now) const { return (now - last_command_time_) >= spacing_ms_; }
 
  void mark_sent(uint32_t now) { last_command_time_ = now; }
 
 private:
  uint8_t spacing_ms_;
  uint32_t last_command_time_{0};
};
#endif  // USE_NEXTION_COMMAND_SPACING
 
class Nextion final : public NextionBase, public PollingComponent, public uart::UARTDevice {
 public:
#ifdef USE_NEXTION_MAX_COMMANDS_PER_LOOP
  inline void set_max_commands_per_loop(uint16_t value) { this->max_commands_per_loop_ = value; }
 
  inline uint16_t get_max_commands_per_loop() const { return this->max_commands_per_loop_; }
#endif  // USE_NEXTION_MAX_COMMANDS_PER_LOOP
#ifdef USE_NEXTION_MAX_QUEUE_SIZE
  inline void set_max_queue_size(size_t size) { this->max_queue_size_ = size; }
 
  inline size_t get_max_queue_size() const { return this->max_queue_size_; }
#endif  // USE_NEXTION_MAX_QUEUE_SIZE
 
#ifdef USE_NEXTION_COMMAND_SPACING
  void set_command_spacing(uint32_t spacing_ms) { this->command_pacer_.set_spacing(spacing_ms); }
#endif  // USE_NEXTION_COMMAND_SPACING
 
  void set_component_text(const char *component, const char *text);
 
  void set_component_text_printf(const char *component, const char *format, ...) __attribute__((format(printf, 3, 4)));
 
  void set_component_value(const char *component, int32_t value);
 
  void set_component_picture(const char *component, uint8_t picture_id) { set_component_picc(component, picture_id); };
 
  void set_component_background_color(const char *component, uint16_t color);
 
  void set_component_background_color(const char *component, const char *color);
 
  void set_component_background_color(const char *component, Color color) override;
 
  void set_component_pressed_background_color(const char *component, uint16_t color);
 
  void set_component_pressed_background_color(const char *component, const char *color);
 
  void set_component_pressed_background_color(const char *component, Color color) override;
 
  void set_component_foreground_color(const char *component, uint16_t color);
 
  void set_component_foreground_color(const char *component, const char *color);
 
  void set_component_foreground_color(const char *component, Color color) override;
 
  void set_component_pressed_foreground_color(const char *component, uint16_t color);
 
  void set_component_pressed_foreground_color(const char *component, const char *color);
 
  void set_component_pressed_foreground_color(const char *component, Color color) override;
 
  void set_component_pic(const char *component, uint16_t pic_id);
 
  void set_component_picc(const char *component, uint16_t pic_id);
 
  void set_component_font_color(const char *component, uint16_t color);
 
  void set_component_font_color(const char *component, const char *color);
 
  void set_component_font_color(const char *component, Color color) override;
 
  void set_component_pressed_font_color(const char *component, uint16_t color);
 
  void set_component_pressed_font_color(const char *component, const char *color);
 
  void set_component_pressed_font_color(const char *component, Color color) override;
 
  void set_component_coordinates(const char *component, uint16_t x, uint16_t y);
 
  void set_component_font(const char *component, uint8_t font_id) override;
 
  void set_nextion_rtc_time(ESPTime time);
 
  void goto_page(const char *page);
 
  void goto_page(uint8_t page);
 
  void set_component_visibility(const char *component, bool show) override;
 
  void hide_component(const char *component) override;
 
  void show_component(const char *component) override;
 
  void enable_component_touch(const char *component);
 
  void disable_component_touch(const char *component);
 
#ifdef USE_NEXTION_WAVEFORM
  void add_waveform_data(uint8_t component_id, uint8_t channel_number, uint8_t value);
 
  void open_waveform_channel(uint8_t component_id, uint8_t channel_number, uint8_t value);
#endif  // USE_NEXTION_WAVEFORM
 
  void display_picture(uint16_t picture_id, uint16_t x_start, uint16_t y_start);
 
  void fill_area(uint16_t x1, uint16_t y1, uint16_t width, uint16_t height, uint16_t color);
 
  void fill_area(uint16_t x1, uint16_t y1, uint16_t width, uint16_t height, const char *color);
 
  void fill_area(uint16_t x1, uint16_t y1, uint16_t width, uint16_t height, Color color);
 
  void line(uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2, uint16_t color);
 
  void line(uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2, const char *color);
 
  void line(uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2, Color color);
 
  void rectangle(uint16_t x1, uint16_t y1, uint16_t width, uint16_t height, uint16_t color);
 
  void rectangle(uint16_t x1, uint16_t y1, uint16_t width, uint16_t height, const char *color);
 
  void rectangle(uint16_t x1, uint16_t y1, uint16_t width, uint16_t height, Color color);
 
  void circle(uint16_t center_x, uint16_t center_y, uint16_t radius, uint16_t color);
 
  void circle(uint16_t center_x, uint16_t center_y, uint16_t radius, const char *color);
 
  void circle(uint16_t center_x, uint16_t center_y, uint16_t radius, Color color);
 
  void filled_circle(uint16_t center_x, uint16_t center_y, uint16_t radius, uint16_t color);
 
  void filled_circle(uint16_t center_x, uint16_t center_y, uint16_t radius, const char *color);
 
  void filled_circle(uint16_t center_x, uint16_t center_y, uint16_t radius, Color color);
 
  void qrcode(uint16_t x1, uint16_t y1, const char *content, uint16_t size = 200, uint16_t background_color = 65535,
              uint16_t foreground_color = 0, int32_t logo_pic = -1, uint8_t border_width = 8);
 
  void qrcode(uint16_t x1, uint16_t y1, const char *content, uint16_t size,
              Color background_color = Color(255, 255, 255), Color foreground_color = Color(0, 0, 0),
              int32_t logo_pic = -1, uint8_t border_width = 8);
 
  void set_backlight_brightness(float brightness);
 
  void sleep(bool sleep);
 
  bool set_protocol_reparse_mode(bool active_mode);
 
  // ======== Nextion Intelligent Series ========
 
  void set_component_vid(const char *component, uint8_t vid_id);
 
  void set_component_drag(const char *component, bool drag);
 
  void set_component_aph(const char *component, uint8_t aph);
 
  void set_component_position(const char *component, uint32_t x, uint32_t y);
 
  // ========== INTERNAL METHODS ==========
  // (In most use cases you won't need these)
  void register_touch_component(NextionComponentBase *obj) { this->touch_.push_back(obj); }
  void register_switch_component(NextionComponentBase *obj) { this->switchtype_.push_back(obj); }
  void register_binarysensor_component(NextionComponentBase *obj) { this->binarysensortype_.push_back(obj); }
  void register_sensor_component(NextionComponentBase *obj) { this->sensortype_.push_back(obj); }
  void register_textsensor_component(NextionComponentBase *obj) { this->textsensortype_.push_back(obj); }
 
  void setup() override;
  void set_brightness(float brightness) { this->brightness_ = brightness; }
  void update() override;
  void loop() override;
  void set_writer(const nextion_writer_t &writer);
 
  // This function has been deprecated
  void set_wait_for_ack(bool wait_for_ack);
 
  bool send_command(const char *command);
 
  bool send_command_printf(const char *format, ...) __attribute__((format(printf, 2, 3)));
 
#ifdef USE_NEXTION_TFT_UPLOAD
  void set_tft_upload_http_timeout(uint16_t timeout_ms) { this->tft_upload_http_timeout_ = timeout_ms; }
 
#ifdef USE_ESP32
  void set_tft_upload_watchdog_timeout(uint32_t timeout_ms) { this->tft_upload_watchdog_timeout_ = timeout_ms; }
#endif  // USE_ESP32
 
  void set_tft_upload_http_retries(uint8_t retries) { this->tft_upload_http_retries_ = retries; }
 
  void set_tft_url(const std::string &tft_url) { this->tft_url_ = tft_url; }
 
  bool upload_tft(uint32_t baud_rate = 0, bool exit_reparse = true);
 
#endif  // USE_NEXTION_TFT_UPLOAD
 
  void dump_config() override;
 
  void soft_reset();
 
  template<typename F> void add_sleep_state_callback(F &&callback) {
    this->sleep_callback_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_wake_state_callback(F &&callback) {
    this->wake_callback_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_setup_state_callback(F &&callback) {
    this->setup_callback_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_new_page_callback(F &&callback) { this->page_callback_.add(std::forward<F>(callback)); }
 
  template<typename F> void add_touch_event_callback(F &&callback) {
    this->touch_callback_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_buffer_overflow_event_callback(F &&callback) {
    this->buffer_overflow_callback_.add(std::forward<F>(callback));
  }
 
  // Callbacks for Nextion "custom protocol" frames (0x90..0x93)
#ifdef USE_NEXTION_TRIGGER_CUSTOM_BINARY_SENSOR
  template<typename F> void add_custom_binary_sensor_callback(F &&callback) {
    this->custom_binary_sensor_callback_.add(std::forward<F>(callback));
  }
#endif  // USE_NEXTION_TRIGGER_CUSTOM_BINARY_SENSOR
 
#ifdef USE_NEXTION_TRIGGER_CUSTOM_SENSOR
  template<typename F> void add_custom_sensor_callback(F &&callback) {
    this->custom_sensor_callback_.add(std::forward<F>(callback));
  }
#endif  // USE_NEXTION_TRIGGER_CUSTOM_SENSOR
 
#ifdef USE_NEXTION_TRIGGER_CUSTOM_SWITCH
  template<typename F> void add_custom_switch_callback(F &&callback) {
    this->custom_switch_callback_.add(std::forward<F>(callback));
  }
#endif  // USE_NEXTION_TRIGGER_CUSTOM_SWITCH
 
#ifdef USE_NEXTION_TRIGGER_CUSTOM_TEXT_SENSOR
  template<typename F> void add_custom_text_sensor_callback(F &&callback) {
    this->custom_text_sensor_callback_.add(std::forward<F>(callback));
  }
#endif  // USE_NEXTION_TRIGGER_CUSTOM_TEXT_SENSOR
 
  void update_all_components();
 
  void set_nextion_sensor_state(int queue_type, const std::string &name, float state);
  void set_nextion_sensor_state(NextionQueueType queue_type, const std::string &name, float state);
  void set_nextion_text_state(const std::string &name, const std::string &state);
 
  void add_no_result_to_queue_with_set(NextionComponentBase *component, int32_t state_value) override;
  void add_no_result_to_queue_with_set(const std::string &variable_name, const std::string &variable_name_to_send,
                                       int32_t state_value) override;
 
  void add_no_result_to_queue_with_set(NextionComponentBase *component, const std::string &state_value) override;
  void add_no_result_to_queue_with_set(const std::string &variable_name, const std::string &variable_name_to_send,
                                       const std::string &state_value) override;
 
  void add_to_get_queue(NextionComponentBase *component) override;
 
#ifdef USE_NEXTION_WAVEFORM
  void add_addt_command_to_queue(NextionComponentBase *component) override;
#endif  // USE_NEXTION_WAVEFORM
 
  void update_components_by_prefix(const std::string &prefix);
 
  void set_touch_sleep_timeout(uint16_t touch_sleep_timeout = 0);
 
  void set_wake_up_page(uint8_t wake_up_page = 255);
 
#ifdef USE_NEXTION_CONF_START_UP_PAGE
  void set_start_up_page(uint8_t start_up_page = 255) { this->start_up_page_ = start_up_page; }
#endif  // USE_NEXTION_CONF_START_UP_PAGE
 
  void set_auto_wake_on_touch(bool auto_wake_on_touch);
 
  size_t queue_size() { return this->nextion_queue_.size(); }
 
  bool is_updating() override;
 
  bool is_connected() { return this->connection_state_.is_connected_; }
 
  inline void set_max_queue_age(uint16_t age_ms) { this->max_q_age_ms_ = age_ms; }
 
  inline uint16_t get_max_queue_age() const { return this->max_q_age_ms_; }
 
  inline void set_startup_override_ms(uint16_t timeout_ms) { this->startup_override_ms_ = timeout_ms; }
 
  inline uint16_t get_startup_override_ms() const { return this->startup_override_ms_; }
 
 protected:
#ifdef USE_NEXTION_MAX_COMMANDS_PER_LOOP
  uint16_t max_commands_per_loop_{1000};
#endif  // USE_NEXTION_MAX_COMMANDS_PER_LOOP
#ifdef USE_NEXTION_MAX_QUEUE_SIZE
  size_t max_queue_size_{0};
#endif  // USE_NEXTION_MAX_QUEUE_SIZE
 
#ifdef USE_NEXTION_COMMAND_SPACING
  NextionCommandPacer command_pacer_{0};
 
  void process_pending_in_queue_();
#endif  // USE_NEXTION_COMMAND_SPACING
 
  std::list<NextionQueue *> nextion_queue_;
#ifdef USE_NEXTION_WAVEFORM
  StaticRingBuffer<NextionQueue *, 4> waveform_queue_;
#endif  // USE_NEXTION_WAVEFORM
  uint16_t recv_ret_string_(std::string &response, uint32_t timeout, bool recv_flag);
  void all_components_send_state_(bool force_update = false);
  uint32_t comok_sent_ = 0;
  bool remove_from_q_(bool report_empty = true);
 
  struct {
    uint8_t is_connected_ : 1;              
    uint8_t sent_setup_commands_ : 1;       
    uint8_t ignore_is_setup_ : 1;           
    uint8_t nextion_reports_is_setup_ : 1;  
    uint8_t is_updating_ : 1;               
    uint8_t auto_wake_on_touch_ : 1;        
    uint8_t reserved_ : 2;                  
  } connection_state_{};                    
 
  void process_nextion_commands_();
  void process_serial_();
  void purge_stale_queue_entries_();
  uint16_t touch_sleep_timeout_ = 0;
  uint8_t wake_up_page_ = 255;
#ifdef USE_NEXTION_CONF_START_UP_PAGE
  uint8_t start_up_page_ = 255;
#endif  // USE_NEXTION_CONF_START_UP_PAGE
  bool auto_wake_on_touch_ = true;
 
  bool send_command_(const std::string &command);
  void add_no_result_to_queue_(const std::string &variable_name);
  bool add_no_result_to_queue_with_ignore_sleep_printf_(const std::string &variable_name, const char *format, ...)
      __attribute__((format(printf, 3, 4)));
  void add_no_result_to_queue_with_command_(const std::string &variable_name, const std::string &command);
 
#ifdef USE_NEXTION_COMMAND_SPACING
  void add_no_result_to_queue_with_pending_command_(const std::string &variable_name, const std::string &command);
#endif  // USE_NEXTION_COMMAND_SPACING
 
  bool add_no_result_to_queue_with_printf_(const std::string &variable_name, const char *format, ...)
      __attribute__((format(printf, 3, 4)));
 
  void add_no_result_to_queue_with_set_internal_(const std::string &variable_name,
                                                 const std::string &variable_name_to_send, int32_t state_value,
                                                 bool is_sleep_safe = false);
 
  void add_no_result_to_queue_with_set_internal_(const std::string &variable_name,
                                                 const std::string &variable_name_to_send,
                                                 const std::string &state_value, bool is_sleep_safe = false);
 
#ifdef USE_NEXTION_WAVEFORM
  void check_pending_waveform_();
#endif  // USE_NEXTION_WAVEFORM
 
#ifdef USE_NEXTION_TFT_UPLOAD
#ifdef USE_ESP8266
  WiFiClient *wifi_client_{nullptr};
  BearSSL::WiFiClientSecure *wifi_client_secure_{nullptr};
  WiFiClient *get_wifi_client_();
#endif  // USE_ESP8266
  std::string tft_url_;
  uint32_t content_length_ = 0;
  int tft_size_ = 0;
  uint32_t original_baud_rate_ = 0;
  bool upload_first_chunk_sent_ = false;
  uint16_t tft_upload_http_timeout_{4500};  
  uint8_t tft_upload_http_retries_{5};      
 
#ifdef USE_ESP32
  uint32_t tft_upload_watchdog_timeout_{0};  
 
  int upload_by_chunks_(esp_http_client_handle_t http_client, uint32_t &range_start);
#elif defined(USE_ESP8266) || defined(USE_LIBRETINY)
  int upload_by_chunks_(HTTPClient &http_client, uint32_t &range_start);
#endif  // USE_ESP32 vs USE_ESP8266/USE_LIBRETINY
 
  bool upload_end_(bool successful);
 
#endif  // USE_NEXTION_TFT_UPLOAD
 
  bool check_connect_();
 
  std::vector<NextionComponentBase *> touch_;
  std::vector<NextionComponentBase *> switchtype_;
  std::vector<NextionComponentBase *> sensortype_;
  std::vector<NextionComponentBase *> textsensortype_;
  std::vector<NextionComponentBase *> binarysensortype_;
  CallbackManager<void()> setup_callback_{};
  CallbackManager<void()> sleep_callback_{};
  CallbackManager<void()> wake_callback_{};
  CallbackManager<void(uint8_t)> page_callback_{};
  CallbackManager<void(uint8_t, uint8_t, bool)> touch_callback_{};
  CallbackManager<void()> buffer_overflow_callback_{};
#ifdef USE_NEXTION_TRIGGER_CUSTOM_BINARY_SENSOR
  CallbackManager<void(StringRef, bool)> custom_binary_sensor_callback_{};
#endif  // USE_NEXTION_TRIGGER_CUSTOM_BINARY_SENSOR
#ifdef USE_NEXTION_TRIGGER_CUSTOM_SENSOR
  CallbackManager<void(StringRef, int32_t)> custom_sensor_callback_{};
#endif  // USE_NEXTION_TRIGGER_CUSTOM_SENSOR
#ifdef USE_NEXTION_TRIGGER_CUSTOM_SWITCH
  CallbackManager<void(StringRef, bool)> custom_switch_callback_{};
#endif  // USE_NEXTION_TRIGGER_CUSTOM_SWITCH
#ifdef USE_NEXTION_TRIGGER_CUSTOM_TEXT_SENSOR
  CallbackManager<void(StringRef, StringRef)> custom_text_sensor_callback_{};
#endif  // USE_NEXTION_TRIGGER_CUSTOM_TEXT_SENSOR
 
  nextion_writer_t writer_;
  optional<float> brightness_;
 
  // Device info populated from comok response (fixed-size, no heap allocation).
  // Sizes derived from Nextion Upload Protocol documentation and observed hardware.
  static constexpr size_t NEXTION_MODEL_MAX = 24;   
  static constexpr size_t NEXTION_FW_MAX = 7;       
  static constexpr size_t NEXTION_SERIAL_MAX = 20;  
  char device_model_[NEXTION_MODEL_MAX + 1]{};
  char firmware_version_[NEXTION_FW_MAX + 1]{};
  char serial_number_[NEXTION_SERIAL_MAX + 1]{};
  uint32_t flash_size_ = 0;  
 
  void remove_front_no_sensors_();
 
#ifdef NEXTION_PROTOCOL_LOG
  void print_queue_members_();
#endif  // NEXTION_PROTOCOL_LOG
  void reset_(bool reset_nextion = true);
 
  std::string command_data_;
  uint32_t started_ms_ = 0;
 
  uint16_t startup_override_ms_ = 8000;  
  uint16_t max_q_age_ms_ = 8000;         
};
 
}  // namespace esphome::nextion