SmartHomeAssistant

SmartHomeAssistant is a local Home Assistant custom integration for safe, room-based light control. It discovers lights and presence sensors, manages reliable room rules, analyzes existing Home Assistant automations, and can reproduce supported YAML light and dependency behavior through guided setup.

Version 0.8.0 adds local, explainable learning per room. It works with sensorless rooms controlled through Home Assistant or HomeKit, partly automated rooms, and sensor-rich rooms. Motion and lux improve context but are never required.

Important

SmartHomeAssistant 0.8.0 is an early development release. Global light control and Learning remain disabled by default. Learning observes and recommends only; it does not autonomously execute learned behavior.

Version 0.8.0: local room learning

The new Learning page lets you enable observation globally and then choose individual rooms and lights. Each room is evaluated independently:

• Manual/sensorless: learns recurring switching times and brightness.
• Partly automated: additionally uses motion or presence as context.
• Sensor-rich: additionally considers illuminance.
• Already automated: automation-originated changes do not become positive user training.

The first possible pattern appears after five matching observations. From ten observations onward it becomes a recommendation; confidence continues to rise up to twenty observations. Suggestions can be accepted as reviewed drafts, ignored, or permanently excluded.

SmartHomeAssistant's own service contexts are discarded before storage. Sensorless turn-off patterns are shown for transparency but cannot be accepted for automatic use. All observations stay local and are limited to 2,000 compact records.

Install with HACS

SmartHomeAssistant is currently installed as a custom HACS repository:

1. Open HACS.
2. Open the three-dot menu and select Custom repositories.
3. Add https://github.com/jl0906/SmartHomeAssistant.
4. Select Integration as the category.
5. Install SmartHomeAssistant and restart Home Assistant.
6. Open Settings → Devices & services → Add integration.
7. Search for SmartHomeAssistant and complete setup.

Version 0.7.0: advanced YAML automation import

The Automations page now has a dedicated advanced-recognition layer for common YAML patterns that cannot be represented by the earlier flat action parser. It builds a structured intermediate model and shows a review popup before anything is stored or disabled.

Paired timer automations

SmartHomeAssistant can join two source automations into one managed room rule when it finds an unambiguous relationship:

• the first automation reacts to one or more motion/presence triggers;
• nested if or choose branches call light.turn_on;
• the first automation starts one timer with a fixed duration;
• the second automation listens for timer.finished from the same timer;
• nested branches turn off the same lights;
• optional input_boolean markers identify which lights were switched on automatically.

The shared timer, matching lights, source IDs, and branch conditions are used to form one automation bundle. Both source automations are backed up and handled together. Choosing Keep originals stores the imported room disabled. Choosing Disable originals disables both source automations only after the new configuration has validated and been stored successfully. Undo restores the previous room configuration and re-enables every source disabled by the import.

Ownership helpers such as input_boolean.*_durch_bewegung are not recreated. Their purpose is converted into SmartHomeAssistant's internal rule: only lights switched on by SmartHomeAssistant may be switched off automatically. Lights that were already on remain untouched.

Trigger-specific illuminance sensors

An imported room can map each presence trigger to its matching illuminance sensor. For example:

Motion hallway small → illuminance hallway small
Motion hallway large → illuminance hallway large

The controller evaluates the sensor associated with the event that actually triggered the rule, instead of forcing one shared lux sensor for the whole room.

Adaptive profiles from recognized templates

0.7.0 recognizes conservative numeric profile templates without executing Jinja. Supported structures include:

• a toggle helper that selects automatic or manual lux behavior;
• sun-elevation thresholds mapped to lux limits;
• a manual fallback from an input_number;
• a toggle helper that selects adaptive or manual brightness;
• measured-lux thresholds mapped to brightness percentages;
• a manual brightness fallback from an input_number.

The extracted steps are stored as structured thresholds. Unknown templates are not guessed: the import remains partial and requires review or is rejected. The original template text is never used by the runtime controller.

Sequential wait_for_trigger rules

A supported sequence such as:

Bedroom motion
→ wait up to 30 seconds for hallway motion
→ require hallway lux below 20 lx
→ switch hallway light on at 5%
→ switch off after 90 seconds without hallway motion
→ force switch-off after at most 5 minutes

is converted into one managed automation rule with:

