https://github.com/alertua/gaggiuino_api
Gaggiuino REST API Wrapper for Python
https://github.com/alertua/gaggiuino_api
api-rest gaggiuino python
Last synced: about 1 year ago
JSON representation
Gaggiuino REST API Wrapper for Python
- Host: GitHub
- URL: https://github.com/alertua/gaggiuino_api
- Owner: ALERTua
- Created: 2025-02-24T13:17:01.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-06T07:45:55.000Z (about 1 year ago)
- Last Synced: 2025-05-06T08:49:01.326Z (about 1 year ago)
- Topics: api-rest, gaggiuino, python
- Language: Python
- Homepage: https://pypi.org/project/gaggiuino_api/
- Size: 115 KB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://stand-with-ukraine.pp.ua)
[](https://stand-with-ukraine.pp.ua)
[](https://stand-with-ukraine.pp.ua)
[](https://stand-with-ukraine.pp.ua)
Gaggiuino REST API Wrapper for Python
---------------------------
Repository: https://github.com/ALERTua/gaggiuino_api
Changelog: https://github.com/ALERTua/gaggiuino_api/releases
PyPi: https://pypi.org/project/gaggiuino_api/
Home Assistant HACS Integration: https://github.com/ALERTua/hass-gaggiuino
The Gaggiuino REST API Wrapper is a Python library that provides a simple and efficient way to interact with [Gaggiuino-enabled](https://gaggiuino.github.io/) espresso machines.
This asynchronous client allows users to manage coffee profiles, retrieve shot data, and control their Gaggiuino-modified espresso machines through a REST API interface.
The library offers comprehensive profile management capabilities, including retrieving and selecting brewing profiles,
accessing historical shot data, and handling machine communication with built-in error handling and connection management.
It leverages modern Python features and async/await patterns to provide non-blocking operations, making it suitable for integration into larger applications or automation systems.
## Usage Instructions
### Prerequisites
- Python 3.13 or higher
- A running Gaggiuino-enabled espresso machine
- Network access to the Gaggiuino device (default: http://gaggiuino.local:80)
### Installation
```bash
pip install gaggiuino_api
```
### Quick Start
```python
import asyncio
from gaggiuino_api import GaggiuinoAPI
async def main():
async with GaggiuinoAPI() as client:
# Get the status
status = await client.get_status()
print(f"Status: {status}")
# Get all available profiles
profiles = await client.get_profiles()
# Select a profile by ID
await client.select_profile(profiles[0])
# Get shot data
shot = await client.get_shot(1)
print(f"Shot duration: {shot.duration}ms")
if __name__ == "__main__":
asyncio.run(main())
```
### More Detailed Examples
#### Working with Profiles
```python
from gaggiuino_api import GaggiuinoAPI
async def profile_management():
async with GaggiuinoAPI(base_url="http://custom.gaggiuino.local") as client:
# Get all profiles
profiles = await client.get_profiles()
# Print profile details
for profile in profiles:
print(f"Profile: {profile.name} (ID: {profile.id})")
print(f"Water Temperature: {profile.waterTemperature}°C")
# Print phases
for phase in profile.phases:
print(f"Phase Type: {phase.type.type}")
print(f"Restriction: {phase.restriction}")
```
#### Retrieving Shot Data
```python
from gaggiuino_api import GaggiuinoAPI
async def analyze_shot():
async with GaggiuinoAPI() as client:
latest_shot_id_result = await client.get_latest_shot_id()
latest_shot_id = latest_shot_id_result.lastShotId
shot = await client.get_shot(latest_shot_id)
# Access shot metrics
print(f"Latest Shot ID: {latest_shot_id}")
print(f"Duration: {shot.duration}ms")
print(f"Timestamp: {shot.timestamp}")
# Access datapoints
pressure_points = shot.datapoints.pressure
flow_points = shot.datapoints.pumpFlow
temperature_points = shot.datapoints.temperature
```
### Troubleshooting
#### Connection Issues
- Problem: Unable to connect to Gaggiuino device
```python
from gaggiuino_api import GaggiuinoAPI, GaggiuinoConnectionError
async def main():
try:
async with GaggiuinoAPI() as client:
profiles = await client.get_profiles()
except GaggiuinoConnectionError:
print("Check if Gaggiuino is powered on and connected to network")
print("Verify the device is accessible at gaggiuino.local")
```
#### Endpoint Not Found
- Problem: API endpoint returns 404
```python
from gaggiuino_api import GaggiuinoAPI, GaggiuinoEndpointNotFoundError
async def main():
try:
async with GaggiuinoAPI() as client:
shot = await client.get_shot(999)
except GaggiuinoEndpointNotFoundError:
print("Shot ID not found - verify the shot exists")
```
## Data Flow
The Gaggiuino API wrapper manages communication between your Python application and the Gaggiuino-enabled espresso machine through HTTP requests.
```ascii
[Python App] <-> [GaggiuinoAPI] <-> [HTTP/REST] <-> [Gaggiuino Device]
| | |
| | |
+--- Profiles +---- HTTP Requests ------------------- Machine Control
| | |
+--- Shot Data +---- Response Parsing --------------- Sensor Data
```
Key component interactions:
- GaggiuinoAPI class handles all HTTP communication using aiohttp
- Async context manager ensures proper connection handling and resource cleanup
- JSON responses are automatically parsed into typed data models
- Error handling provides specific exceptions for common failure modes
- Connection management includes automatic session creation and cleanup
- All API operations are asynchronous for non-blocking operation
I have no idea what this readme is about. It's all ChatGPT.