Smart Home Integration Guide

Overview

The ATOM SaaS platform supports integration with multiple smart home platforms, enabling unified control and automation across different ecosystems. This guide covers setup, configuration, and best practices for integrating smart home devices.

Supported Platforms

Getting Started

Prerequisites

1. Tenant Account: You must have a tenant account on the ATOM SaaS platform
2. Smart Home Hub: Physical hub or cloud account for your devices (e.g., Hue Bridge, SmartThings Hub)
3. Network Connectivity: Hubs must be accessible from your network (local for Hue, cloud for SmartThings/Nest)
4. OAuth Credentials: For cloud-based platforms (SmartThings, Nest), you'll need API credentials

Quick Setup (5 Minutes)

1. Navigate to Settings → Integrations → Smart Home
2. Click Add Integration and select your platform
3. Follow the platform-specific setup instructions below
4. Discover devices and create your first automation

Platform-Specific Setup

Philips Hue

Requirements:

• Hue Bridge (generation 2 or later)
• Bridge connected to same network as ATOM SaaS
• Physical access to bridge for setup

Setup Steps:

1. Discover Bridge

   • Click "Add Hue Integration"
   • The system will automatically discover your Hue Bridge via mDNS
   • If auto-discovery fails, enter bridge IP manually

2. Authenticate

   • Press the link button on your Hue Bridge
   • Click "Authenticate" within 30 seconds of pressing the button
   • The system will create an API username automatically

3. Discover Lights

   • After authentication, click "Discover Lights"
   • All lights associated with your bridge will appear
   • Assign rooms and names for easy identification

4. Discover Groups

   • Click "Discover Groups" to import room groups from Hue
   • Groups allow controlling multiple lights at once

Configuration Options:

Troubleshooting:

• Bridge not found: Ensure bridge is on same network, check firewall settings
• Authentication fails: Press link button within 30 seconds, retry
• Lights not responding: Check Hue app to confirm lights work, restart bridge

Samsung SmartThings

Requirements:

• SmartThings Hub or SmartThings cloud account
• SmartThings Developer Account (free)
• Custom OAuth app configured

Setup Steps:

1. Create SmartThings OAuth App

   • Go to SmartThings Developers
   • Create a new project: "ATOM SaaS Integration"
   • Add OAuth client with redirect URI: https://your-domain.com/api/integrations/smartthings/callback
   • Note your Client ID and Client Secret

2. Configure Integration

   • Enter Client ID and Client Secret in ATOM SaaS
   • Set Scope: r:devices:* r:locations:* x:devices:*
   • Click "Connect to SmartThings"

3. OAuth Flow

   • You'll be redirected to SmartThings for authorization
   • Log in and grant permissions
   • Redirect back to ATOM SaaS with access tokens

4. Select Location

   • Choose the SmartThings location (home) to integrate
   • All devices in that location will be discovered

5. Discover Devices

   • Click "Discover Devices" to import all devices
   • Devices are categorized by type (light, switch, sensor, thermostat, lock)

Configuration Options:

Troubleshooting:

• OAuth fails: Verify redirect URI matches exactly, check Client ID/Secret
• Devices not appearing: Check device visibility in SmartThings app, ensure location selected
• Rate limit errors: Reduce polling frequency, use webhooks for real-time updates

Home Assistant (HomeKit)

Requirements:

• Home Assistant instance running locally or remotely
• Home Assistant configured with smart home devices
• Long-lived access token

Setup Steps:

