Clear stuck motion state for IGNORE-position devices and skip heartbeat polling during travel

[mnaggatz]

Background

After PR #665 (preserve movement state during executing frames with unavailable
positions), is_opening / is_closing can get stuck on True for actuators
whose position frames stay at IGNORE for most of their travel — typically
gates and some garage doors. The session ends only via
FrameCommandRunStatusNotification (CRSN), which the NodeUpdater previously
did not consider as a motion terminator. Downstream consumers (Home Assistant
cover entities) then remained in opening/closing until the next polled
status sweep, sometimes for a full heartbeat period.

A second, independent issue: the heartbeat sweep calls StatusRequest on
every node — including nodes currently executing a command. This can make the
gateway report the active command as completed prematurely (occasionally with
status_reply = COMMAND_OVERRULED) and on some actuators it can interrupt the
motion. Downstream consumers cannot tell that completion apart from a genuine
end-of-travel completion.

What this PR changes

Four small, complementary fixes:

1. node_updater._update_opening_device_status — escape from the preserve
   branch when the cached position has reached the open/closed extreme matching
   the target. Defensive cleanup so a repeated EXECUTING frame at the extreme
   cannot trap motion state.
2. node_updater._process_command_run_status_notification — treat
   run_status ∈ {EXECUTION_COMPLETED, EXECUTION_FAILED} as the
   authoritative end-of-command marker for OpeningDevices. Clear
   is_opening/is_closing and reset state_received_at /
   estimated_completion.
3. Position sync — only on a clean completion: when run_status = EXECUTION_COMPLETED and status_reply = COMMAND_COMPLETED_OK,
   additionally sync the cached position so consumers don't briefly see a
   stale pre-move value between motion-clear and the next house-monitoring
   frame. The sync source is the CRSN payload's main-parameter value
   (frame.parameter_value when node_parameter == NodeParameter.MP and
   the raw value passes Parameter.is_valid_int + is concrete), with
   node.target as fallback. Other status_reply values (e.g.
   COMMAND_OVERRULED) and EXECUTION_FAILED leave the position untouched,
   because the run was pre-empted or failed before reaching the target.
4. heartbeat.pulse — skip StatusRequest for any OpeningDevice whose
   is_opening or is_closing is set. House Monitoring delivers in-flight
   position updates anyway, so the sweep adds no value during motion and only
   risks the side effects above.

Tests:

• New tests covering motion-clear + position sync paths for COMPLETED_OK
  (from CRSN payload), COMPLETED_OK with non-concrete payload (fallback to
  node.target), COMPLETED_OK with an out-of-range payload (defensive
  fallback), OVERRULED (motion clears, position stays), and FAILED (motion
  clears, position stays).
• New test that the heartbeat skips moving OpeningDevices.
• Existing live-sequence tests
  (test_gate_opening_live_sequence_keeps_direction_until_done and the
  closing counterpart) updated to reflect the new contract: motion is
  cleared at CRSN COMPLETED_OK with a concrete MP payload (matching what
  live traces show real gateways send at clean session end), and the
  subsequent state=DONE frame confirms the final state.

make ci is green (498 tests; mypy / pylint / pydocstyle / flake8 / isort
clean).

Trace-based context

To validate the fix in the wild, I ran a single-pass test against my live
gateway, cycling every OpeningDevice through open → close → open (or
open → close for gate/garage). The traces and the throw-away driver script
are local artifacts and are not part of this PR; the conclusions are
summarised below.

What the traces show about the gateway's behaviour:

• Initial state on connect is unreliable. After load_nodes() many
  OpeningDevices first show up with position=UNKNOWN target=UNKNOWN.
  Concrete values arrive later via House-Monitoring frames. Consumers
  must not act on the initial snapshot as if it were authoritative.

• state = OperatingState.UNKNOWN does NOT imply unusable position.
  The gateway emits a steady stream of passive frames such as
  state=OperatingState.UNKNOWN current=0 % target=0 % for idle nodes.
  Position is typically concrete and correct. State and position have
  to be evaluated independently.