• a one-use temporary grant created by the first sensor;
• the second sensor as the actual light trigger;
• an optional daily time window;
• lux, brightness, and light-off prerequisites;
• separate turn-on and turn-off transitions;
• inactivity delay and maximum on-time;
• single-style protection against overlapping sequences.

The master sensor does not switch the light on directly. It only opens the temporary grant. This preserves the intended pet-resistant night-light behavior.

Review popup and source safety

Advanced patterns appear in their own cards and open a focused import popup. The preview shows the source automations, target area, lights, triggers, trigger-to-lux mapping, adaptive profile steps, timer behavior, grants, time windows, transitions, and values inferred from each source.

• YAML files are never edited or deleted.
• Only source automations with stable IDs are importable.
• Source actions are limited to Keep or Disable after import.
• A pair is imported transactionally and rolled back as one unit.
• A sequence import stores its own managed automation rule and backup record.
• Missing entities, duplicate light ownership, invalid areas, unsupported profile values, and incomplete pairings block activation.
• WebSocket import commands remain administrator-only.

Version 0.6.0: importable control rules

The Automations page now analyzes two independent layers:

• Room-light logic: motion/presence triggers, lights, brightness, lux limits, time windows, and switch-off timing.
• Control logic: source events or conditions that grant, require, enable, disable, or otherwise govern a configured SmartHomeAssistant room.

One Home Assistant automation may expose either layer or both. Room and control imports are tracked separately, so a supported automation can first create a room rule and then create its dependency rule without losing the original backup metadata.

Directly importable control patterns

0.6.0 directly recognizes conservative, unambiguous patterns such as:

• one entity state trigger that calls automation.turn_off, waits for a fixed delay, and calls automation.turn_on for the same single automation;
• the inverse automation.turn_on → delay → automation.turn_off sequence;
• a simple entity-state prerequisite on a recognized light automation, converted into a continuous state requirement for the target room;
• one supported daily time window attached to the imported control rule.

The target Home Assistant automation is resolved to a SmartHomeAssistant room when its controlled lights have a clear room assignment. The setup popup remains editable, so the source, state, effect, target room, duration, priority, conditions, and enabled state can be corrected before saving.

Guided control-rule conversion

A red or partially recognized automation can show Reproduce control rule through setup when SmartHomeAssistant can identify a plausible relationship without safely translating it automatically. This includes common previous-event templates, complex state triggers, multiple automation targets, or additional actions.

The popup pre-fills recognized entities and timing where possible, but the administrator must review every field. Templates are never copied or executed by SmartHomeAssistant. They are used only to suggest a source entity and, when recognizable, a duration.

Source behavior and rollback

For YAML and UI automations, a control import offers:

• Keep: retain the original automation. The imported SmartHomeAssistant control rule is stored disabled to prevent duplicate control until the administrator explicitly changes it.
• Disable after import: disable the original automation and activate the imported control rule according to the reviewed setup.

Control-rule imports do not edit or delete manually managed YAML files. Every import stores the original automation configuration and imported rule metadata. Undo import removes the SmartHomeAssistant control rule and re-enables an original automation that the import disabled.

Import safety

• Blueprints are not converted.
• A direct import requires a stable automation ID and at least one configured SmartHomeAssistant room.
• Multiple source triggers, multiple time windows, ambiguous target automations, templated delays, and unsupported actions require guided setup or remain unavailable.
• The imported rule is revalidated with the same entity, target-room, priority, override, and cycle checks as a manually created control rule.
• A master automation that controls another Home Assistant automation is only directly importable when the controlled automation is already disabled or has been safely replaced by an active SmartHomeAssistant room import. Otherwise the guided rule is stored disabled.
• The control-rule WebSocket import endpoint is administrator-only.
• Original source configuration remains excluded from diagnostics and normal frontend payloads.

Version 0.5.0: control rules and dependencies

The new Control rules page provides a five-step setup wizard for relationships between room automations. The wizard only shows source, duration, use-limit, and override fields when they are relevant to the selected effect.

Supported effects

• Previous event required: a source event creates a temporary grant. The dependent room only runs while the grant exists.
• Continuous state requirement: the dependent room only runs while a selected entity has the configured state.
• Temporary block: the target room is prevented from running for a configured duration.
• Override settings: brightness, switch-off delay, transition, and optionally the controlled lights can be replaced temporarily.
• Temporarily enable: a disabled target room can run while the enable effect is active.
• Temporarily disable: an enabled target room is blocked while the disable effect is active.

