Add Multi-Channel Measurement Querying (REST + WebSocket) #1431
Description
🚀 Feature Request: Add Multi-Channel Measurement Querying (REST + WebSocket)
Problem
Many modern sensors (e.g., BME680, BME688, Atlas Scientific multi-probes) expose several measurement
channels—temperature, humidity, pressure, gas, etc.—but the current API only allows querying
one channel UID at a time.
Mobile clients must loop over every channel, multiplying network round-trips, latency, and
power consumption. Attempting to subscribe to several channel UIDs at once over WebSocket
currently returns 404 (see thread below).
“There’s only API endpoints for querying one measurement channel at a time.
For multi-channel querying, a new endpoint would have to be created.”
– Kyle (June 27 2025, in e-mail)
Request
- REST – Add an endpoint that returns all channels from a given sensor or an arbitrary list
of channel UIDs in one payload. - WebSocket – Allow subscribing to multiple UIDs in a single connection so clients receive
synchronized real-time updates.
📐 Proposed API
1. REST
POST /api/measurements/multi
| Field | Type | Required | Example | Description |
|---|---|---|---|---|
channel_uids |
array<string> | Yes | ["2d3f…", "8c4a…"] |
Measurement‐channel UUIDs (existing IDs) |
start |
ISO-8601 | No | "2025-06-27T00:00:00Z" |
Start time (defaults to now – 1 h) |
end |
ISO-8601 | No | "2025-06-27T01:00:00Z" |
End time (defaults to now) |
avg |
integer | No | 60 |
Averaging period in seconds (matches existing single-channel param) |
Response 200
{
"channels": {
"2d3f…": [
{"timestamp": "2025-06-27T00:15:00Z", "value": 23.4},
…
],
"8c4a…": [
{"timestamp": "2025-06-27T00:15:00Z", "value": 51.1},
…
]
}
}
2. WebSocket
• Subscribe event:
{
"event": "subscribe_multi",
"channel_uids": ["2d3f…", "8c4a…"]
}
• Server push:
{
"uid": "2d3f…",
"timestamp": "2025-06-27T13:16:55Z",
"value": 23.7
}
🔨 Implementation Outline
1. REST route mycodo_api/routes/measurements.py
• Accept JSON array of channel IDs; validate length ≤ N (configurable).
• Re-use existing query/average helpers in a loop; aggregate results into dict.
2. WebSocket
• Extend current handler to recognise subscribe_multi.
• Store an array of UIDs in the session; push frames whenever any UID updates.
3. Docs / Swagger – Add schema + examples.
4. Unit tests – Cover: bad payload, > max-channels, success w/ 2+ channels, auth failure.
5. Backwards compatibility – Existing single-channel endpoints remain untouched.
⸻
✅ Acceptance Criteria
• One REST request returns data for N channels (tested with BME680’s 4 UIDs).
• WebSocket client receives live frames for every UID in its subscription.
• 404 / “unknown route” errors no longer occur for multi-UID requests.
• Performance: querying 4 channels in one call ≈ single call ×1.2 or better.
• New endpoints appear in Swagger UI.
• All existing measurement tests pass.