Merge branch 'main' into fix/division-by-zero
# Conflicts: # CHANGELOG.md # custom_components/samsung_soundbar/manifest.json
This commit is contained in:
commit
c121747470
|
@ -8,6 +8,12 @@
|
||||||
greater than `1` and lower than `100`. This will make sure that a division by zero cannot happen.
|
greater than `1` and lower than `100`. This will make sure that a division by zero cannot happen.
|
||||||
- Add default value `100` to `CONF_ENTRY_MAX_VOLUME`
|
- Add default value `100` to `CONF_ENTRY_MAX_VOLUME`
|
||||||
|
|
||||||
|
## [0.3.1] Documentation enhancements
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
|
||||||
|
- Updated the `README` as well as the documentation website
|
||||||
|
|
||||||
## [0.3.0] Icons and Chore
|
## [0.3.0] Icons and Chore
|
||||||
|
|
||||||
### Added
|
### 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
|
## Why YASSI
|
||||||
|
|
||||||
|
@ -18,48 +31,54 @@ 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.
|
||||||
|
- 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
|
### 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 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
|
## 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,7 +1,7 @@
|
||||||
export default defineAppConfig({
|
export default defineAppConfig({
|
||||||
docus: {
|
docus: {
|
||||||
title: 'YASSI',
|
title: '🔊 Yassi',
|
||||||
description: 'HomeAssistant: Yet another Samsung soundbar integration',
|
description: 'Yet another Samsung Soundbar integration for Home Assistant',
|
||||||
image: 'https://user-images.githubusercontent.com/904724/185365452-87b7ca7b-6030-4813-a2db-5e65c785bf88.png',
|
image: 'https://user-images.githubusercontent.com/904724/185365452-87b7ca7b-6030-4813-a2db-5e65c785bf88.png',
|
||||||
socials: {
|
socials: {
|
||||||
github: 'samuelspagl/ha_samsung_soundbar',
|
github: 'samuelspagl/ha_samsung_soundbar',
|
||||||
|
@ -28,7 +28,7 @@ export default defineAppConfig({
|
||||||
fluid: true
|
fluid: true
|
||||||
},
|
},
|
||||||
header: {
|
header: {
|
||||||
logo: true,
|
logo: false,
|
||||||
showLinkIcon: true,
|
showLinkIcon: true,
|
||||||
exclude: [],
|
exclude: [],
|
||||||
fluid: true
|
fluid: true
|
||||||
|
|
|
@ -5,24 +5,19 @@ title: "YASSI"
|
||||||
---
|
---
|
||||||
cta:
|
cta:
|
||||||
- Why another HomeAssistant integration?
|
- Why another HomeAssistant integration?
|
||||||
- #why-another-integration
|
- /first-things-first/why-another-integration
|
||||||
secondary:
|
secondary:
|
||||||
- Open on GitHub →
|
- Open on GitHub →
|
||||||
- https://github.com/nuxtlabs/docus
|
- https://github.com/samuelspagl/ha_samsung_soundbar
|
||||||
snippet:
|
|
||||||
- Custom Components
|
|
||||||
- "- input selection"
|
|
||||||
- "- soundmode selection"
|
|
||||||
- "- eq-preset selection"
|
|
||||||
- "- woofer settings"
|
|
||||||
- "- other cool things"
|
|
||||||
---
|
---
|
||||||
|
|
||||||
#title
|
#title
|
||||||
Yassi
|
Yassi - Yet another Samsung Soundbar integration
|
||||||
|
|
||||||
#description
|
#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
|
::card-grid
|
||||||
|
@ -34,36 +29,42 @@ Quick-Start
|
||||||
#default
|
#default
|
||||||
::card
|
::card
|
||||||
#title
|
#title
|
||||||
Getting Started.
|
❓ Why another integration?
|
||||||
#description
|
#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>
|
||||||
<br>
|
<br>
|
||||||
:button-link[click here]{href="/getting-started"}
|
:button-link[click here]{href="/first-things-first/why-another-integration"}
|
||||||
::
|
::
|
||||||
|
|
||||||
::card
|
::card
|
||||||
#title
|
#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
|
#description
|
||||||
Many cool features are awaiting your eyes to see ✨.
|
Many cool features are awaiting your eyes to see ✨.
|
||||||
<br>
|
<br>
|
||||||
<br>
|
<br>
|
||||||
:button-link[click here]{href="/features"}
|
:button-link[click here]{href="/features"}
|
||||||
::
|
::
|
||||||
|
|
||||||
|
::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"}
|
||||||
|
::
|
||||||
::
|
::
|
||||||
|
|
||||||
|
|
||||||
## 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,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:
|
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 |
|
||||||
|
|
||||||
|
|
||||||
|
## `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