Skip to content
πŸ—‘ Custom Home Assistant sensor for scheduling garbage collection (or other regularly re-occurring events - weekly on given days, semi-weekly or monthly)
Branch: development
Clone or download
Latest commit d3abfa7 Sep 16, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
custom_components/garbage_colection Update Sep 16, 2019
images Create entities.png Aug 28, 2019 Update Sep 16, 2019
hacs.json Update hacs.json Aug 25, 2019 Updated documentation Sep 16, 2019

Garbage Collection

The garbage_collection component is a Home Assistant custom sensor for monitoring regular garbage collection schedule. The sensor can be configured for weekly schedule (including multiple collection days), bi-weekly in even or odd weeks, or monthly schedule (nth day each month). You can also configure seasonal calendars (e.g. for bio-waste collection), by configuring the first and last month.

Table of Contents



  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. Configure the garbage_collection sensor.
  4. Restart Home Assistant.


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


Add garbage_collection sensor in your configuration.yaml. The following example adds three sensors - bio-waste with bi-weekly schedule, waste with weekly schedule and large-waste with monthly schedule on 1st Saturday each month:

# Example configuration.yaml entry
  - platform: garbage_collection
    name: waste # Each week on Monday and Wednesday
    frequency: "weekly"
    - mon
    - wed
  - platform: garbage_collection
    name: "Bio-waste" # Bi-weekly (odd weeks) on Thursday. Between March and November
    frequency: "odd-weeks"
    first_month: "mar"
    last_month: "nov"
    collection_days: "thu"
  - platform: garbage_collection
    name: "Large waste" # First and third saturday each month
    frequency: "monthly"
    collection_days: "sat"
    - 1
    - 3
  - platform: garbage_collection
    name: Paper # Every 4 weeks on Tuesday, starting on 4th week each year
    frequency: "every-n-weeks"
    collection_days: "tue"
    period: 4
    first_week: 4
  - platform: garbage_collection
    name: "Waste not on Holidays" # No collection on Christmas, added extra collection on the 27th
    frequency: "weekly"
    - wed
    - '2019-12-25'
    - '2019-12-27'


Attribute Optional Description
platform No garbage_collection
collection_days No Day three letter abbreviation, list of "mon", "tue", "wed", "thu", "fri", "sat", "sun"
frequency Yes "weekly", "even-weeks", "odd-weeks" "every-n-weeks" or "monthly"
Default: "weekly"
(The week number is using ISO-8601 numeric representatio of the week)
name Yes Sensor friendly name
Default: "garbage_collection"
first_month Yes Month three letter abbreviation, e.g. "jan", "feb"...
Default: "jan"
last_month Yes Month three letter abbreviation.
Default: "dec"
monthly_day_order_number Yes List of week numbers of collection_day each month. E.g., if collection_day is "sat", 1 will mean 1st Saturday each month (integer 1-4)
Default: 1
(relevant for monthly_collection)
period Yes Collection every "period" weeks (integer 1-53)
Default: 1
(relevant for every-n-weeks)
first_week Yes First collection on the "first_week" week (integer 1-53)
Default: 1
(The week number is using ISO-8601 numeric representatio of the week)
(relevant for every-n-weeks)
exclude_dates Yes List of dates with no collection (using international date format 'yyyy-mm-dd'.
include_dates Yes List of extra collection (using international date format 'yyyy-mm-dd'.
icon_normal Yes Default icon Default: mdi:trash-can
icon_today Yes Icon if the collection is today Default: mdi:delete-restore
icon_tomorrow Yes Icon if the collection is tomorrow Default: mdi:delete-circle
verbose_state Yes The sensor state will show collection date and remaining days, instead of number Default: False

IMPORTANT - put include/exclude dates within quotes. Dates without quotes might cause Home Assistant not loading configuration when starting - in case the date is invalid. Validation for dates within quotes works fine. I think this is general bug, I am addressing that. (See the example above)



The state can be one of

Value Meaning
0 Collection is today
1 Collection is tomorrow
2 Collection is later

If the verbose_state parameter is set, it will show date and remaining days, for example "Today" or "Tomorrow" or "on 10-Sep-2019, in 2 days"


Attribute Description
next_date The date of next collection
days Days till the next collection

Buy Me A Coffee

You can’t perform that action at this time.