Document the YAML configuration in the README.

2026-01-08 20:40:39 -07:00 · 2024-10-29 00:35:49 -07:00
parent cedc8d1bbf
commit 0abef4da8a
1 changed files with 124 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -41,6 +41,130 @@ Use either YAML file in the `example_yaml` directory and modify it to your likin

 Execute `esphome run vue-utility.yaml` or `esphome run vue-utility-solar.yaml` to build and install.

+## YAML configuration
+
+This sensor component provides **6** output values and takes **3** configuration options.
+
+A full configuration can look like this:
+```yaml
+# Boilerplate UART configuration.
+uart:
+  id: emporia_uart
+  rx_pin: GPIO21
+  tx_pin: GPIO22
+  baud_rate: 115200
+
+# The actual sensor configuration.
+sensor:
+  - platform: emporia_vue_utility
+    uart_id: emporia_uart
+    debug: true
+    update_interval: 15s
+    power:
+      name: "${name} Watts"
+    power_export:
+      name: "${name} Watts Returned"
+    power_import:
+      name: "${name} Watts Consumed"
+    energy:
+      name: "${name} Wh Net"
+    energy_export:
+      name: "${name} Wh Returned"
+    energy_import:
+      name: "${name} Wh Consumed"
+```
+
+Note: You likely do not need all of these fields.
+
+### Outputs
+
+The output values are all *optional* and categorized into instantaneous power (aka. watts) and total energy usage (aka. watt-hours) in "import", "export", and "net" variations. Their relationship is: `net = import - export`
+
+#### Watts
+- **power** = Net watt usage at that moment in time. Is negative if you have excess solar generation.
+- **power_import** = Watt usage from the grid at that moment in time. Is `0` if your solar generation currently exceeds your usage.
+- **power_export** = Watts sent to the grid at that moment in time. Is `0` if you are using more than your solar is generating.
+
+#### Watt-hours
+This is a total energy usage count for the lifetime of your utility meter. The only situations where the count will decrease is if the 32bit value experiences an integer overflow, or if your utility meter is replaced with a new one. For either situation, it is expected that the count(s) will reset to `0`.
+
+- **energy** = Total net watt-hour usage.
+- **energy_import** = Total watt-hours taken from the grid.
+- **energy_export** = Total watt-hours sent to the grid. Is perpetually `0` if you don't have solar generation.
+
+### Configurations
+
+#### UART
+
+We need to talk to the MGM chip that talks to the utility meter. This chip is connected to the ESP via `GPIO21` and `GPIO22` and the configuration is:
+```yaml
+uart:
+  id: emporia_uart
+  rx_pin: GPIO21
+  tx_pin: GPIO22
+  baud_rate: 115200
+```
+
+Then, within the `sensor:` configuration, you can add optionally add `uart_id: emporia_uart`. I believe it is optional if there is only one `uart:` defined as it should just use the one that exists.
+
+Example with the field added:
+```yaml
+sensor:
+  - platform: emporia_vue_utility
+    uart_id: emporia_uart
+    ...
+```
+
+#### Poll rate
+
+The `update_interval` lets you define the rate at which we ask the utility meter for a new reading. This defaults to `30` seconds, which is also the default in the Emporia stock firmware.
+
+Note that the utility meter has its own update rate, and if you poll more frequently it will just give you the same value as before. Some users report being able to receive new values every 5 seconds while I only see a new value every 15 seconds. You are welcome to trial-and-error and see how frequently you can get updated values and settle on a value that makes sense to you.
+
+Example with the field added:
+```yaml
+sensor:
+  - platform: emporia_vue_utility
+    update_interval: 15s
+    ...
+```
+
+#### Debug logs
+
+Add `debug: true` if you need to see additional details about issues you're experiencing.
+
+When enabled, each reading will cause the log to output something like this:
+```
+[00:05:17][D][emporia_vue_utility:360]: Meter Cost Unit: 1000
+[00:05:17][D][emporia_vue_utility:361]: Meter Divisor: 1
+[00:05:17][D][emporia_vue_utility:362]: Meter Energy Import Flags: 00596680
+[00:05:17][D][emporia_vue_utility:363]: Meter Energy Export Flags: 0078f478
+[00:05:17][D][emporia_vue_utility:364]: Meter Power Flags: 00038d2a
+[00:05:17][D][emporia_vue_utility:365]: Meter Import Energy: 5858.944kWh
+[00:05:17][D][emporia_vue_utility:366]: Meter Export Energy: 7926.904kWh
+[00:05:17][D][emporia_vue_utility:367]: Meter Net Energy: -2067.960kWh
+[00:05:17][D][emporia_vue_utility:368]: Meter Power:  909W
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes   0 to   3: 18 91 01 00
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes   4 to   7: 00 00 25 80
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes   8 to  11: 66 59 00 00
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes  12 to  15: 00 01 00 00
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes  16 to  19: 25 78 f4 78
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes  20 to  23: 00 00 00 01
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes  24 to  27: 03 00 22 01
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes  28 to  31: 00 00 02 03
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes  32 to  35: 00 22 e8 03
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes  36 to  39: 00 00 04 00
+[00:05:17][D][emporia_vue_utility:377]: Meter Response Bytes  40 to  43: 2a 8d 03 00
+```
+
+Example with the field added:
+```yaml
+sensor:
+  - platform: emporia_vue_utility
+    debug: true
+    ...
+```
+
 ## Meaning of LEDs

 There are three LEDs on the device, which have "power", "wifi" and "link" icons stenciled on the case.