homebridge-aiseg-shutter-command

Homebridge plugin for AiSEG-connected shutters.

This plugin exposes AiSEG shutters as HomeKit WindowCovering accessories. It is designed for shutters controlled through the Panasonic AiSEG web interface.

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 AiSEG
• 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 follows the configured tilt preset.

Three-step mode

| HomeKit tilt | Meaning | |---:|---| | 0° | closed tilt | | 30° | middle tilt | | 60° | high tilt | | 90° | open tilt |

Six-step mode

| HomeKit tilt | Meaning | |---:|---| | 0° | closed tilt | | 15° | angle1 | | 30° | angle2 | | 45° | angle3 | | 60° | angle4 | | 75° | angle5 | | 90° | angle6 |

Starting from v0.1.12, the plugin more strongly echoes the snapped tilt value back to HomeKit. This helps prevent the Home app slider from visually sticking to unwanted intermediate values.

Notes

This plugin is designed and tested for Sanwa Shutter shutters connected to AiSEG2/3 with a HEMS-compatible operation unit HEM-800B.

Tested environment includes:

• Sanwa Shutter shutters
• AiSEG2/3 web control
• HEMS-compatible operation unit HEM-800B
• AiSEG adapter / related Panasonic equipment: MKN7751K

Normal users only need to configure:

• AiSEG IP address or host name
• AiSEG web password
• Node ID for each shutter

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 shutter's Node ID from the AiSEG web page:

1. Open the AiSEG web interface.
2. Go to Device Control > Shutter.
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 shutter.
6. Open the operation request.
7. Check the request payload. The shutter Node ID is the 9-digit nodeId value.

Hidden internal settings

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

• device ID
• EOJ
• device type
• page
• page325
• track
• request_by_form
• acceptId

The plugin still uses internal defaults for these values.

Related plugin

For AiSEG2 awning windows, use:

• homebridge-aiseg-awning-window-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 AiSEG3 shutters

For AiSEG3 shutters, the HomeKit position slider does not provide arbitrary intermediate position control.

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

If you want to control the tilt angle, use the tilt control or the dedicated tilt operation instead of relying on the position slider.

Version History

0.2.2

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

0.2.1

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

0.2.0

• Added startup display correction for partially-open AiSEG3 shutter states.
• When the actual device state is detected as vent, half, tilt, or another partially-open state, HomeKit displays the shutter as 50% open.
• Fixed the HomeKit startup display so partially-open shutter states are shown as 50% position with 30° tilt.
• Clarified that the HomeKit position slider is treated as open / close control only.
• Clarified that the 50% display is not an exact physical position, but a HomeKit display value for partially-open states.
• Removed confusing initial position / initial tilt display configuration from the intended setup flow.
• Improved schema labels and descriptions for easier Homebridge UI configuration.

0.1.14

• Improved HomeKit Scene and Shortcut behavior for blind shutter tilt commands.
• Ignores short-lived TargetPosition 0 echoes from HomeKit immediately after a tilt command.
• Prevents HomeKit from converting a tilt command into an unintended close command.
• Keeps normal open and close operations unchanged outside the short guard window.

0.1.13

• Re-published the v0.1.12 improvements under a new npm version because npm versions cannot be overwritten.
• Kept the HomeKit tilt snapping improvement.
• Kept README screenshots, inline version history, CHANGELOG, and simplified Homebridge UI settings.

0.1.12

• Improved the snap behavior of the HomeKit tilt slider for AiSEG2/3 shutters.
• Tilt values now snap more firmly to the configured tilt preset.
• Updated the README and CHANGELOG documentation.
• Added Home app screenshots to the README.
• Hid internal AiSEG request parameters to simplify the Homebridge UI settings.

0.1.11

• Refactored Python scripts to use a shared aiseg_device.py core.
• Kept aiseg_shutter.py as a compatibility wrapper.
• Continued to bundle package-local Python scripts.
• Continued to avoid Python requests dependency.

0.1.10

• Bundled the AiSEG shutter Python script inside the npm package.
• Removed fixed private IP 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.1.9 and earlier

• Early development releases for AiSEG shutter control.
• Improved direct AiSEG status polling and HomeKit display stability.
• See CHANGELOG.md for the same history in changelog format.