Intégration Home Assistant – MEL Waste Collections¶
This documentation explains how to install and configure the mel_collecte custom component, and how to display collections in the Home Assistant interface (calendar and Trash Card).
1. Prerequisites¶
- Home Assistant Core, OS or Supervised (version ≥ 2024.6 recommended).
- Access to the
config/directory of your instance (Samba, VS Code, SSH…). - Internet connection to query the Publidata API of the European Metropolis of Lille.
2. Installing the Component¶
- Download the sources
-
Clone the repository or retrieve the
mel_collecte.ziparchive generated viamake build. -
Copy to Home Assistant
-
Extract the
custom_components/mel_collectefolder to your Home Assistant directory: -
Restart Home Assistant
- From the interface:
Settings → System → Restart. - Or via CLI:
ha core restart.
3. Adding the Integration¶
- Open
Settings → Devices & Services → Add Integration. - Search for "MEL Collecte des déchets".
- Enter your postal address (e.g.
19 rue Example, 59000 Lille). The integration uses the APIhttps://api.publidata.io/v2/geocoderto automatically retrieve the address ID, latitude, and longitude. The address is validated in real-time: if it cannot be found or if it is not in the service area of the European Metropolis of Lille, an explicit error message is displayed before creating the entry. - Validate: the entities are created after the first refresh (a few seconds).
4. Configuring Options¶
The integration allows you to customize several parameters after the initial addition:
- Go to
Settings → Devices & Services → MEL Collecte des déchets. - Click "Configure" next to the integration.
- The available options are:
- Update interval: data refresh frequency in days (1-30, default: 7).
- Forecast window: number of days to look ahead for collection events (7-365, default: 90).
- Visible waste types: selection of waste types to display. If no type is selected, all types are displayed (default behavior).
-
Labels language:
Français(default) orEnglish. Applies to sensor names, waste types, alerts, calendar events and units, independently of the Home Assistant language. -
Validate to save. The integration reloads automatically to apply the new options.
5. Available Entities¶
calendar.collectes_des_dechets: calendar containing all upcoming collections (90-day rolling window).sensor.prochaine_collecte: ISO date/time of the next collection, with attributes:types(raw codesomr,dv,enc, …),types_friendly(French labels: "Ordures ménagères résiduelles", "Déchets verts"…),mode(pickup, drop-off, appointment…),debut/fin.sensor.jours_avant_prochaine_collecte: indicates the integer number of days remaining until the next collection.sensor.collecte_<type>: one sensor per detected type (sensor.collecte_dechets_verts, etc.).sensor.alertes_collecte: number of active collection service alerts, with attributes:alerts: complete list of alerts with details (id, name, type, message, dates),last_alert_name: title of the last alert,last_alert_type: type of the last alert (danger,warning,info),last_alert_message: HTML content of the last alert.
All sensors are automatically updated according to the configured interval + on startup.
6. Displaying in Home Assistant¶
6.1 Internal Calendar¶
- Go to
Dashboards → Add Card → Calendar. - Select
calendar.collectes_des_dechets. - The calendar displays all generated collections (up to the configured forecast window).
6.2 Trash Card¶
For a more visual presentation, you can use the community Trash Card (idaho/hassio-trash-card). This card reads your calendars and displays upcoming collections, with customizable icons and colors.
Quick Installation¶
- Install Trash Card via HACS (or by copying the provided files in the repository).
- Restart Home Assistant or reload Lovelace.
Configuration with mel_collecte¶
The calendar.collectes_des_dechets calendar is used as the source. Events are created with readable French labels: "Ordures ménagères résiduelles", "Déchets verts", "Emballages recyclables", etc.
Example YAML configuration:
type: custom:trash-card
entities:
- calendar.collectes_des_dechets
next_days: 120
pattern:
- label: Residual waste
icon: mdi:trash-can
color: grey
pattern: Ordures ménagères résiduelles
type: waste
- label: Packaging
icon: mdi:recycle
color: yellow
pattern: Emballages recyclables
type: recycle
- label: Biowaste
icon: mdi:leaf
color: brown
pattern: Déchets verts
type: organic
- label: Biowaste
icon: mdi:food-apple
color: brown
pattern: Biodéchets
type: organic
- label: Glass
icon: mdi:bottle-wine
color: green
pattern: Verre
type: others
- label: Bulky items
icon: mdi:sofa
color: purple
pattern: Encombrants
type: others
Colors: they follow the MEL bins — grey lid for residual waste, yellow for packaging, brown for biowaste (the MEL publishes door-to-door biowaste collection under the
dvcode, hence the "Déchets verts" pattern). Glass, collected at drop-off points, is green. Without atypeor a matching pattern, Trash Card falls back to its default color (purple).Important:
pattern(detection field) must exactly match the calendar event label. Sensors provide the complete list via thetypes_friendlyattribute; you can check it inDeveloper Tools → States.
6.3 Alert Card¶
To display collection service alerts, use a Markdown card:
type: markdown
title: 🚨 Collection Alerts
content: |
{% set alerts = state_attr('sensor.alertes_collecte', 'alerts') %}
{% if alerts and alerts | length > 0 %}
{% for alert in alerts %}
### {{ alert.type_friendly }} – {{ alert.name }}
{{ alert.message | regex_replace('<[^>]+>', '') | truncate(200) }}
*Published on {{ alert.published_at[:10] }}*
---
{% endfor %}
{% else %}
No active alerts.
{% endif %}
This card displays all active alerts with their type (⚠️ Alert, ℹ️ Information), title, and message.
7. Possible Automations¶
7.1 Native Events (New)¶
The integration automatically triggers a mel_collecte.collection_upcoming event when a collection is approaching. This allows you to create simple automations without using templates.
Configuring the delay: By default, the event is triggered 24 hours before the collection starts. You can modify this delay via the mel_collecte.set_collection_offset service:
Automation example:
automation:
- trigger:
- platform: event
event_type: mel_collecte.collection_upcoming
condition:
- condition: template
value_template: "{{ trigger.event.data.garbage_types | first == 'omr' }}"
action:
- service: notify.mobile_app
data:
message: "Remember to take out the grey bin in {{ trigger.event.data.hours_until }} hours!"
7.2 Other Automations¶
- Day-before notification: trigger at 8 PM if
sensor.collecte_dechets_verts_dansis at 1. - Voice reminder: use
sensor.prochaine_collectein a TTS script. - Bin management: combine with an
input_booleanto know which bin was put out.
8. Troubleshooting¶
- No collections created: check the address (MEL must serve this street). The log may contain errors if the API returns nothing.
- Incorrect schedules: Publidata data is authoritative. Events are generated from
opening_hoursslots. If an unexpected format appears, open an issue on the repository. - Trash Card not displaying: check that the calendar entity is properly configured in the card and that patterns match exact labels.
- Waste types not displayed: check in the options that the desired types are selected. An unselected type appears neither in sensors nor in the calendar.
- Manual refresh: You can call the
mel_collecte.force_refreshservice via Developer Tools → Services to force an immediate update without restarting Home Assistant.
8.1 Retry Logic and Error Handling¶
The integration distinguishes two categories of errors when calling the Publidata API:
| Category | Examples | Behavior |
|---|---|---|
| Transient error | Network error, timeout, HTTP 429 (too many requests), HTTP 5xx | Automatic retry up to 3 times with exponential delay (1 s, 2 s, 4 s) |
| Permanent error | HTTP 400, 401, 403, 404 (invalid address, incorrect API key) | No retry — error raised immediately |
In case of HTTP 429 (Too Many Requests), the Retry-After header is respected if present; otherwise exponential backoff applies with a 30-second ceiling.
After exhausting all retries, the coordinator marks the update as failed but does not crash Home Assistant. The next scheduled update will start from the beginning.
Data freshness tracking: the last_update_success attribute (available in Developer Tools → States on each entity) indicates the ISO timestamp of the last successful retrieval. If this value is old while the integration appears active, check the logs for repeated transient errors.
Consulting logs: transient errors are logged at the WARNING level (not ERROR), which allows you to filter them easily in Settings → System → Logs.
9. Updating¶
- Copy the new
custom_components/mel_collectefolder over the old one. - Restart Home Assistant.
- Registered options are preserved during the update.
Enjoy! Feel free to contribute or report a malfunction via the repository issues. Improvements (dedicated icons, appointment management, etc.) are being considered. 👍