diff --git a/components/display/nextion.rst b/components/display/nextion.rst index 516c7ef8e..8da2fceb0 100644 --- a/components/display/nextion.rst +++ b/components/display/nextion.rst @@ -63,13 +63,14 @@ Configuration variables: Defaults to ``5s``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **tft_url** (*Optional*, string): The URL to download the TFT file from for updates. See :ref:`Nextion Upload `. -- **on_sleep** (*Optional*, :ref:`Action `): An automation to perform when the Nextion goes to sleep. -- **on_wake** (*Optional*, :ref:`Action `): An automation to perform when the Nextion wakes up. - **touch_sleep_timeout** (*Optional*, int): Sets internal No-touch-then-sleep timer in seconds. - **wake_up_page** (*Optional*, int): Sets the page to display after waking up - **auto_wake_on_touch** (*Optional*, boolean): Sets if Nextion should auto-wake from sleep when touch press occurs. +- **on_setup** (*Optional*, :ref:`Action `): An action to be performed after ESPHome connects to the Nextion. See :ref:`Nextion Automation `. +- **on_sleep** (*Optional*, :ref:`Action `): An action to be performed when the Nextion goes to sleep. See :ref:`Nextion Automation `. +- **on_wake** (*Optional*, :ref:`Action `): An action to be performed when the Nextion wakes up. See :ref:`Nextion Automation `. +- **on_page** (*Optional*, :ref:`Action `): An action to be performed after a page change. See :ref:`Nextion Automation `. - .. _display-nextion_lambda: Rendering Lambda @@ -108,7 +109,7 @@ Please see :ref:`display-printf` for a quick introduction into the ``printf`` fo Lambda Calls ************ -Several methods are available for use within :ref:`lambdas ` ; these permit advanced functionality beyond simple +Several methods are available for use within :ref:`lambdas `; these permit advanced functionality beyond simple display updates. See the full :apiref:`nextion/nextion.h` for more info. .. _nextion_upload_tft: @@ -182,6 +183,80 @@ The developer tools in Home Assistant can be used to trigger the update. The bel - WAVEFORM_SENSOR 4 - NO_RESULT 5 +.. _display-nextion_automation: + +Nextion Automation +------------------ + +With Nextion displays, it's possible to define several automation actions. Depending on your setup, you may or may not need to use some of them. + +.. _nextion-on_setup: + +``on_setup`` +************ + +This automation will be triggered once ESP establishes a connection with Nextion. This happens after a boot up and may take some +noticeable time (e.g. hundreds of milliseconds) to establish a connection over UART. Typical use scenario for this automation is choosing of the initial +page to display depending on some runtime conditions or simply showing a page with a non-zero index (Nextion shows page 0 by default). + +.. code-block:: yaml + + wifi: + ap: {} # This spawns an AP with the device name and mac address with no password. + + captive_portal: + + display: + - platform: nextion + id: disp + on_setup: + then: + lambda: |- + // Check if WiFi hot-spot is configured + if (wifi::global_wifi_component->has_sta()) { + // Show the main page + id(disp).goto_page("main_page"); + } else { + // Show WiFi Access Point QR code for captive portal, see https://qifi.org/ + id(disp).goto_page("wifi_qr_page"); + } + +.. _nextion-on_sleep: + +``on_sleep / on_wake`` +********************** + +The action is called before and after Nextion goes to sleep mode. Nextion is not responsive while in sleep mode. Use these triggers to prepare your code +for that and :ref:`force-update ` the on-screen content once it's back. + +.. _nextion-on_page: + +``on_page`` +*********** + +This automation is triggered when a page is changed on the Nextion display. This includes both ESP and Nextion initiated page changes. +ESP initiates a page change by calling ``goto_page("page_name")`` function. Nextion can change pages as a reaction to user's activity (e.g. clicks) or using a timer. +In either case, this automation can be helpful to update on-screen controls for the newly displayed page. + +If you fully own your Nextoin HMI design and follow the best practice of setting the components' vscope to global in the Nextion Editor, you'll probably never need this trigger. +However, if this is not the case and all / some of your UI components have local visibility scope, ``on_page`` will be your remedy. Here you can initiate updates of the relevant components. + +Before actually updating components, you need to understand which page Nextion was switched to. ``x`` argument will contain a page id integer. +Once you know the page id, it's time to update the components. Two strategies would be possible. The first one is to use :ref:`Nextion Sensors ` for every UI field and use one of the +:ref:`update functions `. The second is to manually set component text or value for each field: + +.. code-block:: yaml + + on_page: + then: + lambda: |- + switch (x) { + case 0x02: // wifi_qr_page + // Manually trigger update for controls on page 0x02 here + id(disp).set_component_text_printf("qr_wifi", "WIFI:T:nopass;S:%s;P:;;", wifi::global_wifi_component->get_ap().get_ssid().c_str()); + break; + } + .. _nextion_upload_tft_file: Uploading A TFT File