From 1903b6fb6bedfe65ddf4c4458836611520b93910 Mon Sep 17 00:00:00 2001
From: Sven Naumann <3747263+sVnsation@users.noreply.github.com>
Date: Fri, 27 Dec 2024 08:42:26 +0100
Subject: [PATCH] twinkly explain operation modes

---
 source/_integrations/twinkly.markdown | 42 +++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/source/_integrations/twinkly.markdown b/source/_integrations/twinkly.markdown
index 9fa2cd95a1b4..791e01ba9f12 100644
--- a/source/_integrations/twinkly.markdown
+++ b/source/_integrations/twinkly.markdown
@@ -20,6 +20,14 @@ ha_integration_type: integration
 
 The Twinkly integration allows you to control [Twinkly](https://twinkly.com/) LED string from Home Assistant.
 
+This integration can be used to:
+- Turn your Twinklys on and off
+- Adjust brightness
+- Control static colors and effects
+- Switch between operation modes (see explanation below)
+
+Music mode is currently not supported.
+
 ## Effects
 
 For devices with software version > 2.7.1, you can also control the effects on your Twinklys.
@@ -27,9 +35,39 @@ For devices with software version > 2.7.1, you can also control the effects on y
 The Twinkly devices do not initially have any effects stored locally. Effects must be added from the Twinkly application before they become visible in Home Assistant.
 
 Make sure the latest firmware is installed on your Twinkly devices and add effects by _apply_-ing them from the Twinkly app.
-This integration can then be used to switch between static colors and effects, and to turn your Twinklys on and off.  
 
-Playlists and Music modes are currently not supported.
+## Operation Modes
+
+Modes can be switched using the select entity. 
+
+For most use cases, "Color", "Movie" and "Playlist" modes are the most relevant.
+
+**Color Mode**
+- Displays a static color
+- Controlled through the light entity
+- Color can be set via RGB/RGBW
+
+**Movie Mode**
+- Plays effects previously uploaded through the Twinkly app
+- Effects must be created and transferred to the device first using the app
+- Effect selection is done through the light entity
+
+**Playlist Mode**
+- Sequential playback of multiple effects
+- Playlist must be uploaded through the Twinkly app first
+
+**Off Mode**
+- Turns off the lighting
+
+**Demo Mode**
+- Shows predefined demo effects
+- Primarily intended for presentation purposes
+- Limited practical use
+
+**Unsupported Modes:**
+- Effect Mode: predefined effects built into the device, you are probably better off using Movie Mode
+- RT (Real-Time): Live control of individual LEDs
+- Music: Music-controlled light show
 
 {% include integrations/config_flow.md %}