You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+17-17Lines changed: 17 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,7 +36,7 @@ A custom integration that finds and deletes **orphan entities** - entities left
36
36
37
37
## Web Panel
38
38
39
-
After installation, the **Orphan Cleaner** icon appears in the HA sidebar. All settings are controlled directly from the panel — no configuration flow needed after the initial setup.
39
+
After installation, the **Orphan Cleaner** icon appears in the HA sidebar. All settings are controlled directly from the panel - no configuration flow needed after the initial setup.
40
40
41
41
### Controls
42
42
@@ -50,7 +50,7 @@ After installation, the **Orphan Cleaner** icon appears in the HA sidebar. All s
50
50
|**Dry run**| Simulate deletion without removing anything (see below) |
51
51
|**Filter**| Filter visible results by entity_id or platform |
52
52
|**Select all / Deselect**| Bulk checkbox controls |
53
-
|**Column headers**| Click to sort by Entity ID, Platform, Detection or Age — click again to reverse |
53
+
|**Column headers**| Click to sort by Entity ID, Platform, Detection or Age - click again to reverse |
54
54
|**Platform badge**| Click on any platform badge to instantly select all entities of that platform |
55
55
|**Detection filter**| Dropdown to show only dead entry, unavailable, timestamp or heuristic entities |
56
56
|**Delete selected**| Delete selected entities with a confirmation dialog |
@@ -64,11 +64,11 @@ Type a platform name or glob pattern in the **Ignore** field in the control bar
64
64
65
65
A collapsible section below the control bar. Entries here are saved to the integration's config entry options and automatically loaded on every scan and page load. Supports:
66
66
67
-
-**Platform names**—`tuya`, `shelly`, `imou_life`
68
-
-**Platform globs**—`imou_*`, `tuya_*`
69
-
-**Entity ID globs**—`sensor.old_*`, `*_deprecated`, `sensor.*_temp`
67
+
-**Platform names**-`tuya`, `shelly`, `imou_life`
68
+
-**Platform globs**-`imou_*`, `tuya_*`
69
+
-**Entity ID globs**-`sensor.old_*`, `*_deprecated`, `sensor.*_temp`
70
70
71
-
Entries are saved automatically when added or removed — no Save button needed. Use the **?** link for a full syntax reference.
71
+
Entries are saved automatically when added or removed - no Save button needed. Use the **?** link for a full syntax reference.
72
72
73
73
### Save & Delete
74
74
@@ -81,7 +81,7 @@ Enable the **Dry run** checkbox in the toolbar before deleting. When active:
81
81
- An amber warning banner appears to remind you that no changes will be made
82
82
-**Delete selected** becomes **Simulate**
83
83
-**Save & Delete** is hidden
84
-
- Clicking **Simulate** highlights the selected entities with a `would delete` badge for 6 seconds and logs the result — nothing is actually removed
84
+
- Clicking **Simulate** highlights the selected entities with a `would delete` badge for 6 seconds and logs the result - nothing is actually removed
85
85
86
86
Dry run is also available as a parameter in the `orphan_cleaner.delete_orphans` service (see Services section).
87
87
@@ -117,21 +117,21 @@ Click any platform badge in the results table to instantly select all entities o
117
117
118
118
## Detection Methods
119
119
120
-
### Method 1 —`orphaned_timestamp` (reliable)
120
+
### Method 1 -`orphaned_timestamp` (reliable)
121
121
122
122
Home Assistant sets this field in the registry when, after a full restart, an entity is not claimed by any integration. This is the official signal and is always active.
123
123
124
124
**Min age (h)** filters out recently orphaned entities, useful if an integration is temporarily offline. Ages above 24 hours are displayed in days (e.g. `377d`) in the panel table.
125
125
126
-
### Method 2 — Dead config entry
126
+
### Method 2 - Dead config entry
127
127
128
128
If an entity's `config_entry_id` points to a config entry that no longer exists or is in a `FAILED` / `NOT_LOADED` state, the entity is considered an orphan.
129
129
130
-
### Method 3 — Unavailable state
130
+
### Method 3 - Unavailable state
131
131
132
132
Entities in `unavailable` state for longer than **Min age (h)** are flagged. Catches entities that HA marks with the yellow warning "no longer provided by the integration".
133
133
134
-
### Method 4 — Heuristic (optional)
134
+
### Method 4 - Heuristic (optional)
135
135
136
136
Enabled by the **Heuristic** checkbox. Also flags entities with no `config_entry_id` and a platform not in the following exclusion list:
137
137
@@ -250,14 +250,14 @@ If you used **Save & Delete**, a backup file was written to `/config/orphan_clea
250
250
251
251
### What you can do
252
252
253
-
-**Check if the entity was truly orphaned**— look at the `method` and `age_hours` fields. If `age_hours` is low, the integration may have been temporarily offline and the entity could reappear after a restart.
254
-
-**Reinstall the integration**— if the platform (e.g. `tuya`, `shelly`, `zha`) is still active and the physical device is reachable, removing and re-adding the integration will recreate its entities automatically.
255
-
-**Restore custom attributes manually**— if the entity reappears, you can reassign its area, icon, and aliases from the HA UI. The backup gives you the original `entity_id` to match it.
256
-
-**Clean up the recorder**— if the entity had historical data and you want to remove it, use the `recorder.purge_entities` service with the `entity_id` from the backup.
253
+
-**Check if the entity was truly orphaned**- look at the `method` and `age_hours` fields. If `age_hours` is low, the integration may have been temporarily offline and the entity could reappear after a restart.
254
+
-**Reinstall the integration**- if the platform (e.g. `tuya`, `shelly`, `zha`) is still active and the physical device is reachable, removing and re-adding the integration will recreate its entities automatically.
255
+
-**Restore custom attributes manually**- if the entity reappears, you can reassign its area, icon, and aliases from the HA UI. The backup gives you the original `entity_id` to match it.
256
+
-**Clean up the recorder**- if the entity had historical data and you want to remove it, use the `recorder.purge_entities` service with the `entity_id` from the backup.
257
257
258
258
### What cannot be recovered
259
259
260
-
- The entity registry entry itself — HA does not expose an API to re-insert entries manually.
260
+
- The entity registry entry itself - HA does not expose an API to re-insert entries manually.
261
261
- Historical recorder data is not deleted by this integration, but it will no longer be linked to an active entity.
262
262
- If the underlying integration or device no longer exists, the entity cannot be recreated without it.
263
263
@@ -274,7 +274,7 @@ All API endpoints require Home Assistant authentication. The panel itself requir
274
274
-**Always make a backup** before deleting entities in bulk. Use **Save & Delete** to automatically export a JSON record before each deletion.
275
275
- Deleted entities are removed from the **registry**: historical data in the **recorder** remains but is no longer associated with an active entity. To clean the recorder as well, use the `recorder.purge_entities` service.
276
276
- An entity with `orphaned_timestamp` may belong to an integration that is temporarily offline. Increase **Min age (h)** if you have unstable integrations.
277
-
- Deletion is **irreversible**. Entities cannot be restored from the backup — the backup is a reference record only.
277
+
- Deletion is **irreversible**. Entities cannot be restored from the backup - the backup is a reference record only.
0 commit comments