haos-blueprints/Common/Dreame Vacuum/README.md

# Dreame Vacuum Notifications

Sends customizable notifications for Dreame vacuum events. Requires the [Dreame Vacuum](https://github.com/Tasshack/dreame-vacuum) integration and Home Assistant 2024.7+ (`notify.send_message` action).

## Features

- Notifications for cleaning started and completed
- Consumable end-of-life alerts (brush, filter, mop pad, sensor, etc.)
- Device warning and error notifications
- Informational alerts (e.g., action blocked by Do Not Disturb)
- Friendly, readable labels for cleaning mode and status (raw enum names are translated)
- Optional localization: override any label, and map numeric codes to your own text
- Individual toggle for each event type
- Per-code/per-type filter lists for silencing routine warnings, errors, or info messages
- Customizable message templates
- Multiple notification targets

## How It Works

The blueprint listens to events fired by the Dreame Vacuum integration:

| Event | Description |
| --- | --- |
| `dreame_vacuum_task_status` | Cleaning job started or completed |
| `dreame_vacuum_consumable` | Consumable reached end-of-life |
| `dreame_vacuum_warning` | Dismissible device warning |
| `dreame_vacuum_error` | Device fault |
| `dreame_vacuum_information` | Action blocked by user settings |

### Matching the configured vacuum

The integration fires every event with an `entity_id` that it derives from the vacuum's **device name** (via `generate_entity_id()`); events do **not** carry a `device_id`. Matching therefore accepts:

1. The event `entity_id` exactly equal to the configured entity.
2. The configured entity followed by a purely numeric suffix (e.g. `vacuum.dreame_x10_2`) — `generate_entity_id()` adds such a suffix when the base id is already taken.

Non-numeric suffixes (e.g. `_pro`) are rejected, so `vacuum.dreame_x10` will not match `vacuum.dreame_x10_pro`.

> **Note:** because the fired `entity_id` is derived from the device name, if you rename the vacuum's entity_id in Home Assistant so it no longer matches the auto-generated id, matching can fail and notifications stop. Keep the integration-generated entity_id (or rename the *device* instead of the entity) for reliable matching.

## Configuration

| Input | Description |
| --- | --- |
| **Vacuum Entity** | The Dreame vacuum entity to monitor |
| **Notification Targets** | One or more `notify` entities |
| **Event Toggles** | Enable/disable each event type independently |
| **Filtering** | Lists of warning/error codes and information types to silence |
| **Message Templates** | Customizable message for each event type |
| **Localization** | Optional label and code translation tables (see [Localization](#localization)) |

### Filtering

- **Warning Codes / Error Codes to Ignore** — compared against the event's numeric `code`. Enter the code as text (e.g. `68`).
- **Information Types to Ignore** — information events carry a *type id*, not a numeric code; enter the id (`dust_collection`, `cleaning_paused`).
- The two temporary-map warnings (new-map / replace-temporary-map) carry **no** code. The spurious "map cleared" warning is suppressed automatically; the genuine "new map generated" warning can be filtered by its text if needed.

## Message Template Variables

### Cleaning Started

| Variable | Description |
| --- | --- |
| `{vacuum_name}` | Friendly name of the vacuum |
| `{cleaning_mode}` | Cleaning mode, friendly-formatted (e.g., Sweeping, Mopping, Sweeping & Mopping) |
| `{status}` | Current status, friendly-formatted (e.g., Cleaning, Room cleaning) |

### Cleaning Completed

| Variable | Description |
| --- | --- |
| `{vacuum_name}` | Friendly name of the vacuum |
| `{cleaning_mode}` | Cleaning mode used, friendly-formatted |
| `{status}` | Final status, friendly-formatted |
| `{cleaned_area}` | Area cleaned (m²) |
| `{cleaning_time}` | Cleaning duration (minutes) |

### Consumable Depleted

| Variable | Description |
| --- | --- |
| `{vacuum_name}` | Friendly name of the vacuum |
| `{consumable}` | Consumable name (e.g., Main Brush, Side Brush, Filter, Mop Pad) |

### Warning

| Variable | Description |
| --- | --- |
| `{vacuum_name}` | Friendly name of the vacuum |
| `{warning}` | Warning description (already human-readable English from the integration) |
| `{code}` | Numeric warning code (empty for the temporary-map warning) |
| `{code_name}` | Optional label for the code — empty unless you fill the code table (see [Localization](#localization)) |

### Error

| Variable | Description |
| --- | --- |
| `{vacuum_name}` | Friendly name of the vacuum |
| `{error}` | Error description (already human-readable English from the integration) |
| `{code}` | Numeric error code |
| `{code_name}` | Optional label for the code — empty unless you fill the code table (see [Localization](#localization)) |

### Information

| Variable | Description |
| --- | --- |
| `{vacuum_name}` | Friendly name of the vacuum |
| `{information}` | Information message (e.g., Dust Collection, Cleaning Paused) |

> The default warning/error templates show `(code: {code})`. When an event has no code, the blueprint automatically strips the empty `(code: )` parenthetical.

## Friendly Labels

`{cleaning_mode}` and `{status}` arrive from the integration as raw `UPPER_SNAKE_CASE` enum names; the blueprint translates them to readable text. Any value not in the tables below falls back to a generic humanizer (underscores → spaces, capitalized). All labels can be overridden — see [Localization](#localization).

### Cleaning Mode (`{cleaning_mode}`)

| Raw enum | Friendly label |
| --- | --- |
| `UNKNOWN` | Unknown |
| `SWEEPING` | Sweeping |
| `MOPPING` | Mopping |
| `SWEEPING_AND_MOPPING` | Sweeping & Mopping |

### Status (`{status}`)

| Raw enum | Friendly label |
| --- | --- |
| `IDLE` | Idle |
| `PAUSED` | Paused |
| `CLEANING` | Cleaning |
| `BACK_HOME` | Returning to dock |
| `PART_CLEANING` | Spot cleaning |
| `FOLLOW_WALL` | Following wall |
| `CHARGING` | Charging |
| `OTA` | Updating firmware |
| `WIFI_SET` | Wi-Fi setup |
| `POWER_OFF` | Powered off |
| `ERROR` | Error |
| `REMOTE_CONTROL` | Remote control |
| `SLEEPING` | Sleeping |
| `STANDBY` | Standby |
| `SEGMENT_CLEANING` | Room cleaning |
| `ZONE_CLEANING` | Zone cleaning |
| `SPOT_CLEANING` | Spot cleaning |
| `FAST_MAPPING` | Mapping |
| `MONITOR_CRUISE` | Patrolling |
| `MONITOR_SPOT` | Spot monitoring |
| `SUMMON_CLEAN` | Summon clean |

(Also mapped: `FCT`, `FACTORY`, `SELF_TEST`, `FACTORY_FUNCION_TEST` — diagnostic states.)

### Consumable (`{consumable}`) and Information (`{information}`)

| Raw id | Friendly label |
| --- | --- |
| `main_brush` | Main Brush |
| `side_brush` | Side Brush |
| `filter` | Filter |
| `sensor` | Sensor |
| `mop_pad` | Mop Pad |
| `silver_ion` | Silver Ion |
| `detergent` | Detergent |
| `dust_collection` | Dust Collection |
| `cleaning_paused` | Cleaning Paused |

## Localization

Two optional inputs (under **Localization**) let you relabel or translate any value without editing the blueprint. Both are entered as YAML key/value pairs (the object selector).

**Label Overrides** — keys are the raw values the integration emits (cleaning-mode/status are `UPPER_SNAKE` enum names; consumable/information are lower-case ids). Applied to `{cleaning_mode}`, `{status}`, `{consumable}`, and `{information}`:

```yaml
SWEEPING_AND_MOPPING: Подметание и мытьё
CLEANING: Уборка
BACK_HOME: Возврат на базу
dust_collection: Очистка контейнера
```

**Warning/Error Code Labels** — keys are numeric codes (unquoted); the value is exposed as `{code_name}`. Leave empty to omit `{code_name}`:

```yaml
68: Снять швабру
47: Робот застрял
```

Lookup order for every value is: your override → built-in friendly label → generic humanizer.

A ready-to-paste **Russian** starter table (all statuses, modes, consumables, information types, and warning/error codes) is provided in [localization.ru.yaml](localization.ru.yaml) — copy each section into the matching Localization input. To show fully Russian warning/error text, reference `{code_name}` in your warning/error templates instead of the English `{warning}`/`{error}`.

> No built-in numeric-code → name table is shipped, because code meanings can differ between integration versions. The `{warning}` / `{error}` text already comes from your installed integration (so it is always correct); use `{code_name}` only if you want a short, localized tag for specific codes.

### Warning vs. Error Codes

The integration classifies a fault as a dismissible **warning** only for the codes below; every other fault with a positive code (except battery-low) is reported as an **error** and carries a numeric `{code}` you can paste into **Error Codes to Ignore**.

| Code | Name |
| --- | --- |
| 47 | Blocked |
| 68 | Remove mop |
| 70 | Mop removed |
| 71 | Mop pad stopped rotating |
| 72 | Mop pad stopped rotating |
| 107 | Water tank dry |
| 114 | Clean mop pad |

## Notes

- The default messages contain emojis. Most modern notify integrations (Mobile App, Telegram, Discord) render them correctly; legacy SMS-based integrations may not.
- `notify.send_message` requires Home Assistant 2024.7 or newer. It accepts only a `message` (no title/tag); put any emphasis directly in the message text.

## Debug Mode

Enable **Debug Notifications** in the Debug section to send a persistent notification for every trigger. Each debug notification includes the blueprint version, dispatched event kind, and the enable decision — useful for confirming filters are doing what you expect. The notification is keyed per vacuum so debug entries from multiple vacuums do not overwrite each other.

## Author

Alexei Dolgolyov (<dolgolyov.alexei@gmail.com>)