homebridge-aiseg-awning-window-command

Homebridge plugin for AiSEG2-connected awning windows.

This plugin exposes AiSEG2 awning windows as HomeKit WindowCovering accessories.

Screenshots

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 24.x

Hidden internal settings

The following AiSEG request parameters are intentionally hidden from the Homebridge UI:

• device type
• page
• page326
• track
• request_by_form
• acceptId

The plugin still uses internal defaults for these values.

Related plugin

For AiSEG3 blind shutters, use:

• homebridge-aiseg-shutter-command

Requirements

• Homebridge
• Node.js
• Python 3 available in the Homebridge environment

No additional Python package installation is required.

About HomeKit slider operation and 50% display

This plugin does not support arbitrary intermediate position control using the HomeKit position slider.

The HomeKit slider is treated as an open / close control only. Setting the slider to a value other than 0% or 100% does not move the actual device to an exact intermediate position.

To avoid confusion, when the actual AiSEG device state is detected as vent, half, tilt, or any other partially-open state, the plugin displays the accessory as 50% open in HomeKit.

The 50% value does not mean that the device is physically opened to exactly 50%. It is only a display value used to represent a partially-open state in HomeKit.

Display mapping:

• closed: 0%
• open: 100%
• vent / half / tilt / partially-open state: 50%

In other words, any state other than fully closed or fully open is displayed as a partially-open state at 50%.

Note for AiSEG2 awning windows

For AiSEG2 awning windows, the HomeKit position slider does not provide arbitrary intermediate position control.

Slider operation is handled as open / close control only. Ventilation, half-open, tilt, or angled states are displayed as 50% in HomeKit.

The 50% display does not represent the exact physical opening position. It is only used to show that the window is in a partially-open state.

Version History

0.3.2

• Cleaned up the README so the version history appears in a single consolidated section.
• No functional changes.

0.3.1

• Added README notes about HomeKit slider behavior and the 50% display policy.
• Added Version History information.

0.3.0

• Added startup display correction for partially-open AiSEG2 awning window states.
• When the actual device state is detected as vent, half, tilt, or another partially-open state, HomeKit displays the window as 50% open.
• Clarified that the HomeKit position slider is treated as open / close control only.
• Clarified that the 50% display is not an exact physical opening position, but a HomeKit display value for partially-open states.
• Improved schema labels and descriptions for easier Homebridge UI configuration.

0.2.8

• Improved HomeKit Scene and Shortcut behavior for tilt commands.
• Ignores short-lived TargetPosition echoes from HomeKit immediately after a tilt command.
• Prevents HomeKit from converting a tilt command into an unintended close command.
• This improves Siri, Scene, and Shortcut reliability for ventilation tilt operation.

0.2.7

• Fixed screenshot image links on the npm README page by using absolute unpkg URLs.
• No functional changes.

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

• 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.
• See CHANGELOG.md for the same history in changelog format.