Skip to content
Get started

Global Variables

In some cases you might need to share a global variable across multiple lambdas, or to remember between periods of deep_sleep. For example, global variables can be used to store the state of a garage door.

# Example configuration entry
globals:
- id: my_global_int
type: int
restore_value: no
initial_value: '0'
# Example for global string variable
- id: my_global_string
type: std::string
restore_value: yes
max_restore_data_length: 24
initial_value: '"Global value is"'
# Kept across deep sleep and restarts without wearing the flash
- id: my_wake_count
type: int
restore_value: yes
storage: rtc
initial_value: '0'
# In an automation
on_...:
then:
- lambda: |-
if (id(my_global_int) > 5) {
// global value is greater than 5
id(my_global_int) += 1;
} else {
id(my_global_int) += 10;
}
ESP_LOGD(TAG, "%s: %d", id(my_global_string).c_str(), id(my_global_int));
  • id (Required, ID): Give the global variable an ID so that you can refer to it later in lambdas.

  • type (Required, string): The C++ type of the global variable, for example bool (for true /false ), int (for integers), float (for decimal numbers), int[50] for an array of 50 integers, etc.

  • restore_value (Optional, boolean): Whether to try to restore the state on boot up. Be careful: on the ESP8266, RTC memory holds only 96 bytes in total for all restored values! Restored std::string globals count toward that at build time, so a configuration that would not fit is rejected instead of failing to save on the device. Defaults to no.

  • storage (Optional, string): Where the value is saved. Only valid when restore_value is yes. One of:

    • flash: survives a power loss, but every save wears the flash a little, so it suits values that change rarely.
    • rtc: RTC memory, which survives software restarts, crashes and deep sleep but not a power loss, and avoids flash wear, so it suits values that change often. On the original ESP32 the hardware reset button (the EN pin) also clears RTC memory.

    Defaults to flash on the ESP32, and on the ESP8266 to rtc unless restore_from_flash: true is set on the ESP8266 platform, which keeps the behaviour from before this option existed. rtc is available on the ESP32 (except the C2 and C61 variants, which have no RTC memory), the ESP8266 and the Beken BK7231T, BK7231N and BK7238; elsewhere only flash is available and rtc is rejected. These Beken chips have no RTC memory: there rtc keeps the value in flash and forgets it after a power cut, so it does not avoid flash wear.

  • update_interval (Optional, Time): The interval to check if the value has changed and needs to be saved. Only applies when restore_value is yes. Defaults to 1s. The value is also saved on shutdown.

  • max_restore_data_length (Optional, integer): Only applies to variables of type std::string. ESPHome will allocate enough space for this many characters, plus single character of overhead. Strings longer than this will not be saved. The max value of this variable is 254 characters, and the default is 63 characters.

  • initial_value (Optional, string): The value with which to initialize this variable if the state can not be restored or if state restoration is not enabled. This needs to be wrapped in quotes! Defaults to the C++ default value for this type (for example 0 for integers).

Within lambdas globals don’t have a state attribute, just a value. Note in the example above the use of id(my_global_int) where other components would require id(my_component).state.

This Action allows you to change the value of a globals variable without having to use the lambda syntax.

on_...:
- globals.set:
id: my_global_var
value: '10'
  • id (Required, ID): The ID of the global variable to set.
  • value (Required, templatable): The value to set the global variable to.

NOTE

This action can also be written in lambdas:

id(my_global_var) = 10;