Download OpenAPI specification:
API contract for monitoring and controlling water tank level in espresso machines. Provides accurate level estimation (±1 cm accuracy), safety interlocks to prevent dry-run and overfill conditions, calibration support, and diagnostic information.
Implementation Note: This OpenAPI specification documents the API contract structure. The actual implementation uses in-code adapters (Python classes) rather than HTTP REST endpoints. The adapters (StatusAdapter, DiagnosticsAdapter, CalibrationAdapter) are called directly from Python code and return dictionaries matching the schemas defined in this specification. The HTTP endpoint paths shown here serve as a contract convention - if an HTTP server layer is added in the future, this contract defines the expected structure.
Returns the current water tank level percentage, state classification, sensor health status, and timestamp of last measurement update. This endpoint is read-only and provides real-time monitoring data.
{- "level_percent": 50,
- "state": "OK",
- "sensor_ok": true,
- "last_update_ms": 1000000
}Returns system diagnostics including moving window statistics (mean and variance of recent distance measurements), fault history, system uptime, and watchdog kick count. Useful for health monitoring and troubleshooting.
{- "moving_window_size": 10,
- "moving_mean_distance_mm": 200.5,
- "moving_variance_distance_mm2": 15.2,
- "last_faults": [ ],
- "uptime_ms": 3600000,
- "watchdog_kicks": 5
}Returns the current calibration profile containing empty and full distance measurements. These values are used to compute level percentage and state classification. Calibration is stored in non-volatile memory and persists across power cycles.
{- "empty_distance_mm": 350,
- "full_distance_mm": 100,
- "version": "1.0",
- "updated_at_ms": 1000000,
- "checksum": "abc123"
}Sets the calibration profile by capturing empty and full distance measurements. The empty distance must be greater than the full distance. The calibration is validated and stored in non-volatile memory. This operation may take longer due to NVM write operations.
Calibration profile with empty and full distance measurements
| empty_distance_mm required | number [ 20 .. 450 ] Distance measurement in millimeters when tank is empty. Must be greater than full_distance_mm. |
| full_distance_mm required | number [ 20 .. 450 ] Distance measurement in millimeters when tank is full. Must be less than empty_distance_mm. |
{- "empty_distance_mm": 350,
- "full_distance_mm": 100
}{- "error": "ValidationError",
- "message": "empty_distance_mm (250.0) must be greater than full_distance_mm (300.0)"
}