• Gates and garage doors differ structurally. The garage door emits
  concrete intermediate positions during travel (17 %, 3 %, 0 %). The
  gate emits current_position = IGNORE for almost the entire travel;
  only target stays concrete. The cached-position / cached-target
  fallback from Preserve movement state during executing frames with unavailable positions #665 is the only way to derive direction during that
  IGNORE phase.

• remaining_time is not a reliable countdown. On the gate
  remaining=3 stayed pinned at the same value across many frames; on
  the garage door several remaining=0 frames arrived before the
  actual session-end. Using remaining_time only as an "is in motion"
  hint, not as a timer, is the right call.

• CRSN is the authoritative end-of-command marker.
  FrameCommandRunStatusNotification (run_status=EXECUTION_COMPLETED, status_reply=COMMAND_COMPLETED_OK) arrived reliably at clean session
  end, either just before or together with the final state=DONE
  position frame, and carried the final main-parameter value in its
  payload. For gate-style devices that stay at IGNORE until the end
  this is the only robust completion signal — which is why fix (2)
  ties motion-clear into the CRSN path, and fix (3) prefers the CRSN
  payload over the cached node.target.

• The KLF200 is sensitive to long/aggressive polling. During a
  long marathon trace the first ~12 devices completed cleanly;
  afterwards the gateway dropped the TCP socket and refused new
  connections ([Errno 61] Connect call failed). This PR does not
  claim to fix that, but it does reduce avoidable StatusRequest
  pressure against devices that are already busy.

Caveats on the trace evidence

• The trace driver uses PyVLX(..., heartbeat_interval=3600), so the
  successful gate cycles (≈ 39 s / 47 s) ran with the regular 30 s
  heartbeat effectively suppressed. The traces therefore confirm the
  conditions under which mid-motion polling is risky (long travel,
  long IGNORE phase, CRSN as only end marker), but they are not a
  direct A/B demonstration of fix (4).
• The garage door CRSN test path is visible in the traces: at
  EXECUTION_COMPLETED the cached position and motion flags update in
  the same tick, and the following state=DONE frame confirms the
  same final state.

Why a 0.2.35 release matters

The currently released pyvlx 0.2.33 does not have this regression
yet — it was introduced together with PR #665 ("Preserve movement
state during executing frames with unavailable positions") and is in
pyvlx 0.2.34. Home Assistant's stable velux integration still
pins pyvlx == 0.2.33; the Home Assistant dev branch already moved
its pin to pyvlx == 0.2.34. The next Home Assistant stable release
cut from dev will therefore ship the regression to the broader user
base unless a fixed pyvlx release replaces the pin first.

User-visible symptoms on IGNORE-position actuators (gates, certain
garage doors) with pyvlx 0.2.34:

• Cover entities stay in opening / closing after the actuator has
  physically reached its end position, until the next heartbeat sweep
  (~30 s) or a fresh user command resets the state. Automations keyed
  on is_closed therefore see a wrong terminal state for that
  window.
• Heartbeat-driven StatusRequest calls during an active motion can
  prematurely complete the running command — on some actuators the
  gateway additionally interrupts the motion mid-travel.

The device remains controllable in all these cases (a new command
resets the state via the usual paths), but the displayed state and
any state-driven automation logic are wrong in the meantime. Cutting
a 0.2.35 with this fix before Home Assistant freezes its next
release would avoid the regression hitting users at all.

Test plan

• make ci green on this branch.
• Live-tested on a private installation: gate (long travel, IGNORE),
  garage door (mixed concrete + IGNORE), Velux roof window
  (concrete throughout), and several roller shutters. All went
  through opening → open / closing → closed cleanly without
  sticking or briefly flipping to the wrong end-state.
• Live-cycled every OpeningDevice via the trace driver in one pass
  (see traces above) — same outcome.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
src/pyvlx
heartbeat.py
node_updater.py
Project Total

This report was generated by python-coverage-comment-action