Display Menu

The integration provides a menu primarily intended to be controlled either by a rotary encoder with a button or a five-button joystick controller. It allows to navigate a hierarchy of items and submenus with the ability to change the values and execute commands. The menu can be activated and deactivated on demand, allowing alternating between using the screen for the menu and other information.

Overview

This document describes the configuration and automations common for the components implementing this integration. At the moment the character based LCD displays are supported using the lcd_menu integration and an instance of this is used in the configuration examples.

# Example configuration entry
display:
  - platform: lcd_pcf8574
    id: my_lcd
    ...
    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
  on_enter:
    then:
      lambda: 'ESP_LOGI("display_menu", "root enter");'
  on_leave:
    then:
      lambda: 'ESP_LOGI("display_menu", "root leave");'
  items:
    - type: back
      text: 'Back'
    - type: label
      text: 'Label 1'
    - type: label
      text: !lambda |-
        return "Templated label";

# Encoder to provide navigation
sensor:
  - platform: rotary_encoder
    ...
    on_anticlockwise:
      - display_menu.up:
    on_clockwise:
      - display_menu.down:

# A de-bounced GPIO is used to 'click'
binary_sensor:
  - platform: gpio
    ...
    filters:
      - delayed_on: 10ms
      - delayed_off: 10ms
    on_press:
      - display_menu.enter:

Configuration variables:

  • root_item_id (Optional, ID): Manually specify the ID of the root menu item.

  • active (Optional, boolean): Whether the menu should start as active, meaning accepting user interactions and displaying output. Defaults to true.

  • mode (Optional, string): Defines the navigation logic. The rotary mode expects the clockwise movement wired to display_menu.down, the anticlockwise one to display_menu.up and the switch to display_menu.enter action. The joystick mode expects the up, down, left and right buttons wired to the display_menu.up, display_menu.down, display_menu.left and display_menu.right actions and the middle button to the display_menu.enter action. Defaults to rotary.

  • menu (Required): The first level of the menu.

Automations:

  • on_enter (Optional, Automation): An automation to perform when the menu level (here the root one) is entered. See on_enter.

  • on_leave (Optional, Automation): An automation to perform when the menu level is not displayed anymore. See on_leave.

Automations

on_enter

This automation will be triggered when the menu level is entered, i.e. the component draws its items on the display. The it parameter points to a MenuItem class with the information of the menu item describing the displayed child items. If present at the top level it is an internally generated root menu item, otherwise an user defined one.

lcd_menu:
  ...
  items:
    - type: menu
      text: 'Submenu 1'
      on_enter:
        then:
          lambda: 'ESP_LOGI("display_menu", "enter: %s", it->get_text().c_str());'

on_leave

This automation will be triggered when the menu level is exited, i.e. the component does not draw its items on the display anymore. The it parameter points to a MenuItem class with the information of the menu item. If present at the top level it is an internally generated root menu item, otherwise an user defined one. It does not matter whether the level was left due to entering the submenu or going back to the parent menu.

lcd_menu:
  ...
  items:
    - type: menu
      text: 'Submenu 1'
      on_leave:
        then:
          lambda: 'ESP_LOGI("display_menu", "leave: %s", it->get_text().c_str());'

on_value

This automation will be triggered when the value edited through the menu changed or a command was triggered.

lcd_menu:
  ...
  items:
    - type: select
      text: 'Select Item'
      select: my_select_1
      on_value:
        then:
          lambda: 'ESP_LOGI("display_menu", "select value: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'

on_next

This automation will be triggered when the user requested to set the value to the next one.

lcd_menu:
  ...
  items:
    - type: custom
      text: 'Custom Item'
      value_lambda: 'return to_string(some_state);'
      on_next:
        then:
          lambda: 'some_state++;'

on_prev

This automation will be triggered when the user requested to set the value to the previous one.

lcd_menu:
  ...
  items:
    - type: custom
      text: 'Custom Item'
      value_lambda: 'return to_string(some_state);'
      on_prev:
        then:
          lambda: 'some_state--;'

display_menu.up Action

This is an Action for navigating up in a menu. The action is usually wired to an anticlockwise turn of a rotary encoder or to the upper button of the joystick.

sensor:
  - platform: rotary_encoder
    ...
    on_anticlockwise:
      - display_menu.up:

Configuration variables:

  • id (Optional, ID): The ID of the menu to navigate.

display_menu.down Action

This is an Action for navigating down in a menu. The action is usually wired to a clockwise turn of a rotary encoder or to the lower button of the joystick.

sensor:
  - platform: rotary_encoder
    ...
    on_clockwise:
      - display_menu.down:

Configuration variables:

  • id (Optional, ID): The ID of the menu to navigate.

display_menu.left Action

This is an Action usually wired to the left button of the joystick. In the joystick mode it is used to set the previous value or to decrement the numeric one; depending on the immediate_edit flag entering the edit mode is required or not. If used in the rotary mode it exits the editing. In both modes it can be also used to navigate back one level when used with the back menu item.

binary_sensor:
  - platform: gpio
    ...
    on_press:
      - display_menu.left:

Configuration variables:

  • id (Optional, ID): The ID of the menu to navigate.

display_menu.right Action

This is an Action usually wired to the right button of the joystick. In the joystick mode it is used to set the next value or to increment the numeric one; depending on the immediate_edit flag entering the edit mode is required or not. In both modes it can be also used to enter the submenu when used with the menu menu item.

binary_sensor:
  - platform: gpio
    ...
    on_press:
      - display_menu.right:

Configuration variables:

  • id (Optional, ID): The ID of the menu to navigate.

display_menu.enter Action

This is an Action for triggering a selected menu item, resulting in an action depending on the type of the item - entering a submenu, starting/stopping editing or triggering a command. The action is usually wired to a press button of a rotary encoder or to the center button of the joystick.

binary_sensor:
  - platform: gpio
    ...
    filters:
      - delayed_on: 10ms
      - delayed_off: 10ms
    on_press:
      - display_menu.enter:

Configuration variables:

  • id (Optional, ID): The ID of the menu to navigate.

display_menu.show Action

This is an Action for showing an inactive menu. The state of the menu remains unchanged, i.e. the menu level shown at the moment it was hidden is restored, as is the selected item. The following snippet shows the menu if it is inactive, otherwise triggers the selected item.

on_press:
  - if:
      condition:
        display_menu.is_active:
      then:
        - display_menu.enter:
      else:
        - display_menu.show:

Configuration variables:

  • id (Optional, ID): The ID of the menu to show.

display_menu.hide Action

This is an Action for hiding the menu. A hidden menu does not react to draw() and does not process navigation actions.

lcd_menu:
  ...
  items:
    - type: command
      text: 'Hide'
      on_value:
        then:
          - display_menu.hide:

Configuration variables:

  • id (Optional, ID): The ID of the menu to hide.

display_menu.show_main Action

This is an Action for showing the root level of the menu.

lcd_menu:
  ...
  items:
    - type: command
      text: 'Show Main'
      on_value:
        then:
          - display_menu.show_main:

Configuration variables:

  • id (Optional, ID): The ID of the menu to hide.

display_menu.is_active Condition

This Condition checks if the given menu is active, i.e. shown on the display and processing navigation events.

on_press:
  - if:
      condition:
        display_menu.is_active:
      ...

See Also