gaggiuino_api 0.2.0

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
• API Reference: https://github.com/GAGGIUINO/gaggiuino.github.io/blob/feature/settings-api/docs/rest-api/rest-api.md
• Gaggiuino REST API Documentation: https://gaggiuino.github.io/rest-api/rest-api.md

The Gaggiuino REST API Wrapper is a Python library that provides a simple and efficient way to interact with Gaggiuino-enabled 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.11 or higher
• A running Gaggiuino-enabled espresso machine
• Network access to the Gaggiuino device (default: http://gaggiuino.local:80)

Installation

pip install gaggiuino_api

Quick Start

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

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

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

  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

  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.

[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.