Shelly Integration
Connect your Shelly IoT relays to Hygate for time-based paid device access.
Overview
Shelly is a line of WiFi-connected IoT relays and sensors. Hygate integrates with Shelly Cloud to sync your devices, control relay power, and manage timed device sessions for guests.
What You Need
Before setting up Shelly in Hygate, you need:
- A Shelly Cloud account (at shelly.cloud)
- Shelly devices that are online and connected to your account
- An Auth Key generated from Shelly Cloud
Getting a Shelly Auth Key
Step 1: Create a Shelly Cloud Account
- Go to shelly.cloud and create an account
- Add your Shelly devices to your account
- Ensure all devices are online
Step 2: Generate an Auth Key
- Log in to Shelly Cloud
- Go to Account → Auth Key (or your profile settings)
- Click Generate new key
- Give the key a name (e.g., "Hygate Integration")
- Copy the Auth Key
Step 3: Enter in Hygate
- Go to Settings → Shelly
- Paste the Auth Key
- The Server URL is usually pre-filled — leave it as default unless you have a custom deployment
- Click Test Connection
- If successful, click Save
How the Integration Works
Device Synchronization
When you click Sync from Shelly, Hygate calls the Shelly Cloud API to retrieve your device list:
Hygate → Shelly Cloud API: listDevices(auth_key)
│
▼
Returns: deviceId, deviceName, deviceType, channelCount, onlineStatus
│
▼
Devices matched against Hygate database
Already-added devices shown as disabled
Relay Control
Hygate sends relay commands via the Shelly Cloud API:
Turn ON: Hygate → Shelly Cloud API: relayOn(deviceId, channel)
Turn OFF: Hygate → Shelly Cloud API: relayOff(deviceId, channel)
Reliability
Hygate implements hardened relay control with:
| Feature | Detail |
|---|---|
| Timeout | 5 seconds per command |
| Retries | Up to 3 attempts per command |
| Backoff | 500ms delay between retries |
| Error handling | 4xx errors treated as non-fatal for OFF commands |
| Logging | All commands logged for audit and debugging |
Session Activation
[1] Guest payment confirmed
│
▼
[2] Hygate creates DeviceSession (ACTIVE)
│
▼
[3] Grace period starts (delayMinutes from usage plan)
┌──────────────────────────────────────────┐
│ Guest loads laundry / connects cable │
│ Relay is NOT yet activated │
└──────────────────────────────────────────┘
│
▼
[4] Timer starts
Hygate → Shelly API: relayOn(deviceId, channel)
│
▼
[5] Relay confirmed ON
Session visible in dashboard
Guest countdown begins
│
▼
[6] Timer ends
Hygate → Shelly API: relayOff(deviceId, channel)
│
▼
[7] Relay confirmed OFF
Session marked COMPLETED
Device Types Supported
Hygate supports all Shelly devices with relay functionality:
| Device Type | Supported | Notes |
|---|---|---|
| Shelly 1 / 1PM | Yes | Single channel relay |
| Shelly 2 / 2.5 | Yes | Dual channel relay |
| Shelly 4Pro / 4PM | Yes | Quad channel relay |
| Shelly Plug / Plug S | Yes | Single channel with power monitoring |
| Shelly Pro series | Yes | Industrial-grade relays |
| Shelly Plus series | Yes | Enhanced processing |
| Shelly Bulb | Partial | Light control (not relay-based) |
| Shelly Sensor | Partial | Temperature/humidity (monitoring only) |
Multi-Channel Devices
For devices with multiple relay channels (like Shelly 4PM), each channel can be configured as a separate Hygate device. This allows:
- Independent usage plans per channel
- Individual relay control per channel
- Separate QR codes per channel
Example: A Shelly Pro 4PM with 4 channels:
- Channel 1 → "Washer 1" (€2.50 / 60 min)
- Channel 2 → "Washer 2" (€2.50 / 60 min)
- Channel 3 → "Dryer 1" (€2.00 / 45 min)
- Channel 4 → "Dryer 2" (€2.00 / 45 min)
What Happens When Shelly Is Disabled
If you disable Shelly in Settings → General:
| Effect | Description |
|---|---|
| Devices page hidden | Operators cannot access the Devices module |
| Device payment flow disabled | Guests cannot purchase device access |
| Existing sessions continue | Active sessions are not affected |
| Device configurations preserved | Device data remains in the database |
Troubleshooting
"Connection test failed"
| Check | Action |
|---|---|
| Auth key | Verify the Auth Key is correct and not expired |
| Shelly Cloud status | Check shelly.cloud for service status |
| Devices online | Ensure devices are connected to WiFi and online in Shelly app |
| Network | Ensure Hygate can reach Shelly Cloud API |
Device Shows Offline
| Check | Action |
|---|---|
| Device WiFi | Check the Shelly device is connected to your network |
| Shelly Cloud pairing | Verify the device is paired with your Shelly Cloud account |
| Power | Ensure the device has power |
| Ping | Try pinging the device directly |
Relay Won't Turn On
| Check | Action |
|---|---|
| Device status | Ensure the device is not in Maintenance Mode |
| Session conflict | Check for an existing ACTIVE session on the same device |
| Network | Verify Shelly Cloud API is reachable |
| Retry | Relay commands have built-in retries — wait and try again |
Session Started But Relay Not On
| Check | Action |
|---|---|
| Audit logs | Check for shelly_on_success or shelly_on_failed |
| Retry activation | Navigate to Sessions → find the session → retry |
| Force-end | If relay is truly stuck, use Force End |
Auth Key Revoked
If you revoke your Shelly Auth Key:
- Generate a new key from Shelly Cloud
- Update the key in Settings → Shelly
- Click Test Connection
Security Notes
- Shelly credentials are encrypted at rest in the Hygate database
- Auth keys provide full API access — treat them like passwords
- Rotate auth keys regularly (every 90 days recommended)
- Do not share auth keys with operators — only admins should have access
- Monitor device activity in audit logs for unauthorized access