From 00d84bd50c6089d66cf463491f3f82d295cec393 Mon Sep 17 00:00:00 2001 From: Diogo Gomes Date: Sat, 26 Jan 2019 15:33:42 +0000 Subject: [PATCH] Utility meter (#8025) * add utility_meter * updates * :pencil2: Tweaks * spellcheck * made it into an embedded component * sensor -> component * bump version --- source/_components/utility_meter.markdown | 130 ++++++++++++++++++ .../images/supported_brands/energy_meter.png | Bin 0 -> 3045 bytes 2 files changed, 130 insertions(+) create mode 100644 source/_components/utility_meter.markdown create mode 100644 source/images/supported_brands/energy_meter.png diff --git a/source/_components/utility_meter.markdown b/source/_components/utility_meter.markdown new file mode 100644 index 00000000000..0007d552880 --- /dev/null +++ b/source/_components/utility_meter.markdown @@ -0,0 +1,130 @@ +--- +layout: page +title: "Utility Meter" +description: "Instructions on how to integrate the Utility Meter into Home Assistant." +date: 2019-01-02 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Sensor +ha_release: 0.87 +ha_iot_class: "Local Push" +logo: energy_meter.png +ha_qa_scale: internal +--- + +The `utility meter` component provides functionality to track consumptions of various utilities (e.g., energy, gas, water, heating). + +From a user perspective, utility meters operate in cycles (usually monthly) for billing purposes. This sensor will track a source sensor values, automatically resetting the meter based on the configured cycle. On reset an attribute will store the previous meter value, providing the means for comparison operations (e.g., "did I spend more or less this month?") or billing estimation (e.g., through a sensor template that multiplies the metered value per the charged unit amount). + +Some utility providers have different tariffs according to time/resource availability/etc. The utility meter enables you to define the various tariffs supported by your utility provider and accounts your consumptions in accordance. When tariffs are defined a new entity will show up indicating the current tariff. In order to change the tariff, the user must call a service, usually through an automation that can be based in time or other external source (eg. a REST sensor). + + +## {% linkable_title Configuration %} + +To enable the Utility Meter Sensor in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +utility_meter: + energy: + source: sensor.energy_in_kwh +``` + +{% configuration %} +source: + description: The entity ID of the sensor providing utility readings (energy, water, gas, heating). + required: true + type: string +cycle: + description: How often to reset the counter. Valid values are `hourly`, `daily`, `weekly`, `monthly` and `yearly`. + required: true + type: string +offset: + description: Cycle reset occur at the beginning of the period (0 minutes, 0h00 hours, Monday, day 1, January). This option enables the offsetting of these beginnings. + required: false + default: 0 + type: integer +tariffs: + description: List of tariffs supported by the utility meter. + required: false + default: [] + type: list +{% endconfiguration %} + +# {% linkable_title Services %} + +### {% linkable_title Service `utility_meter.reset` %} + +Reset the Utility Meter. All sensors tracking tariffs will be reset to 0. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | no | String or list of strings that point at `entity_id`s of utility_meters. + +### {% linkable_title Service `utility_meter.next_tariff` %} + +Change the current tariff to the next in the list. +This service must be called by the user for the tariff switching logic to occur (e.g. using an automation) + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | no | String or list of strings that point at `entity_id`s of utility_meters. + +### {% linkable_title Service `utility_meter.select_tariff` %} + +Change the current tariff to the given tariff. +This service must be called by the user for the tariff switching logic to occur (e.g. using an automation) + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | no | String or list of strings that point at `entity_id`s of utility_meters. +| `tariff` | no | String that is equal to one of the defined tariffs. + +# {% linkable_title Advanced Configuration %} + +The following configuration shows an example where 2 utility_meters (`daily_energy` and `monthly_energy`) track daily and monthly energy consumptions. + +Both track the same sensor (`sensor.energy`) which continously monitors the energy consumed. + +4 different sensors will be created, 2 per utility meter and corresponding to each tariff. +Sensor `sensor.daily_energy_peak`, `sensor.daily_energy_peak`, `sensor.monthly_energy_peak` and `sensor.monthly_energy_offpeak` will automatically be created to track the consumption in each tariff for the given cycle. + +`utility_meter.daily_energy` and `utility_meter.monthly_energy` entities will track the current tariff and provide a service to change the tariff. + +```yaml +utility_meter: + daily_energy: + source: sensor.energy + cycle: daily + tariffs: + - peak + - offpeak + monthly_energy: + source: sensor.energy + cycle: monthly + tariffs: + - peak + - offpeak +``` + +Assuming your energy provider tariffs are time based according to: +- *peak*: from 9h00 to 21h00 +- *offpeak*: from 21h00 to 9h00 next day + +a time based automation can be used: + +```yaml +automation: + trigger: + - platform: time + at: '09:00:00' + - platform: time + at: '21:00:00' + action: + - service: utility_meter.next_tariff + entity_id: utility_meter.daily_energy + - service: utility_meter.next_tariff + entity_id: utility_meter.monthly_energy +``` diff --git a/source/images/supported_brands/energy_meter.png b/source/images/supported_brands/energy_meter.png new file mode 100644 index 0000000000000000000000000000000000000000..602af055d5389898de22b6d8a9190746f099f058 GIT binary patch literal 3045 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