📖 What You'll Learn in This Tutorial:

✓ What each status color means
✓ How OceanRemote determines device status
✓ Understanding the difference between ONLINE, AWAY, and OFFLINE
✓ How session expiry affects status
✓ Troubleshooting status issues

Device Status Overview

OceanRemote displays three status indicators for each device. Understanding these helps you quickly assess your device's health.

Status Indicators:
┌─────────────────────────────────────────────────────────────┐
│  🟢 ONLINE (Green)  → Device is communicating normally     │
│  🟡 AWAY (Yellow)   → Device missed a few polls            │
│  🔴 OFFLINE (Red)   → Device has not communicated recently │
└─────────────────────────────────────────────────────────────┘

How Status is Calculated

OceanRemote determines device status based on the time since the last communication:

Status	Time Since Last Seen	What It Means
🟢 ONLINE	Less than 10 seconds	Device is actively polling, ready to receive commands
🟡 AWAY	10 to 300 seconds (5 minutes)	Device missed 1-2 polls. May have brief WiFi interruption.
🔴 OFFLINE	More than 300 seconds (5 minutes)	Device is not communicating. Check power and WiFi.

📊 Polling Frequency:

OceanRemote devices poll the server every 5 seconds (configurable in firmware). A device that misses 1 poll may be temporarily busy, but 2+ missed polls indicate a problem.

Status in the Dashboard

Device Card Example:
┌───────────────────────────────────────────────────────────────────┐
│  Kitchen Controller                    🟢  NLINE               │ │
│  ─────────────────────────────────────────────────────────        │
│  WiFi: MyHomeWiFi                                                 │
│  IP: 192.168.1.100                                                │
│  Last Seen: just now                                              │
│  ─────────────────────────────────────────────────────────        │
│  RELAYS                                                           │
│  [ Lights OFF ] [ Fan OFF ] [ Pump OFF ] [ Heater OFF ]           │
└───────────────────────────────────────────────────────────────────┘

What Each Status Means in Practice

🟢 ONLINE (Green) - Device is Healthy

Device is polling normally (every 5 seconds)
Commands will be executed immediately
Session is active and refreshing
No action needed

🟡 AWAY (Yellow) - Device May Be Having Issues

Device missed 1-2 polls (10-20 seconds since last communication)
Possible causes:
- Temporary WiFi interference
- Device busy with sensor reading (DHT22 takes 2 seconds)
- Brief network congestion
- Device rebooting
Commands may be delayed but should still execute
Monitor the device; if it returns to ONLINE, no action needed

🔴 OFFLINE (Red) - Device is Not Communicating

No communication for over 5 minutes
Commands will not reach the device
Possible causes:
- Device unplugged or powered off
- WiFi disconnected (router issue, password changed)
- Device crashed or in boot loop
- Server connectivity issue (rare)
- IP address changed (should auto-recover)
Action required: Check device power and WiFi

⚠️ Important:

An OFFLINE device will NOT receive commands. The dashboard button will update the server state, but the device won't execute until it reconnects.

Session Expiry and Status

Each device has an active session that expires after a configurable time (default 60 minutes). The session refreshes automatically with each poll.

Session Status	Device Status	Can Control?
Active (refreshing)	🟢 ONLINE	✅ Yes
Expired, device polling	🟡 AWAY or 🔴 OFFLINE	❌ No (device needs new session)
No session (device deleted)	🔴 OFFLINE	❌ No (re-flash required)

🔐 Session Auto-Renewal:

Sessions refresh automatically every poll. As long as your device is ONLINE, the session stays active. You don't need to manually renew sessions.

Status Transitions

How Status Changes Over Time:

Device powers on
    ↓
Connects to WiFi
    ↓
Registers with server
    ↓
🟢 ONLINE (device active)
    ↓
WiFi disconnected (30 seconds)
    ↓
🟡 AWAY (device missed polls)
    ↓
Still disconnected (5+ minutes)
    ↓
🔴 OFFLINE (device unreachable)
    ↓
