From 655bc4dffaf957468269d67efb3c283ad7f43c14 Mon Sep 17 00:00:00 2001
From: Markus Zehnder <business@markuszehnder.ch>
Date: Mon, 30 Oct 2023 16:04:18 +0100
Subject: [PATCH] docs: add a minimal hello world example

---
 examples/hello_integration.json | 18 ++++++++++++++
 examples/hello_integration.py   | 43 +++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 examples/hello_integration.json
 create mode 100644 examples/hello_integration.py

diff --git a/examples/hello_integration.json b/examples/hello_integration.json
new file mode 100644
index 0000000..cd81104
--- /dev/null
+++ b/examples/hello_integration.json
@@ -0,0 +1,18 @@
+{
+  "driver_id": "hello_integration",
+  "version": "0.0.1",
+  "min_core_api": "0.20.0",
+  "name": { "en": "Hello Python integration" },
+  "icon": "uc:integration",
+  "description": {
+    "en": "Minimal Python integration driver example."
+  },
+  "port": 9080,
+  "developer": {
+    "name": "Unfolded Circle ApS",
+    "email": "hello@unfoldedcircle.com",
+    "url": "https://www.unfoldedcircle.com"
+  },
+  "home_page": "https://www.unfoldedcircle.com",
+  "release_date": "2023-10-30"
+}
diff --git a/examples/hello_integration.py b/examples/hello_integration.py
new file mode 100644
index 0000000..c51a8d9
--- /dev/null
+++ b/examples/hello_integration.py
@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Hello world integration example. Bare minimum of an integration driver."""
+import asyncio
+import logging
+from typing import Any
+
+import ucapi
+
+loop = asyncio.get_event_loop()
+api = ucapi.IntegrationAPI(loop)
+
+
+async def cmd_handler(entity: ucapi.Button, cmd_id: str, _params: dict[str, Any] | None) -> ucapi.StatusCodes:
+    """
+    Push button command handler.
+
+    Called by the integration-API if a command is sent to a configured button-entity.
+
+    :param entity: button entity
+    :param cmd_id: command
+    :param _params: optional command parameters
+    :return: status of the command
+    """
+    print(f"Got {entity.id} command request: {cmd_id}")
+
+    return ucapi.StatusCodes.OK
+
+
+if __name__ == "__main__":
+    logging.basicConfig()
+
+    button = ucapi.Button(
+        "button1",
+        "Push the button",
+        cmd_handler=cmd_handler,
+    )
+    api.available_entities.add(button)
+
+    # We are ready all the time! Otherwise, use @api.listens_to(ucapi.Events.CONNECT) & DISCONNECT
+    api.set_device_state(ucapi.DeviceStates.CONNECTED)
+
+    loop.run_until_complete(api.init("hello_integration.json"))
+    loop.run_forever()