From be19f4e0b590fba30220e9c8973b96750240ea3b Mon Sep 17 00:00:00 2001 From: Victor Chang Date: Sat, 27 Dec 2025 14:12:36 -0800 Subject: [PATCH] Clarify docs and make example yamls consistent. (#12) --- docs/faq.md | 12 +++++++----- example_yaml/vue-utility-simple.yaml | 7 ++++--- example_yaml/vue-utility-throttled-solar.yaml | 16 ++++++++++++---- example_yaml/vue-utility-throttled.yaml | 16 ++++++++++++---- 4 files changed, 35 insertions(+), 16 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index ba7927c..cec1b76 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -41,10 +41,11 @@ api: key: "M3d8zXcnwM4Uo2fRybLjFUNVs+mnlC1XbEfnlvUNI2c=" ``` -- Just a security measure. It’s a shared secret between your device and Home Assistant. +- This key is a shared secret between your device and Home Assistant. - Ensures all ESPHome API traffic (state updates, commands, etc.) is encrypted and authenticated. - Without it, someone on your LAN could spoof commands to the device. -- To generate one manually: +- The [official documentation](https://esphome.io/components/api/#configuration-variables) can generate a key. Find it under "If you need a key, you can use the key below; it is randomly generated by your browser each time this page loads:" +- Or, to generate one manually: ``` python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())" @@ -57,12 +58,13 @@ python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())" Looks like this in the YAML: ``` ota: + platform: esphome password: "blah" ``` -- Just a security measure. It’s a shared secret between your device and Home Assistant. -- Used only when flashing new firmware over Wi-Fi (OTA updates). +- This password is a shared secret between your device and ESPHome. +- Other instances of ESPHome would need to know this password in order to update your device with a new firmware. - Prevents anyone on your LAN from pushing firmware to the device without authorization. -- ESPHome generates one the first time if you don’t set it yourself. +- The `password:` is optional, but `ota:` is **required** if you want the ability to deploy firmware updates wirelessly. --- diff --git a/example_yaml/vue-utility-simple.yaml b/example_yaml/vue-utility-simple.yaml index 2db79a2..95db2ec 100644 --- a/example_yaml/vue-utility-simple.yaml +++ b/example_yaml/vue-utility-simple.yaml @@ -15,14 +15,15 @@ external_components: logger: # Enable Home Assistant API -# Encryption secures it. Any password will work. See FAQ. api: + # Encrypt the API communication with the given key. Must be a 32-byte base64-encoded string. See FAQ. encryption: - key: "some_password" + key: "eU79n2aex33uRofF9yvNIP5gwEFCi5GsVi2Rr3OydjY=" -# Secures OTA Updates. Any password will work. See FAQ. +# Secures OTA Updates. ota: platform: esphome + # Any password will work. See FAQ. password: "some_password" wifi: diff --git a/example_yaml/vue-utility-throttled-solar.yaml b/example_yaml/vue-utility-throttled-solar.yaml index 62a13fa..f9901fd 100644 --- a/example_yaml/vue-utility-throttled-solar.yaml +++ b/example_yaml/vue-utility-throttled-solar.yaml @@ -15,20 +15,28 @@ external_components: type: git url: https://github.com/nekorevend/esphome-emporia-vue-utility +# Enable Home Assistant API +api: + # Encrypt the API communication with the given key. Must be a 32-byte base64-encoded string. See FAQ. + encryption: + key: "eU79n2aex33uRofF9yvNIP5gwEFCi5GsVi2Rr3OydjY=" + +# Secures OTA Updates. +ota: + platform: esphome + # Any password will work. See FAQ. + password: "some_password" + # Add your own wifi credentials wifi: ssid: !secret wifi_ssid password: !secret wifi_password -ota: - logger: logs: # Change to DEBUG / INFO / WARN / ERROR as desired Vue: DEBUG -api: - mqtt: broker: !secret mqtt_broker id: vue_utility diff --git a/example_yaml/vue-utility-throttled.yaml b/example_yaml/vue-utility-throttled.yaml index 851bd13..31c378a 100644 --- a/example_yaml/vue-utility-throttled.yaml +++ b/example_yaml/vue-utility-throttled.yaml @@ -15,20 +15,28 @@ external_components: type: git url: https://github.com/nekorevend/esphome-emporia-vue-utility +# Enable Home Assistant API +api: + # Encrypt the API communication with the given key. Must be a 32-byte base64-encoded string. See FAQ. + encryption: + key: "eU79n2aex33uRofF9yvNIP5gwEFCi5GsVi2Rr3OydjY=" + +# Secures OTA Updates. +ota: + platform: esphome + # Any password will work. See FAQ. + password: "some_password" + # Add your own wifi credentials wifi: ssid: !secret wifi_ssid password: !secret wifi_password -ota: - logger: logs: # Change to DEBUG / INFO / WARN / ERROR as desired Vue: DEBUG -api: - mqtt: broker: !secret mqtt_broker id: vue_utility