homebridge-aiseg-awning-window-command 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## 0.2.6
+
+- Added Home app screenshots to the README.
+- Changed the README version history from a link-only section to an inline visible history.
+- Kept the v0.2.5 tilt snapping behavior and simplified UI settings.
+
+## 0.2.5
+
+- Improved the snap behavior of the HomeKit tilt slider for AiSEG2 awning windows.
+- Tilt values now snap more firmly to 0°, 15°, 30°, 45°, and 60°.
+- Updated the README and CHANGELOG documentation.
+- Hid internal AiSEG request parameters to simplify the Homebridge UI settings.
+
+### Notes
+
+This plugin is designed and tested for Sankyo Aluminum awning windows connected to AiSEG2.
+
+Normal users only need:
+
+- AiSEG2 IP address or host name
+- AiSEG web password
+- Node ID for each window
+
+Each window's Node ID can be checked on the AiSEG2 web page under **Device Control > Window Sash**.
+Open the browser developer tools with **F12**, go to **Network > Fetch/XHR**, press an action button, open the `operation` request, and check the 9-digit `nodeId` value in the request payload.
+
+## 0.2.4
+
+- Refactored Python scripts to use a shared `aiseg_device.py` core.
+- Kept `aiseg_window.py` as a compatibility wrapper.
+- Continued to bundle package-local Python scripts.
+- Continued to avoid Python `requests` dependency.
+
+## 0.2.3
+
+- Bundled the AiSEG awning Python script inside the npm package.
+- Removed fixed private IP, password, and node ID values from the packaged script.
+- Passed user-specific values from Homebridge config to Python via environment variables.
+- Removed dependency on the external Python `requests` package.
+
+## 0.2.2
+
+- Improved HomeKit awning window behavior.
+- Added better motion guard handling for open, close, and tilt operations.
+- Improved HomeKit display consistency during AiSEG state polling.
+
+## 0.2.1 and earlier
+
+- Early development releases for AiSEG2 awning window control.

package/README.md

@@ -1,62 +1,141 @@
 # homebridge-aiseg-awning-window-command
 
-Homebridge plugin for AiSEG2 awning windows
+Homebridge plugin for AiSEG2-connected awning windows.
 
-## Overview
+This plugin exposes AiSEG2 awning windows as HomeKit `WindowCovering` accessories.
 
-This is a command-based Homebridge platform plugin for AiSEG-controlled devices.
+## Screenshots
 
-The plugin calls external commands for actions and optional status polling.
-It is designed for environments where a separate script can already operate the target AiSEG device.
+<p>
+  <img src="./docs/homekit-tile.jpg" alt="Home app tile view showing the awning window at 50 percent open" width="260">
+  <img src="./docs/homekit-settings.jpg" alt="Home app settings view showing the awning window tilt slider" width="260">
+</p>
 
-## Requirements
+The screenshots show the Home app tile view and the detail view with the horizontal tilt slider.
+
+## Features
+
+- Open / close control from HomeKit
+- HomeKit horizontal tilt angle control
+- Stop switch accessory
+- Status polling from AiSEG2
+- Motion guard to reduce stale-state jumps
+- Strong tilt snapping for HomeKit
+- Package-local Python scripts included
+- No external Python `requests` dependency
+- Shared AiSEG Python core used internally
+
+## Supported HomeKit tilt values
+
+The HomeKit tilt slider is snapped to the following values:
+
+| HomeKit tilt | AiSEG command |
+|---:|---|
+| 0° | close |
+| 15° | angle1 |
+| 30° | angle2 |
+| 45° | angle3 |
+| 60° | open |
+
+Starting from v0.2.5, the plugin more strongly echoes the snapped tilt value back to HomeKit.
+This helps prevent the Home app slider from visually stopping around intermediate values such as 25°.
+
+## Notes
+
+This plugin is designed and tested for Sankyo Aluminum awning windows connected to AiSEG2.
+
+Normal users only need to configure:
+
+- AiSEG2 IP address or host name
+- AiSEG web password
+- Node ID for each window
+
+Internal AiSEG request parameters are hidden from the Homebridge UI because they normally do not need to be changed.
+
+## How to find the Node ID
 
+You can check each window's Node ID from the AiSEG2 web page:
+
+1. Open the AiSEG2 web interface.
+2. Go to **Device Control > Window Sash**.
+3. Open the browser developer tools with **F12**.
+4. Go to the **Network** tab and filter by **Fetch/XHR**.
+5. Press an action button for the target window.
+6. Open the `operation` request.
+7. Check the request payload. The window Node ID is the 9-digit `nodeId` value.
+
+## Tested environment
+
+- AiSEG2
+- Sankyo Aluminum awning windows
+- AiSEG adapter / related Panasonic equipment: MKN7751K
 - Homebridge 2.x
