ATOM Documentation

← Back to App

Smart Home Automation Guide

Automation Concepts

The ATOM SaaS automation system uses the **TAP Pattern** (Trigger-Action Pattern) to create powerful smart home automations.

TAP Pattern Components

  1. **Trigger**: What starts the automation
  • State triggers: Device changes (motion detected, temperature exceeded)
  • Time triggers: Schedule-based (8:00 AM, sunset, weekdays)
  • Event triggers: External events (sunrise/sunset, geofence entry)
  1. **Conditions**: Requirements that must be met (optional)
  • State conditions: Device states (door is closed, temperature is below X)
  • Time range conditions: Only during certain hours
  • Presence conditions: Someone is home/away
  • Logical operators: AND, OR, NOT for complex conditions
  1. **Actions**: What the automation does
  • Device control: Turn on lights, adjust temperature
  • Scene activation: Activate predefined scene
  • Delays: Wait before next action
  • Notifications: Send alert

---

Trigger Types

State Triggers

Triggered when device state changes:

**Examples:**

  • Motion detected: motion = active
  • Temperature exceeded: temperature > 75
  • Door opened: contact = open
  • Light turned on: on = true

**Setup:**

  1. Create automation → Add Trigger
  2. Select "Device State"
  3. Choose device and condition
  4. Set comparison value

Time Triggers

Triggered at specific times:

**Examples:**

  • Absolute time: 8:00 AM every day
  • Intervals: Every 2 hours
  • Days of week: Monday through Friday at 7:00 AM

**Setup:**

  1. Create automation → Add Trigger
  2. Select "Time"
  3. Set time or interval
  4. Choose days (optional)

Event Triggers

Triggered by external events:

**Examples:**

  • Sunrise: Turn on outdoor lights
  • Sunset: Turn on indoor lights
  • Geofence: Arrive home, leave home
  • Mode change: Home/Away/Sleep mode changed

**Setup:**

  1. Create automation → Add Trigger
  2. Select "Event"
  3. Choose event type
  4. Configure event parameters

---

Condition Types

State Conditions

Require devices to be in specific states:

**Examples:**

  • Door is closed before locking
  • Temperature > 70 before turning on AC
  • Luminance < 100 before turning on lights

Time Range Conditions

Only trigger during certain time periods:

**Examples:**

  • Between 10 PM and 6 AM
  • Weekdays only
  • Except weekends

Presence Conditions

Based on home/away status:

**Examples:**

  • Someone is home
  • Everyone is away
  • Specific user is home

Logical Operators

Combine multiple conditions:

**AND Conditions:**

All conditions must be true:

  • Motion detected **AND** sunset **AND** door closed

**OR Conditions:**

Any condition can be true:

  • Door opened **OR** window opened **OR** motion detected

**NOT Conditions:**

Condition must be false:

  • NOT motion detected for 10 minutes

---

Action Types

Device Control

Control individual devices:

**Actions:**

  • Turn on/off: on: true, on: false
  • Set brightness: brightness: 50
  • Set color: color: { r: 255, g: 100, b: 50 }
  • Set temperature: temperature: 72
  • Set mode: mode: ECO
  • Lock/unlock: lock: true, lock: false

Scene Activation

Activate predefined scene:

**Scenes:**

  • Movie Night: Dims lights, lowers temperature
  • Good Morning: Turns on lights, raises temperature
  • Away: Turns off all lights, lowers temperature

Delays

Wait before executing next action:

**Examples:**

  • Turn on porch light → Wait 5 minutes → Turn off porch light
  • Lock door → Wait 30 seconds → Arm security system

Notifications

Send alerts:

**Channels:**

  • Push notification: Mobile app
  • Email: Email notification
  • SMS: Text message (if configured)
  • Webhook: External service

---

Example Automations

1. Turn on Lights at Sunset

**Trigger:** Sunset event

**Conditions:** None

**Actions:**

  • Turn on Living Room Light (brightness: 80%)
  • Turn on Kitchen Light (brightness: 50%)
  • Turn on Porch Light (brightness: 100%)

**Setup:**

  1. Create automation: "Lights at Sunset"
  2. Trigger: Event → Sunset
  3. Actions: Add each light with brightness
  4. Enable automation

2. Turn off All Lights When Away

**Trigger:** Presence → Everyone away

**Conditions:** None

**Actions:**

  • Turn off all lights
  • Lower thermostat to 65°F
  • Arm security system

**Setup:**

  1. Create automation: "Away Mode"
  2. Trigger: Event → Geofence → Leave home
  3. Actions: Turn off lights, set thermostat, arm security
  4. Enable automation

