From e015aca5cad20186b06ee97f2f30aae6c2550094 Mon Sep 17 00:00:00 2001 From: SenexCrenshaw <35600301+SenexCrenshaw@users.noreply.github.com> Date: Wed, 14 Jul 2021 20:51:30 -0400 Subject: [PATCH] Nextion update (#934) Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Co-authored-by: Samuel Sieb --- components/binary_sensor/nextion.rst | 159 +++++++++++++++++++-- components/display/nextion.rst | 197 +++++++++++++++++++++++++-- components/sensor/images/nextion.jpg | Bin 0 -> 6221 bytes components/sensor/nextion.rst | 178 ++++++++++++++++++++++++ components/switch/nextion.rst | 143 +++++++++++++++++++ components/text_sensor/nextion.rst | 138 +++++++++++++++++++ index.rst | 6 +- 7 files changed, 798 insertions(+), 23 deletions(-) create mode 100644 components/sensor/images/nextion.jpg create mode 100644 components/sensor/nextion.rst create mode 100644 components/switch/nextion.rst create mode 100644 components/text_sensor/nextion.rst diff --git a/components/binary_sensor/nextion.rst b/components/binary_sensor/nextion.rst index 08be47c00..b7d978b7f 100644 --- a/components/binary_sensor/nextion.rst +++ b/components/binary_sensor/nextion.rst @@ -1,13 +1,14 @@ -Nextion Touch Component -======================= +.. _nextion_binary_sensor: + +Nextion Binary Sensor Component +=============================== .. seo:: - :description: Instructions for setting up Nextion touch binary sensors. + :description: Instructions for setting up Nextion binary sensor. :image: nextion.jpg -The ``nextion`` binary sensor platform lets you track when a component on the display is -touched or not. The binary sensor will turn on when the component with the given component and page id is -pressed on, and will turn off as soon as the finger is released. +The ``nextion`` binary sensor platform supports the many switched components in the Nextion as well as integer variables (>0 == True). It can be a component or variable in the Nextion display. +It is best to set the components vscope to global in the Nextion Editor. This way the component will be available if the page is shown or not. See :doc:`/components/display/nextion` for setting up the display @@ -16,27 +17,159 @@ See :doc:`/components/display/nextion` for setting up the display # Example configuration entry display: - platform: nextion + id: nextion1 # ... binary_sensor: - platform: nextion page_id: 0 - component_id: 2 - name: "Nextion Component 2 Touch" + component_id: 8 + component_name: page0.mode # Only needed to support changing colors + id: mode + - platform: nextion + id: r0_binary_sensor + name: "Radio 0 Binary Sensor" + component_name: page0.r0 # r0 is a global component in the Nextion Editor on page 0 + update_interval: 4s + - platform: nextion + id: darkmode + name: "Is Darkmode Set" + variable_name: darkmode Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the binary sensor. -- **page_id** (**Required**, int): The ID of the page the component is on. Use ``0`` for the default page. -- **component_id** (**Required**, int): The ID (the number, not name!) of the component to track. -- **nextion_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the Nextion display. +- **name** (**Required**, string): The name of the sensor. +- **nextion_id** (*Optional*, :ref:`config-id`): The ID of the Nextion display. +- **component_name** (*Optional*, string): The name of the Nextion component. +- **variable_name** (*Optional*, string): The name of the Nextion variable. Any value over ``0`` is considered to be **on** +- **page_id** (*Optional*, string): The ID of the page the component is on. Use ``0`` for the default page. +- **component_id** (*Optional*, string): The ID (the number, not name!) of the component to track. +- **update_interval** (*Optional*, :ref:`config-time`): The duration to update the sensor. If using a :ref:`nextion_custom_binary_sensor_protocol` this should not be used +- **background_color** (*Optional*, :ref:`config-color`): The background color +- **background_pressed_color** (*Optional*, :ref:`config-color`): The background color when pressed +- **foreground_color** (*Optional*, :ref:`config-color`): The foreground color +- **foreground_pressed_color** (*Optional*, :ref:`config-color`): The foreground color when pressed +- **visible** (*Optional*, boolean ): Visible or not - All other options from :ref:`Binary Sensor `. +**Touch Sensor:** +The Nextion will send a **page_id** and **component_id** when the *Send Component ID* check box is selected for the component. To enable +this native event **page_id** and **component_id** are required. No :ref:`nextion_custom_binary_sensor_protocol` is required. If **page_id** and **component_id** are set then the component will only react to touch events from the Nextion. Setting **component_name** will allow setting options like forground color. + + .. note:: + + ``background_color(s)`` , ``foreground_color(s)`` and ``visible`` do not retain their state on page change. :ref:`Binary Sensor Settings `. + A :ref:`Nextion Sensor ` with a custom protocol sending the current page can be used to execute the API call :ref:`Update Components By Prefix ` to update all the components for that page + + +Example: + +.. code-block:: yaml + + - platform: nextion + id: current_page + nextion_id: nextion1 + name: current_page + variable_name: current_page + on_value: + lambda: |- + id(nextion1).update_components_by_page_prefix("page"+x+"."); + + + +See :ref:`nextion_binary_sensor_how_things_update` for additional information + +Globals +******* +The Nextion does not retain data on Nextion page changes. Additionally if a page is changed and the **nextion_component_name** does not exist on that page then +nothing will be updated. To get around this the Nextion components can be changed to have a vscope of ``global``. If this is set then the **nextion_component_name** +should be prefixed with the page name (page0/page1). + +*Example* + +``nextion_component_name: page0.r0`` + +.. _nextion_binary_sensor_lambda_calls: + +Lambda Calls +************ + +From :ref:`lambdas `, you can call several methods to access some +more advanced functions (see the full :apiref:`nextion/binary_sensor/nextion_binarysensor.h` for more info). + +.. _nextion_binary_sensor_set_state: + +- ``set_state(bool value, bool publish, bool send_to_nextion)``: Set the state to **value**. Publish the new state to HASS. Send_to_Nextion is to publish the state to the Nextion. + +.. _nextion_binary_sensor_update: + +- ``update()``: Poll from the Nextion + +.. _nextion_binary_sensor_settings: + +- ``set_background_color(Color color)``: Sets the background color to **Color** +- ``set_background_pressed_color(Color color)``: Sets the background color to **Color** +- ``set_foreground_color(Color color)``: Sets the background color to **Color** +- ``set_foreground_pressed_color(Color color)``: Sets the background color to **Color** +- ``set_visible(bool visible)`` : Sets visible or not. If set to false, no updates will be sent to the component + + +.. _nextion_binary_sensor_how_things_update: + +How things Update +----------------- +A Nextion component with an integer value (.val) or Nextion variable will be automatically polled if **update_interval** is set. +To have the Nextion send the data you can use the :ref:`nextion_custom_binary_sensor_protocol` for this. Add the :ref:`nextion_custom_binary_sensor_protocol` to the +component or function you want to trigger the send. Typically this is in *Touch Press Event* but some components, like a slider, should have it +set in the *Touch Release Event* to capture all the changes. Since this is a custom protocol it can be sent from anywhere (timers/functions/componenets) +in the Nextion. + +.. note:: + + There is no need to check the *Send Component ID* for the *Touch Press Event* or *Touch Release Event* + for an integer value component since this will be sending the real value to esphome, + but make sure you have both checked for a touch sensor. + + +Using the above yaml example: + - "mode" is a touch sensor and will trigger when a user presess the component with ID ``8`` in page ``0`` + - "Radio 0 Binary Sensor" will poll the Nextion for the ``r0.val`` value and set the state accordingly. + - "Is Darkmode Set" will NOT poll the Nextion. Either the Nextion will need to use the :ref:`nextion_custom_binary_sensor_protocol` or use a lambda: + + - :ref:`Lambda Calls `. + +.. note:: + + No updates will be sent to the Nextion if it is sleeping. Once it wakes the components will be updated. If a component is invisible , :code:`visible(false)` , then it wont update until it is set to be visible. + +.. _nextion_custom_binary_sensor_protocol: + +Nextion Custom Binary Sensor Protocol +------------------------------------- +All lines are required + +.. code-block:: c++ + + printh 93 + prints "r0",0 + printh 00 + prints r0.val,0 + printh FF FF FF + +*Explanation* + +- ``printh 93`` Tells the library this is a binary sensor bool/integer data +- ``prints "r0",0`` Sends the name that matches **nextion_component_name** or **nextion_variable_name** +- ``printh 00`` Sends a NULL +- ``prints r0.val,0`` The actual value to send. For a variable use the Nextion variable name ``r0`` with out ``.val`` +- ``printh FF FF FF`` Nextion command ack + + See Also -------- - :doc:`/components/display/nextion` - :doc:`index` -- :apiref:`nextion/nextion.h` +- :apiref:`nextion/binary_sensor/nextion_binarysensor.h` - :ghedit:`Edit` diff --git a/components/display/nextion.rst b/components/display/nextion.rst index 3e5590914..43459b5fb 100644 --- a/components/display/nextion.rst +++ b/components/display/nextion.rst @@ -17,19 +17,36 @@ with ESPHome. As the communication with the Nextion LCD display is done using UART, you need to have an :ref:`UART bus ` in your configuration with ``rx_pin`` both the ``tx_pin`` set to the respective pins on the display. -Additionally, you need to set the baud rate to 9600. +The Nextion uses a baud rate of 9600 by default. It may be configured to use a faster speed by adding (for +example) + +.. code-block:: c++ + + baud=115200 // Sets the baud rate to 115200 + bkcmd=0 // Tells the Nextion to not send responses on commands. This is the current default but can be set just in case + + + +to the ``program.s`` source file (in the Nextion Editor) before the ``page`` line. +This permits faster communication with the Nextion display and it is highly recommended when using :ref:`uart-hardware_uarts`. Without a hardware uart make sure to set the baud rate to 9600. + + +The below example configures a UART for the Nextion display to use .. code-block:: yaml # Example configuration entry uart: - rx_pin: D0 - tx_pin: D1 - baud_rate: 9600 + id: uart_2 + rx_pin: GPIO16 + tx_pin: GPIO17 + baud_rate: 115200 display: - platform: nextion + id: nextion1 + uart_id: uart_2 lambda: |- it.set_component_value("gauge", 50); it.set_component_text("textview", "Hello World!"); @@ -41,10 +58,17 @@ Configuration variables: Use this if you want to use multiple UART buses at once. - **brightness** (*Optional*, percentage): Set display brightness in %. Defaults to ``100%`` - **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the nextion display. - See :ref:`display-nextion_lambda` for more information. + See :ref:`display-nextion_lambda` for more information. This is typically empty. The individual components for the Nextion will handle almost all features needed for updating - **update_interval** (*Optional*, :ref:`config-time`): The interval to call the lambda to update the display. 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. + .. _display-nextion_lambda: @@ -54,9 +78,9 @@ Rendering Lambda With Nextion displays, a dedicated chip on the display itself does the whole rendering. ESPHome can only send *instructions* to the display to tell it *how* to render something and *what* to render. -First, you need to use the `Nextion Editor `__ to -create a display file and insert it using the SD card slot. Then, in the rendering ``lambda``, you have 3 main methods -you can call to populate data on the display: +First, you need to use the `Nextion Editor `__ to +create a display file and insert it using the SD card slot. Then, in the rendering ``lambda``, you can use the various API calls +to populate data on the display: .. code-block:: yaml @@ -74,16 +98,171 @@ you can call to populate data on the display: // set the text of a component with formatting it.set_component_text_printf("textview", "The uptime is: %.1f", id(uptime_sensor).state); +.. note:: + + Although you can use the rendering lambda most, if not all, updates to the Nextion can be handled by the individual Nextion components. **See Below** Please see :ref:`display-printf` for a quick introduction into the ``printf`` formatting rules and :ref:`display-strftime` for an introduction into the ``strftime`` time formatting. +Lambda Calls +************ + +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: + +- ``upload_tft``: Start the upload process. See :ref:`nextion_upload_tft_file` + +The developer tools in Home Assistant can be used to trigger the update. The below code block is an example on how to set this up. + .. code-block:: yaml + + api: + services: + - service: update_nextion + then: + - lambda: 'id(nextion1)->upload_tft();' + +.. _nextion_update_all_components: + +- ``update_all_components()``: All the components will publish their states. + + .. code-block:: c++ + + id(nextion1).update_all_components(); + +.. _update_components_by_prefix: + +- ``update_components_by_prefix(std::string page)``: This will send the current state of any **component_name** matching the prefix. Some settings like background color need to be resent on page change. This is a good hook for that. + + .. code-block:: c++ + + id(nextion1).update_components_by_prefix("page0."); + +.. _set_nextion_sensor_state: + +- ``set_nextion_sensor_state(NextionQueueType queue_type, std::string name, float state);`` : Sets the sensor state. See :ref:`Queue Types ` +- ``set_nextion_sensor_state(int queue_type, std::string name, float state);`` : Sets the sensor state. See :ref:`Queue Types ` + +- ``set_nextion_text_state(std::string name, std::string state);`` : Sets the text sensor state + +.. note:: + + Below is a method for HASS to send updates to the Nextion by code. + + .. code-block:: yaml + + # Enable Home Assistant API + api: + services: + - service: set_nextion_sensor + variables: + nextion_type: int + name: string + state: float + then: + - lambda: |- + id(nextion1).set_nextion_sensor_state(nextion_type,name,state); + - service: set_nextion_text + variables: + name: string + state: string + then: + - lambda: |- + id(nextion1).set_nextion_text_state(name,state); + +.. _nextion_queue_types: + + Queue Types: + - SENSOR 0 + - BINARY_SENSOR 1 + - SWITCH 2 + - TEXT_SENSOR 3 + - WAVEFORM_SENSOR 4 + - NO_RESULT 5 + +.. _nextion_upload_tft_file: + +Uploading A TFT File +-------------------- +This will download the file from the tft_url and will transfer it over the UART to the Nextion. +Once completed both the ESP and Nextion will reboot. During the upload process esphome will be +unresponsive and no logging will take place. This uses the same protocol as the Nextion editor and +only updates the changes of the TFT file. If HTTPS/SSL is enabled it will be about 1kB/sec. + +.. warning:: + + If :ref:`uart-hardware_uarts` are not available then inconsistent results WILL occur. Lowering the speed to 9600 baud may help. + + +To host the TFT file you can use Home Assistant itself or any other web server. HTTPS, while always recommended on any network, will greatly reduce the upload speed. + +Home Assistant +************** +To host the TFT file from Home Assistant, create a www directory if it doesn't exist in your config +directory. You can create a subdirectory for those files as well. + +For example if the file is located +under your configuration directory ``www/tft/default.tft`` the URL to access it will be +``http(s)://your_home_assistant_url:port/local/tft/default.tft`` + +NGINX +***** + +`NGINX `__ + +The below NGINX example configuration will serve files out of the /var/www/nextion directory. + +.. code-block:: nginx + + server { + listen 80; + access_log /var/log/nginx/nextion_access.log; + error_log /var/log/nginx/nextion_error.log; + root /var/www/nextion; + } + + + +Components +---------- +This library supports a few different components allowing communication back and forth from HA <-> MCU <-> Nextion. + +.. note:: + + If the Nextion is sleeping or if the component was set to be hidden, it will not update its components even if updates are sent. + After the Nextion wakes up, all components will send their states to the Nextion to get around this. + +With the exception of the :doc:`../binary_sensor/nextion` that has the ``page_id``/``component_id`` options configured, the example below illustrates: + - Polling the Nextion for updates + - Dynamic updates sent from the Nextion to the ESP device + + .. code-block:: yaml + + sensor: + - platform: nextion + nextion_id: nextion1 + name: "n0" + component_name: n0 + - platform: nextion + id: current_page + name: "current_page" + variable_name: dp + update_interval: 1s + + +Note that the first one requires a custom protocol to be included in the Nextion display's code/configuration. See the individual components for more detail. See Also -------- - :doc:`index` -- :doc:`/components/binary_sensor/nextion` +- :doc:`../binary_sensor/nextion` +- :doc:`../sensor/nextion` +- :doc:`../switch/nextion` +- :doc:`../text_sensor/nextion` +- :doc:`../uart` - :apiref:`nextion/nextion.h` - `Simple Nextion Library `__ by `Bentley Born `__ - `Official Nextion Library `__ by `iTead `__ diff --git a/components/sensor/images/nextion.jpg b/components/sensor/images/nextion.jpg new file mode 100644 index 0000000000000000000000000000000000000000..0029825e8877aea3643ee25a523da253f6aa9a75 GIT binary patch literal 6221 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 B-Ut8y literal 0 HcmV?d00001 diff --git a/components/sensor/nextion.rst b/components/sensor/nextion.rst new file mode 100644 index 000000000..e936f9541 --- /dev/null +++ b/components/sensor/nextion.rst @@ -0,0 +1,178 @@ +.. _nextion_sensor: + +Nextion Sensor Component +======================== + +.. seo:: + :description: Instructions for setting up Nextion sensor. + :image: nextion.jpg + +The ``nextion`` sensor platform supports integers or floats (Xfloat). It can be a component, a variable or a waveform in the Nextion display. +It is best to set the component's vscope to global in the Nextion Editor. This way the component will be available +if the page is shown or not. + +.. note:: + + The Nextion can receive an integer but it can only send 3 bytes for a negative integer. The range if using the :ref:`nextion_custom_sensor_protocol` is: + -16777215 to 4294967295 + +See :doc:`/components/display/nextion` for setting up the display + +.. code-block:: yaml + + # Example configuration entry + display: + - platform: nextion + id: nextion1 + # ... + + sensor: + - platform: nextion + name: "Current Humidity" + component_name: humidity # pageX.humidity for a global + nextion_precision: 1 + update_interval: 4s + - platform: nextion + nextion_id: nextion1 + name: "Current Temperature" + variable_name: temperature + hass_component_name: sensor.temperature + - platform: nextion + id: s01 + component_id: 2 + wave_channel_id: 0 + wave_max_value: 100 + waveform_send_last_value: "true" + wave_max_length: 400 + update_interval: 1s + - platform: nextion + id: s02 + component_id: 2 + wave_channel_id: 1 + wave_max_value: 100 + update_interval: 1s + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the sensor. +- **nextion_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the Nextion display. +- **component_name** (*Optional*, string): Manually specify the name of the Nextion component. +- **variable_name** (*Optional*, string): Manually specify the name of the Nextion variable. +- **update_interval** (*Optional*, :ref:`config-time`): The duration to update the sensor +- **nextion_precision** (*Optional*, uint8_t): This is for Nextion float components. This sets + the precision that the component is set to. This typically is the ``vvs1`` setting of the component. +- **background_color** (*Optional*, :ref:`config-color`): The background color +- **foreground_color** (*Optional*, :ref:`config-color`): The foreground color +- **visible** (*Optional*, boolean ): Visible or not + +Waveform Settings +***************** +- **wave_channel_id** (*Optional*, uint8_t): The waveform ID in a range of 0-3 +- **wave_max_value** (*Optional*, uint8_t): The max value. Set ``dis`` to the height of the component in the Nextion editor + and this to the max value that will be sent. This will set up the proper scaling. +- **waveform_send_last_value** (*Optional*, uint8_t): This will send the last value set during an update interval. Setting to true will give a timeseries style graph +- **wave_max_length** (*Optional*, int): How many data points to store. Typically this is the width of the component in the Nextion +- **update_interval** (*Optional*, :ref:`config-time`): The duration to update the sensor. This typically should be set for waveforms to send periodic updates. + +- All other options from :ref:`Sensor `. + +**Only one** *component_name* **or** *variable_name* **can be set** + + .. note:: + + ``background_color`` , ``foreground_color`` and ``visible`` do not retain their state on page change. :ref:`Sensor Settings`. + A :ref:`Nextion Sensor ` with a custom protocol sending the current page can be used to execute the API call :ref:`Update Components By Prefix ` to update all the components for that page + + +See :ref:`nextion_sensor_how_things_update` for additional information + +Globals +******* +The Nextion does not retain data on Nextion page changes. Additionally if a page is changed and the **component_name** does not exist on that page then +nothing will be updated. To get around this the Nextion components can be changed to have a vscope of ``global``. If this is set then the **component_name** +should be prefixed with the page name (page0/page1 or whatever you have changed it to). + +*Example* + +``component_name: page0.humidity`` + +.. _nextion_sensor_lambda_calls: + +Lambda Calls +************ + +From :ref:`lambdas `, you can call several methods to access +some more advanced functions (see the full :apiref:`nextion/sensor/nextion_sensor.h` for more info). + +.. _nextion_sensor_set_state: + +- ``set_state(bool value, bool publish, bool send_to_nextion)``: Set the state to **value**. Publish the new state to HASS. Send_to_Nextion is to publish the state to the Nextion. + +.. _nextion_sensor_update: + +- ``update()``: Poll from the Nextion + +.. _nextion_sensor_settings: + +- ``set_background_color(Color color)``: Sets the background color to **Color** +- ``set_foreground_color(Color color)``: Sets the background color to **Color** +- ``set_visible(bool visible)`` : Sets visible or not. If set to false, no updates will be sent to the component + + +.. _nextion_sensor_how_things_update: + +How things Update +----------------- +A Nextion component with an integer value (.val) or Nextion variable will be automatically polled if **update_interval** is set. +To have the Nextion send the data you can use the :ref:`nextion_custom_sensor_protocol` for this. Add the :ref:`nextion_custom_sensor_protocol` to the +component or function you want to trigger the send. Typically this is in *Touch Press Event* but some components, like a slider, should have it +set in the *Touch Release Event* to capture all the changes. Since this is a custom protocol it can be sent from anywhere (timers/functions/componenets) +in the Nextion. + +.. note:: + + There is no need to check the *Send Component ID* for the *Touch Press Event* or *Touch Release Event* + since this will be sending the real value to esphome. + +Using the above yaml example: + - "Current Humidity" will poll the Nextion for the ``humidity.val`` value and set the sensor accordingly. + - "Current Temperature" will NOT poll the Nextion. Either the Nextion will need to use the :ref:`nextion_custom_sensor_protocol` or use a lambda: + + - :ref:`Lambda Calls `. + +.. note:: + + No updates will be sent to the Nextion if it is sleeping. Once it wakes, the components will be updated. If a component is invisible, :code:`visible(false)`, then it won't update until it is set to be visible. + + +.. _nextion_custom_sensor_protocol: + +Nextion Custom Sensor Protocol +------------------------------ +All lines are required + +.. code-block:: c++ + + printh 91 + prints "temperature",0 + printh 00 + prints temperature.val,0 + printh FF FF FF + +*Explanation* + +- ``printh 91`` Tells the library this is a sensor (int) data +- ``prints "temperature",0`` Sends the name that matches **component_name** or **variable_name** +- ``printh 00`` Sends a NULL +- ``prints temperature.val,0`` The actual value to send. For a variable use the Nextion variable name ``temperature`` with out ``.val`` +- ``printh FF FF FF`` Nextion command ack + + +See Also +-------- + +- :doc:`/components/display/nextion` +- :doc:`index` +- :apiref:`nextion/sensor/nextion_sensor.h` +- :ghedit:`Edit` diff --git a/components/switch/nextion.rst b/components/switch/nextion.rst new file mode 100644 index 000000000..9801946e4 --- /dev/null +++ b/components/switch/nextion.rst @@ -0,0 +1,143 @@ +.. _nextion_switch: + +Nextion Switch Component +=============================== + +.. seo:: + :description: Instructions for setting up Nextion Switch. + :image: nextion.jpg + +The ``nextion`` switch platform supports the many switched components in the Nextion as well as integer variables. It can be a component or variable in the Nextion display. +It is best to set the components vscope to global in the Nextion Editor. This way the component will be available if the page is shown or not. + +See :doc:`/components/display/nextion` for setting up the display + +.. code-block:: yaml + + # Example configuration entry + display: + - platform: nextion + id: nextion1 + # ... + + switch: + - platform: nextion + id: r0_switch + name: "Radio 0 Switch" + component_name: r0 # pageX.r0 for a global + update_interval: 4s + - platform: nextion + id: darkmode + name: "Is Darkmode Set" + variable_name: darkmode + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the sensor. +- **nextion_id** (*Optional*, :ref:`config-id`): The ID of the Nextion display. +- **component_name** (*Optional*, string): The name of the Nextion component. +- **variable_name** (*Optional*, string): The name of the Nextion variable. Any value over ``0`` is considerd to be **on** +- **update_interval** (*Optional*, :ref:`config-time`): The duration to update the sensor. If using a :ref:`nextion_custom_switch_protocol` this should not be used +- **background_color** (*Optional*, :ref:`config-color`): The background color +- **background_pressed_color** (*Optional*, :ref:`config-color`): The background color when pressed +- **foreground_color** (*Optional*, :ref:`config-color`): The foreground color +- **foreground_pressed_color** (*Optional*, :ref:`config-color`): The foreground color when pressed +- **visible** (*Optional*, boolean ): Visible or not +- All other options from :ref:`Switch `. + +**Only one** *component_name* **or** *variable_name* **can be set** + +See :ref:`nextion_switch_how_things_update` for additional information + +Globals +******* +The Nextion does not retain data on Nextion page changes. Additionally, if a page is changed and the **component_name** does not exist on that page then +nothing will be updated. To get around this, the Nextion components can be changed to have a vscope of ``global``. If this is set then the **component_name** +should be prefixed with the page name (page0/page1 or whatever you have changed it to). + +*Example* + +``component_name: page0.r0`` + +.. _nextion_switch_lambda_calls: + +Lambda Calls +************ + +From :ref:`lambdas `, you can call several methods to access +some more advanced functions (see the full :apiref:`nextion/nextion_switch.h` for more info). + +.. _nextion_switch_set_state: + +- ``set_state(bool value, bool publish, bool send_to_nextion)``: Set the state to **value**. Publish the new state to HASS. Send_to_Nextion is to publish the state to the Nextion. + +.. _nextion_switch_update: + +- ``update()``: Poll from the Nextion + +.. _nextion_switch_settings: + +- ``set_background_color(Color color)``: Sets the background color to **Color** +- ``set_background_pressed_color(Color color)``: Sets the background color to **Color** +- ``set_foreground_color(Color color)``: Sets the background color to **Color** +- ``set_foreground_pressed_color(Color color)``: Sets the background color to **Color** +- ``set_visible(bool visible)`` : Sets visible or not. If set to false, no updates will be sent to the component + + +.. _nextion_switch_how_things_update: + +How things Update +----------------- +A Nextion component with an integer value (.val) or Nextion variable will be automatically polled if **update_interval** is set. +To have the Nextion send the data you can use the :ref:`nextion_custom_switch_protocol` for this. Add the :ref:`nextion_custom_switch_protocol` to the +component or function you want to trigger the send. Typically this is in *Touch Press Event* but some components, like a slider, should have it +set in the *Touch Release Event* to capture all the changes. Since this is a custom protocol it can be sent from anywhere (timers/functions/componenets) +in the Nextion. + +.. note:: + + There is no need to check the *Send Component ID* for the *Touch Press Event* or *Touch Release Event* + since this will be sending the real value to esphome. + +Using the above yaml example: + - "Radio 0 switch" will poll the Nextion for the ``r0.val`` value and set the state accordingly. + - "Is Darkmode Set" will NOT poll the Nextion. Either the Nextion will need to use the :ref:`nextion_custom_switch_protocol` or use a lambda: + + - :ref:`Lambda Calls `. + +.. note:: + + No updates will be sent to the Nextion if it is sleeping. Once it wakes, the components will be updated. If a component is invisible, :code:`visible(false)`, then it won't update until it is set to be visible. + + +.. _nextion_custom_switch_protocol: + +Nextion Custom Switch Protocol +------------------------------ +All lines are required + +.. code-block:: c++ + + printh 90 + prints "r0",0 + printh 00 + prints r0.val,0 + printh FF FF FF + +*Explanation* + +- ``printh 90`` Tells the library this is a switch bool/integer data +- ``prints "r0",0`` Sends the name that matches **component_name** or **variable_name** +- ``printh 00`` Sends a NULL +- ``prints r0.val,0`` The actual value to send. For a variable use the Nextion variable name ``r0`` with out ``.val`` +- ``printh FF FF FF`` Nextion command ack + + +See Also +-------- + +- :doc:`/components/display/nextion` +- :doc:`index` +- :apiref:`nextion/switch/nextion_switch.h` +- :ghedit:`Edit` diff --git a/components/text_sensor/nextion.rst b/components/text_sensor/nextion.rst new file mode 100644 index 000000000..d4891d7e2 --- /dev/null +++ b/components/text_sensor/nextion.rst @@ -0,0 +1,138 @@ +.. _nextion_text_sensor: + +Nextion Text Sensor Component +=============================== + +.. seo:: + :description: Instructions for setting up Nextion text sensor. + :image: nextion.jpg + +The ``nextion`` text sensor platform supports text strings. It can be a component or variable in the Nextion display. +It is best to set the components vscope to global in the Nextion Editor. This way the component will be available +if the page is shown or not. + +See :doc:`/components/display/nextion` for setting up the display + +.. code-block:: yaml + + # Example configuration entry + display: + - platform: nextion + id: nextion1 + # ... + + text_sensor: + - platform: nextion + nextion_id: nextion1 + name: text0 + id: text0 + update_interval: 4s + component_name: text0 + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the sensor. +- **nextion_id** (*Optional*, :ref:`config-id`): The ID of the Nextion display. +- **component_name** (*Optional*, string): The name of the Nextion component. +- **variable_name** (*Optional*, string): The name of the Nextion variable. Any value over ``0`` is considerd to be **on** +- **update_interval** (*Optional*, :ref:`config-time`): The duration to update the sensor. If using a :ref:`nextion_custom_text_sensor_protocol` this should not be used +- **background_color** (*Optional*, :ref:`config-color`): The background color +- **foreground_color** (*Optional*, :ref:`config-color`): The foreground color +- **font_id** (*Optional*, uint8_t): The font id for the component +- **visible** (*Optional*, boolean ): Visible or not +- All other options from :ref:`Text Sensor `. + +**Only one** *component_name* **or** *variable_name* **can be set** + +See :ref:`nextion_text_sensor_how_things_update` for additional information + +Globals +******* +The Nextion does not retain data on Nextion page changes. Additionally, if a page is changed and the **component_name** does not exist on that page then +nothing will be updated. To get around this, the Nextion components can be changed to have a vscope of ``global``. If this is set, then the **component_name** +should be prefixed with the page name (page0/page1 or whatever you have changed it to). + +*Example* + +``component_name: page0.text0`` + +.. _nextion_text_sensor_lambda_calls: + +Lambda Calls +************ + +From :ref:`lambdas `, you can call several methods to access +some more advanced functions (see the full :apiref:`nextion/text_sensor/nextion_textsensor.h` for more info). + +.. _nextion_text_sensor_set_state: + +- ``set_state(bool value, bool publish, bool send_to_nextion)``: Set the state to **value**. Publish the new state to HASS. Send_to_Nextion is to publish the state to the Nextion. + +.. _nextion_text_sensor_update: + +- ``update()``: Poll from the Nextion + +.. _nextion_text_sensor_settings: + +- ``set_background_color(Color color)``: Sets the background color to **Color** +- ``set_foreground_color(Color color)``: Sets the background color to **Color** +- ``set_visible(bool visible)`` : Sets visible or not. If set to false, no updates will be sent to the component + +.. _nextion_text_sensor_how_things_update: + +How things Update +----------------- +A Nextion component with an integer value (.val) or Nextion variable will be automatically polled if **update_interval** is set. +To have the Nextion send the data you can use the :ref:`nextion_custom_text_sensor_protocol` for this. Add the :ref:`nextion_custom_text_sensor_protocol` to the +component or function you want to trigger the send. Typically this is in *Touch Press Event* but some components, like a slider, should have it +set in the *Touch Release Event* to capture all the changes. Since this is a custom protocol it can be sent from anywhere (timers/functions/componenets) +in the Nextion. + +.. note:: + + There is no need to check the *Send Component ID* for the *Touch Press Event* or *Touch Release Event* + since this will be sending the real value to esphome. + +Using the above yaml example: + - "text0" will poll the Nextion for ``text0.txt`` value and set the state accordingly. + + - :ref:`Lambda Calls `. + +.. note:: + + No updates will be sent to the Nextion if it is sleeping. Once it wakes, the components will be updated. If a component is invisible, :code:`visible(false)`, then it won't update until it is set to be visible. + + +.. _nextion_custom_text_sensor_protocol: + +Nextion Custom Text Sensor Protocol +----------------------------------- +All lines are required + +.. code-block:: c++ + + printh 92 + prints "text0",0 + printh 00 + prints text0.txt,0 + printh 00 + printh FF FF FF + +*Explanation* + +- ``printh 92`` Tells the library this is text sensor +- ``prints "text0",0`` Sends the name that matches **component_name** or **variable_name** +- ``printh 00`` Sends a NULL +- ``prints text0.txt,0`` The actual text to send. For a variable use the Nextion variable name ``text0`` with out ``.txt`` +- ``printh 00`` Sends a NULL +- ``printh FF FF FF`` Nextion command ack + + +See Also +-------- + +- :doc:`/components/display/nextion` +- :doc:`index` +- :apiref:`nextion/text_sensor/nextion_textsensor.h` +- :ghedit:`Edit` diff --git a/index.rst b/index.rst index 4ef1d9951..55f1ad49e 100644 --- a/index.rst +++ b/index.rst @@ -193,6 +193,7 @@ Sensor Components MPU6050, components/sensor/mpu6050, mpu6050.jpg MQTT Subscribe, components/sensor/mqtt_subscribe, mqtt.png MS5611, components/sensor/ms5611, ms5611.jpg + Nextion, components/sensor/nextion, nextion.jpg NTC Thermistor, components/sensor/ntc, ntc.jpg PMSX003, components/sensor/pmsx003, pmsx003.svg Pulse Counter, components/sensor/pulse_counter, pulse.svg @@ -253,7 +254,7 @@ Binary Sensor Components ESP32 BLE Presence, components/binary_sensor/ble_presence, bluetooth.svg ESP32 Touch Pad, components/binary_sensor/esp32_touch, touch.svg MPR121 Capacitive Touch Sensor, components/binary_sensor/mpr121, mpr121.jpg - Nextion Touch, components/binary_sensor/nextion, nextion.jpg + Nextion Binary Sensor, components/binary_sensor/nextion, nextion.jpg Template Binary Sensor, components/binary_sensor/template, description.svg PN532, components/binary_sensor/pn532, pn532.jpg RC522, components/binary_sensor/rc522, rc522.jpg @@ -325,6 +326,7 @@ Switch Components Custom Switch, components/switch/custom, language-cpp.svg Tuya Switch, components/switch/tuya, tuya.png BLE Client Switch, components/switch/ble_client, bluetooth.svg + Nextion Switch, components/switch/nextion, nextion.jpg Fan Components -------------- @@ -385,6 +387,8 @@ Text Sensor Components BLE Scanner, components/text_sensor/ble_scanner, bluetooth.svg Template Text Sensor, components/text_sensor/template, description.svg Custom Text Sensor, components/text_sensor/custom, language-cpp.svg + Custom UART Text Sensor, components/text_sensor/uart, language-cpp.svg + Nextion Text Sensor, components/text_sensor/nextion, nextion.jpg Climate Components ------------------