Cat-resistant night-light example

A practical setup is:

1. Configure the hallway as a normal SmartHomeAssistant room with an active window from 00:00 to 05:00 and a night brightness of 5%.
2. Create a control rule with Previous event required.
3. Select the bedroom motion sensor as the source and state on.
4. Select the hallway as the dependent target room.
5. Set the grant duration to 30 seconds and uses to 1.
6. Save and enable the rule.

The hallway motion sensor remains the actual trigger for the hallway light. Bedroom motion only opens a one-use, 30-second grant. Hallway motion without that grant is logged and ignored. SmartHomeAssistant rejects a normal on grant that uses the target room's own presence trigger, because that would open and consume the grant in the same movement event.

This reduces false activation by pets but is not guaranteed person detection. A pet that triggers both sensors in the same sequence can still satisfy the rule. Additional state conditions such as bed occupancy, a door contact, or house mode can make the sequence stricter.

Multiple requirements

Each target room has a Multiple grants setting:

• Require all grants: every active previous-event and state requirement must be satisfied.
• Any grant is enough: at least one requirement must be satisfied.

Additional entity-state conditions can be attached to each control rule and combined with all or any logic.

Priorities

Control rules use five readable priority levels:

1. Low
2. Normal
3. High
4. Override
5. Safety

When an enable and a block/disable effect conflict, the higher-priority effect wins. At equal priority, blocking is conservative and wins. Override rules are applied from highest to lowest priority, and the highest-priority rule owns each overridden field. Two enabled override rules at the same priority cannot assign different values to the same field; the second configuration is rejected instead of producing an ambiguous result.

Observation mode

Every control rule can run in Observation mode. The source event and intended effect are recorded in the activity page, but no gate, block, override, enable, or disable state is created. This is intended for safe testing before activation.

Runtime behavior

Temporary grants and effects:

• are held only in memory;
• have visible expiration times and remaining uses;
• can be cleared from the Control rules page;
• are discarded after a Home Assistant restart;
• are cleared when control-rule configuration changes or global light control is disabled.

Room-to-room relationships are checked for direct and indirect cycles before saving and again when a previously disabled rule is enabled.

Reliable room-based light control

Each room can be configured independently with:

• one or more lights;
• one or more motion or presence sensors;
• an optional illuminance sensor;
• a configurable lux threshold;
• a configurable switch-off delay;
• a configurable manual-override duration;
• a configurable transition duration;
• an optional daily active time window, including overnight windows;
• separate day, evening, and night brightness levels;
• dependency mode for multiple control-rule requirements.

Safety behavior

• Global light control is disabled by default.
• Every room is disabled by default.
• A room requires at least one light and one motion/presence sensor before it can be enabled.
• SmartHomeAssistant only switches off lights that it previously switched on itself.
• Lights already on before a trigger are left untouched.
• A manual or external light change pauses automatic control for the configured override period.
• New presence cancels a pending switch-off timer.
• A room is switched off only after all configured presence sensors are inactive.
• One light cannot be assigned to multiple configured rooms.
• Unavailable lights are skipped without blocking the remaining lights.
• Imported room settings replace an existing room only after explicit confirmation.

Automation discovery and import

The Automations page shows loaded Home Assistant automations with their source, status, triggers, light targets, lux conditions, time windows, brightness, transition, switch-off delay, and import limitations.

SmartHomeAssistant classifies them as:

• fully importable;
• partially importable;
• not importable but reproducible through guided setup;
• not importable;
• not a light automation.

YAML setup conversion

Complex YAML automations that contain recognizable light behavior can display Reproduce through setup. The popup maps the intended room, lights, sensors, lux threshold, switch-off delay, transition, and brightness profile.

SmartHomeAssistant never edits or deletes manually managed YAML files. The source automation can be kept or disabled after successful conversion. Templates, notifications, scenes, scripts, nested branches, and unrelated side effects are not copied.

Room and control imports

The same automation card can offer separate actions for Import automation and Import as control rule. Each import has its own record and can be undone independently. A control-rule import opens the same five-step editor used for manually created master/dependency rules, prefilled with the detected source and effect.

Direct room-import actions

For directly supported room automations:

