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 00000000000..602af055d53 Binary files /dev/null and b/source/images/supported_brands/energy_meter.png differ