Smart Home Troubleshooting Guide

Common Issues

Device Not Discovered

Symptoms:

• Device exists in hub app but not in ATOM SaaS
• Discovery returns 0 devices

Causes:

1. Device not paired with hub
2. Hub not connected to network
3. Device excluded from selected location/room
4. Hub firmware outdated

Solutions:

1. Verify hub connectivity: Check hub app can see devices
2. Refresh discovery: Integrations → [Platform] → Discover Devices
3. Check device pairing: Pair device with hub first
4. Restart hub: Unplug for 30 seconds, plug back in
5. Update firmware: Check for hub updates in hub app
6. Re-pair device: Remove from hub, re-add, re-discover

Advanced:

• Check network: Hub and ATOM SaaS on same network (for local hubs)
• Firewall rules: Allow mDNS (Hue), WebSocket (Home Assistant)
• API limits: Rate limiting may block discovery, wait and retry

OAuth Connection Failed

Symptoms:

• Authorization page shows error
• Redirect fails with 400/401 error
• Tokens invalid immediately after authorization

Causes:

1. Redirect URI mismatch
2. Invalid Client ID or Secret
3. OAuth consent screen not configured
4. Token expired

Solutions:

1. Verify redirect URI: Must match exactly in OAuth app settings

   Correct: https://your-domain.com/api/integrations/smartthings/callback
   Incorrect: http://your-domain.com/api/integrations/smartthings/callback
   

2. Check credentials: Copy-paste Client ID/Secret, ensure no extra spaces
3. Configure consent screen: OAuth app must have consent screen configured
4. Re-authorize: Revoke old tokens, run OAuth flow again
5. Check app status: Verify OAuth app is active in developer console

Platform-specific:

• SmartThings: Check API Key permissions, ensure scope includes r:devices:*
• Nest: Verify Google Cloud project has SDM API enabled
• Alexa: Check security profile credentials, redirect URL in LWA console

Device Not Responding

Symptoms:

• Command sent but device doesn't change state
• State shows "offline" or "unreachable"
• Commands timeout

Causes:

1. Device powered off or disconnected
2. Device out of range of hub
3. Hub offline or disconnected from network
4. Rate limiting (commands delayed)
5. Device firmware bug

Solutions:

1. Check device power: Verify device is plugged in, battery charged
2. Check hub status: Hub app shows hub online?
3. Test in hub app: Control device from hub app (rules out hub/device issue)
4. Sync device state: ATOM SaaS → Devices → [Device] → Sync
5. Check distance: Device within range of hub? (Zigbee/Z-Wave ~100ft)
6. Restart device: Unplug for 30 seconds, plug back in
7. Re-pair device: Remove from hub, re-add
8. Check for interference: Microwaves, other wireless devices

Rate limiting:

• Hue: 10 req/sec limit, commands auto-queued
• SmartThings: 150 req/min, exponential backoff on 429
• Nest: 1500 req/min, rarely hit limit

State Not Syncing

Symptoms:

• Device state in ATOM SaaS doesn't match actual state
• State updates delayed by minutes/hours
• State shows "unknown" or "error"

Causes:

1. Polling interval too long
2. WebSocket disconnected (Home Assistant)
3. Hub not reporting state changes
4. State cache outdated

Solutions:

1. Manually sync: Devices → [Device] → Sync
2. Adjust polling: Integrations → [Platform] → Poll Interval (reduce for faster updates)
3. Check WebSocket: Home Assistant → WebSocket Status (should be "Connected")
4. Verify hub reporting: Check hub app for state changes, hub push notifications enabled
5. Clear cache: Devices → [Device] → Clear Cache → Sync
6. Restart integration: Integrations → [Platform] → Restart

WebSocket issues (Home Assistant):

• Check HA logs for WebSocket errors
• Verify long-lived access token is valid
• Test WebSocket connection: Browser DevTools → WS → connect to ws://ha-url/api/websocket
• Reconnect: Integrations → Home Assistant → Reconnect

Rate Limit Errors

Symptoms:

• API returns 429 status code
• Commands delayed or queued
• "Rate limit exceeded" error messages

Causes:

1. Too many API calls in short time
2. Polling interval too short
3. Too many automations triggering at once
4. Bulk operations on many devices

Solutions:

1. Reduce polling frequency: Increase poll interval (default: 5-10 seconds)
2. Use webhooks: Enable webhooks for real-time updates instead of polling
3. Batch commands: Use scenes/groups instead of individual device control
4. Add delays in automations: Spread out device control over time
5. Optimize automations: Reduce number of automations, combine where possible
6. Check usage: Integrations → [Platform] → Rate Limits (view current usage)

Platform limits:

• Hue: 10 req/sec (strict, enforced by bridge)
• SmartThings: 150 req/min (enforced by cloud API)
• Nest: 1500 req/min (generous, rarely hit)
• Home Assistant: Unlimited (local WebSocket)

Hub-Specific Issues

Hue Bridge Not Found

Diagnosis:

• Hue app can find bridge? → Yes: Bridge OK, ATOM SaaS network issue
• Hue app can't find bridge? → No: Bridge network issue

Solutions:

1. Check bridge LEDs: 3 blue LEDs = network OK, 1 blinking = searching for network
2. Manual IP entry: Discover → Manual Entry → Enter bridge IP (find in Hue app → Settings → My Bridge → Network info)
3. Network check: Bridge and ATOM SaaS on same network? Same subnet?
4. Firewall: Allow mDNS (UDP port 5353), TCP port 80
5. Restart bridge: Unplug 30 seconds, plug back in
6. Factory reset: Last resort (hold button until LED flashes)

mDNS issues:

• macOS: System Preferences → Security → Firewall → Allow incoming connections
• Windows: Windows Firewall → Allow mDNS
• Router: Enable mDNS/Bonjour/UPnP

SmartThings API Errors

Error Codes:

• 400: Invalid request, bad parameters
• 401: Unauthorized, tokens expired
• 403: Forbidden, insufficient permissions
• 404: Device/location not found
• 429: Rate limit exceeded
• 500: SmartThings cloud error

Solutions:

1. Check tokens: Integrations → SmartThings → Re-authenticate
2. Verify scope: OAuth app must have r:devices:* and x:devices:*
3. Check location: Device exists in selected location?
4. Review permissions: OAuth app has permission for device type?
5. SmartThings status: Check status.smartthings.com
6. Reduce polling: Increase poll interval to avoid rate limits

Device not in SmartThings:

• Device must be paired with SmartThings Hub first
• Check SmartThings app → My Home → Devices
• Exclude/include device: SmartThings app → Device → Remove, re-add

Home Assistant Connection Issues

WebSocket Connection Failed:

Diagnosis:

1. Test in browser: ws://your-ha-url:8123/api/websocket
2. Check HA logs: Settings → System → Logs → WebSocket errors
3. Verify token: Profile → Long-Lived Access Tokens → Regenerate

Solutions:

1. Regenerate token: Old token may have expired
2. Check URL: Include port (default: 8123), use ws:// or wss:// for HTTPS
3. CORS settings: configuration.yaml must include ATOM SaaS domain:

   http:
     cors_allowed_origins:
       - https://your-atom-saas-domain.com

4. Restart HA: Configuration → Server Controls → Restart
5. Check firewall: Allow TCP port 8123
6. Use HTTPS: For remote HA, enable SSL, use wss://

Entity Not Found:

• Check entity ID in HA (Developer Tools → States)
• Entity must be enabled (disable/enable in HA)
• ATOM SaaS filters hidden entities by default

Nest Authentication Failures

OAuth Flow Errors:

Common errors:

• redirect_uri_mismatch: Redirect URI doesn't match OAuth app
• access_denied: User denied authorization
• invalid_client: Client ID/Secret wrong
• unauthorized_client: OAuth app misconfigured

Solutions:

1. Verify redirect URI: Exactly match in Google Cloud Console
2. Check OAuth screen: Consent screen configured, published
3. Verify scopes: https://www.googleapis.com/auth/sdm.service enabled
4. Check billing: Google Cloud project must have billing enabled (even for free tier)
5. Test OAuth: Use OAuth 2.0 Playground
6. Recreate credentials: Delete OAuth client, create new

No Devices Found:

• Device must be in Google Home app
• Check structure: OAuth linked to correct home/structure?
• Device type: Only thermostats supported currently (SDM API limitation)
• Firmware: Nest device must be updated to latest firmware

Automation Issues

Rule Not Triggering

Diagnosis:

1. Check run history: Automations → [Automation] → Run History
2. View current states: Compare trigger conditions with actual device states
3. Test manually: Automations → [Automation] → Test Run

Solutions:

1. Verify trigger conditions: Are trigger conditions actually met?
2. Check device states: View device state, compare with trigger
3. Verify time zone: Automation time zone matches your location?
4. Check enablement: Automation is enabled (not disabled)?
5. Review conditions: All conditions must be true (AND) or any true (OR)
6. Circular dependency: Rule triggers itself? (causes infinite loop)

Example:

• Trigger: "Motion detected"
• Check: Motion sensor shows "active" in device state?
• If not: Motion sensor not working, not trigger issue

Conditions Not Evaluating

Symptoms:

• Conditions always false
• Conditions never met
• Logic not working as expected

Solutions:

1. Test conditions individually: Create automation with single condition, test
2. Check logical operators: AND = all true, OR = any true, NOT = inverted
3. Verify comparison: > vs >=, = vs contains
4. Check time zones: Time range in local time zone?
5. Review condition order: Conditions evaluated top-to-bottom
6. Test rule manually: Automations → [Automation] → Test

Complex conditions:

• Break into multiple rules (simpler debugging)
• Use scenes instead of complex logic
• Add logging action (send notification) to see execution flow

Actions Failing

Symptoms:

• Automation triggers but actions don't execute
• Partial execution (some actions work, some fail)
• Actions timeout

