{"id":25735695,"url":"https://github.com/alertua/gaggiuino_api","last_synced_at":"2025-05-07T23:21:16.287Z","repository":{"id":279232909,"uuid":"938127526","full_name":"ALERTua/gaggiuino_api","owner":"ALERTua","description":"Gaggiuino REST API Wrapper for Python","archived":false,"fork":false,"pushed_at":"2025-05-06T07:45:55.000Z","size":118,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-06T08:49:01.326Z","etag":null,"topics":["api-rest","gaggiuino","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/gaggiuino_api/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ALERTua.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-24T13:17:01.000Z","updated_at":"2025-05-06T07:45:56.000Z","dependencies_parsed_at":"2025-04-15T15:26:26.479Z","dependency_job_id":"a914dc7d-e1e3-4154-934e-4e950f16b3a5","html_url":"https://github.com/ALERTua/gaggiuino_api","commit_stats":null,"previous_names":["alertua/gaggiuino_api"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALERTua%2Fgaggiuino_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALERTua%2Fgaggiuino_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALERTua%2Fgaggiuino_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALERTua%2Fgaggiuino_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ALERTua","download_url":"https://codeload.github.com/ALERTua/gaggiuino_api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252654209,"owners_count":21783361,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-rest","gaggiuino","python"],"created_at":"2025-02-26T05:31:40.714Z","updated_at":"2025-05-07T23:21:16.279Z","avatar_url":"https://github.com/ALERTua.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct-single.svg)](https://stand-with-ukraine.pp.ua)\n[![Made in Ukraine](https://img.shields.io/badge/made_in-Ukraine-ffd700.svg?labelColor=0057b7)](https://stand-with-ukraine.pp.ua)\n[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua)\n[![Russian Warship Go Fuck Yourself](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/RussianWarship.svg)](https://stand-with-ukraine.pp.ua)\n\nGaggiuino REST API Wrapper for Python\n---------------------------\nRepository: https://github.com/ALERTua/gaggiuino_api\n\nChangelog: https://github.com/ALERTua/gaggiuino_api/releases\n\nPyPi: https://pypi.org/project/gaggiuino_api/\n\nHome Assistant HACS Integration: https://github.com/ALERTua/hass-gaggiuino\n\nThe 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.\nThis asynchronous client allows users to manage coffee profiles, retrieve shot data, and control their Gaggiuino-modified espresso machines through a REST API interface.\n\nThe library offers comprehensive profile management capabilities, including retrieving and selecting brewing profiles,\naccessing historical shot data, and handling machine communication with built-in error handling and connection management.\nIt leverages modern Python features and async/await patterns to provide non-blocking operations, making it suitable for integration into larger applications or automation systems.\n\n## Usage Instructions\n### Prerequisites\n- Python 3.13 or higher\n- A running Gaggiuino-enabled espresso machine\n- Network access to the Gaggiuino device (default: http://gaggiuino.local:80)\n\n### Installation\n```bash\npip install gaggiuino_api\n```\n\n### Quick Start\n\n```python\nimport asyncio\nfrom gaggiuino_api import GaggiuinoAPI\n\n\nasync def main():\n  async with GaggiuinoAPI() as client:\n    # Get the status\n    status = await client.get_status()\n    print(f\"Status: {status}\")\n\n    # Get all available profiles\n    profiles = await client.get_profiles()\n\n    # Select a profile by ID\n    await client.select_profile(profiles[0])\n\n    # Get shot data\n    shot = await client.get_shot(1)\n    print(f\"Shot duration: {shot.duration}ms\")\n\n\nif __name__ == \"__main__\":\n  asyncio.run(main())\n```\n\n### More Detailed Examples\n#### Working with Profiles\n\n```python\nfrom gaggiuino_api import GaggiuinoAPI\n\n\nasync def profile_management():\n  async with GaggiuinoAPI(base_url=\"http://custom.gaggiuino.local\") as client:\n    # Get all profiles\n    profiles = await client.get_profiles()\n\n    # Print profile details\n    for profile in profiles:\n      print(f\"Profile: {profile.name} (ID: {profile.id})\")\n      print(f\"Water Temperature: {profile.waterTemperature}°C\")\n\n      # Print phases\n      for phase in profile.phases:\n        print(f\"Phase Type: {phase.type.type}\")\n        print(f\"Restriction: {phase.restriction}\")\n```\n\n#### Retrieving Shot Data\n\n```python\nfrom gaggiuino_api import GaggiuinoAPI\n\n\nasync def analyze_shot():\n  async with GaggiuinoAPI() as client:\n    latest_shot_id_result = await client.get_latest_shot_id()\n    latest_shot_id = latest_shot_id_result.lastShotId\n    shot = await client.get_shot(latest_shot_id)\n\n    # Access shot metrics\n    print(f\"Latest Shot ID: {latest_shot_id}\")\n    print(f\"Duration: {shot.duration}ms\")\n    print(f\"Timestamp: {shot.timestamp}\")\n\n    # Access datapoints\n    pressure_points = shot.datapoints.pressure\n    flow_points = shot.datapoints.pumpFlow\n    temperature_points = shot.datapoints.temperature\n```\n\n### Troubleshooting\n#### Connection Issues\n- Problem: Unable to connect to Gaggiuino device\n  ```python\n  from gaggiuino_api import GaggiuinoAPI, GaggiuinoConnectionError\n\n  async def main():\n      try:\n          async with GaggiuinoAPI() as client:\n              profiles = await client.get_profiles()\n      except GaggiuinoConnectionError:\n          print(\"Check if Gaggiuino is powered on and connected to network\")\n          print(\"Verify the device is accessible at gaggiuino.local\")\n  ```\n\n#### Endpoint Not Found\n- Problem: API endpoint returns 404\n  ```python\n  from gaggiuino_api import GaggiuinoAPI, GaggiuinoEndpointNotFoundError\n\n  async def main():\n      try:\n          async with GaggiuinoAPI() as client:\n              shot = await client.get_shot(999)\n      except GaggiuinoEndpointNotFoundError:\n          print(\"Shot ID not found - verify the shot exists\")\n  ```\n\n## Data Flow\nThe Gaggiuino API wrapper manages communication between your Python application and the Gaggiuino-enabled espresso machine through HTTP requests.\n\n```ascii\n[Python App] \u003c-\u003e [GaggiuinoAPI] \u003c-\u003e [HTTP/REST] \u003c-\u003e [Gaggiuino Device]\n     |              |                                      |\n     |              |                                      |\n     +--- Profiles  +---- HTTP Requests ------------------- Machine Control\n     |              |                                      |\n     +--- Shot Data +---- Response Parsing --------------- Sensor Data\n```\n\nKey component interactions:\n- GaggiuinoAPI class handles all HTTP communication using aiohttp\n- Async context manager ensures proper connection handling and resource cleanup\n- JSON responses are automatically parsed into typed data models\n- Error handling provides specific exceptions for common failure modes\n- Connection management includes automatic session creation and cleanup\n- All API operations are asynchronous for non-blocking operation\n\n\nI have no idea what this readme is about. It's all ChatGPT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falertua%2Fgaggiuino_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falertua%2Fgaggiuino_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falertua%2Fgaggiuino_api/lists"}