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 000000000..0029825e8 Binary files /dev/null and b/components/sensor/images/nextion.jpg differ 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 ------------------