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

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.