diff --git a/README.md b/README.md index 34975b7..0458cf6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,19 @@ -# HomeAssistant: Samsung Soundbar Integration +# YASSI: Yet Another Samsung Soundbar Integration (for HomeAssistant) -> Yet another Samsung Soundbar Integration (YASSI) +Welcome to YASSI, the HomeAssistant 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,55 @@ 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. +- HomeAssistant 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 HomeAssistant configuration. +2. Restart HomeAssistant. + +> [!NOTE] +> It is planned to add it to the public `HACS` repository list, but not done yet. + +### Configuration + +To integrate your Samsung Soundbar with HomeAssistant using YASSI, you'll need 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 HomeAssistant. +- **Max Volume**: Define the maximum volume level for the `media_player` slider (between `1` and `100`). + +Please use the HomeAssistant UI to setup the integration, providing a yaml configuration in the `configuration.yaml` +should be possible but is not recommended. + +## 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/docs/content/1.getting-started/0.index.md b/docs/content/1.getting-started/0.index.md index 36b0026..b4e3227 100644 --- a/docs/content/1.getting-started/0.index.md +++ b/docs/content/1.getting-started/0.index.md @@ -1,30 +1,42 @@ -# Getting Started +# 🚀 Getting Started with Yassi -## Installation +Welcome to Yassi, the HomeAssistant integration for your Samsung Soundbar. This guide will help you get up and running in no time. -### HACS (official) +## 📦 Installation Options -> ⚠️ Not done yet, hopefully soon. +### 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. -### HACS (custom repository) +#### ➕ Custom Repository +In the meantime, you can manually add this repository to HACS: +1. Navigate to HACS in your HomeAssistant. +2. Go to 'Settings' and add this repository URL as a custom repository. +3. Search for 'Yassi' under integrations and proceed with the installation. -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 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. -### Manual +## ⚙️ Configuration Steps -Copy the contents of `custom_components/samsung_soundbar` to `config/custom_components/samsung_soundbar` -on your HomeAssistant instance. +Once Yassi is installed, you can configure it via the HomeAssistant UI: -## Configuration +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. -After you installed the custom component, it should be possible to configure the integration -in the `device` settings of your HomeAssistant. +Follow these steps, and you'll be enjoying seamless control over your Samsung Soundbar with Yassi in no time! -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 +::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/2.features/0.index.md b/docs/content/2.features/0.index.md index fad8bd0..e12def8 100644 --- a/docs/content/2.features/0.index.md +++ b/docs/content/2.features/0.index.md @@ -1,35 +1,44 @@ -# 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 | + +This table format provides a clear and concise view of what Yassi can do with your Samsung Soundbar, making it easier to understand and configure.