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
|
||||
|
||||
|
|
@ -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.
|
||||
- Like already mentioned, thanks to @PiotrMachowski / @thierryBourbon for the general 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.
|
||||
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`
|
||||
::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.
|
||||
::
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue