{"id":9011,"library":"ghome-foyer-api","title":"Google Home Foyer API Stubs","description":"ghome-foyer-api provides generated protobuf stubs for interacting with the Google Home Foyer API. This library simplifies client-side development for devices that expose this gRPC interface. It currently supports protobuf v5 and v6, with releases often driven by updates to underlying gRPC and protobuf dependencies.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/KapJI/ghome-foyer-api","tags":["grpc","protobuf","google home","stubs","api client","foyer api"],"install":[{"cmd":"pip install ghome-foyer-api","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required runtime dependency for protobuf message serialization/deserialization.","package":"protobuf","optional":false},{"reason":"Required runtime dependency for gRPC communication.","package":"grpcio","optional":false}],"imports":[{"note":"For protobuf message definitions (requests, responses).","symbol":"foyer_v1_pb2","correct":"from ghome_foyer_api import foyer_v1_pb2"},{"note":"For gRPC service stubs (client and server implementations).","symbol":"foyer_v1_pb2_grpc","correct":"from ghome_foyer_api import foyer_v1_pb2_grpc"},{"note":"Example for other specific service stubs, replace 'device' with actual service name if available.","symbol":"device_pb2","correct":"from ghome_foyer_api import device_pb2"}],"quickstart":{"code":"import grpc\nfrom ghome_foyer_api import foyer_v1_pb2_grpc, foyer_v1_pb2\nimport os\n\n# This library provides generated protobuf/gRPC stubs for the Google Home Foyer API.\n# It requires a running gRPC server that implements this API (e.g., a Google Home device\n# exposing the Foyer API on the local network) to be functional.\n\n# Replace with the actual address of your Google Home Foyer API server.\n# For local testing or development, 'localhost:50051' is a common placeholder.\nSERVER_ADDRESS = os.environ.get('GHOME_FOYER_API_SERVER_ADDRESS', 'localhost:50051')\n\ntry:\n    # Establish an insecure gRPC channel to the server.\n    # For production environments, consider secure channels (e.g., `grpc.ssl_channel`).\n    with grpc.insecure_channel(SERVER_ADDRESS) as channel:\n        # Create a stub for the Foyer service.\n        # This object exposes the RPC methods defined in the Foyer API.\n        stub = foyer_v1_pb2_grpc.FoyerStub(channel)\n\n        print(f\"Successfully created FoyerStub for server at {SERVER_ADDRESS}\")\n        print(\"To interact, call specific RPC methods defined in the Foyer API using 'stub.'\")\n        # Example (illustrative, actual method names and parameters vary per API):\n        # request = foyer_v1_pb2.GetDeviceInfoRequest(device_id='some_id')\n        # response = stub.GetDeviceInfo(request)\n        # print(f\"Device Info: {response}\")\n\nexcept grpc.RpcError as e:\n    print(f\"Error connecting or calling gRPC: {e.code().name} - {e.details()}\")\n    print(\"Ensure the gRPC server is running and accessible at the specified address.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"Demonstrates how to import the generated stubs and create a gRPC client stub for the Foyer service. This quickstart assumes a gRPC server implementing the Google Home Foyer API is running and accessible at the specified `SERVER_ADDRESS`."},"warnings":[{"fix":"Ensure `protobuf` and `grpcio` versions installed align with the `ghome-foyer-api`'s declared dependencies. Consider using a `pip compile` workflow or virtual environments to manage dependencies strictly.","message":"Protobuf version compatibility is critical. This library is sensitive to the `protobuf` and `grpcio` versions installed. Mismatches can lead to serialization errors or runtime crashes. Check the `pyproject.toml` or `setup.py` for exact dependency ranges.","severity":"breaking","affected_versions":"All versions, especially when upgrading `protobuf` or `grpcio` separately."},{"fix":"Understand that this is a client-side stub library. You need a separate gRPC server implementing the Foyer API to connect to. This is often an internal API used on local networks.","message":"This library provides only generated *stubs* for the Google Home Foyer API. It does not implement the API itself or provide a direct connection to public Google services. You must have access to a gRPC server (e.g., a local Google Home device or an emulator) that exposes the Foyer API for these stubs to be functional.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Upgrade to the latest version of `ghome-foyer-api` (>=1.2.0) to ensure compatibility with Protobuf v5 and v6. Always ensure your `grpcio` and `protobuf` versions are within the library's specified ranges.","message":"Older versions (prior to v1.1.0) only supported Protobuf v4. Version v1.1.0 added support for Protobuf v5, and v1.2.0 added support for Protobuf v6. Using an older version of this library with newer Protobuf installations, or vice versa, can lead to incompatibility issues.","severity":"deprecated","affected_versions":"<1.2.0 (for protobuf v6), <1.1.0 (for protobuf v5)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that the gRPC server is running and listening on the correct IP address and port (e.g., `localhost:50051`). Check network connectivity and firewall rules. Ensure `SERVER_ADDRESS` in your code is correct.","cause":"The gRPC server you are trying to connect to is not running, is not accessible at the specified address, or a firewall is blocking the connection.","error":"grpc._channel._MultiThreadedRendezvous: <_Rendezvous of RPC ... code=UNAVAILABLE, details='failed to connect to all addresses'"},{"fix":"Ensure that the `ghome-foyer-api` library, `protobuf`, and `grpcio` are all up-to-date and compatible. If you are interacting with a server, ensure it was built with compatible protobuf definitions and versions. Re-installing `ghome-foyer-api --no-cache-dir` can sometimes resolve build-time dependency issues.","cause":"This error typically indicates a protobuf message type mismatch, often due to different versions of generated stubs (client vs. server) or an incompatibility with the installed `protobuf` library version.","error":"TypeError: Parameter to MergeFrom() must be instance of same class: expected <your.message.Type> got <another.message.Type>"},{"fix":"Install the package using `pip install ghome-foyer-api`. If using a virtual environment, ensure it is activated before running your script.","cause":"The `ghome-foyer-api` library has not been installed in the current Python environment or the environment is not active.","error":"ModuleNotFoundError: No module named 'ghome_foyer_api'"}]}