-- Node.js 22 or later
-- Working command or script for device operation
-- Optional status command for state polling
+- Node.js 24.x
 
-## Installation
+## Hidden internal settings
 
-```bash
-npm install -g homebridge-aiseg-awning-window-command
-```
+The following AiSEG request parameters are intentionally hidden from the Homebridge UI:
 
-## Configuration
+- device type
+- page
+- page326
+- track
+- request_by_form
+- acceptId
 
-Use the Homebridge UI to configure this plugin.
+The plugin still uses internal defaults for these values.
 
-Typical settings include:
+## Related plugin
 
-- display name
-- command path
-- open / close / stop / position commands where supported
-- status command
-- polling interval
-- movement guard / transition timing where supported
+For AiSEG3 blind shutters, use:
 
-## Notes
+- `homebridge-aiseg-shutter-command`
+
+## Requirements
+
+- Homebridge
+- Node.js
+- Python 3 available in the Homebridge environment
+
+No additional Python package installation is required.
+
+## Version history
+
+### 0.2.6
+
+- Added screenshots to the README.
+- Changed the README version history from a link-only section to an inline visible history.
+- Kept the v0.2.5 tilt snapping behavior and simplified UI settings.
+
+### 0.2.5
+
+- Improved the snap behavior of the HomeKit tilt slider for AiSEG2 awning windows.
+- Tilt values now snap more firmly to 0°, 15°, 30°, 45°, and 60°.
+- Updated the README and CHANGELOG documentation.
+- Hid internal AiSEG request parameters to simplify the Homebridge UI settings.
+
+### 0.2.4
 
-This plugin does not include AiSEG login or operation scripts.
-Prepare and test the command scripts before configuring Homebridge.
+- Refactored Python scripts to use a shared `aiseg_device.py` core.
+- Kept `aiseg_window.py` as a compatibility wrapper.
+- Continued to bundle package-local Python scripts.
+- Continued to avoid Python `requests` dependency.
 
-A command should be tested manually first, for example:
+### 0.2.3
 
-```bash
-python3 /path/to/script.py target status
-python3 /path/to/script.py target open
-python3 /path/to/script.py target close
-```
+- Bundled the AiSEG awning Python script inside the npm package.
+- Removed fixed private IP, password, and node ID values from the packaged script.
+- Passed user-specific values from Homebridge config to Python via environment variables.
+- Removed dependency on the external Python `requests` package.
 
-## Troubleshooting
+### 0.2.2
 
-If the accessory does not respond:
+- Improved HomeKit awning window behavior.
+- Added better motion guard handling for open, close, and tilt operations.
+- Improved HomeKit display consistency during AiSEG state polling.
 
-1. Run the configured command manually.
-2. Confirm the command path is correct inside the Homebridge environment.
-3. Confirm the Homebridge container has permission to execute the command.
-4. Check Homebridge logs for command timeout or stderr output.
+### 0.2.1 and earlier
 
-## Disclaimer
+- Early development releases for AiSEG2 awning window control.
 
-This project is not affiliated with Apple, Homebridge, Panasonic, or AiSEG.
+See [CHANGELOG.md](./CHANGELOG.md) for the same history in changelog format.

package/config.schema.json

@@ -115,42 +115,6 @@
             "aisegId"
           ]
         }
