kerbl-iot 0.1.1__tar.gz

kerbl_iot-0.1.1/.gitignore

@@ -0,0 +1,24 @@
+# Python bytecode and tooling caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+
+# Test and coverage output
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Packaging artifacts
+build/
+dist/
+*.egg-info/
+
+# Editor settings
+.vscode/

kerbl_iot-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 derjoerg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kerbl_iot-0.1.1/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: kerbl-iot
+Version: 0.1.1
+Summary: Async client for the Kerbl IoT web API
+Project-URL: Source, https://github.com/derjoerg/kerbl-iot
+Project-URL: Issues, https://github.com/derjoerg/kerbl-iot/issues
+Author: derjoerg
+License: MIT
+License-File: LICENSE
+Keywords: home-assistant,iot,kerbl,poultry,smartcoop
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.10
+Requires-Dist: python-socketio[asyncio-client]<6,>=5.11
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: coverage[toml]<8,>=7.6; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Kerbl IoT
+
+Async Python client for Kerbl IoT devices.
+
+`KerblIOTApi` owns authentication, HTTP, token refresh, and Socket.IO transport.
+`KerblIOT` loads devices and dispatches their live updates. Device actions belong to
+their respective model classes.
+
+```python
+import asyncio
+import os
+
+from kerbl_iot import KerblIOT, KerblIOTApi
+
+
+async def main() -> None:
+    async with KerblIOT(
+        KerblIOTApi(
+        email=os.environ["KERBL_EMAIL"],
+        password=os.environ["KERBL_PASSWORD"],
+        )
+    ) as kerbl:
+        await kerbl.connect_websocket()
+
+        coop = kerbl.smart_coops[0]
+        print(coop.name, coop.air_temperature, coop.door.state)
+        await coop.light.turn_on()
+        await coop.door.close()
+
+
+asyncio.run(main())
+```
+
+## Releasing to PyPI
+
+Releases are published automatically by GitHub Actions when a GitHub Release is
+marked as published. Before the first release, configure PyPI Trusted Publishing
+for the `derjoerg/kerbl-iot` repository and the `.github/workflows/publish.yml`
+workflow, using the `pypi` environment.
+
+To create a release, update the `version` in `pyproject.toml`, commit the change,
+create a matching tag such as `v0.1.1`, and publish a GitHub Release for that tag.
+The version must not already exist on PyPI.
+
+## Error reason reference
+
+`SmartCoopLog` exposes the API's raw `error_key` and `error_code`. Applications
+should translate the key in their own presentation layer. The following table
+preserves the German translations previously included in this library for
+reference:
+
+| API error key | Former German translation |
+| --- | --- |
+| `errorReason.doorLocked` | Klappe verriegelt |
+| `errorReason.doorClosingSoon` | Klappe schliesst bald |
+| `errorReason.feederLocked` | Futterautomat gesperrt |
+| `errorReason.batteryLow` | Akku schwach |
+| `errorReason.waterHeaterActive` | Wasserheizung aktiv |
+| `errorReason.waterEmpty` | Wasser leer |
+| `errorReason.feederError` | Futterautomatenstoerung |
+| `errorReason.feedEmpty` | Futter leer |
+| `errorReason.batteryEmpty` | Akku leer |
+| `errorReason.doorError` | Klappenstoerung |
+| `errorReason.waterTemperatureLow` | Wassertemperatur zu niedrig |
+| `errorReason.externalLightError` | Fremdlichtstoerung |
+| `errorReason.timeError` | Uhrzeit muss eingestellt werden |
+| `errorReason.flashError` | Flash-Fehler |

kerbl_iot-0.1.1/README.md