WiFi reconnects
    ↓
🟢 ONLINE (device resumes polling)

Session expiry timer resets on each poll.

Troubleshooting by Status

Device Stuck at AWAY (Yellow)

Possible Cause	Solution
Weak WiFi signal	Move device closer to router, check RSSI in debug
WiFi interference	Change WiFi channel, reduce interference sources
Device overloaded	Reduce polling frequency (modify firmware)
Router issues	Restart router, check for firmware updates

Device Shows OFFLINE (Red) But Serial Monitor Shows Activity

Cause: Device registered but dashboard not updating
Fix:
- Refresh dashboard (Ctrl+F5)
- Check that device ID matches
- Verify you're logged into the correct account
- Clear browser cache

Device Shows ONLINE But Commands Don't Work

Check relay logic (Positive vs Negative)
Verify GPIO pin connections
Check relay VCC (needs 5V)
Test relay with a simple blink sketch

Device Cycles Between ONLINE and OFFLINE

Cause: Power supply insufficient or device rebooting
Fix:
- Use external 5V 2A+ power supply
- Add capacitor (1000µF) across power pins
- Check for electrical interference

💡 Debug Console:

Use the Debug page (/debug/) to see real-time device status, last seen times, and session expiry for all your devices.

Understanding "Last Seen" Timestamps

The "Last Seen" field shows when your device last communicated with the server.

Last Seen Examples:
┌──────────────────────────────────────────────────────────────────┐
│  Last Seen: just now        → Device is ONLINE                   │
│  Last Seen: 2s ago          → Device is ONLINE                   │
│  Last Seen: 15s ago         → Device is AWAY (or just turned on) │
│  Last Seen: 2m ago          → Device is AWAY                     │
│  Last Seen: 10m ago         → Device is OFFLINE                  │
└──────────────────────────────────────────────────────────────────┘

Session Info Display

The dashboard shows session information for each device:

Session Display:
┌───────────────────────────────────────────────────────────────────────┐
│  📅 Session: ✓ 1 hours    → Session active, 1 hour left              │  
│  📅 Session: ⚠️ 5 minutes  → Session expiring soon                   │
│  📅 Session: ✗ Expired     → Session expired (device may reconnect) 
└───────────────────────────────────────────────────────────────────────┘

🔄 Session Renewal:

When a device polls, it automatically refreshes its session. A healthy ONLINE device will always show "✓ X hours" (where X is the configured session duration).

Common Status Questions

Q: Why does my device show AWAY after waking from deep sleep?

A: Devices in deep sleep don't poll. When they wake up, the status will update to ONLINE on the next poll (within 5 seconds).

Q: Can a device be ONLINE but not receive commands?

A: Yes, if the session expired but the device is still polling. The dashboard will show ONLINE but commands won't execute. The device will automatically get a new session on the next poll.

Q: How long does it take for OFFLINE to become ONLINE?

A: Within 5-10 seconds of the device reconnecting to WiFi and polling the server.

Q: Does the dashboard auto-refresh?

A: Yes, the dashboard automatically refreshes device status every 3 seconds (via the debug API).

Status Summary Table

Status	Color	Last Seen	Action Required
ONLINE	🟢 Green	< 10 seconds	None - device working
AWAY	🟡 Yellow	10-300 seconds	Monitor, may resolve itself
OFFLINE	🔴 Red	> 300 seconds	Check power and WiFi

🎯 Pro Tip:

Use the Debug page (/debug/) to see detailed status information including exact last seen times and session expiry for all your devices at a glance.

Next Steps

Now that you understand device status:

Tutorial 27: How to Claim and Manage Devices
Tutorial 25: Common Connection Issues and Fixes
Tutorial 29: WiFi Connection Troubleshooting
Use the Debug page to monitor your devices in real-time

📊 Quick Status Check:

If your device is ONLINE, it's working. If it's AWAY, wait a minute. If it's OFFLINE for more than 5 minutes, check power and WiFi.

Tutorial 26: Understanding Device Status (Online/Away/Offline)