---
owner: gmikcon
status: active
last_reviewed: 2026-09-04
review_interval: 90d
confidence: high
source_of_truth: ssh-host-verified
---

# Smart Home Overview

... (existing content) ...

## Automation Actions (verified 2026-09-04)

Actions are implemented as PHP Scope classes in `/home/shome/smart-home-server/automation/Scopes/` (Bathroom, Hall, Kitchen, MasterBedroom, Office, Outdoor, PlantsRoom, ServerRoom). Each class extends `ControlScripts` and registers actions in `register_actions_scripts()` via helpers from the `Common` trait:

- `add_toggle_action(alias, name, relay_alias, channel, attrs)` — single relay toggle
- `add_group_toggle_action(alias, name, ["device:channel", ...], attrs)` — multi-relay toggle
- `add_action_script(attrs, callable)` — custom action (attrs: `alias`, `name`, `description`, `icon`, `author`, `danger_level` safe/cautious/dangerous, `state_callback`, `params_schema`)
- `add_off_action(...)`, `add_hatch_action(...)` — specialized helpers

**Registration vs DB (important, corrected 2026-09-04):** code registration does NOT auto-create rows in the `scripts` DB table. `run_action_script` resolves the alias from the runtime registry AND requires an `enabled` row in `scripts` (`Scripts::script_state`), otherwise returns null. To activate a newly registered action, call `Scripts::set_script_state("action", alias, true)` — via CLI bootstrap (`fury_init("SHServ")`, same path as CronController timers) or HTTP API with a GAuth session. Aliases removed from code are dead even if still `enabled` in the DB. Code changes are picked up without restart (`opcache.validate_timestamps=1`).

### Trigger via API

`POST http://192.168.1.101/api/v1/scripts/actions/run` with `{"alias": "...", "params": {}}` — requires GAuth permission `scripts.run` (session or Bearer from `shserv_sessions`). CLI equivalent: `\SHServ\Middleware\ControlScripts::run_action_script(alias, [])` via `fury_init("SHServ")` bootstrap.

### Current live actions (18, verified 2026-09-04)

| Alias | Description | Target |
| --- | --- | --- |
| `master_toggle` | Вкл/Выкл. свет в спальне | `light_hub_1:1` |
| `hall1_toggle` | Вкл/Выкл. свет в нижнем холле | `light_hub_1:3` |
| `hall2_toggle` | Вкл/Выкл. свет в холле 2 эт | `light_hub_1:2` |
| `office_main_toggle` | Вкл/Выкл. основной свет в кабинете | `light_hub_1:0` |
| `bathroom_light_switch` | Вкл/Выкл. свет в ванной (2 сан узел) | `bathroom_2_light:0` |
| `kitchen1_toggle` | Вкл/Выкл. свет на кухне 1 | `fisrt_floor_big_relay:0` |
| `kitchen2_toggle` | Вкл/Выкл. свет на кухне 2 | `fisrt_floor_big_relay:1` |
| `computer_table_lamp_switch` | Вкл/Выкл. настольную компьютерную лампу | `computer_table_lamp:0` |
| `craft_table_lamp_switch` | Вкл/Выкл. лампу в мастерской | `craft_table_lamp:0` |
| `plants_room_light_switch` | Вкл/Выкл. свет в комнате растений | `plants_room_light:0` |
| `italy_lamp_switch` | Вкл/Выкл. Italy лампу | `italy_lamp_relay:0` |
| `floor_lamp_switch` | Вкл/Выкл. торшер | `floor_lamp_relay:0` |
| `server_room_light_switch` | Вкл/Выкл. свет в серверной | `server_room_light:0` |
| `front_spotlight_toggle` | Вкл/Выкл. передний прожектор | `spotlight_main_front_1:0` |
| `back_spotlight_1_toggle` | Вкл/Выкл. прожектор на заднем дворе | `spotlight_main_back_1:0` |
| `back_spotlight_2_toggle` | Вкл/Выкл. боковой уличный прожектор | `spotlight_main_back_2:0` |
| `hatch_open` | Открыть люк в подвал | `kitchen_hatch` (dangerous) |
| `hatch_close` | Закрыть люк в подвал | `kitchen_hatch` (dangerous) |

The 5 toggles added on 2026-09-04 (front/back spotlights individually, hall1, office main) were verified live: each ran on→off→on cycles with state confirmed via device `GET /status`; group spotlight aliases were removed the same day (owner decision: individual control instead of group).

### Dead aliases (do not use)

Legacy rows remain in the `scripts` DB table but are NOT registered by code and return null: `master_room_lamp_switcher`, `hallway2_lamp_switcher`, `bathroom2_lamp_switcher`, `main_lamps_switcher`, `hall1_light_switcher`, `kitchen_light_switcher`, `all_hub_toggle`, `spotlights_on/off`, `computer/craft_table_lamp_on/off`, `front_spotlight_on`, `stand_relay_toggle`, `spotlights_by_time`, `all_spotlights_off`, `back_spotlights_off`, `front_spotlight_off` (group spotlight actions removed 2026-09-04). Docs referencing `master_room_lamp_switch`/`_switcher` are outdated — the bedroom action is `master_toggle`.

### Known coverage gaps (as of 2026-09-04)

- No global "all lights off" action — backlog, owner decision pending.
- ~17 legacy dead rows in `scripts` DB table — cleanup pending (backlog).
- `light_hub_1:3` has no sync-map connection (physical button in lower hall, if any, is not synchronized with API toggles).
- No relay hardware for: гостинная, гостевая спальня, vika_room, главный сан узел, подвал, чердак, хоз домик.