1. Generate Access Token

   • Open Home Assistant
   • Go to Profile → Long-Lived Access Tokens
   • Create token: "ATOM SaaS Integration"
   • Copy the token (you won't see it again)

2. Configure Integration

   • Enter Home Assistant URL (e.g., http://homeassistant.local:8123)
   • Paste access token
   • Click "Connect"

3. WebSocket Connection

   • System connects via WebSocket for real-time updates
   • All entities are automatically discovered
   • Devices are categorized by domain (light, switch, sensor, climate)

Configuration Options:

Best Practices:

• Use HTTPS for remote Home Assistant instances
• Create dedicated API user in Home Assistant
• Enable device filters to exclude unwanted entities
• Use Home Assistant's built-in automations for complex logic

Troubleshooting:

• Connection fails: Verify URL, check Home Assistant is running, test token in HA
• Devices missing: Check entity IDs in HA, ensure devices are enabled
• WebSocket disconnects: Check network stability, increase heartbeat interval

Google Nest

Requirements:

• Google Cloud Project with SDM API enabled
• Nest devices registered in Google Home app
• OAuth credentials for SDM API

Setup Steps:

1. Create Google Cloud Project

   • Go to Google Cloud Console
   • Create project or use existing
   • Enable Smart Device Management API
   • Configure OAuth consent screen

2. Create OAuth Credentials

   • Go to Credentials → Create Credentials → OAuth Client ID
   • Application type: Web application
   • Redirect URI: https://your-domain.com/api/integrations/nest/callback
   • Note Client ID and Client Secret

3. Link Nest Account

   • Enter Client ID in ATOM SaaS
   • Click "Link Nest Account"
   • Authorize via Google OAuth
   • Select home structure to integrate

4. Discover Thermostats

   • All Nest thermostats are automatically discovered
   • Temperature scales are respected (Fahrenheit/Celsius)

Configuration Options:

Troubleshooting:

• OAuth fails: Verify redirect URI, check Google Cloud project settings
• No devices found: Ensure devices are in Google Home app, check structure selection
• API errors: Verify SDM API is enabled, check Google Cloud quotas

Configuration

Rate Limiting

All platforms enforce rate limits to prevent API throttling:

Best Practices:

• Use webhooks/WebSocket instead of polling where available
• Batch device commands where possible
• Use scenes/groups instead of individual device control
• Cache device state locally to reduce API calls

Multi-Room Grouping

Organize devices by rooms for unified control:

1. Assign Devices to Rooms

   • During discovery, assign room names
   • Rooms can be modified later in device settings

2. Create Custom Groups

   • Navigate to Rooms → Create Group
   • Select devices from multiple rooms
   • Example: "Downstairs Lights" = Living Room + Kitchen + Hallway

3. Room-Based Automations

   • Triggers can be room-specific: "If motion detected in Bedroom"
   • Actions can target rooms: "Turn off all lights in Kitchen"

Polling vs. Webhooks

Recommendation: Use WebSocket for Home Assistant, polling for Hue, webhooks for SmartThings/Nest.

API Reference

Device Control Endpoints

Get All Devices

GET /api/smarthome/devices

Response:

{
  "devices": [
    {
      "id": "device-123",
      "name": "Living Room Light",
      "type": "light",
      "provider": "hue",
      "room": "Living Room",
      "capabilities": ["on_off", "brightness", "color", "color_temp"],
      "state": {
        "on": false,
        "brightness": 0
      }
    }
  ]
}

Execute Device Command

POST /api/smarthome/devices/{id}/execute

Body:

{
  "action": "on",
  "params": {
    "brightness": 80,
    "color": { "r": 255, "g": 100, "b": 50 }
  }
}

Get Device State

GET /api/smarthome/devices/{id}/state

Sync Device State

POST /api/smarthome/devices/{id}/sync

Discovery Endpoints

Discover Devices

POST /api/smarthome/{provider}/discover

Get Hub Status

GET /api/smarthome/{provider}/status

Automation Endpoints

Create Automation Rule

POST /api/smarthome/automations

Body:

{
  "name": "Motion-Activated Lights",
  "trigger": {
    "type": "state",
    "deviceId": "motion-sensor-1",
    "condition": "motion",
    "value": "active"
  },
  "conditions": [
    {
      "deviceId": "sun-sensor",
      "condition": "sunState",
      "value": "sunset"
    }
  ],
  "actions": [
    {
      "deviceId": "porch-light",
      "action": "on",
      "params": { "brightness": 100 }
    }
  ],
  "enabled": true
}

Execute Automation Rule

POST /api/smarthome/automations/{id}/execute

Best Practices

Hub Placement

• Hue Bridge: Central location, away from metal objects, elevated if possible
• SmartThings Hub: Central location, near router for cloud connectivity
• Range Considerations: Zigbee/Z-Wave range ~100ft indoors, reduce by walls/floors

Network Requirements

• Dedicated VLAN: Separate smart home devices from main network (optional)
• 2.4GHz WiFi: Many hubs only support 2.4GHz (not 5GHz)
• Static IPs: Assign static IPs to hubs for reliability
• Firewall Rules: Allow outbound HTTPS for cloud platforms, local network for Hue

Device Compatibility

Security Considerations

• OAuth Tokens: Store securely, rotate annually
• Local Networks: Use VPN for remote access, don't expose hubs to internet
• Device Updates: Keep hub firmware updated for security patches
• Access Control: Limit device permissions to minimum required

Troubleshooting

Common Issues

Device Not Discovered

Symptoms: Device exists in hub app but not in ATOM SaaS

Solutions:

1. Refresh device discovery: Integrations → [Platform] → Discover Devices
2. Check device is powered on and connected to hub
3. Verify device is included in selected location/room
4. Restart hub and re-run discovery

OAuth Connection Failed

Symptoms: Authorization fails or tokens invalid

Solutions:

1. Verify redirect URI matches exactly in OAuth app settings
2. Check Client ID and Secret are correct
3. Ensure OAuth consent screen is configured
4. Revoke old tokens and re-authorize

Device Not Responding

Symptoms: Commands sent but no change in device state

Solutions:

1. Check device is powered on and connected to hub
2. Verify hub is online (check hub app)
3. Sync device state: Devices → [Device] → Sync
4. Restart hub: Unplug for 30 seconds, plug back in
5. Re-pair device to hub (last resort)

Rate Limit Errors

Symptoms: API returns 429 errors, commands delayed

Solutions:

1. Reduce polling frequency in integration settings
2. Use scenes/groups instead of individual device control
3. Enable webhooks for real-time updates (if available)
4. Batch commands in automations

State Not Syncing

Symptoms: Device state in ATOM SaaS doesn't match actual state

Solutions:

1. Manually sync device: Devices → [Device] → Sync
2. Check WebSocket connection status (for Home Assistant)
3. Increase poll interval if using polling
4. Verify hub is reporting state changes correctly

Hub-Specific Issues

Hue Bridge Not Found

Diagnosis:

• Check bridge is powered on (LED solid)
• Verify network connection (3 blue LEDs)
• Test with Hue app to confirm bridge works

Solutions:

• Use manual IP entry if mDNS discovery fails
• Check network firewall rules
• Ensure bridge and ATOM SaaS on same network
• Restart bridge (unplug 30 seconds)

SmartThings API Errors

Diagnosis:

• Check SmartThings status page for outages
• Verify API credentials are valid
• Review rate limit usage in SmartThings developer portal

Solutions:

• Reduce polling frequency
• Use SmartThings webhooks for real-time updates
• Re-authenticate if tokens expired

Home Assistant Connection Issues

Diagnosis:

• Test WebSocket connection in browser DevTools
• Check Home Assistant logs for errors
• Verify long-lived access token is valid

Solutions:

• Regenerate access token
• Check CORS settings in Home Assistant configuration
• Ensure Home Assistant is accessible from ATOM SaaS network

Nest Authentication Failures

Diagnosis:

• Verify Google Cloud project has SDM API enabled
• Check OAuth consent screen is configured
• Test OAuth flow with OAuth 2.0 Playground

Solutions:

• Re-create OAuth credentials
• Verify redirect URI matches exactly
• Check Google Cloud quotas and billing

Diagnostic Tools

Connection Testing

Test connectivity to hubs:

1. Navigate to Integrations → [Platform] → Test Connection
2. View connection status: Online, Offline, Error
3. Check latency: Lower is better (ideally < 100ms)

State Viewing

View raw device state for debugging:

1. Go to Devices → [Device] → View State
2. See last updated timestamp
3. Compare with hub app state

Log Analysis

View integration logs:

1. Navigate to Settings → Logs → Smart Home
2. Filter by platform, device, or date range
3. Export logs for support

Rate Limit Monitoring

Monitor API usage:

1. Go to Integrations → [Platform] → Rate Limits
2. View current usage vs. limit
3. See timestamps of recent requests

Recovery Procedures

Re-authentication

If OAuth tokens expire or become invalid:

1. Navigate to Integrations → [Platform] → Settings
2. Click "Re-authenticate"
3. Complete OAuth flow again
4. Devices will be re-discovered automatically

Device Rediscovery

If devices are missing or outdated:

1. Go to Integrations → [Platform] → Discover Devices
2. Existing devices will be updated, new devices added
3. Devices removed from hub will be marked offline

Factory Reset

As last resort, reset integration to defaults:

Warning: This will remove all devices, automations, and scenes.

1. Navigate to Integrations → [Platform] → Settings
2. Scroll to bottom → "Reset Integration"
3. Confirm reset
4. Set up integration from scratch

Advanced Configuration

Custom Device Types

Define custom device types for specialized hardware:

1. Go to Settings → Smart Home → Device Types
2. Click "Add Device Type"
3. Define capabilities and commands
4. Map to platform-specific device classes

Webhook Configuration

Configure webhooks for real-time updates:

1. Navigate to Integrations → [Platform] → Webhooks
2. Enable webhooks
3. Configure webhook URL (platform sends updates here)
4. Verify webhook endpoint is accessible

Scene Import/Export

Export scenes for backup or sharing:

1. Go to Scenes → Export
2. Download JSON file with all scenes
3. Import on another tenant or system

Support

For additional help:

• Documentation: docs/smarthome/AUTOMATION_GUIDE.md
• Troubleshooting: docs/smarthome/TROUBLESHOOTING.md
• Voice Control: docs/smarthome/VOICE_CONTROL.md
• Community: Post questions in the ATOM SaaS forum
• Support: Contact support@atom-saas.com for platform issues