Clarify docs and make example yamls consistent. (#12)

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.
+- This password is a shared secret between your device and ESPHome.
-- Used only when flashing new firmware over Wi-Fi (OTA updates).
+- 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.
 
 ---
 

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:

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

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