3. Lower Thermostat at Night

**Trigger:** Time → 10:00 PM

**Conditions:**

  • Weekdays only (Mon-Fri)
  • Set thermostat to 68°F
  • Enable eco mode

**Setup:**

  1. Create automation: "Nighttime Temperature"
  2. Trigger: Time → 10:00 PM
  3. Condition: Time Range → Weekdays only
  4. Actions: Set temperature, enable eco mode
  5. Enable automation

4. Notify When Door Unlocked

**Trigger:** State → Door Lock → lock = unlocked

**Conditions:**

  • Between 10 PM and 6 AM
  • No one is home
  • Send push notification: "Front door unlocked"
  • Turn on all lights (security measure)

**Setup:**

  1. Create automation: "Door Unlock Alert"
  2. Trigger: State → Front Door Lock → unlocked
  3. Conditions: Time range (10 PM - 6 AM), No one home
  4. Actions: Send notification, turn on lights
  5. Enable automation

---

Scene Creation

What are Scenes?

Scenes are predefined device states that can be activated manually or by automations. Scenes group multiple device changes into a single action.

Creating Scenes

  1. Navigate to Scenes → Create Scene
  2. Name your scene: "Movie Night"
  3. Add devices and set their states:
  • Living Room Light: on, brightness 30%, color warm
  • Kitchen Light: off
  • Thermostat: 68°F, eco mode
  1. Save scene

Scene Features

  • **Multi-room**: Include devices from multiple rooms
  • **Delays**: Add delays between device state changes
  • **Transitions**: Gradual brightness/color changes (if supported)
  • **Preview**: Test scene before activating

Example Scenes

**Movie Night:**

  • Living Room Light: 30% brightness, warm color
  • Kitchen Light: Off
  • Dining Room Light: Off
  • Thermostat: Lower to 68°F
  • Activate: 5 second delay between lights

**Good Morning:**

  • Bedroom Light: On, 80% brightness, cool white
  • Kitchen Light: On, 100% brightness
  • Thermostat: Raise to 72°F
  • Coffee Maker: On (if smart plug)

**Away:**

  • All Lights: Off
  • Thermostat: 65°F, eco mode
  • Lock: All doors locked
  • Security: Arm system

---

Scheduling

Cron Expressions

Automations use cron expressions for recurring schedules:

**Format:**

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

**Examples:**

  • 0 8 * * * - 8:00 AM every day
  • 0 */2 * * * - Every 2 hours
  • 0 8 * * 1-5 - 8:00 AM Monday-Friday
  • 0 0 * * 0 - Midnight on Sundays
  • 30 8,12,18 * * * - 8:30 AM, 12:30 PM, 6:30 PM daily

Recurring Schedules

Create schedules that repeat:

**Daily:**

  • Run at specific time every day
  • Example: Turn on lights at sunset

**Weekdays:**

  • Run Monday-Friday only
  • Example: Morning routine on weekdays

**Weekends:**

  • Run Saturday-Sunday only
  • Example: Late morning wake-up

**Custom Days:**

  • Select specific days
  • Example: Trash pickup on Tuesdays and Fridays

Sunset/Sunrise Schedules

Automatically adjust for sunset/sunrise times:

**Sunset Offset:**

  • "At sunset" → Exactly at sunset
  • "30 min after sunset" → Sunset + 30 minutes
  • "1 hour before sunset" → Sunset - 1 hour

**Example Automations:**

  • Turn on outdoor lights at sunset
  • Turn off outdoor lights at sunrise
  • Close blinds 30 min before sunset

One-Time Schedules

Schedule single events:

  1. Create automation → Trigger → Time
  2. Set date and time
  3. Actions → Execute scene or commands
  4. Automation disables after running

**Use Cases:**

  • Vacation mode: Simulate presence while away
  • Special events: Holiday lighting
  • Maintenance: Run diagnostics

---

Conflict Resolution

Detecting Overlapping Rules

When multiple automations affect the same devices:

**Conflicts:**

  • Rule A: Turn on light at sunset
  • Rule B: Turn off light at 10 PM
  • Rule C: Turn on light when motion detected (after 10 PM)

**Priority System:**

  1. **Manual commands** always override automations
  2. **Recent automations** override older ones (if conflict)
  3. **Priority setting**: Set automation priority (1-10, 10 highest)

Priority Settings

Assign priority to automations:

  1. Edit automation → Settings
  2. Set priority (1-10)
  3. Higher priority automations win conflicts

**Example:**

  • Security automation: Priority 10 (highest)
  • Comfort automation: Priority 5
  • Ambiance automation: Priority 1 (lowest)

Debugging Failed Rules

**Why rules fail:**

  1. Conditions not met: Check current device states
  2. Device offline: Verify device connectivity
  3. Rate limiting: Too many API calls
  4. Circular dependencies: Rule triggers itself

**Debug steps:**

  1. Go to Automations → [Automation] → Run History
  2. View last execution: Success/Failure, reasons
  3. Test rule manually: Automations → [Automation] → Test
  4. Check device states: Compare trigger conditions with actual states

---

Best Practices

1. Start Simple

Begin with basic automations:

  • Single trigger, single action
  • Test thoroughly before adding complexity
  • Gradually add conditions and actions

2. Use Descriptive Names

Name automations clearly:

  • ✅ "Turn on porch light at sunset"
  • ❌ "Automation 1"

3. Test Before Enabling

Always test automations:

  1. Create automation but keep disabled
  2. Click "Test Run" to verify
  3. Check all actions execute correctly
  4. Enable after successful test

4. Use Scenes for Common Actions

Create scenes for repeated actions:

  • Morning routine
  • Nighttime routine
  • Away mode
  • Movie mode

Then trigger scenes via automations instead of duplicating actions.

5. Avoid Circular Dependencies

Don't create rules that trigger themselves:

  • ❌ "When light turns on, turn off light" (infinite loop)
  • ✅ "When motion detected, turn on light" (no loop)

6. Consider Device Limitations

Not all devices support all features:

  • Basic bulbs: On/off only
  • Color bulbs: On/off, brightness, color
  • Switches: On/off only
  • Sensors: Read-only (no control)

7. Plan for Failures

What happens if:

  • Device is offline? → Add condition: check device state
  • Internet is down? → Use local automations (Hue, Home Assistant)
  • Power outage? → Devices reset to default state

8. Monitor Execution

Review automation performance:

  • Check run history: How often triggered, success rate
  • Adjust timing: If triggers at wrong time
  • Disable unused automations: Reduce clutter

---

Advanced Features

Multi-Condition Triggers

Combine multiple trigger types:

**Example:**

  • Trigger: (Motion detected **OR** Door opened) **AND** (After sunset **AND** Before sunrise)

**Setup:**

  1. Add multiple triggers
  2. Set logical operator (AND/OR) between triggers
  3. Add time range condition

Conditional Actions

Execute different actions based on conditions:

**Example:**

  • If temperature > 75: Turn on AC, set to 68°F
  • Else if temperature < 65: Turn on heat, set to 70°F

**Setup:**

  1. Add action → Conditional
  2. Define condition → action mapping
  3. Add else-if conditions as needed

Action Sequences

Execute actions in specific order with delays:

**Example:**

  1. Turn off all lights
  2. Wait 30 seconds
  3. Lock all doors
  4. Wait 10 seconds
  5. Arm security system

**Setup:**

  1. Add actions in sequence
  2. Add delays between actions
  3. Set delay duration

Error Handling

Handle automation failures gracefully:

**On failure:**

  • Retry: Attempt action again (1-3 retries)
  • Fallback: Execute alternative action
  • Notify: Send alert about failure
  • Skip: Continue to next action

**Setup:**

  1. Edit action → Error handling
  2. Choose failure behavior
  3. Configure fallback or notification

---

Tips and Tricks

Energy Saving Automations

  • Turn off lights in empty rooms (motion sensor + 10 min no motion)
  • Lower thermostat when away (presence sensor)
  • Run appliances during off-peak hours (schedule + electricity rates)
  • Turn off standby devices at night (schedule + smart plugs)

Security Automations

  • Simulate presence when away (random light patterns)
  • Alert on unexpected activity (motion when away, door unlock at night)
  • Automate security system (arm when away, disarm when arrive home)
  • Outdoor lighting at sunset (deterrent)

Comfort Automations

  • Morning routine (lights, thermostat, coffee maker)
  • Nighttime routine (dim lights, lower temperature)
  • Adjust temperature based on room usage
  • Pre-heat/cool before arriving home (geofence + thermostat)

Convenience Automations

  • Voice control scenes ("Movie time", "Bedtime")
  • Automatic blinds based on sun position
  • Turn on lights when walking into room (motion sensor)
  • Flash all lights when doorbell rings (alert)

---

Troubleshooting

See TROUBLESHOOTING.md for detailed troubleshooting.

**Common automation issues:**

  • Rule not triggering: Check conditions, verify device states
  • Actions failing: Check device connectivity, rate limits
  • Timing wrong: Verify time zone, sunset/sunrise offset
  • Conflicts: Check priority, review run history