-      },
-      "deviceType": {
-        "title": "種別",
-        "description": "AiSEG2オーニング窓の種別です。通常は 0x0f です。",
-        "type": "string",
-        "default": "0x0f"
-      },
-      "page": {
-        "title": "Page",
-        "description": "詳細設定です。通常は 1 です。",
-        "type": "string",
-        "default": "1"
-      },
-      "page326": {
-        "title": "Page326",
-        "description": "詳細設定です。通常は 1 です。",
-        "type": "string",
-        "default": "1"
-      },
-      "track": {
-        "title": "Track",
-        "description": "詳細設定です。通常は 326 です。",
-        "type": "string",
-        "default": "326"
-      },
-      "requestByForm": {
-        "title": "Request By Form",
-        "description": "詳細設定です。通常は 1 です。",
-        "type": "string",
-        "default": "1"
-      },
-      "acceptId": {
-        "title": "Accept ID",
-        "description": "詳細設定です。通常は 65550 です。",
-        "type": "string",
-        "default": "65550"
       }
     },
     "required": [

package/index.js

@@ -162,17 +162,52 @@ class AwningWindow {
       .onGet(() => this.positionState);
 
     this.service.getCharacteristic(this.Characteristic.CurrentHorizontalTiltAngle)
-      .setProps({ minValue: 0, maxValue: 60, minStep: 15 })
+      .setProps({ minValue: 0, maxValue: 60, minStep: 15, validValues: [0, 15, 30, 45, 60] })
       .onGet(() => this.currentTilt);
 
     this.service.getCharacteristic(this.Characteristic.TargetHorizontalTiltAngle)
-      .setProps({ minValue: 0, maxValue: 60, minStep: 15 })
+      .setProps({ minValue: 0, maxValue: 60, minStep: 15, validValues: [0, 15, 30, 45, 60] })
       .onGet(() => this.targetTilt)
       .onSet(async (value) => this.setTargetTilt(value));
 
     this.updateHomeKit();
   }
 
+
+  forceTiltSnap(snapped, source, mirrorCurrent) {
+    const v = clamp(Number(snapped), 0, 60);
+
+    this.targetTilt = v;
+
+    const targetChar = this.service.getCharacteristic(this.Characteristic.TargetHorizontalTiltAngle);
+    const currentChar = this.service.getCharacteristic(this.Characteristic.CurrentHorizontalTiltAngle);
+
+    targetChar.updateValue(v);
+
+    if (mirrorCurrent) {
+      this.currentTilt = v;
+      currentChar.updateValue(v);
+    }
+
+    // HomeKit sometimes keeps the raw slider value briefly.
+    // Echo the snapped value several times so 25° etc. returns to 15/30/45/60 cleanly.
+    for (const delay of [100, 350, 900]) {
+      setTimeout(() => {
+        if (this.targetTilt === v || Date.now() < this.motionUntil) {
+          targetChar.updateValue(v);
+
+          if (mirrorCurrent) {
+            currentChar.updateValue(v);
+          }
+
+          if (source && this.lastUnknownStatus === "__never__") {
+            // no-op: keep linter-free structure without extra log noise
+          }
+        }
+      }, delay);
+    }
+  }
+
   async setTargetPosition(value) {
     const raw = clamp(Number(value), 0, 100);
     const normalized = raw <= 50 ? 0 : 100;
@@ -201,14 +236,14 @@ class AwningWindow {
 
     this.log.info(`[${this.name}] TargetHorizontalTiltAngle ${raw} -> ${snapped}`);
 
-    this.targetTilt = snapped;
-    this.service.getCharacteristic(this.Characteristic.TargetHorizontalTiltAngle).updateValue(snapped);
+    this.forceTiltSnap(snapped, "setTargetTilt-start", false);
 
     if (snapped === 0) {
       this.targetPosition = 0;
       this.service.getCharacteristic(this.Characteristic.TargetPosition).updateValue(0);
       this.startMotion("closed", this.motionGuardSeconds, 0);
       await this.runAction("close", "tilt 0 / close");
+      this.forceTiltSnap(0, "tilt-close-done", true);
       return;
     }
 
@@ -217,6 +252,7 @@ class AwningWindow {
       this.service.getCharacteristic(this.Characteristic.TargetPosition).updateValue(100);
       this.startMotion("open", Math.max(this.motionGuardSeconds, this.openAcceptDelaySeconds), 60);
       await this.runAction("open", "tilt 60 / open");
+      this.forceTiltSnap(60, "tilt-open-done", true);
       return;
     }
 
@@ -227,12 +263,15 @@ class AwningWindow {
     if (snapped === 15) {
       this.startMotion("angle1", this.tiltMotionGuardSeconds, 15);
       await this.runAction("angle1", "angle1");
+      this.forceTiltSnap(15, "angle1-done", true);
     } else if (snapped === 30) {
       this.startMotion("angle2", this.tiltMotionGuardSeconds, 30);
       await this.runAction("angle2", "angle2");
+      this.forceTiltSnap(30, "angle2-done", true);
     } else {
       this.startMotion("angle3", this.tiltMotionGuardSeconds, 45);
       await this.runAction("angle3", "angle3");
+      this.forceTiltSnap(45, "angle3-done", true);
     }
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-aiseg-awning-window-command",
-  "version": "0.2.4",
-  "description": "Homebridge plugin for AiSEG2 awning windows",
+  "version": "0.2.6",
+  "description": "Homebridge plugin for AiSEG2 awning windows with HomeKit tilt snapping",
   "main": "index.js",
   "keywords": [
     "homebridge-plugin",
@@ -10,7 +10,13 @@
     "window",
     "homekit",
     "homebridge",
-    "command"
+    "command",
+    "aiseg2",
+    "window-covering",
+    "tilt",
+    "sankyo",
+    "sankyo-aluminum",
+    "panasonic"
   ],
   "engines": {
     "homebridge": ">=1.8.0",
@@ -23,6 +29,10 @@
     "README.md",
     "LICENSE",
     "scripts/aiseg_window.py",
-    "scripts/aiseg_device.py"
-  ]
+    "scripts/aiseg_device.py",
+    "CHANGELOG.md",
+    "docs/homekit-tile.jpg",
+    "docs/homekit-settings.jpg"
+  ],
+  "displayName": "Homebridge AiSEG Awning Window Command"
 }