From 39a17e688ba250ba51b6f9165b213e1d904fcbc4 Mon Sep 17 00:00:00 2001
From: Chris Oloff <chris@uber5.com>
Date: Mon, 15 Dec 2025 13:34:44 +0200
Subject: [PATCH] update README, add geyser sample (as per quickstart in
 README)

---
 README.md        | 50 ++++++++++++++++++++++++++++++++++++++++--------
 geyser_on_off.py | 23 ++++++++++++++++++++++
 2 files changed, 65 insertions(+), 8 deletions(-)
 create mode 100644 geyser_on_off.py

diff --git a/README.md b/README.md
index 299396f..8402efd 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,42 @@
 # Watt42 Viewlib
 
-Supports building a view for Watt42 systems.
+Watt42 Viewlib supports building browser-based front ends for Watt42 systems.
+The purpose of those front ends is to visualize the state of a Watt42 system,
+and to allow users to interact with it.
 
-## Prerequisites
+# Quickstart
+
+Given a Watt42 system that exposes the status of a smart device (`is_geyser_on`
+is either `true` or `false`), the following code creates a simple view that
+shows the status of the device.
+
+```python
+import os
+import panel
+from typing import Any
+
+from watt42_viewlib import attach_w42_state
+
+SYSTEM_ID = os.environ.get("WATT42_SYSTEM_ID", "invalid-system-id")
+API_TOKEN = os.environ.get("WATT42_API_TOKEN", "invalid-api-token")
+
+w42_state = panel.rx(None)
+
+attach_w42_state(rx_var=w42_state, system_id=SYSTEM_ID, token=API_TOKEN)
+
+def get_geyser_state(state: dict[str, Any]) -> bool:
+    if not state:
+        return False
+    return state.get("is_geyser_on", False)
+
+geyser_state = panel.rx(get_geyser_state)(w42_state)
+
+indicator = panel.indicators.BooleanStatus(value=geyser_state, name="W42 Connected", color="success")
+
+_ = indicator.servable()
+```
+
+# Prerequisites
 
 You should be familiar with Python.
 
@@ -10,15 +44,15 @@ You need poetry installed:
 
 - [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer)
 
-## Demo
+# Demo
 
 You can [run the sample online](https://viewlib-demo.watt42.com). The sample code is in [sample.py](./sample.py).
 
-TODO: provide more sophisticated demos online.
+TODO: publish demo, provide more sophisticated demos online.
 
-## Documentation
+# Documentation
 
-### Installation
+## Installation
 
 Make sure you have poetry installed (see above), then run:
 
@@ -40,7 +74,7 @@ Your view will be available at `http://localhost:5006/sample`. In order for the
 view to work, you need to configure an access token, and the Watt42 system that
 you want to use. See #how-to-use below.
 
-### How to use
+## How to use
 
 Build your own front end for a Watt42 system by creating a Python script that
 uses Viewlib. Start off with the sample code in [sample.py](./sample.py). You
@@ -53,7 +87,7 @@ can then extend the view by adding more widgets and logic.
     - `WATT42_API_TOKEN`: Your access token.
 
 
-### Howtos
+## Howtos
 
 - See above on how to use Viewlib to build your own view.
 - [How to add a diagram](https://source.c3.uber5.com/watt42-public/watt42_viewlib/src/branch/main/docs/howto_add_diagram.md)
diff --git a/geyser_on_off.py b/geyser_on_off.py
new file mode 100644
index 0000000..46cb85d
--- /dev/null
+++ b/geyser_on_off.py
@@ -0,0 +1,23 @@
+import os
+import panel
+from typing import Any
+
+from watt42_viewlib import attach_w42_state
+
+SYSTEM_ID = os.environ.get("WATT42_SYSTEM_ID", "invalid-system-id")
+API_TOKEN = os.environ.get("WATT42_API_TOKEN", "invalid-api-token")
+
+w42_state = panel.rx(None)
+
+attach_w42_state(rx_var=w42_state, system_id=SYSTEM_ID, token=API_TOKEN)
+
+def get_geyser_state(state: dict[str, Any]) -> bool:
+    if not state:
+        return False
+    return state.get("is_geyser_on", False)
+
+geyser_state = panel.rx(get_geyser_state)(w42_state)
+
+indicator = panel.indicators.BooleanStatus(value=geyser_state, name="W42 Connected", color="success")
+
+_ = indicator.servable()