whisplay renders list of channels, selects channel, and connects

AGENTS.md

@@ -1,34 +1,50 @@
 # LXST Client
 
-Single-file Python CLI for managing LXST Channel connections via Reticulum Network (RNS) and LXMF protocols.
+Single-file Python application for managing LXST Channel connections via Reticulum Network (RNS) and LXMF protocols. Supports CLI and Whisplay HAT GUI modes.
 
-## Running
+## Running (CLI mode, default)
 
   python client.py [-c CONFIGDIR] [-w WHITELIST]
 
   Options:
-    -c, --config  : config directory (default: ~/.lxst-client or /etc/lxst-client)
-    -w, --whitelist: path to bridge_whitelist.json
-    -v, --verbose : enable debug logging
-    --rnsconfig   : alternative Reticulum config directory
+    -c, --config       : config directory (default: ~/.lxst-client or /etc/lxst-client)
+    -w, --whitelist    : path to bridge_whitelist.json
+    -v, --verbose      : enable debug logging
+    --rnsconfig        : alternative Reticulum config directory
+    --whisplay, -W     : enable Whisplay HAT GUI mode
 
-## Commands
+## Running (Whisplay GUI mode)
 
-  python client.py -c /etc/lxst-client -w /etc/lxst-client/bridge_whitelist.json
+  python client.py -W [-c CONFIGDIR] [-w WHITELIST]
+
+## CLI Commands
 
   Inside the interactive client:
-    d  Discover channels from whitelist
-    l  List discovered channels
-    <NUM>  Connect to channel at index NUM (1-based)
-    q  Quit
+    d        Discover channels from whitelist
+    l        List discovered channels
+    <NUM>    Connect to channel at index NUM (1-based)
+    h / ?    Show help
+    q        Quit
+
+## Whisplay GUI Controls
+
+  Short press (<1s)     Cycle to next channel in list
+  Long press (>=1s)     Call the selected channel
+  Press (while in call) Hang up
+
+  RGB LED indicates state:
+    Blue   = ready, showing channels
+    Orange = calling
+    Green  = in call
 
 ## Initial Setup Order
 
   1. Ensure ~/.lxst-client or /etc/lxst-client exists
   2. Place bridge_whitelist.json in either directory (or pass with -w)
   3. First run creates identity automatically at configdir/identity
-  4. Run `python client.py` then `d` to discover channels
-  5. Messages appear in configdir/lxmf/
+  4. In CLI mode: run `python client.py` then `d` to discover channels
+  5. In GUI mode: run `python client.py -W` — auto-discovers on startup
+  6. Messages appear in configdir/lxmf/
 
 ## Known quirks
 
@@ -36,3 +52,5 @@ Single-file Python CLI for managing LXST Channel connections via Reticulum Netwo
   - Identity is auto-generated on first run if not present.
   - Use -v for RNS debug output (path discovery is verbose here).
   - Path discovery waits up to 10s for relays; increase timeout in client code if needed.
+  - Whisplay mode requires Pillow and the Whisplay runtime (whisplay.py / whisplay_client.py).
+  - Falls back to CLI gracefully if Whisplay hardware or dependencies are unavailable.