Hydros Connect + Official API

[johnacharles93]

Hello! I'm building the Home Assistant integration for HYDROS and planning to migrate to the official API. I've got some specific questions about how this affects Home Assistant users and what we need to plan for.

QUESTIONS ABOUT LIMITATIONS

RATE LIMITS FOR HOME ASSISTANT USE

The 10 state updates/min per key...that's tight for a multi-device setup. Home Assistant users often run:

• Sensor polling every 30-60 seconds
• Multiple automations that read/write state simultaneously
• Cross-tank automations that chain requests

With 3 tanks on 60-second polling, I'm at 3 updates/min just for reads. Add automations and I'm approaching the limit.

Questions:

• Can users request higher rate limit tiers?
• Is there a way to batch operations or will each update count separately?
• What happens at rate limit? (Error message? Backoff needed? Dropped request?)

POLLING VS. PUSH MODEL

The docs mention "polling sessions" (5/hour limit) For Home Assistant:

• Is WebSocket or Server-Sent Events on the roadmap?
• When would polling sessions launch? (Need to plan timeline)
• Will push notifications be included in the free tier or premium only?

If we're stuck with polling, I need to plan for higher latency and trade-offs between freshness and rate limits.

ERROR HANDLING & RESILIENCY

What are the edge cases?

• If a key gets invalidated or revoked mid-automation, what does HA get back? Specific error code?
• Are there transient errors vs. permanent auth failures? (Need to retry vs. immediate fail)
• If the API is down, do failed requests queue or just error immediately?
• Any circuit breaker patterns recommended for integration reliability?

Feature Requests:

Not blockers, but would make integration better:

1. Batch operations: Get/set multiple device states in one call instead of N calls
2. Query filtering: "Give me all devices in feed mode" instead of polling all devices
3. Webhook support: HA could expose a webhook to receive state change notifications
4. Scope granularity: "Read-only on tank 1, read-write on tank 2" from one key (instead of separate keys)

@hydros team:

• What's the recommended polling interval for a single device? (30s? 60s? longer?)
• When should I tell users to expect the migration from account auth to API keys?

Appreciate the clarity on these. Building a great integration requires understanding the real constraints and roadmap. I know this was a little chaotic and skattered, but I needed to get my thoughts out.

Thanks!

 

[Carlos]

RATE LIMITS FOR HOME ASSISTANT USE

The 10 state updates/min per key...that's tight for a multi-device setup. Home Assistant users often run:

• Sensor polling every 30-60 seconds
• Multiple automations that read/write state simultaneously
• Cross-tank automations that chain requests

With 3 tanks on 60-second polling, I'm at 3 updates/min just for reads. Add automations and I'm approaching the limit.

The limit here is PER DEVICE, not account-wide. Each key corresponds to one device, not the provider. Current rate limits should be fine for 30-second polling.

Questions:

• Can users request higher rate limit tiers?
• Is there a way to batch operations or will each update count separately?
• What happens at rate limit? (Error message? Backoff needed? Dropped request?)

• If the rate limits, as currently designed, are too strict, we will adjust. If you need substantially higher rate limits, we can talk.
• No batching yet, but with per-device keys driving the rate limit, it shouldn't be a big problem
• HTTP 429, JSON {"error":"Rate limit exceeded: ..."}, request dropped, retry after backoff. Not queued.

POLLING VS. PUSH MODEL

The docs mention "polling sessions" (5/hour limit) For Home Assistant:

• Is WebSocket or Server-Sent Events on the roadmap?
• When would polling sessions launch? (Need to plan timeline)
• Will push notifications be included in the free tier or premium only?

If we're stuck with polling, I need to plan for higher latency and trade-offs between freshness and rate limits.

• Something to consider for future enhancement.
• After the next firmware update, polling sessions will be live. Starting a session "wakes up" a device, and the device starts updating state every 30s (faster immediately after an override operation).
• The HYDROS app already offers push notifications.

ERROR HANDLING & RESILIENCY

What are the edge cases?

• If a key gets invalidated or revoked mid-automation, what does HA get back? Specific error code?
• Are there transient errors vs. permanent auth failures? (Need to retry vs. immediate fail)
• If the API is down, do failed requests queue or just error immediately?
• Any circuit breaker patterns recommended for integration reliability?

• 401/403 treat as permanent, 429 / 500 treat as transient
• Not currently. Key works or does not work.
• If the API is down, requests do not queue.

Feature Requests:

Not blockers, but would make integration better:

1. Batch operations: Get/set multiple device states in one call instead of N calls
2. Query filtering: "Give me all devices in feed mode" instead of polling all devices
3. Webhook support: HA could expose a webhook to receive state change notifications
4. Scope granularity: "Read-only on tank 1, read-write on tank 2" from one key (instead of separate keys)

1. Good idea! I will bring that up in the next developer meeting.
2. This would be a more fundamental change to the device/collective-scoped keys. The integration will need to track separate keys for each device/collective being controlled. To ensure we are on the same page, a collective (regardless of how many devices it has) uses only one device key.
3. This is also something to consider.
4. Not on the current roadmap.

@hydros team:

• What's the recommended polling interval for a single device? (30s? 60s? longer?)
• When should I tell users to expect the migration from account auth to API keys?

• 30 seconds. That's how fast the device sends updates after a session has started. It will keep sending 30-second updates for 6 hours. You can reset the 6-hour time up to 5 times per hour and get a new polling token.
  
  Immediately after sending an override, the device accelerates updates to once every 5 seconds. You can poll faster after the override is received to verify that the override change had the intended effect. The rate limit should allow occasional bursts of state polling. We will tune rate limits if needed
  
  
• The existing password flow will stop working sometime after 4 weeks from now. Using the API will be required after.