Flume Water Monitor

Current flow rate, water-running state, usage totals (today / this month / last hour), battery, and cloud notification mirroring (smart leak alerts, usage alerts) for Flume 1 and Flume 2 whole-home water monitors via the api.flumewater.com Personal API.

Flume hardware is read-only — a strap-on sensor on the utility meter plus a Wi-Fi bridge. There is nothing to actuate; the value in GEM is telemetry and alerting: leak-alert triggers into notification profiles, irrigation cross-checks, and usage history.

Cloud-only path

Flume publishes no LAN protocol. The GEM host must have outbound HTTPS to api.flumewater.com. If the internet path is down, no telemetry flows even though the bridge is on the same LAN.

Prerequisites

• A Flume account with the bridge and sensor onboarded through the Flume mobile app.
• A personal API client. Sign in to portal.flumetech.com, open Settings → API Access, and click Generate API Client. This yields the client_id and client_secret. A portal-generated client can only authenticate the account that created it.
• Personal clients are rate limited to 120 requests/hour (HTTP 429 beyond that). The driver budgets around this automatically — see Rate limiting.

Setup

1. Navigate to Admin → Devices and click Add Device.
2. Choose flume as the driver.
3. Fill in:
   • API Client ID (client_id) and API Client Secret (client_secret) — from the portal's API Access page.
   • Flume Account Email (username) and Flume Account Password (password) — the mobile-app login. Secret and password are stored encrypted.
4. Save the device. GEM authenticates with the OAuth password grant, decodes the user_id from the JWT access token, and discovers hardware.
5. Run the get_devices command (device detail page, Commands tab). Bridges report type=bridge; the meter sensors report type=sensor.
6. Under Admin → Zones, create one zone per sensor:
   • Subsystem: a plumbing/water subsystem (or security if the sensor is primarily a leak-response input).
   • Address: the sensor's id string from get_devices. Do not use the bridge id — bridges carry no flow data.
7. On the next poll the zone populates state, flow_rate, usage_today, usage_month, usage_last_hour, battery_level, and the notification attributes.

Attribute reference

Device attributes

Attribute	Required	Description
client_id	yes	Personal API client id from the Flume portal.
client_secret	yes	Personal API client secret. Stored encrypted.
username	yes	Flume cloud account email.
password	yes	Flume cloud account password. Stored encrypted.
api_base	no	Cloud endpoint. Defaults to https://api.flumewater.com.
units	no	Unit for the usage_* attributes: GALLONS (default), LITERS, CUBIC_FEET, or CUBIC_METERS.
status_interval	no	Poll interval in ms. Default 120000, floor 60000. Stretched automatically when needed to stay inside the rate budget.
request_timeout	no	HTTP request timeout in ms. Default 15000.

Zone attributes (populated by the driver)

Attribute	Type	Description
state	string	on while water is actively flowing, off when idle. Mirrors the cloud's active flag, which can lag real flow by a minute or two.
flow_rate	float	Current flow in gallons per minute.
usage_today	float	Usage since local midnight, in the configured units.
usage_month	float	Usage since the first of the month.
usage_last_hour	float	Usage over the trailing 60 minutes.
battery_level	string	Sensor battery, as reported by the cloud: low, medium, or high.
sensor_connected	boolean	Whether the cloud currently sees the sensor.
last_seen	string	Last cloud check-in datetime for the sensor.
timezone	string	IANA timezone of the Flume location. Discovered automatically; day/month usage boundaries are computed in this timezone.
last_notification	string	Message of the newest cloud notification for this sensor.
last_notification_type	string	usage_alert, budget, general, heartbeat, or battery.
last_notification_datetime	string	Timestamp of the newest notification — the trigger-friendly change signal.
usage_alert_active	boolean	true while an unread usage alert (including Flume smart leak alerts) exists for this sensor. Clears when the alert is marked read in the Flume app.

Commands

Command	Args	Description
get_devices	—	List account hardware: id, type (bridge/sensor), product, connectivity, battery, location, timezone.
get_status	address	Poll one sensor now (flow + usage totals) and apply to its zone.
query_usage	address, bucket, since_datetime, until_datetime, operation, units, group_multiplier	Ad-hoc usage query. Buckets MIN/HR/DAY/MON/YR; operations SUM/AVG/MIN/MAX/CNT. Datetimes are YYYY-MM-DD HH:MM:SS in device-local time.
get_notifications	limit, unread_only	Recent account notifications, newest first.
get_usage_alerts	address, limit	Usage alerts (including smart leak alerts) for a sensor.
refresh_token	—	Discard the cached OAuth token and re-authenticate.

Rate limiting

Each poll tick costs 2 requests per sensor (current flow + one batched usage query) plus 1 notifications fetch, and a device-cache refresh every 5th tick. The driver computes this per-tick cost and stretches the effective poll interval so the account stays near 100 requests/hour, leaving headroom of the 120/hour limit for manual commands. On a 429 response it additionally backs off the next polls (up to 4×) until a tick completes cleanly. With one sensor at the default 120 s interval the budget is comfortable; each additional sensor on the same account stretches the interval automatically (a log line notes the effective value).

Leak alerting

Flume's "Smart Leak Alert" arrives as a usage-alert notification. Two trigger patterns:

• Edge: trigger on last_notification_datetime change, filtered by last_notification_type = usage_alert — fires once per new alert.
• Level: trigger on usage_alert_active = true — stays raised until the alert is marked read in the Flume app, useful for status dashboards and shelving-style alarm flows.

Troubleshooting

Symptom	Check
400/403 from /oauth/token on connect	Verify all four credentials. client_id/client_secret come from the portal API Access page and only work for the generating account. A 403 means the Flume account never finished signup.
HTTP 429 in the log, telemetry gaps	The 120 requests/hour budget is exhausted — status_interval too low or several sensors on one account. Raise the interval; the driver self-heals via stretch + backoff.
usage_today resets at an odd hour	Day boundaries follow the Flume location timezone (timezone zone attribute), set in the Flume app. Correct it there.
get_devices works but no telemetry	The zone address is the bridge id. Use a type=sensor id.