esphome-docs/components/display_menu/lcd_menu.rst
2023-01-24 14:56:46 -03:00

122 lines
4.0 KiB
ReStructuredText

.. _lcd_menu:
LCD Menu
========
.. seo::
:description: Instructions for setting up a simple hierarchical menu on displays.
:image: lcd_menu.png
The component provides an infrastructure for setting up a hierarchical menu
on character based LCD displays. This offers the user an interactive method to display
labels, control entities like ``switch``, ``select``, ``number`` available locally on the
ESPHome node, without the requirement of a network connection.
.. figure:: images/lcd_menu.png
:align: center
:width: 60.0%
Overview
--------
The integration implements the :ref:`Display Menu <display_menu>` integration providing
a hierarchical menu primarily intended to be controlled either by a rotary encoder
with a button or a five-button joystick controller.
The component needs to be connected to an instance of a character based LCD display, which
like :ref:`lcd-pcf8574` or :ref:`lcd-gpio`. For the best results the GPIO connection is
recommended; the I²C one running at the speed according to the datasheet (usually ``100``
kHz) or even ESPHome default (``50`` kHz) will create perceptible delays especially when
changing a numeric value using the rotary encoder. Most ``PCF8574`` adapters used with
these displays will happily run at ``200`` or even ``400`` kHz though so if you are comfortable
accepting risks from running your hardware out of spec, you might want to try that
in your :ref:`i2c` configuration.
.. code-block:: yaml
# Example configuration entry
display:
- platform: lcd_pcf8574
id: my_lcd
dimensions: 20x4
...
user_characters:
- position: 0
data: # mark_back symbol
- 0b00100
- 0b01000
- 0b11110
- 0b01001
- 0b00101
- 0b00001
- 0b11110
- 0b00000
lambda: |-
id(my_lcd_menu).draw();
if (!id(my_lcd_menu).is_active())
it.print("Menu is not active");
# Declare a LCD menu
lcd_menu:
id: my_lcd_menu
display_id: my_lcd
active: true
mode: rotary
mark_back: 0x08
mark_selected: 0x3e
mark_editing: 0x2a
mark_submenu: 0x7e
items:
...
# Rotary encoder to provide navigation
sensor:
- platform: rotary_encoder
...
filters:
debounce: 30ms
on_anticlockwise:
- display_menu.up:
on_clockwise:
- display_menu.down:
# A debounced GPIO push button is used to 'click'
binary_sensor:
- platform: gpio
...
filters:
- delayed_on: 30ms
- delayed_off: 30ms
on_press:
- display_menu.enter:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **display_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the LCD display.
- **mark_back** (*Optional*, 0-255): Code of the character used to mark menu items going back
one level. As the character set lacks a good looking back arrow, using a user defined character
is advisable (use ``8`` to reference one at position ``0`` to avoid problems with zeros
in a string). Defaults to ``0x5e`` (``^``).
- **mark_selected** (*Optional*, 0-255): Code of the character used to mark menu item selected.
Defaults to ``0x3e`` (``>``).
- **mark_editing** (*Optional*, 0-255): Code of the character used to mark menu item editing mode.
Defaults to ``0x2a`` (``*``).
- **mark_submenu** (*Optional*, 0-255): Code of the character used to mark menu item leading to a
submenu. Defaults to ``0x7e`` (a right arrow).
The rest of the configuration is described in the :ref:`Display Menu <display_menu>` component.
The menu inherits the dimensions of the connected LCD display and uses the entire area.
See Also
--------
- :ref:`i2c`
- :ref:`lcd-pcf8574`
- :ref:`lcd-gpio`
- :ref:`Display Menu <display_menu>`
- :doc:`/components/sensor/rotary_encoder`
- :doc:`/components/binary_sensor/index`
- :apiref:`lcd_menu/lcd_menu.h`
- :ghedit:`Edit`