- ✓ Understanding pending devices vs claimed devices
- ✓ How automatic claiming works
- ✓ Manual claiming for conflict resolution (rare cases)
- ✓ Managing device settings after claiming
- ✓ Deleting devices and regenerating tokens
Pending Devices vs Claimed Devices
When you generate firmware from OceanRemote, the device configuration is stored as a pending device. Once the device connects and registers, it becomes a claimed device.
Device Lifecycle: ┌─────────────────────────────────────────────────────────────┐ │ │ │ Generate Firmware │ │ ↓ │ │ Pending Device (appears in dashboard) │ │ ↓ │ │ Flash firmware to device │ │ ↓ │ │ Device connects to WiFi │ │ ↓ │ │ Device registers with server │ │ ↓ │ │ ✅ AUTOMATICALLY CLAIMED (by the user who generated it) │ ↓ │ │ Claimed Device (appears in "My Devices" section) │ │ │ └─────────────────────────────────────────────────────────────┘
When a device registers, it is automatically claimed by the user who generated the firmware. You don't need to do anything. The device will appear in your "My Devices" section within seconds of registration.
This is the normal, expected behavior for 99.9% of devices.
Understanding the Dashboard Sections
My Devices Section
This section shows all your claimed devices. Each device appears as a card with controls.
My Devices Section: ┌─────────────────────────────────────────────────────────────┐ │ MY DEVICES │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Kitchen Controller 🟢 ONLINE │ │ │ │ ─────────────────────────────────────────────────── │ │ │ │ WiFi: MyHomeWiFi │ │ │ │ IP: 192.168.1.100 │ │ │ │ Last Seen: just now │ │ │ │ 🔐 Secure v2 │ │ │ │ ─────────────────────────────────────────────────── │ │ │ │ [ Lights OFF ] [ Fan OFF ] [ Pump OFF ] │ │ │ │ │ │ │ │ [ DETAILS ] [ DELETE ] │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘
Pending Devices Section
This section shows devices that have been configured but haven't registered yet, or devices awaiting manual claim (rare).
Pending Devices Section: ┌─────────────────────────────────────────────────────────────┐ │ PENDING DEVICES │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ New Device Ready READY │ │ │ │ ─────────────────────────────────────────────────── │ │ │ │ Code: ESP_AABBCCDDEEFF │ │ │ │ Board: ESP8266 D1 Mini │ │ │ │ Created: 2 hours ago │ │ │ │ │ │ │ │ [ CLAIM THIS DEVICE ] [ DELETE ] │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘
Pending devices expire after 24 hours. If you don't flash and register the device within this time, you'll need to generate new firmware.
Automatic Claiming (Normal Operation)
For the vast majority of users, device claiming happens automatically. Here's how it works:
- You generate firmware from your OceanRemote account
- Your account information is embedded in the firmware's registration token
- When the device first connects, it sends the registration token to the server
- The server identifies which user generated the token
- The device is automatically claimed by that user
- The device appears in your "My Devices" section within seconds
In normal operation, you never need to click "CLAIM THIS DEVICE". Automatic claiming handles everything. The "Pending Devices" section is primarily informational.
Manual Claiming (Rare Conflict Cases)
In very rare circumstances, a device may not be automatically claimed. This can happen if:
- Network interruption during registration
- Server-side processing delay (less than 1% of cases)
- Multiple users generating firmware with the same token (extremely rare)
When to Claim Manually:
- Your device is powered on and connected to WiFi (check Serial Monitor)
- The device shows as registered in Serial Monitor
- But the device is not appearing in your "My Devices" section
- The device appears in "Pending Devices" section instead
How to Claim Manually:
- Go to your OceanRemote dashboard
- Scroll to the "Pending Devices" section
- Find the device you want to claim
- Click the "CLAIM THIS DEVICE" button
- The device will move to "My Devices" section
- You can now control it normally
Manual claiming does not affect your device's operation. It simply links the pending configuration to your account. Your device will continue working normally.
Managing Device Settings
Click the "DETAILS" button on any device card to access advanced settings.
Device Detail Page Features:
- Security & Authentication - View token status, regenerate or revoke tokens
- System Information - View device ID, last seen, IP address, board type
- Relay Configuration - Change relay names and logic (see Tutorial 23)
- Sensor Configuration - View sensor type and calibration offset
- Token Management - Upgrade legacy devices to Secure v2
Device Detail Page Example: ┌─────────────────────────────────────────────────────────────┐ │ DEVICE DETAILS │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Security & Authentication │ │ │ │ 🔐 Secure Token Active │ │ │ │ Type: Permanent │ │ │ │ Created: March 30, 2026 │ │ │ │ │ │ │ │ [ Regenerate Token ] [ Revoke Token ] │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ System Information │ │ │ │ Device ID: ESP_AABBCCDDEEFF │ │ │ │ Last Seen: just now │ │ │ │ IP Address: 192.168.1.100 │ │ │ │ Board: ESP8266 D1 Mini │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘
Deleting a Device
To remove a device from your account:
- Find the device card in "My Devices" section
- Click the "DELETE" button
- Confirm deletion in the popup dialog
- The device will be removed from your dashboard
Deleting a device is permanent and cannot be undone. The device will no longer appear in your dashboard, and you'll need to generate new firmware to reconnect it.
Deleting a device does NOT delete the physical device or its firmware. The device will continue polling but will receive 404 errors. You can re-flash it with new firmware to reconnect.
Deleting a Pending Device
To remove an unclaimed pending device:
- Scroll to "Pending Devices" section
- Click the "DELETE" button next to the device
- Confirm deletion
- The pending configuration is removed
- Clean up expired configurations (they auto-delete after 24 hours)
- Remove test devices you no longer need
- Free up mental space - keep your dashboard clean
Token Management
Secure v2 Tokens (Recommended)
All new devices use Secure v2 tokens. These provide:
- ✅ MAC address binding (prevents token cloning)
- ✅ One-time registration tokens
- ✅ Automatic session management
- ✅ Rate limiting for security
Regenerating a Token
If you suspect your token has been compromised, or you want to force a device to re-authenticate:
- Go to device DETAILS page
- Click "Regenerate Token"
- Confirm the action
- A new token is generated (old token is revoked)
- You'll receive new firmware code to flash
- Flash the new firmware to your device
Revoking a Token
To immediately disconnect a device (e.g., stolen device):
- Go to device DETAILS page
- Click "Revoke Token"
- Confirm the action
- The device will be disconnected immediately
- The device cannot reconnect until you generate new firmware
Regenerating or revoking a token will disconnect your device. You must flash new firmware to restore connectivity.
Upgrading Legacy Devices
If you have older devices using Legacy v1 tokens, you'll see an "Upgrade to Secure v2" option in the device details page.
- Click "Upgrade to Secure v2"
- A new secure token is generated
- You'll receive new firmware code
- Flash the new firmware to your device
- Your device will now use Secure v2 authentication
Secure v2 tokens provide MAC address binding, preventing token cloning. This is a significant security improvement over legacy tokens.
Common Scenarios
Scenario 1: Device registered but not showing in dashboard
- Wait 10-15 seconds (registration takes a moment)
- Refresh the dashboard (Ctrl+F5)
- Check "Pending Devices" section
- If device is pending, click "CLAIM THIS DEVICE"
- If not found, check Serial Monitor for errors
Scenario 2: Device shows in dashboard but can't control
- Check device status (should be 🟢 ONLINE)
- If AWAY or OFFLINE, wait for device to reconnect
- Check relay logic (Positive vs Negative) in DETAILS page
- Verify wiring (relay VCC needs 5V)
Scenario 3: Device was deleted accidentally
- Generate new firmware from "Add New Device" page
- Flash the new firmware to your device
- Device will register as a new device
- Previous device history is lost (cannot be recovered)
| Action | Result | Requires Re-flash? |
|---|---|---|
| Delete device | Device removed from account | ✅ Yes (generate new firmware) |
| Regenerate token | New token, old token revoked | ✅ Yes (flash new firmware) |
| Revoke token | Device disconnected immediately | ✅ Yes (to reconnect) |
| Change relay name/logic | Dashboard updates instantly | ❌ No (server-side only) |
| Upgrade to Secure v2 | New token, legacy token revoked | ✅ Yes (flash new firmware) |
Next Steps
Now that you understand device claiming and management:
- Tutorial 28: Temperature Calibration with Offset
- Tutorial 29: WiFi Connection Troubleshooting
- Tutorial 30: FAQ and Best Practices
- Return to Tutorial 02: Generate firmware for new devices
Device claiming is automatic in most cases. Simply generate firmware, flash your device, and it will appear in your dashboard. Manual claiming is only needed in rare conflict situations.