Xaibatsu-Control-Panel/README.md

XION Arcade Control Panel
================================================================================

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.

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 net.buzzert.XaibatsuControlPanel
```

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
```

TestFlight releases
--------------------------------------------------------------------------------

Gitea Actions publishes tags named `release/vX.X.X` to TestFlight. The semantic
version from the tag and the Gitea `GITHUB_RUN_NUMBER` are written into the
app's Info.plist before it is archived. The workflow also copies the
`HOME_ASSISTANT_ACCESS_TOKEN` Gitea secret into the app's
`HomeAssistantAccessToken` Info.plist entry and verifies the archived app
contains it. For example:

```sh
git tag -a release/v2.0.0 -m 'Release 2.0.0'
git push origin release/v2.0.0
```

The workflow uses the `macos-arm64` runner and Fastlane Match. It expects these
repository Actions secrets:

- `ASC_KEY_ID`
- `ASC_ISSUER_ID`
- `ASC_KEY`
- `MATCH_PASSWORD`
- `MATCH_GIT_BASIC_AUTHORIZATION`
- `HOME_ASSISTANT_ACCESS_TOKEN`