Enhance documentation (#25)
--------- Co-authored-by: Jorim Tielemans <tielemans.jorim@gmail.com>
This commit is contained in:
Samuel Spagl
GitHub
parent
5e24680d5d
commit
3bcabb8c77
|
|
@ -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
|
||||
|
|
|
|||
91
README.md
91
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
|
||||
- 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.
|
||||
|
||||
[](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.
|
||||
- Like already mentioned, thanks to @PiotrMachowski / @thierryBourbon for the general idea on how to do things.
|
||||
|
|
@ -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"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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! 🎶🔊
|
||||
|
||||
[](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"}
|
||||
::
|
||||
::
|
||||
|
||||
|
||||
## 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... ;)
|
||||
::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.
|
||||
<br>
|
||||
<br>
|
||||
:button-link[click here]{href="/features"}
|
||||
::
|
||||
::
|
||||
|
|
@ -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... ;)
|
||||
|
|
@ -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':
|
||||
[](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.
|
||||
::
|
||||
|
|
@ -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! 🎶🔊
|
||||
|
|
@ -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`
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue