Documentation fixes, and a few changes. (#11)

README.md

@@ -48,9 +48,10 @@ Need help?
 Note: There is a **pairing process**. It is advisable to pair the Vue with your utility meter using the stock firmware and the Emporia app first.
 
 **2. Hardware**
-- **Emporia Vue Utility Connect** — purchase from [Emporia’s store](https://shop.emporiaenergy.com/products/utility-connect).  
+- **Emporia Vue Utility Connect** — purchase from [Emporia’s store](https://shop.emporiaenergy.com/products/utility-connect).
 - **USB-to-Serial adapter** — required for initial flashing.  See: [Wiring and USB adapter](docs/wiring_and_usb.md)
 - **Basic wiring hardware and skills** — you will need to open the Vue and connect to a row of through-hole pads.  See: [Wiring and USB adapter](docs/wiring_and_usb.md)
+- USB type A Power Supply **(optional)** - some Emporia USB power supplies have failed, which can appear like the device is powered but not working.  You may want to use something else.
 
 **3. Software**
 - **ESPHome** — the toolchain to build the firmware and flash it onto the Vue.  There are options.  See: [Installing ESPHome](docs/installing_esphome.md)
@@ -70,7 +71,7 @@ Let's say you flash your Vue device and it's working, but later your smart meter
 
 So should you flash the Vue with this firmware as soon as you receive it?  This is not advised.  **It is better to pair it with stock firmware** and use the Emporia App to confirm it is working.  This is the supported way to do so, and if you have any problems you can get the support of Emporia.
 
-**Note:** The Vue device needs to wirelessly talk to your meter, and your Wi-Fi at the same time to properly function.  So it needs to be located within range of both, and it is best to work in such a location.  This is important whenever you expect the device to be working (pairing the device, and testing it after flashing).
+**Note:** The Vue device needs to wirelessly talk to your meter and your Wi-Fi at the same time to properly function.  So it needs to be located within range of both, and it is best to work in such a location.  This is important whenever you expect the device to be working (pairing the device, and testing it after flashing).
 
 
 ----
@@ -105,7 +106,7 @@ Pick one of the [example YAML files](example_yaml/) in this project as a startin
 
 In any case, you will need to customize it.
 1. for ESPHome CLI, you will do this in a text file on your computer.
-2. for ESPHome Device Builder, you will do within the Device Builder editor in Home Assistant UI.
+2. for ESPHome Device Builder, you will do this within the Device Builder editor of the Home Assistant UI.
 
 Minimally, you need to fill out this section of the YAML file.  By default, ESPHome looks in a file called `secrets.yaml` for them.
 
@@ -136,7 +137,7 @@ mqtt:
 
 ### 6. Compile and Flash:
 
-Whether you use the ESPHome CLI or the Device Builder, the first time you flash you will need to do this with a USB to TTL Adapter.  After that, you will be given the option to flash over wifi, which is much faster.
+Whether you use the ESPHome CLI or the Device Builder, the first time you flash you will need to do this with a USB to TTL Adapter.  After that, you will be given the option to flash over Wi-Fi, which is much faster.
 
 **Reminder:** triple check your wiring, making sure you are not connecting +5V to anything other than pin 6.  You can now plug it into your computer and the Vue device should power up and start working as normal.  ESPHome will flash it when it comes time.
 
@@ -144,7 +145,7 @@ You would do **ONE** of these steps depending on which [ESPHome Install method](
 
 #### A) For ESPHome CLI:
 
-You **do not need** to clone this git repo.  Even though this project has custom code in it (Python and C++), ESPHome will download the latest custom code from this project automatically from GitHub as part of the compilation step.  Assuming you called this file `vue-utility-simple.yaml` from the previous step, you would run:
+You **do not need to clone this git repo**.  Even though this project has custom code in it (Python and C++), ESPHome will download the latest custom code from this project automatically from GitHub as part of the compilation step.  Assuming you called this file `vue-utility-simple.yaml` from the previous step, you would run:
 
 ```
 esphome run vue-utility-simple.yaml
@@ -162,8 +163,10 @@ This should build the firmware and flash the device all on the command line.
 - Click `Install`.
 
 This should build the firmware and flash the device all within the web browser:
-- ESPHome uses WebSerial (a browser API supported in Chrome/Edge).  ESPHome compiles the firmware on your HA server, streams it over WebSerial and flashes the Vue on your computer.
-- To be clear: if Home Assistant is running on a Raspberry Pi in a closet, you will have the USB to TTL Adapter connected to your computer, not the Raspberry Pi.
+- ESPHome compiles the firmware on your HA server.
+- ESPHome can flash the Vue over USB when it is either:
+  - connected to the HA server, or
+  - connected to your computer (using WebSerial)
 
 
 ----
@@ -172,15 +175,17 @@ This should build the firmware and flash the device all within the web browser:
 
 Install the [ESPHome Integration](https://www.home-assistant.io/integrations/esphome) in Home Assistant.  You can you do this ahead of time of course.
 
+----
+
 That's it.
 
 If everything works, Home Assistant will detect the Vue and automatically create a device and associated sensor entites.  You should be able to read your energy usage immediately.  See [Basics Explained](docs/basics.md) for what that looks like.
 
 #### Bonus:
 
-Set up the [Energy Module](https://www.home-assistant.io/home-energy-management/) in Home Assistant.  Just go to the `Energy configuration` page and:
- - add the `Utility Watt-hours Consumed` to `Grid consumption`
- - add the `Utility Watt-hours Produced` to `Returned to Grid`
+Set up the [Energy Dashboard](https://www.home-assistant.io/home-energy-management/) in Home Assistant.  Just go to the `Energy configuration` page and:
+ - add `Utility Watt-hours Consumed` to `Grid consumption`
+ - add `Utility Watt-hours Produced` to `Returned to Grid`
 
 <br>
 
@@ -225,7 +230,7 @@ Got Questions?  Check out the [Frequently Asked Questions](docs/faq.md).  Then h
 There are three LEDs on the device, which have "power", "wifi" and "link" icons stenciled on the case.
 
 - **Power** = An ESPHome status led. Slowly flashing means warning, quickly flashing means error, solid on means OK. See [status_led](https://esphome.io/components/status_led.html) docs.
-- **Wifi** = Normally solid on, will briefly flash each time a meter rejoin is attempted which indicates poor signal from the meter.
+- **Wi-Fi** = Normally solid on, will briefly flash each time a meter rejoin is attempted which indicates poor signal from the meter.
 - **Link** = Flashes off briefly about once every 5 seconds. More specifically, the LED turns off when a reading from the meter is requested and turns back on when a response is received. If no response is received then the LED will remain off. If this LED is never turning on then no readings are being returned by the meter.
 
 ## More Details

docs/basics.md

@@ -28,7 +28,7 @@ The ESPHome Integration is quite magical.  Once your device is flashed and runni
 
 ![ESPHome integration](esphome_screenshot.png)
 
-### Energy module
-You can add the cumulative sensors **Watt-hours Consumed** and **Watt-hours Produced** Home Assistant’s [Energy module](https://www.home-assistant.io/home-energy-management/). This provides a polished and feature-rich view of your energy usage and production.
+### Energy dashboard
+You can add the cumulative sensors **Watt-hours Consumed** and **Watt-hours Produced** to Home Assistant’s [Energy dashboard](https://www.home-assistant.io/home-energy-management/). This provides a polished and feature-rich view of your energy usage and production.
 
-![Energy module](energy_screenshot.png)
+![Energy dashboard](energy_screenshot.png)

docs/faq.md

@@ -26,7 +26,7 @@ Later, if you want to customize, see the [section on YAML configuration](yaml.md
 
 ### 4. I'm getting intermittent drop outs.  What do I check?
 
-- First: **swap the USB power supply**.  We have seen a number of the Emporia supply USB power supplies fail, which started out like this and the device failing.
+- First: **swap the USB power supply**.  We have seen a number of the Emporia USB power supplies fail, which started out like this.
 - You may need to move the device closer to your power meter.
 - You may need to contact your utililty and ask them to reprovision the device.
 
@@ -38,13 +38,17 @@ Looks like this in the YAML:
 ```
 api:
   encryption:
-    key: "blah"
+    key: "M3d8zXcnwM4Uo2fRybLjFUNVs+mnlC1XbEfnlvUNI2c="
 ```
 
 - Just a security measure.  It’s 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.
-- ESPHome generates one if you don’t set it yourself.
+- To generate one manually:
+
+```
+python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"
+```
 
 ---
 
@@ -52,9 +56,8 @@ api:
 
 Looks like this in the YAML:
 ```
-api:
-  encryption:
-    key: "blah"
+ota:
+  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).

docs/installing_esphome.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-If this is your time to [ESPHome](https://esphome.io/), the terminology can be confusing. You may hear “flash ESPHome on your device”, but that’s not a totally accurate statement.
+If this is your first time to [ESPHome](https://esphome.io/), the terminology can be confusing. You may hear "flash ESPHome on your device", but that’s not a totally accurate statement.
 
 ESPHome is a **framework and toolchain** for creating custom firmware. This usually involves:
 - Writing a short YAML configuration file, and optionally providing custom code.
@@ -21,7 +21,7 @@ There are multiple ways to do this and much of the documentation out there is di
 
 You will interact with two distinct parts of ESPHome:  
 1. **ESPHome** — this is software you will use this to back up the stock firmware, compile this project, and flash the Vue.  There are two main ways to do this, with some caveats.
-2. **ESPHome integration** — you only need to install the [ESPHome Integration](https://www.home-assistant.io/integrations/esphome) in Home Assistant.  It is quite magical.  Once the Vue is flashed and running on Wi-Fi, it will auto-discover it and create the sensor entities automatically.
+2. **ESPHome Integration** — you only need to install the [ESPHome Integration](https://www.home-assistant.io/integrations/esphome) in Home Assistant.  It is quite magical.  Once the Vue is flashed and running on Wi-Fi, it will auto-discover it and create the sensor entities automatically.
 
 
 ### How ESPHome works
@@ -46,7 +46,7 @@ This gives you a CLI (command-line interface) to run ESPHome.  You run this in t
  - Better for developers: quick iteration, local editing of YAML/Python/C++.
  - Flexible: you can use local custom code without publishing to GitHub.
  - Full control over build logs, debugging, and advanced options.
- - You **can** backup the original firmware with this.
+ - You **can backup the original firmware** with this.
 
 
 #### 2. ESPHome Device Builder --- [install guide](https://esphome.io/guides/getting_started_hassio/#installing-esphome-device-builder)
@@ -56,13 +56,13 @@ This is a Home Assistant add-on.  It is basically a UI wrapper for the ESPHome C
  - Runs inside Home Assistant (web UI).
  - Better for end users: simpler UI.
  - Initial flashing still happens on your PC.  It works using WebSerial (via a browser).
- - You **cannot** use this to backup the original firmware.
+ - You **cannot use this to backup the original firmware**.
 
 
 ### What is best for you?
 
-- If you are adamant about [backing up the original Vue firmware](backup_firmware.md), minimally install the CLI just to get the backup step done.  You can use either the CLI or the Device Builder to program and flash, and you can switch between them as well.
+- If you are adamant about [backing up the original Vue firmware](backup_firmware.md), minimally install the CLI just to get the backup step done.  You can use either the CLI or the Device Builder to program and flash, and you can switch between them at any time as well.
 
-- If you like working from the command line and want full control, the ESPHome CLI is straightforward: you write YAML by hand, build, and flash. It’s lean, reproducible, and great if you’re already comfortable with terminals.
+- If you like working from the command line and want full control, the ESPHome CLI is straightforward: you write YAML in a text file, build, and flash. It’s lean, reproducible, and great if you’re already comfortable with terminals.
 
 - The Device Builder adds a friendlier interface.  It’s easier for beginners, integrates neatly with Home Assistant, and makes troubleshooting or rebuilding devices more point-and-click.

docs/wiring_and_usb.md

@@ -77,7 +77,6 @@ Flashing tools (like `esptool`, used by ESPHome) do not have “EN/IO0” pins.
 
 On some USB-serial adapters, those labels or polarities are effectively flipped. That’s why you’ll sometimes need to swap the connections.
 
-
 Many ESP32 dev boards (NodeMCU/WROOM devkits) hide this logic behind transistors/inverters, so you never think about it. **Bare USB-TTL dongles expose raw DTR/RTS**, where names and polarity are not standardized.
 - **Label drift:** Some boards label the header “RTS” where the chip is actually driven like DTR (or vice-versa).
 - **Polarity/inversion:** CH340, CP210x, FTDI, etc. often invert DTR/RTS differently. A vendor may “fix” this on the PCB without changing the silkscreen names.
@@ -104,5 +103,5 @@ Those all mean EN/IO0 aren’t being driven with the expected timing and polarit
 
 ### Why `--before usb_reset` sometimes works
 
-`--before usb_reset` avoids DTR/RTS entirely by bouncing the USB device. That can momentarily create the right conditions for the bootloader, but it’s crude and unreliable.  It also explains why some people need to manually unplug/replug after flashing. Fixing EN/IO0 mapping makes this unnecessary.
+The underlying `esptool` has a `--before usb_reset` option, which can work. It avoids DTR/RTS entirely by bouncing the USB device. That can momentarily create the right conditions for the bootloader, but it’s crude and unreliable. It also explains why some people need to manually unplug/replug after flashing. Fixing EN/IO0 mapping makes this unnecessary.
 

docs/yaml.md

@@ -9,7 +9,7 @@ The example YAMLs should work out of the box, provided you fill in the necessary
 ### Examples
 
 - The [Web Server](https://esphome.io/components/web_server/) component adds a browser-accessible web UI with sensors and logs. Neat, but it duplicates functionality already in Home Assistant, and consumes a lot of memory on the device. If you won’t use it, disable it.
-- The [WiFi Signal Strength](https://esphome.io/components/sensor/wifi_signal/) component creates a sensor in HA showing the devices Wi-Fi strength.  You can also see this is the device logs.  Handy for troubleshooting, but once the connection is stable you may not need an extra entity cluttering HA.
+- The [WiFi Signal Strength](https://esphome.io/components/sensor/wifi_signal/) component creates a sensor in HA showing the devices Wi-Fi strength.  You can also see this in the device logs.  Handy for troubleshooting but once the connection is stable, you may not need an extra entity cluttering HA.
 - The [Uptime Sensor](https://esphome.io/components/sensor/uptime/?utm_source=chatgpt.com) reports how long the device has been running since the last reboot. Handy for debugging stability (e.g. “is my device randomly restarting?”). But if you don’t actively monitor it, it’s more HA clutter.
 - [MQTT](https://esphome.io/components/mqtt/) is a powerful but more complex alternative to HA’s native ESPHome API.  It is essential for some setups, but if you don’t already use MQTT, you can remove it.