add documentation site

2023-09-07 14:44:35 +02:00 · 2023-09-07 14:44:35 +02:00 · 425fab7c62
parent 8a547a3caf
commit 425fab7c62
21 changed files with 9595 additions and 2 deletions
--- a/.github/workflows/pages.yaml
+++ b/.github/workflows/pages.yaml
@ -0,0 +1,6 @@
+name: "GitHub Pages"
+
+on:
+  pull_request:
+    branches:
+      - "main"
--- a/README.md
+++ b/README.md
@ -40,8 +40,9 @@ are not documented... ;)
  - bass level
  - *[to come] equalizer bands*
 - `select` entity
-  - *[to come] sound mode* (additional control in the "Device" tab)
-  - *[to come] equalizer preset*
+  - sound mode (additional control in the "Device" tab)
+  - input (additional control in the "Device" tab)
+  - equalizer preset

 ## How to install it:

--- a/docs/.eslintignore
+++ b/docs/.eslintignore
@ -0,0 +1,4 @@
+dist
+node_modules
+.output
+.nuxt
--- a/docs/.eslintrc.cjs
+++ b/docs/.eslintrc.cjs
@ -0,0 +1,8 @@
+module.exports = {
+  root: true,
+  extends: '@nuxt/eslint-config',
+  rules: {
+    'vue/max-attributes-per-line': 'off',
+    'vue/multi-word-component-names': 'off'
+  }
+}
--- a/docs/.gitignore
+++ b/docs/.gitignore
@ -0,0 +1,12 @@
+node_modules
+*.iml
+.idea
+*.log*
+.nuxt
+.vscode
+.DS_Store
+coverage
+dist
+sw.*
+.env
+.output
--- a/docs/.npmrc
+++ b/docs/.npmrc
@ -0,0 +1,2 @@
+shamefully-hoist=true
+strict-peer-dependencies=false
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,57 @@
+# Docus Starter
+
+Starter template for [Docus](https://docus.dev).
+
+## Clone
+
+Clone the repository (using `nuxi`):
+
+```bash
+npx nuxi init -t themes/docus
+```
+
+## Setup
+
+Install dependencies:
+
+```bash
+yarn install
+```
+
+## Development
+
+```bash
+yarn dev
+```
+
+## Edge Side Rendering
+
+Can be deployed to Vercel Functions, Netlify Functions, AWS, and most Node-compatible environments.
+
+Look at all the available presets [here](https://v3.nuxtjs.org/guide/deploy/presets).
+
+```bash
+yarn build
+```
+
+## Static Generation
+
+Use the `generate` command to build your application.
+
+The HTML files will be generated in the .output/public directory and ready to be deployed to any static compatible hosting.
+
+```bash
+yarn generate
+```
+
+## Preview build
+
+You might want to preview the result of your build locally, to do so, run the following command:
+
+```bash
+yarn preview
+```
+
+---
+
+For a detailed explanation of how things work, check out [Docus](https://docus.dev).
--- a/docs/app.config.ts
+++ b/docs/app.config.ts
@ -0,0 +1,37 @@
+export default defineAppConfig({
+  docus: {
+    title: 'YASSI',
+    description: 'HomeAssistant: Yet another Samsung soundbar integration',
+    image: 'https://user-images.githubusercontent.com/904724/185365452-87b7ca7b-6030-4813-a2db-5e65c785bf88.png',
+    socials: {
+      github: 'samuelspagl/ha_samsung_soundbar',
+      nuxt: {
+        label: 'Nuxt',
+        icon: 'simple-icons:nuxtdotjs',
+        href: 'https://nuxt.com'
+      }
+    },
+    github: {
+      dir: 'docs/content',
+      branch: 'main',
+      repo: 'ha_samsung_soundbar',
+      owner: 'samuelspagl',
+      edit: true
+    },
+    aside: {
+      level: 0,
+      collapsed: false,
+      exclude: []
+    },
+    main: {
+      padded: true,
+      fluid: true
+    },
+    header: {
+      logo: true,
+      showLinkIcon: true,
+      exclude: [],
+      fluid: true
+    }
+  }
+})
--- a/docs/content/0.index.md
+++ b/docs/content/0.index.md
@ -0,0 +1,69 @@
+---
+title: "YASSI"
+---
+::block-hero
+---
+cta:
+  - Why another HomeAssistant integration?
+  - #why-another-integration
+secondary:
+  - Open on GitHub →
+  - https://github.com/nuxtlabs/docus
+snippet:
+  - Custom Components
+  - "- input selection"
+  - "- soundmode selection"
+  - "- eq-preset selection"
+  - "- woofer settings"
+  - "- other cool things"
+---
+
+#title
+Yassi
+
+#description
+Yet another Samsung soundbar integration for HomeAssistant
+::
+
+::card-grid
+#title
+Quick-Start
+#root
+:ellipsis
+
+#default
+  ::card
+  #title
+  Getting Started.
+  #description
+  Go, Go, Go... Here you will find information on "How to install / configure".
+  <br>
+  <br>
+  :button-link[click here]{href="/getting-started"}
+  ::
+
+  ::card
+  #title
+  Features
+  #description
+  Many cool features are awaiting your eyes to see ✨.
+  <br>
+  <br>
+  :button-link[click here]{href="/features"}
+  ::
+::
+
+
+## Why another integration
+
+The current Samsung Soundbar Integration by @PiotrMachowski / @thierryBourbon are already pretty cool.
+But I wanted it to appear as a device, and base the Foundation on the `pysmartthings` python package.
+
+Additionally, I wanted full control over the *Soundmode* and more. So I tried out a few things with the API,
+and found that also the **Subwoofer** as well as the **Equalizer** are controllable.
+
+I created a new wrapper around the `pysmartthings.DeviceEntity` specifically set up for a Soundbar, and this
+is the Result.
+
+I hope to integrate also controls for **surround speaker** as well as **Space-Fit Sound**, but as these features
+are not documented... ;) 
--- a/docs/content/1.getting-started/0.index.md
+++ b/docs/content/1.getting-started/0.index.md
@ -0,0 +1,30 @@
+# Getting Started
+
+## Installation
+
+### HACS (official)
+
+> ⚠️ Not done yet, hopefully soon.
+
+
+### HACS (custom repository)
+
+You can add this repository as a custom repository to your hacs.
+After you've done that, you can search for it like with the "official"
+integrations.
+
+### Manual
+
+Copy the contents of `custom_components/samsung_soundbar` to `config/custom_components/samsung_soundbar`
+on your HomeAssistant instance.
+
+## Configuration
+
+After you installed the custom component, it should be possible to configure the integration
+in the `device` settings of your HomeAssistant.
+
+You will need:
+- a SmartThings `api_key` [click here](https://account.smartthings.com/tokens)
+- the `device_id` of your device [click here](https://my.smartthings.com/advanced/devices)
+- a name for your Soundbar
+- and a `max_volume`
--- a/docs/content/2.features/0.index.md
+++ b/docs/content/2.features/0.index.md
@ -0,0 +1,35 @@
+# Features
+
+**YASSI** and retrieve / set the status of the following features grouped as a device:
+- `media_player`:
+  - `on / off` [*read, write*]
+  - `volume` (set, step) [*read, write*]
+  - `input` (select) [*read*, write*]
+  - `sound_mode` (select) [*read, write*]
+  - `play` (button) [*write*]
+  - `pause` (button) [*write*]
+  - `media_artwork` (image) [*read*]
+  - `media_title` (text) [*read*]
+  - `media_artist` (text) [*read*]
+
+- `number`
+  - **Woofer**
+    - level (set) [*read, write*]
+- `select`
+  - **Input**
+    - `input` [*read, write*]
+    - `supported_inputs` [*read*]
+  - **Soundmode**
+    - `active_soundmode` [*read, write*]
+    - `supported_soundmodes` [*read*]
+  - **EQ-Preset**
+    - `active_eq_preset` [*read, write*]
+    - `supported_eq_preset` [*read*]
+
+- `button`
+  - `night_mode` [*read, write*]
+  - `voice_amplifier` [*read, write*]
+  - `bass_mode` [*read, write*]
+
+- `image`
+  - `media_coverart` [*read*]
--- a/docs/content/3.smartthings-api/1.current_status.md
+++ b/docs/content/3.smartthings-api/1.current_status.md
@ -0,0 +1,47 @@
+# "Standard" information
+
+This is the "standard" information that you can fetch with the `pysmartthings` library
+for a given soundbar:
+
+```python
+{
+    'supportedPlaybackCommands': status(value=['play', 'pause', 'stop'], unit=None, data=None),
+    'playbackStatus': status(value='paused', unit=None, data=None),
+    'mode': status(value=10, unit=None, data=None),
+    'detailName': status(value='TV', unit=None, data=None),
+    'volume': status(value=16, unit='%', data=None),
+    'supportedInputSources': status(value=['digital', 'HDMI1', 'bluetooth', 'wifi'], unit=None, data=None),
+    'inputSource': status(value='digital', unit=None, data=None),
+    'data': status(value=None,unit=None,data=None),
+    'switch': status(value='on', unit=None, data=None),
+    'role': status(value=None, unit=None, data=None),
+    'channel': status(value=None, unit=None, data=None),
+    'masterName': status(value=None, unit=None, data=None),
+    'status': status(value=None, unit=None, data=None),
+    'st': status(value='1970-01-01T00:00:28Z', unit=None, data=None),
+    'mndt': status(value='2022-01-01', unit=None, data=None),
+    'mnfv': status(value='HW-Q935BWWB-1010.0', unit=None, data=None),
+    'mnhw': status(value='', unit=None, data=None),
+    'di': status(value='##############################', unit=None, data=None),
+    'mnsl': status(value=None, unit=None, data=None),
+    'dmv': status(value='res.1.1.0,sh.1.1.0', unit=None, data=None),
+    'n': status(value='Samsung Soundbar Q935B', unit=None, data=None),
+    'mnmo': status(value='HW-Q935B', unit=None, data=None),
+    'vid': status(value='VD-NetworkAudio-002S', unit=None, data=None),
+    'mnmn': status(value='Samsung Electronics', unit=None, data=None),
+    'mnml': status(value=None, unit=None, data=None),
+    'mnpv': status(value='6.5', unit=None, data=None),
+    'mnos': status(value='Tizen', unit=None, data=None),
+    'pi': status(value='##################################', unit=None, data=None),
+    'icv': status(value='core.1.1.0', unit=None, data=None),
+    'mute': status(value='unmuted', unit=None, data=None),
+    'totalTime': status(value=174590, unit=None, data=None),
+    'audioTrackData': status(value={'title': 'QUIET', 'artist': 'ELEVATION RHYTHM', 'album': ''}, unit=None, data=None),
+    'elapsedTime': status(value=28601, unit=None, data=None)
+}
+```
+
+It is possible to fetch the current status (on/off) or information about the input.
+and if Spotify / AirPlay or Bluetooth are used, also the `title` and `artist` of a played track.
+
+All of these states can also be set. Eg. the input, volume, mute and more.
--- a/docs/content/3.smartthings-api/2.extra_information.md
+++ b/docs/content/3.smartthings-api/2.extra_information.md
@ -0,0 +1,234 @@
+# Additional information
+
+It is possible to retrieve even more information / control more aspects of
+your Samsung soundbar, by utilizing the (undocumented) execute status.
+
+As the [API states](https://developer.smartthings.com/docs/api/public/#operation/executeDeviceCommands), 
+it is possible to execute custom commands. You can retrieve the status / values of your
+custom command in the `data` attribute when fetching new information of the device.
+
+<details>
+<summary>Expand to see a sample of the fetched data of a soundbar device</summary>
+
+This is a dictionary fetched by a `pysmartthings.device.status.attributes` after a `device.status.refresh()`.
+
+```python
+{
+    'supportedPlaybackCommands': status(value=['play', 'pause', 'stop'], unit=None, data=None),
+    'playbackStatus': status(value='paused', unit=None, data=None),
+    'mode': status(value=10, unit=None, data=None),
+    'detailName': status(value='TV', unit=None, data=None),
+    'volume': status(value=16, unit='%', data=None),
+    'supportedInputSources': status(value=['digital', 'HDMI1', 'bluetooth', 'wifi'], unit=None, data=None),
+    'inputSource': status(value='digital', unit=None, data=None),
+    'data': status(
+        value={
+            'payload': {
+                'rt': ['x.com.samsung.networkaudio.eq'],
+                'if': ['oic.if.rw', 'oic.if.baseline'],
+                'x.com.samsung.networkaudio.supportedList': ['NONE', 'POP', 'JAZZ', 'CLASSIC', 'CUSTOM'],
+                'x.com.samsung.networkaudio.EQname': 'NONE',
+                'x.com.samsung.networkaudio.action': 'setEQmode',
+                'x.com.samsung.networkaudio.EQband': ['0', '0', '0', '0', '0', '0', '0']
+            }
+        },
+        unit=None,
+        data={'href': '/sec/networkaudio/eq'}
+    ),
+    'switch': status(value='on', unit=None, data=None),
+    'role': status(value=None, unit=None, data=None),
+    'channel': status(value=None, unit=None, data=None),
+    'masterName': status(value=None, unit=None, data=None),
+    'status': status(value=None, unit=None, data=None),
+    'st': status(value='1970-01-01T00:00:28Z', unit=None, data=None),
+    'mndt': status(value='2022-01-01', unit=None, data=None),
+    'mnfv': status(value='HW-Q935BWWB-1010.0', unit=None, data=None),
+    'mnhw': status(value='', unit=None, data=None),
+    'di': status(value='##############################', unit=None, data=None),
+    'mnsl': status(value=None, unit=None, data=None),
+    'dmv': status(value='res.1.1.0,sh.1.1.0', unit=None, data=None),
+    'n': status(value='Samsung Soundbar Q935B', unit=None, data=None),
+    'mnmo': status(value='HW-Q935B', unit=None, data=None),
+    'vid': status(value='VD-NetworkAudio-002S', unit=None, data=None),
+    'mnmn': status(value='Samsung Electronics', unit=None, data=None),
+    'mnml': status(value=None, unit=None, data=None),
+    'mnpv': status(value='6.5', unit=None, data=None),
+    'mnos': status(value='Tizen', unit=None, data=None),
+    'pi': status(value='##################################', unit=None, data=None),
+    'icv': status(value='core.1.1.0', unit=None, data=None),
+    'mute': status(value='unmuted', unit=None, data=None),
+    'totalTime': status(value=174590, unit=None, data=None),
+    'audioTrackData': status(value={'title': 'QUIET', 'artist': 'ELEVATION RHYTHM', 'album': ''}, unit=None, data=None),
+    'elapsedTime': status(value=28601, unit=None, data=None)
+}
+```
+
+</details>
+
+The `data` attribute can also be fetched separately with an undocumented API endpoint.
+```python
+    url = f"https://api.smartthings.com/v1/devices/{self._device_id}/components/main/capabilities/execute/status"
+```
+
+It seems that the normal `device.status.refresh()` retrieves cached results from the execute status. Therefore
+using this endpoint separately seems to be a better solution.
+
+To set the status of a given setting a command needs to be issued with the following (sample) structure:
+
+```python
+data = {
+            "commands": [
+                {
+                    "component": component_id,
+                    "capability": capability,
+                    "command": command,
+                    "arguments": ["/sec/networkaudio/advancedaudio"]
+                }
+            ]
+        }
+```
+To set a setting, you will "update" an object in the given path, with a payload
+similar to the following:
+```python
+data = {
+            "commands": [
+                {
+                    "component": component_id,
+                    "capability": capability,
+                    "command": command,
+                    "arguments": ["/sec/networkaudio/advancedaudio", {"x.com.samsung.networkaudio.bassboost": 1}]
+                }
+            ]
+        }
+```
+
+## Soundmode
+
+This setting has the href: `"/sec/networkaudio/soundmode"`
+
+<details>
+<summary>
+A sample status looks like this:
+</summary>
+
+```python
+{
+    'data': {
+        'value': {
+            'payload': {
+                'rt': ['x.com.samsung.networkaudio.soundmode'],
+                'if': ['oic.if.a', 'oic.if.baseline'],
+                'x.com.samsung.networkaudio.soundmode': 'adaptive sound',
+                'x.com.samsung.networkaudio.supportedSoundmode': ['standard', 'surround', 'game', 'adaptive sound']
+            }
+        },
+        'data': {'href': '/sec/networkaudio/soundmode'},
+        'timestamp': '2023-09-05T14:59:50.581Z'
+    }
+}
+```
+</details>
+
+## Advanced Audio
+
+This setting has the href: `"/sec/networkaudio/advancedaudio"`
+
+<details>
+<summary>
+A sample status looks like this:
+</summary>
+
+```python
+{
+    'data': {
+        'value': {
+            'payload': {
+                'rt': ['x.com.samsung.networkaudio.advancedaudio'],
+                'if': ['oic.if.rw', 'oic.if.baseline'],
+                'x.com.samsung.networkaudio.voiceamplifier': 0,
+                'x.com.samsung.networkaudio.bassboost': 0,
+                'x.com.samsung.networkaudio.nightmode': 0
+            }
+        },
+        'data': {'href': '/sec/networkaudio/advancedaudio'},
+        'timestamp': '2023-09-05T15:00:14.665Z'
+    }
+}
+
+```
+</details>
+
+## Subwoofer
+
+This setting has the href: `"/sec/networkaudio/woofer"`
+
+<details>
+<summary>
+A sample status looks like this:
+</summary>
+
+```python
+{
+    'value': {
+        'payload': {
+            'rt': ['x.com.samsung.networkaudio.woofer'],
+            'if': ['oic.if.a', 'oic.if.baseline'],
+            'x.com.samsung.networkaudio.woofer': 3,
+            'x.com.samsung.networkaudio.connection': 'on'
+        }
+    },
+    'data': {'href': '/sec/networkaudio/woofer'},
+    'timestamp': '2023-09-05T14:57:36.450Z'
+}
+
+```
+</details>
+
+## Equalizer
+
+This setting has the href: `"/sec/networkaudio/eq"`
+
+<details>
+<summary>
+A sample status looks like this:
+</summary>
+
+```python
+{
+    'data': {
+        'value': {
+            'payload': {
+                'rt': ['x.com.samsung.networkaudio.eq'],
+                'if': ['oic.if.rw', 'oic.if.baseline'],
+                'x.com.samsung.networkaudio.supportedList': ['NONE', 'POP', 'JAZZ', 'CLASSIC', 'CUSTOM'],
+                'x.com.samsung.networkaudio.EQname': 'NONE',
+                'x.com.samsung.networkaudio.action': 'setEQmode',
+                'x.com.samsung.networkaudio.EQband': ['0', '0', '0', '0', '0', '0', '0']
+            }
+        },
+        'data': {'href': '/sec/networkaudio/eq'},
+        'timestamp': '2023-09-05T14:59:03.490Z'
+    }
+}
+```
+</details>
+
+## Volume
+
+This setting has the href: `"/sec/networkaudio/audio"`
+
+<details>
+<summary>
+A sample status looks like this:
+</summary>
+
+```python
+{
+    'data': {
+        'value': {'payload': {'rt': ['oic.r.audio'], 'if': ['oic.if.a', 'oic.if.baseline'], 'mute': False, 'volume': 3}},
+        'data': {'href': '/sec/networkaudio/audio'},
+        'timestamp': '2023-09-05T15:09:04.980Z'
+    }
+}
+```
+</details>
--- a/docs/nuxt.config.ts
+++ b/docs/nuxt.config.ts
@ -0,0 +1,13 @@
+export default defineNuxtConfig({
+  // https://github.com/nuxt-themes/docus
+  extends: '@nuxt-themes/docus',
+  app: {
+    baseURL: '/ha_samsung_soundbar/',
+    },
+  modules: [
+    // https://github.com/nuxt-modules/plausible
+    '@nuxtjs/plausible',
+    // https://github.com/nuxt/devtools
+    '@nuxt/devtools'
+  ]
+})
--- a/docs/package.json
+++ b/docs/package.json
@ -0,0 +1,21 @@
+{
+  "name": "YASSI",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "nuxi dev",
+    "build": "nuxi build",
+    "generate": "nuxi generate",
+    "preview": "nuxi preview",
+    "lint": "eslint ."
+  },
+  "devDependencies": {
+    "@nuxt-themes/docus": "^1.13.1",
+    "@nuxt/devtools": "^0.6.7",
+    "@nuxt/eslint-config": "^0.1.1",
+    "@nuxtjs/plausible": "^0.2.1",
+    "@types/node": "^20.4.0",
+    "eslint": "^8.44.0",
+    "nuxt": "^3.6.2"
+  }
+}
--- a/docs/public/favicon.ico
+++ b/docs/public/favicon.ico
--- a/docs/renovate.json
+++ b/docs/renovate.json
@ -0,0 +1,8 @@
+{
+    "extends": [
+      "@nuxtjs"
+    ],
+    "lockFileMaintenance": {
+      "enabled": true
+    }
+}
--- a/docs/tokens.config.ts
+++ b/docs/tokens.config.ts
@ -0,0 +1,4 @@
+import { defineTheme } from 'pinceau'
+
+export default defineTheme({
+})
--- a/docs/tsconfig.json
+++ b/docs/tsconfig.json
@ -0,0 +1,3 @@
+{
+  "extends": "./.nuxt/tsconfig.json"
+}
--- a/docs/yarn.lock
+++ b/docs/yarn.lock
--- a/test.py
+++ b/test.py
@ -0,0 +1,36 @@
+class Stuff:
+    def __init__(self, a: int):
+        self.__a = a
+
+    def set_a(self, new_a: int):
+        self.__a = new_a
+
+    @property
+    def a(self):
+        return self.__a
+
+
+class Stuff2:
+    def __init__(self, a: int):
+        self.stuff = Stuff(a)
+
+
+    def set_a(self, a):
+        self.stuff.set_a(a)
+
+    @property
+    def a(self):
+        return self.stuff.a
+
+hal = Stuff(3)
+print(hal.a)
+hal.set_a(5)
+print(hal.a)
+print()
+print()
+has = Stuff2(3)
+print(has.a)
+print(has.stuff.set_a(5))
+print(has.a)
+print(has.set_a(10))
+print(has.a)