Solutions:

1. Test actions individually: Device control page → Execute action
2. Check device connectivity: Device online? Hub online?
3. Verify capability: Device supports the action? (e.g., basic bulb can't change color)
4. Check rate limits: Too many actions in short time?
5. Review action parameters: Correct format? (brightness 0-254 for Hue, 0-100 for SmartThings)
6. Add delays: Spread out actions over time (avoid rate limits)

Partial execution:

• Actions executed sequentially, first failure stops execution
• Enable "Continue on error" in automation settings
• Use error handling per action (retry, fallback, skip)

Schedule Not Running

Symptoms:

• Scheduled automation doesn't run at specified time
• Runs at wrong time
• Runs multiple times

Solutions:

1. Check cron expression: Verify format, test in crontab guru
2. Verify time zone: Schedule in correct time zone?
3. Check enablement: Automation enabled?
4. Review history: Automations → [Automation] → Run History (last run time)
5. Server time: ATOM SaaS server time correct?
6. Sunset/sunrise: Location set correctly? (affects sunrise/sunset times)

Time zone issues:

• Automation uses tenant time zone (Settings → Tenant → Time Zone)
• Schedules stored in UTC, displayed in local time
• Daylight saving time: Automatic if time zone set correctly

Diagnostic Tools

Connection Testing

Test connectivity to hubs:

1. Navigate: Integrations → [Platform] → Test Connection
2. View results:
   • ✓ Online: Hub reachable
   • ✗ Offline: Hub not reachable
   • ⚠ Latency: Connection slow (>500ms)
3. Interpret results:
   • Online but high latency: Network congestion, distance
   • Offline: Check hub power, network, firewall

State Viewing

View raw device state for debugging:

1. Navigate: Devices → [Device] → View State
2. See:
   • Current state (on/off, brightness, etc.)
   • Last updated timestamp
   • State source (hub, cached, manual)
3. Compare: Check against hub app state
4. Sync: If stale, click "Sync" to refresh

Log Analysis

View integration logs:

1. Navigate: Settings → Logs → Smart Home
2. Filter by:
   • Platform (Hue, SmartThings, etc.)
   • Device ID
   • Date range
   • Log level (Error, Warning, Info, Debug)
3. Export: Download logs for support ticket
4. Common log entries:
   • Rate limit exceeded: Too many API calls
   • Device offline: Hub reports device unreachable
   • Auth failed: Token expired, re-authenticate
   • Connection timeout: Network issue

Rate Limit Monitoring

Monitor API usage:

1. Navigate: Integrations → [Platform] → Rate Limits
2. View:
   • Current usage: Requests in last minute
   • Limit: Max requests per period
   • % Used: Usage as percentage of limit
3. Timestamps: See request times to identify spikes
4. Optimize: If consistently near limit, reduce polling

Recovery Procedures

Re-authentication

If OAuth tokens expire:

1. Navigate: Integrations → [Platform] → Settings
2. Click: "Re-authenticate"
3. Complete OAuth flow: Authorize again
4. Verify: Devices re-discovered, tokens valid

Prevent token expiry:

• Tokens auto-refresh before expiry (SmartThings, Nest)
• Long-lived tokens don't expire (Home Assistant)
• Re-authenticate annually for security

Device Rediscovery

Refresh device list:

1. Navigate: Integrations → [Platform] → Discover Devices
2. Process:
   • Existing devices: Updated (name, capabilities, state)
   • New devices: Added to device registry
   • Removed devices: Marked offline (not deleted)
3. Review: Check device list for accuracy
4. Clean up: Delete old/removed devices

Factory Reset Integration

Warning: Removes all devices, automations, scenes

When to use:

• Integration completely broken
• OAuth cannot be fixed
• Major hub firmware update

Steps:

1. Navigate: Integrations → [Platform] → Settings
2. Scroll: Bottom of page
3. Click: "Reset Integration"
4. Confirm: Enter integration name to confirm
5. Wait: Integration removed, data cleared
6. Re-setup: Follow initial setup process

Before factory reset:

• Export automations and scenes (if available)
• Note device configurations (names, rooms)
• Save OAuth credentials (may still work)

Getting Help

Self-Service Resources

• Integration Guide: INTEGRATION_GUIDE.md
• Automation Guide: AUTOMATION_GUIDE.md
• Voice Control: VOICE_CONTROL.md
• Community Forum: Post questions, search similar issues

Support Contact

For platform issues or bugs:

• Email: support@atom-saas.com
• Include:
  • Platform (Hue, SmartThings, etc.)
  • Error messages (screenshots helpful)
  • Steps to reproduce
  • Diagnostic logs (export from Settings → Logs)
  • Browser console errors (if web UI issue)

Response Times

• Critical issues: All hubs down, security vulnerabilities (4 hours)
• High priority: Automation failures, major features broken (24 hours)
• Normal priority: Minor bugs, documentation questions (48 hours)
• Low priority: Feature requests, improvements (1 week)