From cf96297a9bc33a3764fc2f2bd6670d217e5ccb58 Mon Sep 17 00:00:00 2001
From: Mattias Holmlund <mattias@holmlund.se>
Date: Thu, 21 May 2026 22:04:28 +0200
Subject: [PATCH] docs: document blinds API based on real-device testing

- Remove "Not tested, feedback required." notice
- Document blindsTargetLevel scale (0 = fully up, 100 = fully down)
- Document setState behavior (stops automatically at level 0 or 100)
- Add inline comments on get response attributes
- Note that setCurrentLevel is not supported by the hub

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 1a7429d..dd27f5a 100644
--- a/README.md
+++ b/README.md
@@ -205,31 +205,35 @@ await client.airPurifiers.setStatusLight({
 
 #### [Blinds](./src/api/blinds.ts)
 
-Not tested, feedback required.
-
 ```typescript
 const blinds = await client.blinds.list()
 
 const blind = await client.blinds.get({
   id: 'YOUR_DEVICE_ID',
 })
+// blind.attributes.blindsCurrentLevel — where the blind currently is (0–100)
+// blind.attributes.blindsTargetLevel  — where the blind is heading (0–100)
+// blind.attributes.blindsState        — 'stopped' | 'up' | 'down'
+// blind.attributes.batteryPercentage  — battery level of the blind motor
 
-await client.blinds.setCurrentLevel({
-  id: 'YOUR_DEVICE_ID',
-  blindsCurrentLevel: 0,
-})
-
+// Move the blind to a specific level and stop there.
+// 0 = fully up (open), 50 = halfway down, 100 = fully down (closed).
 await client.blinds.setTargetLevel({
   id: 'YOUR_DEVICE_ID',
-  blindsTargetLevel: 60,
+  blindsTargetLevel: 50,
 })
 
+// Start moving the blind continuously up or down, or stop it.
+// The blind stops automatically and sets its state to 'stopped'
+// when it reaches level 0 (fully up) or 100 (fully down).
 await client.blinds.setState({
   id: 'YOUR_DEVICE_ID',
-  blindsState: 'stopped', // 'stopped' | 'up' | 'down'
+  blindsState: 'up', // 'stopped' | 'up' | 'down'
 })
 ```
 
+> **Note:** `setCurrentLevel` is not supported by the hub and returns an API error.
+
 #### [Controllers](./src/api/controllers.ts)
 
 Some controllers, such as the BILRESA remote appear as multiple devices.