Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Nextion update (#934) 

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Co-authored-by: Samuel Sieb <samuel-github@sieb.net>
This commit is contained in:
SenexCrenshaw 2021-07-14 20:51:30 -04:00 committed by GitHub
parent c5741a0042
commit 86ed64201c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 798 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

159
components/binary_sensor/nextion.rst
View File

@ -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 <config-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 <nextion_binary_sensor_settings>`.
A :ref:`Nextion Sensor <nextion_sensor>` with a custom protocol sending the current page can be used to execute the API call :ref:`Update Components By Prefix <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 <config-lambda>`, 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 <nextion_binary_sensor_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`

197
components/display/nextion.rst
View File

@ -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 <uart>`
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 <config-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 <nextion_upload_tft>`.
- **on_sleep** (*Optional*, :ref:`Action <config-action>`): An automation to perform when the Nextion goes to sleep.
- **on_wake** (*Optional*, :ref:`Action <config-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 <https://nextion.tech/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 <https://nextion.itead.cc/resources/download/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 <config-lambda>` ; 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 <nextion_queue_types>`
- ``set_nextion_sensor_state(int queue_type, std::string name, float state);`` : Sets the sensor state. See :ref:`Queue Types <nextion_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 <https://www.nginx.com/>`__
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 <https://github.com/bborncr/nextion>`__ by `Bentley Born <https://github.com/bborncr>`__
- `Official Nextion Library <https://github.com/itead/ITEADLIB_Arduino_Nextion>`__ by `iTead <https://www.itead.cc/>`__

BIN
components/sensor/images/nextion.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.1 KiB

178
components/sensor/nextion.rst Normal file
View File

@ -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 <config-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<nextion_sensor_settings>`.
A :ref:`Nextion Sensor <nextion_sensor>` with a custom protocol sending the current page can be used to execute the API call :ref:`Update Components By Prefix <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 <config-lambda>`, 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 <nextion_sensor_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`

143
components/switch/nextion.rst Normal file
View File

@ -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 <config-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 <config-lambda>`, 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 <nextion_switch_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`

138
components/text_sensor/nextion.rst Normal file
View File

@ -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 <config-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 <config-lambda>`, 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 <nextion_text_sensor_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`

6
index.rst
View File

@ -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
------------------