Devices
Manage Shelly IoT relays, configure usage plans, and control device power remotely.
Overview
Devices in Hygate are Shelly IoT relays that control appliances like washing machines, dryers, EV chargers, and other equipment. Guests pay for time-based access to these devices through usage plans.
Adding a Device
Prerequisites
Before adding devices, configure the Shelly integration in Settings → Shelly.
Step 1: Sync Devices
- Go to Devices
- Click Sync from Shelly
- Wait for the device list to load
- Review the list — already-added devices appear disabled
Step 2: Configure Each Device
| Setting | Required | Description |
|---|---|---|
| Shelly Device | Yes | The device from your Shelly Cloud account |
| Location | Yes | Physical location assignment |
| Name | No | Display name (e.g., "Washer 1", "EV Charger A") |
| Description | No | Internal notes |
| Channel | No | Relay channel (for multi-channel devices) |
Step 3: Add Usage Plans
After adding the device, create at least one usage plan (see below).
Step 4: Save
Usage Plans
Usage plans define the pricing and time structure for each device session.
What Makes Up a Usage Plan
| Field | Description | Example |
|---|---|---|
| Program Name | Guest-facing name | "1-Hour Wash" |
| Description | Optional details | "Standard cotton cycle" |
| Duration | Session length in minutes | 60 |
| Delayed Start | Grace period before timer starts | 5 minutes |
| Price | Amount in your currency | €2.50 |
| Sort Order | Display order on payment page | 1 |
| Active | Whether guests can select this plan | true |
Why Delayed Start Exists
The delayed start gives guests a grace period to prepare before the timer begins:
| Use Case | Why Delay Matters |
|---|---|
| Laundry | Guest needs to load clothes, add detergent, close the door |
| EV Charging | Guest needs to connect the charging cable |
| Gym Equipment | Guest needs to adjust settings, wipe down surfaces |
| Tanning Bed | Guest needs to apply lotion, get positioned |
| Massage Chair | Guest needs to remove shoes, sit comfortably |
Creating a Usage Plan
- Open the device detail page
- Scroll to Usage Plans
- Click Add Usage Plan
- Fill in the fields (see table above)
- Set Sort Order to control display order
- Toggle Active on
- Save
Multiple Plans Per Device
You can offer multiple plans for the same device. For example, a single washer might offer:
| Plan | Duration | Delay | Price |
|---|---|---|---|
| Quick Wash | 30 min | 3 min | €1.50 |
| Standard Wash | 60 min | 5 min | €2.50 |
| Extended Dry | 90 min | 5 min | €3.50 |
Managing Usage Plans
- Edit — Change price, duration, or any field
- Reorder — Change sort order to reorder on the payment page
- Deactivate — Turn off without deleting (existing sessions continue)
- Delete — Remove the plan entirely (only if no active sessions use it)
Device Status
Active Mode
The device accepts payments and relay commands. This is the default mode.
Maintenance Mode
New payments are blocked. Active sessions continue unaffected.
| What Happens | Active Mode | Maintenance Mode |
|---|---|---|
| New payments accepted | Yes | No |
| Relay controllable | Yes | No |
| Existing sessions affected | No | No |
| Visible in dashboard | Yes | Yes (badge) |
When to use maintenance mode:
- Equipment needs inspection or repair
- Staff needs to clear a jam or perform maintenance
- You want to temporarily stop new sales without affecting current users
Relay Control
Hygate sends real-time commands to Shelly devices to control power.
Manual Control
From the device detail page:
- Power ON — Turns the relay on immediately
- Power OFF — Turns the relay off immediately
These commands are useful for:
- Testing device connectivity
- Emergency shutdown
- Manual overrides
Automatic Control
During a guest session, Hygate manages the relay automatically:
Payment confirmed
│
▼
Grace period starts (delayMinutes)
┌──────────────────────────────────────┐
│ Guest loads laundry / prepares │
│ device │
└──────────────────────────────────────┘
│
▼
Timer starts → Relay turns ON
│
▼
Guest sees countdown on session page
(polling every 2 seconds)
│
▼
Timer reaches 0 → Relay turns OFF
│
▼
Session marked COMPLETED
Relay Reliability
Hygate includes automatic retry logic for relay commands:
| Command | Retries | Timeout | On Final Failure |
|---|---|---|---|
| Power ON | 3 attempts | 5 seconds each | Session marked CANCELLED |
| Power OFF | 3 attempts | 5 seconds each | Logged, retry on next cycle |
Device Session Lifecycle
Session States
| State | Relay | Timer | Guest Sees |
|---|---|---|---|
| ACTIVE | ON | Running | Countdown circle |
| COMPLETED | OFF | Finished | "Session Complete" |
| CANCELLED | OFF | Ended early | "Session Ended" |
Session States Explained
ACTIVE
The relay is on and the countdown is running. The guest sees a live countdown circle on their session page. The page polls every 2 seconds for updates.
COMPLETED
The timer reached zero and the relay was turned off normally. This is the expected end state.
CANCELLED
The session ended before the timer expired. This can happen because:
- Admin force-ended — You manually ended the session
- Relay failure — The relay turned off unexpectedly
- Reconciliation — The background reconciliation process detected the relay was off
Cancelled sessions are logged with a failure reason.
The Countdown Circle
The guest-facing session page shows a countdown circle with seven states:
| State | When It Appears |
|---|---|
| Loading | Initial load while session data is fetched |
| Running | ACTIVE session with time remaining |
| Finishing | ACTIVE session with 0 seconds remaining (waiting for relay OFF) |
| Complete | Session finished normally |
| Interrupted | Session cancelled after starting |
| Failed to Start | Session cancelled before relay turned on |
| Unavailable | Device went offline during the session |
Startup Recovery
When the Hygate server restarts, it performs a recovery check on all active sessions:
- Query all ACTIVE sessions
- Check each session:
- If expired → turn relay OFF, mark COMPLETED
- If not expired → verify relay state
- Relay ON → session is valid, log confirmation
- Relay OFF → mark CANCELLED (interrupted)
- Log all recovery actions in audit logs
This ensures no sessions are left in an orphaned state after downtime.
Session Reconciliation
A background reconciliation process runs every 2 minutes to verify session integrity:
| Check | Action |
|---|---|
| Relay is ON but session not started | Wait for grace period |
| Relay is OFF but session still ACTIVE | Mark as CANCELLED |
| Session expired but still ACTIVE | Force completion |
Why Reconciliation Matters
- Relay bugs — Some Shelly devices can lose relay state during power fluctuations
- Network issues — Temporary network loss can prevent a command from completing
- Race conditions — Payment confirmation race conditions are caught
- Ghost sessions — Stuck sessions are identified and resolved
Multi-Channel Devices
Some Shelly devices have multiple relay channels. You can configure each channel as a separate Hygate device, allowing different usage plans and independent control per channel.
For example, a Shelly Pro 4PM with 4 channels could represent:
- Channel 1 → Washer 1
- Channel 2 → Washer 2
- Channel 3 → Dryer 1
- Channel 4 → Dryer 2
Troubleshooting
Device Shows Offline
| Check | Action |
|---|---|
| Shelly device online | Check Shelly Cloud app or device status |
| Shelly credentials | Verify Auth Key in Settings → Shelly |
| Network connectivity | Ensure Shelly device has WiFi/Ethernet connection |
| Channel configured | Verify the correct channel number is set |
Relay Won't Turn On
| Check | Action |
|---|---|
| Device status | Ensure device is not in Maintenance Mode |
| Active session | Check Sessions page for conflicting sessions |
| Network | Verify Hygate can reach Shelly Cloud API |
| Retry | Click Power ON again — relay commands are retried automatically |
Session Not Ending Automatically
- Go to Sessions
- Find the active session
- Click Force End to manually terminate
The reconciliation process also runs every 2 minutes to catch and end stale sessions.
Payment Succeeded But Relay Didn't Turn On
| Check | Action |
|---|---|
| Active sessions | Check Sessions page — was a session created? |
| Device status | Is the device in Maintenance Mode? |
| Relay failure | Was the relay ON? Check session failure reason |
| Retry | Navigate to the session → Retry Activation |
Usage Plan Not Showing on Payment Page
| Check | Action |
|---|---|
| Plan is Active | Check the plan's Active toggle |
| Price is > 0 | Free plans may be handled differently |
| Device is Active | Check device status |
| Sync | Regenerate the payment link |