diff --git a/CHANGELOG.md b/CHANGELOG.md index 89b48de..9c8724f 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 34975b7..dde9676 100644 --- a/README.md +++ b/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:** + +* [Why YASSI](#why-yassi) +* [Features](#features) +* [Installation / Setup](#installation--setup) + * [Prerequisites](#prerequisites) + * [Installation:](#installation) + * [Configuration](#configuration) +* [Support](#support) +* [Contributing](#contributing) +* [General Thanks](#general-thanks) + ## 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 - - On / Off - - Volume - - Mute - - Input Source - - Sound Mode - - Media - - 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 +- **UI Setup**: You can easily set up your Soundbar through the UI. +- **Media Player Controls**: Power, volume, mute, source selection, and media controls are all at your fingertips. +- **Selectable Sound Modes**: Choose from various sound modes and inputs for optimal audio. +- **Subwoofer & Equalizer Adjustment**: Fine-tune your audio experience. +- **Switchable Enhancements**: Toggle features like night mode and voice amplification. +- **Customizable Bass Level**: Set the bass to your preference. +- **Multiple Devices**: should be theoretically possible but **not** tested -## 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: -> ⚠️ not done yet but planned (hopefully) +## Installation / Setup -### 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 -your `config/custom_components` folder. +### Installation +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 -idea on how to do things. \ No newline at end of file +- Like already mentioned, thanks to @PiotrMachowski / @thierryBourbon for the general idea on how to do things. \ No newline at end of file diff --git a/custom_components/samsung_soundbar/manifest.json b/custom_components/samsung_soundbar/manifest.json index df644b0..b3363ff 100644 --- a/custom_components/samsung_soundbar/manifest.json +++ b/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" } diff --git a/docs/app.config.ts b/docs/app.config.ts index bd0c510..251d94d 100644 --- a/docs/app.config.ts +++ b/docs/app.config.ts @@ -1,7 +1,7 @@ export default defineAppConfig({ docus: { - title: 'YASSI', - description: 'HomeAssistant: Yet another Samsung soundbar integration', + title: 'πŸ”Š Yassi', + 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 diff --git a/docs/content/0.index.md b/docs/content/0.index.md index a10eb2b..b933845 100644 --- a/docs/content/0.index.md +++ b/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 -snippet: - - Custom Components - - "- input selection" - - "- soundmode selection" - - "- eq-preset selection" - - "- woofer settings" - - "- other cool things" + - https://github.com/samuelspagl/ha_samsung_soundbar --- #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 ;).

- :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". +
+
+ :button-link[click here]{href="/first-things-first/getting-started"} + :: + + ::card + #title + ✨ Features #description Many cool features are awaiting your eyes to see ✨.

: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... ;) \ No newline at end of file + ::card + #title + βš™οΈ SmartThings API related information + #description + If you want to know some background information on how equalizer support and + other things were implemented, this is your section. +
+
+ :button-link[click here]{href="/features"} + :: +:: \ No newline at end of file diff --git a/docs/content/1.first-things-first/0.why-another-integration.md b/docs/content/1.first-things-first/0.why-another-integration.md new file mode 100644 index 0000000..56188b0 --- /dev/null +++ b/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... ;) \ No newline at end of file diff --git a/docs/content/1.first-things-first/1.getting-started.md b/docs/content/1.first-things-first/1.getting-started.md new file mode 100644 index 0000000..9aa28e6 --- /dev/null +++ b/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. +:: \ No newline at end of file diff --git a/docs/content/1.first-things-first/2.issues-and-other-things.md b/docs/content/1.first-things-first/2.issues-and-other-things.md new file mode 100644 index 0000000..50b5b9f --- /dev/null +++ b/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! πŸŽΆπŸ”Š \ No newline at end of file diff --git a/docs/content/1.getting-started/0.index.md b/docs/content/1.getting-started/0.index.md deleted file mode 100644 index 36b0026..0000000 --- a/docs/content/1.getting-started/0.index.md +++ /dev/null @@ -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` \ No newline at end of file diff --git a/docs/content/2.features/0.index.md b/docs/content/2.features/0.index.md index fad8bd0..e0f6099 100644 --- a/docs/content/2.features/0.index.md +++ b/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: -- `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*] +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. -- `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*] +## `media_player` Entity -- `button` - - `night_mode` [*read, write*] - - `voice_amplifier` [*read, write*] - - `bass_mode` [*read, write*] +| **Feature** | **Capability** | **Access Type** | +|-------------------|----------------|-----------------| +| Power | on / off | 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` - - `media_coverart` [*read*] +## `number` Entity + +| **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.