End of Support

Home Assistant has introduced local calendars in 2022, in the 2023.1 release they added an option for different recurent events. With this, most of the functionality of this custom helper is supported natively. So I will end developing and supporting this helper in 2023.

Table of Contents

• Description

• Installation

  • Manual Installation
  • Installation via Home Assistant Community Store (HACS)

• Configuration

• Blueprints for Manual Update

  • Public Holidays
  • Include and Exclude
  • Offset
  • Import TXT
  • Monthly on a fixed date

• State and Attributes

• Lovelace configuration examples

Garbage Collection

The garbage_collection component is a Home Assistant helper that creates a custom sensor for monitoring a regular garbage collection schedule. The sensor can be configured for a number of different patterns:

• weekly schedule (including multiple collection days, e.g. on Tuesday and Thursday)
• every-n-weeks repeats every period of weeks, starting from the week number first_week. It uses the week number - therefore, it restarts each year, as the weeks start from number 1 each year.
• bi-weekly in even-weeks or odd-weeks (technically, it is the same as every 2 weeks with 1^st or 2^nd first_week)
• every-n-days (repeats regularly from the given first date). If n is a multiply of 7, it works similar to every-n-weeks, with the difference that it does not use the week numbers (that restart each year) but continues infinitely from the initial date.
• monthly schedule (n^th weekday each month), or a specific weekday of each n^th week. Using the period it could also be every 2^nd, 3^rd etc month.
• annually (e.g. birthdays). This is once per year. Using include dates, you can add additional dates manually.
• blank does not automatically schedule any collections - to be used in cases where you want to make completely own schedule with manual_update.

You can also configure seasonal calendars (e.g. for bio-waste collection), by configuring the first and last month. And you can group entities, which will merge multiple schedules into one sensor.

These are some examples using this sensor. The Lovelace config examples are included below.

Installation

MANUAL INSTALLATION

1. Download the latest release.
2. Unpack the release and copy the custom_components/garbage_collection directory into the custom_components directory of your Home Assistant installation.
3. Restart Home Assistant.
4. Configure the garbage_collection helper.

INSTALLATION VIA Home Assistant Community Store (HACS)

1. Ensure that HACS is installed.
2. Search for and install the "Garbage Collection" integration.
3. Restart Home Assistant.
4. Configure the garbage_collection helper.

Configuration

Go to Settings/Devices & Services/Helpers, click on the + CREATE HELPER button, select Garbage Collection and configure the helper.
If you would like to add more than one collection schedule, click on the + CREATE HELPER button again and add another Garbage Collection helper instance.

The configuration hapend in 2 steps. In the first step, you select the frequency and common parameters. In the second step you configure additional parameters depending on the selected frequency.

The configuration via configuration.yaml has been deprecated. If you have previously configured the integration there, it will be imported to ConfigFlow, and you should remove it.

STEP 1 - Common Parameters

STEP 2 - parameters depending on the selected frequency

...FOR ALL FREQUENCIES EXCEPT ANNUAL, GROUP and BLANK

...FOR ALL FREQUENCIES EXCEPT ANNUAL, EVERY-N-DAYS, GROUP and BLANK

...FOR COLLECTION EVERY-N-WEEKS

...FOR COLLECTION EVERY-N-DAYS

...FOR MONTHLY COLLECTION

The monthly schedule has two flavors: it can trigger either on the n^th occurrence of the weekday in a month, or on the weekday in the n^th week of each month.

...FOR ANNUAL COLLECTION

...FOR GROUP

Blueprints for Manual Update

Prerequisites

1. To use the blueprints, you need to set the garbage_collection entity for Manual update, that will fire the garbage_collection_loaded event on each sensor update and trigger the automation blueprint.
2. Install/Import blueprint
3. From the blueprint, create and configure the automation

Public Holidays

There are a couple of blueprints, automatically moving the collection falling on a public holiday. Or if there was a public holiday in the week before the scheduled collection.

The Public Holidays blueprints use a separate custom helper Holidays, available through HACS, that you can configure for different countries.

	Move the collection to the next day, if the collection falls on public holiday
	Remove events falling on provided "exclude" list of dates. Then check the calendar of public holidays and move events that fall on a public holiday to the next day. Finally, add additional events on dates from "include" list.
	Move forward one day if a public holiday was in the collection week, before or on the collection day (and keep moving if the new collection day also falls on a holiday)
	Move forward by a day for each public holiday was in the collection week, before or on the collection day (and keep moving if the new collection day also falls on a holiday). So if there were two public holidays, move by two days.
	Move forward by one day if there was a public holiday in the collection week, before or on the collection day (and keep moving if the new collection day also falls on a holiday). Only move by one day, but if there was more than one public holiday in the week, carry it over to the following week. So if there were 2 public holidays this week, move it by one day this week and one day next week.
	Skip the holiday

Include and Exclude

A list of fixed dates to include and exclude from the calculated schedule.

	Include and Exclude
	Include
	Exclude

Offset

The offset blueprint will move the calculated collections by a number of days. This can be used, for example, to schedule collection for last Saturday each month - just set the collection to the first Saturday each month and offset it by -7 days.

Import txt

This blueprint requires a command_line sensor reading content of a txt file, containig a set of dates, one per line.

#!/bin/bash
new_dates=$(for x in $(cat /share/import_dates.txt); do
                if [[ $(date -d $x +"%y%m%d") -ge $(date +"%y%m%d") ]]; then
                    echo $x
                fi
            done)
echo "$new_dates" | head -n20

sensor:
  - platform: command_line
    name: Import dates
    command: "sh /share/import_dates.sh"

Monthly on a fixed date

This will create a schedule on a fixed date each month. For example on the 3rd each month. The helper does not allow it, as it is generally designed around paterns evolving around weekly schedules (since garbage collection typically happens on a set day in a week, rather than set day in a month). But few of you wanted that, so here you go.

One fixed date

Two dates

STATE AND ATTRIBUTES

State

The state can be one of

If the verbose_state parameter is set, it will show the date, and the remaining days. For example: "Today" or "Tomorrow" or "on 10-Sep-2019, in 2 days" (configurable)

Attributes

Services

garbage_collection.collect_garbage

If the collection is scheduled for today, mark it completed and look for the next collection. It will set the last_collection attribute to the current date and time.

Manual update

There are standard blueprints provided to handle manual updates - to move collection on public holidays or offset the collection.

If these blueprints do not work for you, you can create your own custom rules to handle any scenario. If you do so, please share the blueprints with the others by posting them to the blueprints directory - someone else might find them useful. Thanks! To help you with creating custom automations, see the following examples:

!!! Advanced !!! If you think this is too complicated, then this is not for you!!!

flowchart TD
    A[HA updates entity] -->B[triggered garbage_collection_loaded event]
    B --> C[calling services]
    C --> D[garbage_collection.add_date] & E[garbage_collection.remove_date] & F[garbage_collection.offset_date] --> C
    D & E & F --> G[manual update finished -> garbage_collection.update_state]

alias: garbage_collection event
description: "Manually add a collection date, then trigger entity state update."
trigger:
  - platform: event
    event_type: garbage_collection_loaded
    event_data:
      entity_id: sensor.test
action:
  - service: garbage_collection.add_date
    data:
      entity_id: "{{ trigger.event.data.entity_id }}"
      date: "2022-01-07"
  - service: garbage_collection.update_state
    data:
      entity_id: sensor.test
mode: single

alias: test garbage_collection event
description: "Loop through all calculated dates, add extra collection a day after the calculate one"
trigger:
  - platform: event
    event_type: garbage_collection_loaded
    event_data:
      entity_id: sensor.test
action:
  - repeat:
      for_each: "{{ trigger.event.data.collection_dates }}"
      sequence:
        - service: garbage_collection.add_date
          data:
            entity_id: "{{ trigger.event.data.entity_id }}"
            date: >-
              {{( as_datetime(repeat.item) + timedelta( days = 1)) | as_timestamp | timestamp_custom("%Y-%m-%d") }}
  - service: garbage_collection.update_state
    data:
      entity_id: "{{ trigger.event.data.entity_id }}"
mode: single

alias: test garbage_collection event
description: >-
  Loop through all calculated dates, move the collection by 1 day if a public holiday was in the week before or on the calculated collection date calculate one
trigger:
  - platform: event
    event_type: garbage_collection_loaded
    event_data:
      entity_id: sensor.test
action:
  - repeat:
      for_each: "{{ trigger.event.data.collection_dates }}"
      sequence:
        - condition: template
          value_template: >-
            {%- set collection_date = as_datetime(repeat.item) %}
            {%- set ns = namespace(found=false) %}
            {%- for i in range(collection_date.weekday()+1) %}
              {%- set d = ( collection_date + timedelta( days=-i) ) | as_timestamp | timestamp_custom("%Y-%m-%d") %}
              {%- if d in state_attr(trigger.event.data.entity_id,'holidays') %}
                {%- set ns.found = true %}
              {%- endif %}
            {%- endfor %}  
            {{ ns.found }}
        - service: garbage_collection.offset_date
          data:
            entity_id: "{{ trigger.event.data.entity_id }}"
            date: "{{ repeat.item }}"
            offset: 1
  - service: garbage_collection.update_state
    data:
      entity_id: "{{ trigger.event.data.entity_id }}"
mode: single

Lovelace config examples

For information/inspiration - not supported.

Garbage Collection custom card

You can use the custom garbage collection card developed by @amaximus.

With images (picture-entity)

This is what I use (I like images). I use a horizontal stack of picture-entities, with card-templater plugin (Lovelace Card Templater) to show the number of days:

(The state is designed to be used as traffic lights. That's why it has 3 values. You obviously cannot use this with verbose_state)

This is the configuration

- type: "custom:card-templater"
  card:
    type: picture-entity
    name_template: >-
      {{ state_attr('sensor.bio','days') }} days
    show_name: True
    show_state: False
    entity: sensor.bio
    state_image:
      "0": "/local/containers/bio_today.png"
      "1": "/local/containers/bio_tomorrow.png"
      "2": "/local/containers/bio_off.png"
  entities:
    - sensor.bio

List view (entities)

The simplest visualization is to use entities. In this case, I use verbose_state to show state as text.

Lovelace configuration

- type: entities
  entities:
    - sensor.general_waste
    - sensor.bio
    - sensor.paper
    - sensor.plastic

Icon view (glance)

Lovelace Configuration

- type: glance
  entities:
    - sensor.general_waste