@@ -0,0 +1,67 @@
+# Kerbl IoT
+
+Async Python client for Kerbl IoT devices.
+
+`KerblIOTApi` owns authentication, HTTP, token refresh, and Socket.IO transport.
+`KerblIOT` loads devices and dispatches their live updates. Device actions belong to
+their respective model classes.
+
+```python
+import asyncio
+import os
+
+from kerbl_iot import KerblIOT, KerblIOTApi
+
+
+async def main() -> None:
+    async with KerblIOT(
+        KerblIOTApi(
+        email=os.environ["KERBL_EMAIL"],
+        password=os.environ["KERBL_PASSWORD"],
+        )
+    ) as kerbl:
+        await kerbl.connect_websocket()
+
+        coop = kerbl.smart_coops[0]
+        print(coop.name, coop.air_temperature, coop.door.state)
+        await coop.light.turn_on()
+        await coop.door.close()
+
+
+asyncio.run(main())
+```
+
+## Releasing to PyPI
+
+Releases are published automatically by GitHub Actions when a GitHub Release is
+marked as published. Before the first release, configure PyPI Trusted Publishing
+for the `derjoerg/kerbl-iot` repository and the `.github/workflows/publish.yml`
+workflow, using the `pypi` environment.
+
+To create a release, update the `version` in `pyproject.toml`, commit the change,
+create a matching tag such as `v0.1.1`, and publish a GitHub Release for that tag.
+The version must not already exist on PyPI.
+
+## Error reason reference
+
+`SmartCoopLog` exposes the API's raw `error_key` and `error_code`. Applications
+should translate the key in their own presentation layer. The following table
+preserves the German translations previously included in this library for
+reference:
+
+| API error key | Former German translation |
+| --- | --- |
+| `errorReason.doorLocked` | Klappe verriegelt |
+| `errorReason.doorClosingSoon` | Klappe schliesst bald |
+| `errorReason.feederLocked` | Futterautomat gesperrt |
+| `errorReason.batteryLow` | Akku schwach |
+| `errorReason.waterHeaterActive` | Wasserheizung aktiv |
+| `errorReason.waterEmpty` | Wasser leer |
+| `errorReason.feederError` | Futterautomatenstoerung |
+| `errorReason.feedEmpty` | Futter leer |
+| `errorReason.batteryEmpty` | Akku leer |
+| `errorReason.doorError` | Klappenstoerung |
+| `errorReason.waterTemperatureLow` | Wassertemperatur zu niedrig |
+| `errorReason.externalLightError` | Fremdlichtstoerung |
+| `errorReason.timeError` | Uhrzeit muss eingestellt werden |
+| `errorReason.flashError` | Flash-Fehler |

kerbl_iot-0.1.1/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.31,<1.32"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kerbl-iot"
+version = "0.1.1"
+description = "Async client for the Kerbl IoT web API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "derjoerg" }]
+keywords = ["kerbl", "iot", "smartcoop", "poultry", "home-assistant"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+]
+dependencies = [
+    "aiohttp>=3.10,<4",
+    "python-socketio[asyncio_client]>=5.11,<6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2,<2",
+    "coverage[toml]>=7.6,<8",
+    "pytest>=8.3,<9",
+    "twine>=6,<7",
+]
+
+[project.urls]
+Source = "https://github.com/derjoerg/kerbl-iot"
+Issues = "https://github.com/derjoerg/kerbl-iot/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kerbl_iot"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/LICENSE",
+    "/README.md",
+    "/pyproject.toml",
+    "/src",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kerbl_iot-0.1.1/src/kerbl_iot/__init__.py

@@ -0,0 +1,41 @@
+"""Asynchronous client for the Kerbl IoT web API."""
+
+from .api import KerblIOTApi
+from .kerbl_iot import KerblIOT
+from .exceptions import (
+	KerblAuthenticationError,
+	KerblConnectionError,
+	KerblError,
+	KerblProtocolError,
+	KerblStateError,
+)
+from .models import (
+	CommandResult,
+	DoorState,
+	SmartCoop,
+	SmartCoopBrightness,
+	SmartCoopDoor,
+	SmartCoopFeeder,
+	SmartCoopLight,
+	SmartCoopLog,
+	SmartCoopWaterHeater,
+)
+
+__all__ = [
+	"CommandResult",
+	"DoorState",
+	"KerblIOTApi",
+	"KerblIOT",
+	"KerblAuthenticationError",
+	"KerblConnectionError",
+	"KerblError",
+	"KerblProtocolError",
+	"KerblStateError",
+	"SmartCoop",
+	"SmartCoopBrightness",
+	"SmartCoopDoor",
+	"SmartCoopFeeder",
+	"SmartCoopLight",
+	"SmartCoopLog",
+	"SmartCoopWaterHeater",
+]

kerbl_iot-0.1.1/src/kerbl_iot/api.py

