Merge pull request #1 from Shaffer-Softworks/hacs

Initial commit of Android WS Player integration for Home Assistant, i…

Author: sickkick

.cursor/rules/android-ws-player.mdc

@@ -0,0 +1,65 @@
+---
+description: Android WS Player — Home Assistant custom integration context
+alwaysApply: true
+---
+
+# Android WS Player
+
+Home Assistant **custom integration** (HACS-ready) that exposes Android tablets as `media_player` entities. Commands are sent via the HA event bus; the tablet app listens on a WebSocket connection.
+
+- **Repo**: https://github.com/Shaffer-Softworks/Android-WS-Player
+- **Domain**: `android_ws_player`
+- **Version**: `0.2.1` (manifest)
+- **Min HA**: `2024.11.0` (`hacs.json`) — required for modern `OptionsFlow`
+
+## Architecture
+
+```
+custom_components/android_ws_player/
+  __init__.py          # setup_entry, reload on options change
+  config_flow.py       # user setup + options (gear icon)
+  media_player.py      # fires bus events (play_media, stop, set_volume)
+  const.py             # DOMAIN, CONF_DEVICE_ID, CONF_EVENT_TYPE
+  strings.json + translations/en.json
+  brand/               # custom icons (Android + headphones/play/waves); ignore brands in HACS CI
+```
+
+Each config entry = one tablet. Unique ID = `device_id`.
+
+## Event contract (default type: `android_ws_player_command`)
+
+```json
+{ "device_id": "kitchen_tablet", "command": "play_media", "url": "...", "media_type": "music" }
+{ "device_id": "...", "command": "stop" }
+{ "device_id": "...", "command": "set_volume", "volume": 0.8 }
+```
+
+## Options flow (important)
+
+HA 2024.11+ sets `self.config_entry` on `OptionsFlow` — **do not** pass `config_entry` to `__init__` or assign `self.config_entry`. Pattern:
+
+```python
+def async_get_options_flow(config_entry):
+    return AndroidWsPlayerOptionsFlow()  # no args
+```
+
+Gear-icon 500 errors were caused by the old `__init__(config_entry)` pattern.
+
+## HACS
+
+- Root: `hacs.json`, `README.md`, `LICENSE`, `.github/workflows/validate.yaml`
+- CI: `hassfest` + `hacs/action` with `ignore: brands` (brand assets ship in `custom_components/.../brand/`)
+- GitHub repo must have **at least one topic** (e.g. `home-assistant`, `hacs-integration`) or HACS validation fails
+- Default store: PR to `hacs/default` → add `"Shaffer-Softworks/Android-WS-Player"` to `integration` list (alphabetical); also needs a GitHub **release**
+
+## Brand assets
+
+Custom-generated artwork (not copied from Android-Management): Android mascot + headphones + play button + sound waves. Icons: 256/512 square; logos: wide format with `@2x` variants. Source drafts may live in Cursor `assets/`; committed files are under `brand/`.
+
+## Config fields
+
+| Field | Where | Purpose |
+|-------|--------|---------|
+| `name` | entry title | Friendly name |
+| `device_id` | entry data | Tablet listener ID |
+| `event_type` | data/options | Bus event name |

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Shaffer-Softworks

.github/workflows/validate.yaml

@@ -0,0 +1,39 @@
+name: Validate
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "0 0 * * *"
+
+permissions: {}
+
+jobs:
+  hassfest:
+    name: Hassfest validation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v6
+
+      - name: Run hassfest validation
+        uses: home-assistant/actions/hassfest@master
+
+  hacs:
+    name: HACS validation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v6
+
+      - name: Run HACS validation
+        uses: hacs/action@main
+        with:
+          category: integration
+          # Custom integrations ship brand assets in-repo (HA 2026.3+).
+          ignore: brands

.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.env
+.venv/
+venv/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+*.swp
+
+# Home Assistant dev
+.storage/
+.homeassistant/
+config/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaffer-Softworks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,77 @@
+# Android WS Player
+
+[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)
+[![Validate](https://github.com/Shaffer-Softworks/Android-WS-Player/actions/workflows/validate.yaml/badge.svg)](https://github.com/Shaffer-Softworks/Android-WS-Player/actions/workflows/validate.yaml)
+
+Home Assistant custom integration that exposes each Android tablet as a **media player** entity. Play, stop, and volume commands are delivered to your tablet app as Home Assistant bus events.
+
+## Features
+
+- One media player entity per tablet
+- Configurable `device_id` and event type per device
+- Rename devices from the integration options (gear icon)
+- `play_media`, `stop`, and `volume_set` support
+
+## Installation
+
+### HACS (recommended)
+
+1. Install [HACS](https://hacs.xyz/docs/setup/download) if you have not already.
+2. Open **HACS → Integrations → ⋮ → Custom repositories**.
+3. Add `https://github.com/Shaffer-Softworks/Android-WS-Player` as category **Integration**, then search for **Android WS Player** and install.
+4. Restart Home Assistant.
+5. Go to **Settings → Devices & services → Add integration** and choose **Android WS Player**.
+
+If this repository is listed in the [HACS default store](https://github.com/hacs/default), you can install it directly without adding a custom repository.
+
+### Manual
+
+1. Copy `custom_components/android_ws_player` into your Home Assistant `config/custom_components/` directory.
+2. Restart Home Assistant.
+3. Add the integration from **Settings → Devices & services**.
+
+## Configuration
+
+During setup you provide:
+
+| Field | Description |
+| --- | --- |
+| **Name** | Friendly name shown in Home Assistant (e.g. `Kitchen Tablet`) |
+| **Device ID** | Identifier your Android app listens for (e.g. `kitchen_tablet`) |
+| **Event type** | HA event name fired for commands (default: `android_ws_player_command`) |
+
+Use the integration **gear icon** to change the name or event type later.
+
+## Android app
+
+Your tablet app should subscribe to the configured event type on the Home Assistant WebSocket API. Each event payload includes:
+
+| Field | Description |
+| --- | --- |
+| `device_id` | Matches the ID configured in Home Assistant |
+| `command` | `play_media`, `stop`, or `set_volume` |
+| `url` | Media URL (for `play_media`) |
+| `volume` | Level 0.0–1.0 (for `set_volume`) |
+
+Example `play_media` event:
+
+```json
+{
+  "device_id": "kitchen_tablet",
+  "command": "play_media",
+  "url": "https://example.com/stream.mp3",
+  "media_type": "music"
+}
+```
+
+## Development
+
+Validation runs on every push via GitHub Actions (`hassfest` + HACS). Brand images are bundled under `custom_components/android_ws_player/brand/` for Home Assistant 2026.3+.
+
+## Support
+
+- [Open an issue](https://github.com/Shaffer-Softworks/Android-WS-Player/issues)
+
+## License
+
+MIT — see [LICENSE](LICENSE).