# Rooms

[Back to main README](../README.md)

This document explains how rooms work in my Home Assistant configuration.

## Overview

Every room in my smart home is treated as an independent unit with its own state machine. Rooms have:
- An `input_select` that manages the current **mode** (Auto, Off, etc.)
- An `input_boolean` that tracks **occupancy**
- Automations that respond to mode and occupancy changes

This approach allows for granular control and avoids complex, monolithic automations.

---

## Room Modes

| Mode | Description |
|------|-------------|
| **Auto** | Automations are fully enabled. Motion triggers occupancy, lights respond to brightness, etc. |
| **Off** | No automations run. The room behaves like a "dumb" room with manual control only. |
| **Away** | Room/house is unoccupied. Lights off, media off, climate adjusted. Used by common areas. |
| **Bedtime** | Sleep mode with reduced lighting, no TTS, quiet automations. Used by bedrooms. |
| **Wake** | Morning transition with gradual lighting increase. Used by main bedroom. |
| **DnD** | Do Not Disturb. Disables TTS, shows busy indicator, pauses non-essential automations. Used by the Office. |

---

## Room Occupancy

Each room has an `input_boolean.{room}_occupied` that indicates whether someone is currently in the room. Occupancy is the key driver for most automations.

### What Triggers Occupancy

Rooms become occupied when any of these are detected:

- **Motion sensors** - Primary trigger for most rooms
- **Presence sensors** - mmWave/PIR sensors that detect stationary presence
- **BLE room presence** - ESPresense tracking phones/watches
- **Door sensors** - Door closed often means occupied (bedrooms)
- **Bed sensors** - FSR sensors detect bed occupancy
- **Lights on** - Manual light activation implies presence
- **Media playing** - TV or speakers active

### What Happens When Occupied

- Lights turn on if it's dark (below illuminance threshold)
- Music can auto-play based on conditions
- TTS announcements route to this room
- Room appears in "Active Rooms" dashboard

### What Happens When Unoccupied

- Lights turn off (after a short delay)
- Music stops
- Room disappears from "Active Rooms" dashboard

---

## Anatomy of a Room: The Office

The Office is the most advanced room in my house (mostly because nobody complains when I experiment). It demonstrates the full lifecycle of a smart room.

### The Setup

| Entity | Purpose |
|--------|---------|
| `input_select.office` | Mode: Auto, Off, DnD |
| `input_boolean.office_occupied` | Is someone in the office? |
| `binary_sensor.office_aqara_motion_sensor` | Motion detection |
| `binary_sensor.office_presence` | Bayesian presence (combines multiple signals) |

### A Day in the Life

**8:30 AM - The Office Wakes Up**

I walk into the office. The motion sensor triggers, and `input_boolean.office_occupied` turns on. The room is in **Auto** mode, so automations kick in:

- It's still a bit dark → ceiling lights turn on
- The Office detects John is present and working → music starts playing softly
- Adaptive lighting adjusts color temperature for morning focus

**9:15 AM - A Call Comes In**

My calendar shows a meeting starting. My laptop camera turns on. The Office detects I'm on a call and transitions to **DnD** mode:

- Music stops immediately
- A red light turns on outside the office door → family knows not to interrupt
- TTS notifications are disabled → no "John, dinner's ready!" mid-presentation
- The El Gato camera light turns on (synced with my laptop camera)

**10:00 AM - Back to Work**

The call ends. My laptop camera turns off. The Office transitions back to **Auto** mode:

- The red light outside turns off
- Music resumes
- TTS notifications are re-enabled

**12:30 PM - Lunch Break**

I leave for lunch. After a few minutes with no motion or presence detected, `input_boolean.office_occupied` turns off:

- Lights turn off
- Music stops
- The room waits patiently for my return

**1:15 PM - Back to Work**

Motion detected. Occupied again. The cycle continues.

### The Office Automations

Here's what's happening behind the scenes:

| Automation | Trigger | Action |
|------------|---------|--------|
| Office occupied | Motion, presence, lights on | Turn on `input_boolean.office_occupied` |
| Office not occupied | No motion/presence for 3 min | Turn off `input_boolean.office_occupied` |
| Lights on when dark | Occupied + illuminance < 150 lux | Turn on ceiling lights |
| Music auto-play | Occupied + John present + working hours | Start music playback |
| Enter DnD | Camera on + calendar active | Change mode to DnD |
| Exit DnD | Camera off | Change mode to Auto |
| DnD indicator | DnD mode active | Turn on red light outside |
| Disable TTS | DnD mode active | Block TTS to office speakers |

### File Structure

```
packages/office/
├── office_state.yaml              # input_select with modes
├── office_occupancy.yaml          # input_boolean for occupancy
├── modes/
│   ├── office_occupied.yaml       # Triggers occupancy on
│   ├── office_not_occupied.yaml   # Triggers occupancy off
│   ├── office_mode_auto.yaml      # Auto mode behaviors
│   ├── office_mode_dnd.yaml       # DnD mode behaviors
│   └── office_mode_off.yaml       # Off mode behaviors
├── lights/
│   ├── office_lights_on.yaml      # Turn on when dark + occupied
│   └── office_lights_off.yaml     # Turn off when unoccupied
└── media/
    └── office_music_on.yaml       # Auto-play music logic
```

---

## Customization Patterns

### Room-Specific Booleans

Some rooms have additional `input_boolean` entities for granular control:

| Boolean | Purpose |
|---------|---------|
| `input_boolean.{room}_occupied` | Track occupancy state |
| `input_boolean.{room}_lighting_automations` | Enable/disable lighting automations |

### Linking to House State

Room modes respond to house-level changes:

- When `input_boolean.house_occupied` turns off → Rooms transition to Away
- When everyone is sleeping → Bedrooms transition to Bedtime
- When `input_boolean.guest_mode` is on → Some automations are modified

---

## Dashboard

![Room Details](../dashboards/kohbo/assets/room-details.jpg)

The Kohbo dashboard provides full visibility and control over room states. Each room has a detail page with climate, lights, music, devices, and quick settings.

See [Dashboard Documentation](../dashboards/README.md) for details.