@@ -0,0 +1,332 @@
+"""HTTP client for the confirmed Kerbl IoT API endpoints."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import aiohttp
+import socketio
+
+from .exceptions import (
+    KerblAuthenticationError,
+    KerblConnectionError,
+    KerblProtocolError,
+)
+from .models import CommandResult, SmartCoop, SmartCoopLog
+
+BASE_URL = "https://app.kerbl-iot.com/api/v0.1/"
+SOCKET_URL = "https://app.kerbl-iot.com"
+SOCKET_PATH = "ws/v0.1/socket.io"
+
+
+class KerblIOTApi:
+    """Authenticate with and retrieve data from Kerbl IoT."""
+
+    def __init__(
+        self,
+        email: str,
+        password: str,
+        timeout: float = 15.0,
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero.")
+        self._email = email
+        self._password = password
+        self._timeout = timeout
+        self._provided_session = session
+        self._session = session
+        self._session_owned = False
+        self._socket: socketio.AsyncClient | None = None
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._refresh_lock = asyncio.Lock()
+        self._smart_coop_update_callbacks: list[Callable[[SmartCoop], Awaitable[None]]] = []
+        self._socket_event_callbacks: list[
+            Callable[[str, Any], Awaitable[None]]
+        ] = []
+        self._socket_disconnect_callbacks: list[Callable[[], Awaitable[None]]] = []
+        self._socket_connect_callbacks: list[Callable[[], Awaitable[None]]] = []
+        self._subscribed_device_ids: list[str] = []
+        self._socket_user_id: str | None = None
+
+    async def __aenter__(self) -> "KerblIOTApi":
+        await self.login()
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP session."""
+        socket, session = self._socket, self._session
+        self._socket = None
+        self._session = None
+        self._access_token = None
+        self._refresh_token = None
+        try:
+            if socket is not None and socket.connected and self._socket_user_id is not None:
+                await socket.emit(
+                    "leave_room",
+                    {
+                        "deviceIds": self._subscribed_device_ids,
+                        "userId": self._socket_user_id,
+                    },
+                )
+        finally:
+            self._subscribed_device_ids = []
+            self._socket_user_id = None
+            try:
+                if socket is not None:
+                    await socket.disconnect()
+            finally:
+                if session is not None and self._session_owned:
+                    await session.close()
+                self._session_owned = False
+
+    async def login(self) -> dict[str, Any]:
+        """Sign in using the request format captured from the web application."""
+        await self.close()
+        if self._provided_session is not None:
+            self._session = self._provided_session
+        else:
+            self._session = aiohttp.ClientSession(
+                base_url=BASE_URL,
+                headers={"Accept": "application/json"},
+                timeout=aiohttp.ClientTimeout(total=self._timeout),
+                raise_for_status=True,
+            )
+            self._session_owned = True
+        payload = {
+            "email": self._email,
+            "password": self._password,
+            "appBrand": "kerbl",
+            "appVersion": "137.6.1",
+            "loginId": str(uuid.uuid4()),
+        }
+        try:
+            authentication = await self._request_json(
+                "POST", "auth/sign-in", payload, refresh_on_unauthorized=False
+            )
+            self._set_authentication(authentication)
+        except Exception:
+            await self.close()
+            raise
+
+        return authentication
+
+    async def refresh_token(self) -> None:
+        """Refresh the access token using the token pair from the last login."""
+        async with self._refresh_lock:
+            if not self._access_token or not self._refresh_token:
+                raise KerblAuthenticationError("No refresh token is available.")
+            try:
+                authentication = await self._request_json(
+                    "POST",
+                    "auth/refresh",
+                    {
+                        "accessToken": self._access_token,
+                        "refreshToken": self._refresh_token,
+                    },
+                    refresh_on_unauthorized=False,
+                )
+                self._set_authentication(authentication)
+            except (KerblAuthenticationError, KerblConnectionError, KerblProtocolError):
+                raise
+
+    def get_tokens(self) -> tuple[str, str]:
+        """Return the access and refresh tokens for persistent storage."""
+        if not self._access_token or not self._refresh_token:
+            raise KerblAuthenticationError("No authentication tokens are available.")
+        return self._access_token, self._refresh_token
+
+    def restore_tokens(self, access_token: str, refresh_token: str) -> None:
+        """Restore tokens from persistent storage without signing in again."""
+        self._set_authentication(
+            {"accessToken": access_token, "refreshToken": refresh_token}
+        )
+
+    def _set_authentication(self, authentication: dict[str, Any]) -> None:
+        access_token = authentication.get("accessToken")
+        refresh_token = authentication.get("refreshToken")
+        if not isinstance(access_token, str) or not access_token:
+            raise KerblAuthenticationError("Kerbl response did not include an access token.")
+        if not isinstance(refresh_token, str) or not refresh_token:
+            raise KerblAuthenticationError("Kerbl response did not include a refresh token.")
+        self._access_token = access_token
+        self._refresh_token = refresh_token
+        self._require_session().headers["Authorization"] = f"Bearer {access_token}"
+
+    async def _request_json(
+        self,
+        method: str,
+        endpoint: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        refresh_on_unauthorized: bool = True,
+    ) -> dict[str, Any]:
+        """Send one JSON request and refresh the access token once after a 401."""
+        session = self._require_session()
+        request_url = endpoint if self._provided_session is None else f"{BASE_URL}{endpoint}"
+        try:
+            async with session.request(method, request_url, json=payload) as response:
+                return await response.json()
+        except aiohttp.ClientResponseError as error:
+            if error.status == 401 and refresh_on_unauthorized:
+                await self.refresh_token()
+                return await self._request_json(
+                    method, endpoint, payload, refresh_on_unauthorized=False
+                )
+            if error.status == 401:
+                raise KerblAuthenticationError("Kerbl rejected the request.") from error
+            raise KerblConnectionError("Kerbl IoT service returned an HTTP error.") from error
+        except (aiohttp.ClientError, asyncio.TimeoutError) as error:
+            raise KerblConnectionError("Kerbl IoT service could not be reached.") from error
+        except (TypeError, ValueError) as error:
+            raise KerblProtocolError("Kerbl returned an invalid JSON response.") from error
+
+    async def get_smart_coops(self) -> list[SmartCoop]:
+        """Retrieve all SmartCoop devices assigned to the current user."""
+        devices = await self._request_json("GET", "device")
+        return [SmartCoop.from_api(data, self) for data in devices.get("smartCoop", [])]
+
+    async def get_smart_coop_logs(self, smart_coop_id: str) -> list[SmartCoopLog]:
+        """Retrieve error and informational logs for one SmartCoop."""
+        endpoint = f"device/smart-coop/{smart_coop_id}/log"
+        payload = await self._request_json("GET", endpoint)
+        return [SmartCoopLog.from_api(data) for data in payload.get("logs", [])]
+
+    async def _press_light(self, smart_coop_id: str) -> CommandResult:
+        """Press a SmartCoop light using its confirmed manual-control command."""
+        endpoint = f"device/smart-coop/{smart_coop_id}/command/lightControl"
+        return CommandResult.from_api(await self._request_json("PATCH", endpoint, {"value": 1}))
+
+    async def _press_feeder(self, smart_coop_id: str) -> CommandResult:
+        """Press a SmartCoop feeder using its confirmed manual-control command."""
+        endpoint = f"device/smart-coop/{smart_coop_id}/command/feederControl"
+        return CommandResult.from_api(await self._request_json("PATCH", endpoint, {"value": 1}))
+
+    async def _press_door(self, smart_coop_id: str) -> CommandResult:
+        """Press a SmartCoop door using its confirmed manual-control command."""
+        endpoint = f"device/smart-coop/{smart_coop_id}/command/doorControl"
+        return CommandResult.from_api(await self._request_json("PATCH", endpoint, {"value": 1}))
+
+    async def _acknowledge_errors(
+        self, smart_coop_id: str, error_codes: list[int]
+    ) -> CommandResult:
+        """Acknowledge one or more active SmartCoop error codes."""
+        if not error_codes:
+            raise ValueError("Provide at least one error code to acknowledge.")
+
+        endpoint = f"device/smart-coop/{smart_coop_id}/command/acknowledgeErrorControl"
+        return CommandResult.from_api(
+            await self._request_json("PATCH", endpoint, {"value": error_codes})
+        )
+
+    async def connect_websocket(
+        self, smart_coops: list[SmartCoop], debug: bool = False
+    ) -> None:
+        """Connect to Socket.IO and subscribe to updates for all SmartCoops."""
+        if self.websocket_connected:
+            return
+
+        if not smart_coops:
+            return
+
+        session = self._require_session()
+        socket = socketio.AsyncClient(
+            reconnection=True,
+            logger=debug,
+            engineio_logger=debug,
+        )
+        socket.on("smart-coop_update", self._handle_smart_coop_update)
+        socket.on("*", self._handle_socket_event)
+        socket.on("connect", self._handle_socket_connect)
+        socket.on("disconnect", self._handle_socket_disconnect)
+        try:
+            await socket.connect(
+                SOCKET_URL,
+                socketio_path=SOCKET_PATH,
+                headers={"Authorization": session.headers["Authorization"]},
+            )
+            self._subscribed_device_ids = [coop.id for coop in smart_coops]
+            self._socket_user_id = smart_coops[0].user_id
+            await socket.emit(
+                "join_room",
+                {
+                    "deviceIds": self._subscribed_device_ids,
+                    "userId": self._socket_user_id,
+                },
+            )
+        except (aiohttp.ClientError, socketio.exceptions.ConnectionError, asyncio.TimeoutError) as error:
+            await socket.disconnect()
+            self._subscribed_device_ids = []
+            self._socket_user_id = None
+            raise KerblConnectionError("Kerbl WebSocket could not be connected.") from error
+        self._socket = socket
+
+    async def _handle_socket_connect(self) -> None:
+        """Rejoin subscribed SmartCoop rooms after a Socket.IO reconnect."""
+        if self._socket is not None and self._socket_user_id is not None:
+            await self._socket.emit(
+                "join_room",
+                {
+                    "deviceIds": self._subscribed_device_ids,
+                    "userId": self._socket_user_id,
+                },
+            )
+        for callback in self._socket_connect_callbacks:
+            await callback()
+
+    @property
+    def websocket_connected(self) -> bool:
+        """Return whether the Socket.IO connection is active."""
+        return self._socket is not None and self._socket.connected
+
+    def register_smart_coop_update_callback(
+        self, callback: Callable[[SmartCoop], Awaitable[None]]
+    ) -> None:
+        """Register an asynchronous callback for SmartCoop Socket.IO updates."""
+        self._smart_coop_update_callbacks.append(callback)
+
+    def register_socket_event_callback(
+        self, callback: Callable[[str, Any], Awaitable[None]]
+    ) -> None:
+        """Register an asynchronous callback for all Socket.IO server events."""
+        self._socket_event_callbacks.append(callback)
+
+    def register_socket_disconnect_callback(
+        self, callback: Callable[[], Awaitable[None]]
+    ) -> None:
+        """Register an asynchronous callback for Socket.IO disconnects."""
+        self._socket_disconnect_callbacks.append(callback)
+
+    def register_socket_connect_callback(
+        self, callback: Callable[[], Awaitable[None]]
+    ) -> None:
+        """Register an asynchronous callback for Socket.IO connects and reconnects."""
+        self._socket_connect_callbacks.append(callback)
+
+    async def _handle_smart_coop_update(self, data: dict[str, Any]) -> None:
+        """Forward a parsed SmartCoop state update from Socket.IO."""
+        smart_coop = SmartCoop.from_api(data, self)
+        for callback in self._smart_coop_update_callbacks:
+            await callback(smart_coop)
+
+    async def _handle_socket_event(self, event: str, data: Any) -> None:
+        """Forward Socket.IO events to registered diagnostic callbacks."""
+        for callback in self._socket_event_callbacks:
+            await callback(event, data)
+
+    async def _handle_socket_disconnect(self) -> None:
+        """Notify subscribers after Socket.IO loses its connection."""
+        for callback in self._socket_disconnect_callbacks:
+            await callback()
+
+    def _require_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            raise RuntimeError("Call login() before requesting devices.")
+        return self._session

kerbl_iot-0.1.1/src/kerbl_iot/exceptions.py

@@ -0,0 +1,21 @@
+"""Exceptions raised by the Kerbl IoT client."""
+
+
+class KerblError(Exception):
+    """Base exception for Kerbl IoT client errors."""
+
+
+class KerblAuthenticationError(KerblError):
+    """Authentication failed or the stored session could not be refreshed."""
+
+
+class KerblConnectionError(KerblError):
+    """The Kerbl IoT service could not be reached."""
+
+
+class KerblProtocolError(KerblError):
+    """The Kerbl IoT service returned an unexpected response."""
+
+
+class KerblStateError(KerblError):
+    """A command cannot safely be applied to the reported device state."""