Improve Home Assistant connection reliability

README.md

@@ -1,12 +1,42 @@
-XION Arcade WEMO-Enabled Control Panel
+XION Arcade Control Panel
 ================================================================================
 
-This is an iOS application designed for remote control of XION Arcade devices.
-The app is designed for XION but could work with any WEMO-enabled household by
-changing only one line of code.
+This is an iOS control panel for the XION/Xaibatsu arcade. It connects to Home
+Assistant's websocket API, displays entities with the `control_panel` label, and
+renders entities with the additional `control_panel_light` label in the lights
+section.
 
-The control panel is powered by the server-side client application called
-[Ouimeaux](http://ouimeaux.readthedocs.org). The application talks to any
-Ouimeaux server instance that is running and uses this to retrieve device
-information and to toggle devices on the network.
+Configuration
+--------------------------------------------------------------------------------
 
+The Home Assistant access token is intentionally not stored in source control.
+Provide it either through the `HOME_ASSISTANT_ACCESS_TOKEN` process environment
+variable or as the `HOME_ASSISTANT_ACCESS_TOKEN` Xcode build setting. The latter
+is expanded into the app's `HomeAssistantAccessToken` Info.plist entry.
+
+For a Simulator launch from the command line:
+
+```sh
+SIMCTL_CHILD_HOME_ASSISTANT_ACCESS_TOKEN='token' \
+  xcrun simctl launch booted com.zanneth.XIONControlPanel
+```
+
+The client disconnects cleanly when the app resigns active, reconnects and
+refreshes immediately when it returns, and uses Home Assistant `ping`/`pong`
+messages as a heartbeat while active.
+
+Testing
+--------------------------------------------------------------------------------
+
+The live integration test is opt-in because it briefly changes the `Asteroids`
+switch and restores its original state:
+
+```sh
+HOME_ASSISTANT_ACCESS_TOKEN='token' \
+RUN_LIVE_HOME_ASSISTANT_TESTS=1 \
+xcodebuild -project XIONControlPanel.xcodeproj \
+  -scheme XIONControlPanel \
+  -destination 'platform=iOS Simulator,name=iPhone 17' \
+  -only-testing:XIONControlPanelTests/HomeAssistantIntegrationTests \
+  test
+```