Add Changelog, bump version

Co-authored-by: Jorim Tielemans <tielemans.jorim@gmail.com>

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.3.1] Documentation enhancements
+
+### Changed
+
+- Updated the `README` as well as the documentation website
+
 ## [0.3.0] Icons and Chore
 
 ### Added

README.md

@@ -1,6 +1,19 @@
-# HomeAssistant: Samsung Soundbar Integration
+# YASSI: Yet Another Samsung Soundbar Integration (for Home Assistant)
 
-> Yet another Samsung Soundbar Integration (YASSI)
+Welcome to YASSI, the Home Assistant integration designed to bring comprehensive control over your Samsung Soundbar into your smart home ecosystem.
+
+**Table of Contents:**
+<!-- TOC -->
+* [Why YASSI](#why-yassi)
+* [Features](#features)
+* [Installation / Setup](#installation--setup)
+  * [Prerequisites](#prerequisites)
+  * [Installation:](#installation)
+  * [Configuration](#configuration)
+* [Support](#support)
+* [Contributing](#contributing)
+* [General Thanks](#general-thanks)
+<!-- TOC -->
 
 ## Why YASSI
 
@@ -18,48 +31,54 @@ are not documented... ;)
 
 ## Features
 
-- Set-Up through HomeAssistant-UI
-- Theoretically it should be possible to have multiple Devices (not tested)
 
-- `media_player` Entity
+- **UI Setup**: You can easily set up your Soundbar through the UI.
-  - On / Off
+- **Media Player Controls**: Power, volume, mute, source selection, and media controls are all at your fingertips.
-  - Volume
+- **Selectable Sound Modes**: Choose from various sound modes and inputs for optimal audio.
-  - Mute
+- **Subwoofer & Equalizer Adjustment**: Fine-tune your audio experience.
-  - Input Source
+- **Switchable Enhancements**: Toggle features like night mode and voice amplification.
-  - Sound Mode
+- **Customizable Bass Level**: Set the bass to your preference.
-  - Media
+- **Multiple Devices**: should be theoretically possible but **not** tested
-    - Play / Pause / Stop
-    - Artist
-    - Title
-    - Music Cover Art url (iTunes Api)
-- `switch` entity
-  - Night mode
-  - Bass mode
-  - Voice amplifier
-- `number` entity
-  - bass level
-  - *[to come] equalizer bands*
-- `select` entity
-  - sound mode (additional control in the "Device" tab)
-  - input (additional control in the "Device" tab)
-  - equalizer preset
 
-## How to install it:
+For the full feature list per entity type, please take a look at the [documentation](ha-samsung-soundbar.vercel.app) website.
 
-### HACS: 
+## Installation / Setup
->  ⚠️ not done yet but planned (hopefully)
 
-### Adding this repository as custom repository
+### Prerequisites
 
-Add this repository as custom repository in HACS and install it ;)
+Before you begin, ensure you have the following:
 
-### Manual
+- A Samsung Soundbar compatible with SmartThings.
+- Home Assistant installed and running.
+- HACS (Home Assistant Community Store) for easy installation.
 
-You can also copy the `samsung_soundbar` folder in the `custom_components` folder to
+### Installation
-your `config/custom_components` folder.
 
+1. Add this repository as a custom repository in HACS or manually copy the `samsung_soundbar` folder to the `custom_components` directory in your Home Assistant configuration.
+
+  [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=samuelspagl&repository=ha_samsung_soundbar&category=integration)
+2. Restart Home Assistant.
+
+> [!NOTE]
+> It is planned to add it to the default `HACS` repository list, but not done yet.
+
+### Configuration
+
+To integrate your Samsung Soundbar with Home Assistant using YASSI, you will be asked for the following variables:
+
+- **SmartThings API Key**: [Retrieve your API key from SmartThings Tokens.](https://account.smartthings.com/tokens)
+- **Device ID**: [Find your device ID at SmartThings Devices.](https://my.smartthings.com/advanced/devices)
+- **Device Name**: Choose a name for your soundbar to be recognized in Home Assistant.
+- **Max Volume**: Define the maximum volume level for the `media_player` slider (between `1` and `100`).
+
+## Support
+
+For support, feature requests, or bug reporting, please visit the Issues section of this GitHub repository.
+
+## Contributing
+
+Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
 
 ## General Thanks
 
-Like already mentioned, thanks to @PiotrMachowski / @thierryBourbon for the general
+- Like already mentioned, thanks to @PiotrMachowski / @thierryBourbon for the general idea on how to do things.
-idea on how to do things.

custom_components/samsung_soundbar/manifest.json

@@ -8,5 +8,5 @@
   "iot_class": "cloud_polling",
   "issue_tracker": "https://github.com/samuelspagl/ha_samsung_soundbar/issues",
   "requirements": ["pysmartthings"],
-  "version": "0.3.0"
+  "version": "0.3.1"
 }

docs/app.config.ts

@@ -1,7 +1,7 @@
 export default defineAppConfig({
   docus: {
-    title: 'YASSI',
+    title: '🔊 Yassi',
-    description: 'HomeAssistant: Yet another Samsung soundbar integration',
+    description: 'Yet another Samsung Soundbar integration for Home Assistant',
     image: 'https://user-images.githubusercontent.com/904724/185365452-87b7ca7b-6030-4813-a2db-5e65c785bf88.png',
     socials: {
       github: 'samuelspagl/ha_samsung_soundbar',
@@ -28,7 +28,7 @@ export default defineAppConfig({
       fluid: true
     },
     header: {
-      logo: true,
+      logo: false,
       showLinkIcon: true,
       exclude: [],
       fluid: true

docs/content/0.index.md

@@ -5,24 +5,19 @@ title: "YASSI"
 ---
 cta:
   - Why another HomeAssistant integration?
-  - #why-another-integration
+  - /first-things-first/why-another-integration
 secondary:
   - Open on GitHub →
-  - https://github.com/nuxtlabs/docus
+  - https://github.com/samuelspagl/ha_samsung_soundbar
-snippet:
-  - Custom Components
-  - "- input selection"
-  - "- soundmode selection"
-  - "- eq-preset selection"
-  - "- woofer settings"
-  - "- other cool things"
 ---
 
 #title
-Yassi
+Yassi - Yet another Samsung Soundbar integration
 
 #description
-Yet another Samsung soundbar integration for HomeAssistant
+**YASSI** is a **HomeAssistant** integration for **Samsung Soundbars**. It enhances control, and adds features like equalizer settings. Install it via HACS or manually. Kudos to the original idea by @PiotrMachowski and @thierryBourbon! 🎶🔊
+
+[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=samuelspagl&repository=ha_samsung_soundbar&category=integration)
 ::
 
 ::card-grid
@@ -34,36 +29,42 @@ Quick-Start
 #default
   ::card
   #title
-  Getting Started.
+  ❓ Why another integration?
   #description
-  Go, Go, Go... Here you will find information on "How to install / configure".
+  Whether you thought about it or not, here is the answer ;).
   <br>
   <br>
-  :button-link[click here]{href="/getting-started"}
+  :button-link[click here]{href="/first-things-first/why-another-integration"}
   ::
 
   ::card
   #title
-  Features
+  🚀 Getting Started
+  #description
+  Go, Go, Go... Here you will find information on "How to install / configure".
+  <br>
+  <br>
+  :button-link[click here]{href="/first-things-first/getting-started"}
+  ::
+
+  ::card
+  #title
+  ✨ Features
   #description
   Many cool features are awaiting your eyes to see ✨.
   <br>
   <br>
   :button-link[click here]{href="/features"}
   ::
-::
 
-
+  ::card
-## Why another integration
+  #title
-
+  ⚙️ SmartThings API related information
-The current Samsung Soundbar Integration by @PiotrMachowski / @thierryBourbon are already pretty cool.
+  #description
-But I wanted it to appear as a device, and base the Foundation on the `pysmartthings` python package.
+  If you want to know some background information on how equalizer support and
-
+  other things were implemented, this is your section.
-Additionally, I wanted full control over the *Soundmode* and more. So I tried out a few things with the API,
+  <br>
-and found that also the **Subwoofer** as well as the **Equalizer** are controllable.
+  <br>
-
+  :button-link[click here]{href="/features"}
-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... ;) 

docs/content/1.first-things-first/0.why-another-integration.md

@@ -0,0 +1,13 @@
+# ❓ 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... ;) 

docs/content/1.first-things-first/1.getting-started.md

@@ -0,0 +1,43 @@
+# 🚀 Getting Started with Yassi
+
+Welcome to Yassi, the HomeAssistant integration for your Samsung Soundbar. This guide will help you get up and running in no time.
+
+## 📦 Installation Options
+
+### HACS (Home Assistant Community Store)
+
+#### 🌟 Official Repository (Coming Soon)
+The Yassi integration will be available through the official HACS repository shortly. Stay tuned for updates.
+
+#### ➕ Custom Repository
+In the meantime, you can manually add this repository to HACS:
+1. Click the following button and 'open link':
+[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=samuelspagl&repository=ha_samsung_soundbar&category=integration)
+2. Click 'add' to add the custom repository.
+3. Download 'Yassi' and restart Home Assistant.
+
+### 📂 Manual Installation
+If you prefer to install Yassi manually:
+1. Download the latest release from the repository.
+2. Extract and copy the `custom_components/samsung_soundbar` folder.
+3. Paste it into the `config/custom_components/samsung_soundbar` directory of your HomeAssistant setup.
+
+## ⚙️ Configuration Steps
+
+Once Yassi is installed, you can configure it via the HomeAssistant UI:
+
+1. Go to 'Configuration' and then 'Integrations'.
+2. Click on 'Add Integration' and search for 'Yassi'.
+3. Enter the following details to complete the setup:
+   - 🔑 SmartThings API Key: [Obtain it here](https://account.smartthings.com/tokens).
+   - 🆔 Device ID: [Find your Soundbar's device ID here](https://my.smartthings.com/advanced/devices).
+   - ㍻ Soundbar Name: Choose a name for easy identification.
+   - 🔊 Max Volume: Set the maximum volume limit for your Soundbar.
+
+Follow these steps, and you'll be enjoying seamless control over your Samsung Soundbar with Yassi in no time!
+
+::alert{type="info"}
+The `🔊 Max Volume` setting will readjust the internal values of the `media_player` entity from 0-100 to 0-MaxVolume.
+Therefore will the slider not display the same value as the one provided by the `sensor` entity, which will always display
+the raw value retrieved from the SmartThings API.
+::

docs/content/1.first-things-first/2.issues-and-other-things.md

@@ -0,0 +1,17 @@
+# ‼️ Issues and other things
+
+As the creator of this personal and fun project, I am thrilled to see people using it. While I won’t always have immediate availability to address every request, I’ll do my best to fix issues and implement features. Thanks a lot in advance! 🙌
+
+Here are some best practices to help me help you:
+
+1. 🐞 GitHub Issues: For any issues or bugs, please submit them via GitHub Issues. ([🔗 click here](https://github.com/samuelspagl/ha_samsung_soundbar/issues/new))
+2. 📋 Provide Details: Include essential information:
+    - Home Assistant OS Version
+    - Samsung Soundbar Model
+    - Other Relevant Details (like debug logs)
+3. 🎇 Icons for Fun:
+    - 📦 = Feature Request
+    - 🐛 = Bug Report
+    - ❓ = General Questions
+
+Let’s collaborate to enhance your soundbar experience! 🎶🔊

docs/content/1.getting-started/0.index.md

@@ -1,30 +0,0 @@
-# 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`

docs/content/2.features/0.index.md

@@ -1,35 +1,52 @@
-# Features
+# ✨ Features Overview
 
-**YASSI** and retrieve / set the status of the following features grouped as a device:
+Yassi allows you to retrieve and set the status of various features on your Samsung Soundbar. Below is a breakdown of capabilities organized by entity type.
-- `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`
+## `media_player` Entity
-  - **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`
+| **Feature**       | **Capability** | **Access Type** |
-  - `night_mode` [*read, write*]
+|-------------------|----------------|-----------------|
-  - `voice_amplifier` [*read, write*]
+| Power             | on / off       | Read, Write     |
-  - `bass_mode` [*read, write*]
+| Volume            | set, step      | Read, Write     |
+| Input Selection   | select         | Read, Write     |
+| Sound Mode        | select         | Read, Write     |
+| Playback Control  | play, pause    | Write           |
+| Media Information | artwork, title, artist | Read    |
 
-- `image`
+## `number` Entity
-  - `media_coverart` [*read*]
+
+| **Feature** | **Capability** | **Access Type** |
+|-------------|----------------|-----------------|
+| Woofer Level | set           | Read, Write     |
+
+## `select` Entity
+
+| **Feature**       | **Capability**        | **Access Type** |
+|-------------------|-----------------------|-----------------|
+| Input             | input, supported_inputs | Read, Write   |
+| Sound Mode        | active_soundmode, supported_soundmodes | Read, Write |
+| EQ-Preset         | active_eq_preset, supported_eq_preset | Read, Write |
+
+## `button` Entity
+
+| **Feature**       | **Capability** | **Access Type** |
+|-------------------|----------------|-----------------|
+| Night Mode        | toggle         | Read, Write     |
+| Voice Amplifier   | toggle         | Read, Write     |
+| Bass Mode         | toggle         | Read, Write     |
+
+## `image` Entity
+
+| **Feature**       | **Capability** | **Access Type** |
+|-------------------|----------------|-----------------|
+| Media Cover Art   | display        | Read            |
+
+
+## `sensor` Entity
+
+| **Feature** | **Capability**     | **Access Type** |
+|-------------|--------------------|-----------------|
+| Volume      | float sensor value | Read            |
+
+
+Hopefully this format provides a clear and concise view of what Yassi can do with your Samsung Soundbar, making it easier to understand and configure.