Enhance documentation
This commit is contained in:
samuelspagl
parent
5e24680d5d
commit
bd86e799e1
92
README.md
92
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:**
|
||||||
|
<!-- 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
|
## Why YASSI
|
||||||
|
|
||||||
|
|
@ -18,48 +31,55 @@ are not documented... ;)
|
||||||
|
|
||||||
## Features
|
## 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.
|
||||||
|
- 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
|
### 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 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
|
## 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.
|
|
||||||
|
|
@ -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.
|
### 📂 Manual Installation
|
||||||
After you've done that, you can search for it like with the "official"
|
If you prefer to install Yassi manually:
|
||||||
integrations.
|
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`
|
Once Yassi is installed, you can configure it via the HomeAssistant UI:
|
||||||
on your HomeAssistant instance.
|
|
||||||
|
|
||||||
## 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
|
Follow these steps, and you'll be enjoying seamless control over your Samsung Soundbar with Yassi in no time!
|
||||||
in the `device` settings of your HomeAssistant.
|
|
||||||
|
|
||||||
You will need:
|
::alert{type="info"}
|
||||||
- a SmartThings `api_key` [click here](https://account.smartthings.com/tokens)
|
The `🔊 Max Volume` setting will readjust the internal values of the `media_player` entity from 0-100 to 0-MaxVolume.
|
||||||
- the `device_id` of your device [click here](https://my.smartthings.com/advanced/devices)
|
Therefore will the slider not display the same value as the one provided by the `sensor` entity, which will always display
|
||||||
- a name for your Soundbar
|
the raw value retrieved from the SmartThings API.
|
||||||
- and a `max_volume`
|
::
|
||||||
|
|
@ -1,35 +1,44 @@
|
||||||
# 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 |
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue