Sessions
Monitor and manage active device access sessions in real time.
Overview
Sessions represent active or completed access to Shelly-controlled devices. Each session tracks who used the device, when they used it, and how long they had access.
Door access does not use sessions — it uses QR access codes that are checked directly at the lock. Only Shelly device sessions are tracked in this module.
Session States
| State | Relay | Timer | Guest Experience |
|---|---|---|---|
| ACTIVE | ON | Running | Countdown circle visible |
| COMPLETED | OFF | Expired | "Session Complete" message |
| CANCELLED | OFF | Ended early | "Session Ended" message |
Understanding Each State
ACTIVE
The relay is powered on and the countdown is running. The guest can see a live countdown circle on their session page, which polls every 2 seconds for updates.
Active sessions appear on the Dashboard as the primary operational metric.
COMPLETED
The timer reached zero and the relay was automatically turned off. This is the expected, successful end state for a session.
CANCELLED
The session ended before the timer expired. This is an abnormal termination and is logged with a failure reason.
Common cancellation reasons:
| Reason | Cause |
|---|---|
force_ended_by_admin | Administrator manually ended the session |
relay_off_prematurely | Relay lost power before session ended |
reconciliation_timeout | Background process detected relay was off |
payment_reversed | Stripe reversed the payment after session started |
Viewing Sessions
Session List
The Sessions page shows all sessions with filtering options:
| Filter | Description |
|---|---|
| Status | ACTIVE, COMPLETED, or CANCELLED |
| Device | Filter by specific device |
| Location | Filter by physical location |
Session Details
Click any session to see the full details:
| Field | Description |
|---|---|
| Session Token | Unique identifier for the session |
| Device | Name of the Shelly device |
| Location | Where the device is located |
| Usage Plan | Which plan the guest selected |
| Duration | Configured session length (minutes) |
| Actual Duration | Time between relay ON and relay OFF |
| Started At | When the grace period began |
| Ends At | When the session timer expires |
| Status | ACTIVE, COMPLETED, or CANCELLED |
| Payment ID | Reference to the Stripe payment |
| Guest Token | Token for the guest's session page |
| Failure Reason | Why the session was cancelled (if applicable) |
Session Countdown Circle
The guest-facing session page shows a visual countdown circle with seven distinct states:
States
| State | Trigger | Color |
|---|---|---|
| Loading | Initial fetch while session data loads | Gray |
| Running | Active session with time remaining | Primary color |
| Finishing | Active session at 0 seconds remaining | Primary color |
| Complete | Session ended normally | Green |
| Interrupted | Session cancelled after starting | Amber |
| Failed to Start | Session cancelled before relay turned on | Red |
| Unavailable | Device went offline during session | Red |
Polling Behavior
| Phase | Polling Interval | Why |
|---|---|---|
| Initial load | Every 2 seconds | Fast feedback during active session |
| Steady state | Every 30 seconds | Reduce server load during long sessions |
| Finishing (< 60s remaining) | Every 2 seconds | Precise end-time notification |
Admin Recovery Actions
For active sessions that need manual intervention:
Force End
Ends the session immediately — turns the relay off and marks the session as COMPLETED.
When to use:
- Guest has left but relay won't turn off automatically
- Equipment malfunction requiring immediate shutdown
- Guest requests early termination (with consent)
Mark as Failed
Logs the session as CANCELLED with a failure reason without sending a relay command.
When to use:
- Technical error prevented session from starting
- Payment was reversed mid-session
- Equipment damage during session
Session Lifecycle (Full)
[1] Guest Payment
│
▼
Stripe Payment Intent created
Status: PENDING
│
▼
[2] Payment Confirmed
Stripe webhook: payment_intent.succeeded
│
▼
[3] Session Created
DeviceSession created with status: ACTIVE
│
▼
[4] Grace Period (delayMinutes)
Relay state is checked but NOT activated
┌────────────────────────────────────┐
│ Guest loads laundry / connects cable│
│ Timer has not started yet │
└────────────────────────────────────┘
│
▼
[5] Timer Starts
Relay turns ON
Countdown begins
Guest sees countdown circle (polls every 2s)
│
▼
[6] Finishing
Remaining seconds = 0
Waiting for relay OFF command
│
▼
[7] Relay OFF
Relay turns OFF
Session marked COMPLETED
Background Processes
Startup Recovery
When Hygate starts, it scans for active sessions:
- Query all ACTIVE sessions
- For each session:
- If expired (endsAt < now) → turn relay OFF, mark COMPLETED
- If valid → verify relay is ON, log confirmation
- If relay is OFF → mark CANCELLED (interrupted)
This prevents orphaned sessions after server restarts.
Session Cleanup (Every 5 Minutes)
A cron job runs every 5 minutes to expire stale sessions:
- Find all ACTIVE sessions where endsAt < now
- Turn relay OFF for each
- Mark as COMPLETED
- Retry if relay OFF fails
Session Reconciliation (Every 2 Minutes)
A reconciliation job runs every 2 minutes to catch state mismatches:
- Find all ACTIVE sessions where relay state does not match
- If relay is OFF but session is ACTIVE → mark CANCELLED
- If session is expired but ACTIVE → force completion
- Log all reconciliation actions
Role Permissions
| Action | Administrator | Operator |
|---|---|---|
| View all sessions | Yes | Yes |
| Force end a session | Yes | No |
| Mark as failed | Yes | No |
| View session details | Yes | Yes |
Troubleshooting
Session Stuck on "Finishing"
- Go to Sessions
- Find the active session
- Click Force End
The reconciliation job also catches these every 2 minutes automatically.
Session Not Starting
| Check | Action |
|---|---|
| Payment succeeded | Check Payments for a SUCCEEDED record |
| Device not in maintenance | Verify device status is Active |
| Relay command succeeded | Check audit logs for shelly_on_success |
| No conflicting session | Only one ACTIVE session per device |
Session Cancelled Unexpectedly
| Check | Action |
|---|---|
| Relay offline | Check Shelly device connectivity |
| Power fluctuation | Check power supply to the Shelly device |
| Reconciliation log | Check audit logs for reconciliation events |
| Payment reversed | Check Stripe for chargebacks |
Multiple Sessions on Same Device
Hygate prevents overlapping sessions. If payment fails because a session is already active, the guest sees a message indicating the device is in use.