• Keep: imports the room configuration but leaves the original active; the new room remains disabled to avoid duplicate execution.
• Disable after import: disables the original and enables the imported room according to its source state.
• Delete after import: available only for stable entries in the standard automations.yaml, with a complete local recovery backup.

Imports can be undone, and deleted UI-managed automations can be restored through the backups section.

Sidebar pages

Overview

Shows global control, configured rooms, active rooms, pending switch-offs, manual overrides, detected light automations, and imports.

Rooms

Configures lights, presence sensors, lux behavior, time profiles, transition, switch-off timing, manual override, and dependency mode.

Control rules

Shows master/dependency relationships, active temporary effects, priorities, source-to-target flow, conditions, and the setup popup.

Automations

Shows discovery, classifications, YAML reproduction, direct import, conflicts, and recovery backups.

Activity

Shows decisions and actions including missing grants, active blocks, shadow-mode triggers, consumed one-use grants, temporary effect expiration, imports, manual overrides, and light service errors.

The activity history is held in memory and intentionally limited.

Upgrade from 0.7.0

Version 0.8.0 keeps the existing config entry, rooms, control rules, imports, automation rules, and backups. Learning settings and observations are additive; Learning remains disabled after the update.

After updating:

1. Restart Home Assistant completely.
2. Confirm the panel header shows 0.8.0.
3. Open Rooms and verify existing room settings.
4. Open Learning and select only the rooms and lights that should be observed.
5. Enable Learning globally; this does not enable light control.
6. Allow at least five matching observations before evaluating early patterns.
7. Review recommendations and their automation previews before accepting them.

Manual installation

1. Download the latest release archive.
2. Copy custom_components/smart_home_assistant to the Home Assistant config/custom_components directory.
3. Restart Home Assistant.
4. Add SmartHomeAssistant under Settings → Devices & services.

Current limitations

• Advanced import recognizes documented structural patterns; it is not a general Jinja or arbitrary-script translator.
• Templates are parsed only for explicit entities and numeric threshold branches and are never executed.
• A timer bundle requires exactly one matching start automation, one matching timer.finished automation, and identical controlled lights.
• Sequential import currently supports one source trigger, one required target trigger, one turn-on action, one turn-off action, and fixed timeouts.
• Device-, area-, floor-, scene-, and script-based indirect light targets still require manual reproduction.
• Control rules target SmartHomeAssistant room rules, not arbitrary Home Assistant automation entities.
• Previous-event grants are based on entity state changes, not device trigger payloads.
• Temporary effects and sequence grants are not restored after restart.
• State conditions currently compare exact state strings.
• Observation mode records intended effects but does not simulate downstream light actions.
• Multi-room route prediction and cross-room behavior learning are not included yet.
• Accepted Learning suggestions remain reviewed drafts in 0.8.0 and are not autonomously executed.
• Pet filtering is probabilistic unless additional occupancy or direction signals are available.

Roadmap

• 0.1.0: discovery and read-only sidebar.
• 0.2.0: reliable room-based light control.
• 0.3.0: automation discovery, import, backup, and restoration.
• 0.4.0: guided reproduction of complex YAML light automations.
• 0.5.0: master/dependency rules, temporary gates, blocks, overrides, priorities, and observation mode.
• 0.6.0: automation-to-control-rule import and guided dependency conversion.
• 0.7.0: advanced YAML bundles, nested actions, adaptive profiles, and sequential wait_for_trigger imports.
• 0.8.0: local room learning and shadow recommendations for timing and brightness.
• 0.9.0: vacation mode and learned presence simulation.
• 1.0.0: controlled autonomous room prediction.

Diagnostics

Open Settings → Devices & services → SmartHomeAssistant → Download diagnostics. Diagnostics include discovery, sanitized automation analysis, room settings, control-rule configuration, active relation metadata, import metadata, and controller runtime state. Full original automation backups are excluded.

Development and validation

The repository includes .github/workflows/validate.yml with Home Assistant Hassfest and HACS validation. It runs on pushes, pull requests, a daily schedule, and manual dispatch.

Support

Use the GitHub issue tracker for reproducible bugs and feature requests. Include the Home Assistant version, SmartHomeAssistant version, relevant diagnostics, and a short description of the affected room or rule.

License

SmartHomeAssistant is released under the MIT License.