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 entryglobals: - 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));Configuration variables
Section titled “Configuration variables”-
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(fortrue/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::stringglobals count toward that at build time, so a configuration that would not fit is rejected instead of failing to save on the device. Defaults tono. -
storage (Optional, string): Where the value is saved. Only valid when
restore_valueisyes. 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
flashon the ESP32, and on the ESP8266 tortcunlessrestore_from_flash: trueis set on the ESP8266 platform, which keeps the behaviour from before this option existed.rtcis 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 onlyflashis available andrtcis rejected. These Beken chips have no RTC memory: therertckeeps 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_valueisyes. Defaults to1s. 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
0for 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.
globals.set Action
Section titled “globals.set Action”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'Configuration variables
Section titled “Configuration variables”- 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;