warema-wms-jog — drive WAREMA WMS blinds/awnings from a USB stick that "won't move" them

If you control WAREMA WMS blinds with the WMS USB stick (via the santam85/addon-warema-wms Home Assistant add-on, the Marc-Berg/wms2mqtt fork, or the warema-wms-venetian-blinds npm library) and you've hit the wall where the stick reads positions fine but the blind never moves — this is for you. You do not need the ~€200 WMS WebControl pro.

The problem (sound familiar?)

People keep reporting the same thing:

• the add-on discovers the device, position shows up in Home Assistant, but open/close does nothing — the log just shows wmsRetry blindMoveToPos → wmsTimeout;
• it's usually blamed on USB3 RF interference or weak range — and sometimes that's real —
• but on many installs reads work perfectly while only commands are ignored, which is not a range problem.

The cause on those installs is the command, not radio and not authorization. The stick's absolute move-to-position (blindMoveToPos, 7070 03) is protocol-ACKed (7071…) but the motor never moves. This shows up especially on awnings, which generally have no intermediate positioning the way venetian blinds do — the actuator simply doesn't act on a go-to-position command.

Not an authorization/enrollment problem (an earlier version of this README claimed that — it was wrong). The network-key transfer already authorizes the stick: it reads positions and jog drives the motor. Jog (7070 06/07) and absolute (7070 03) are the same stick → same actuator → same auth context; only the subcommand differs. If the stick were an unauthorized transmitter, jog wouldn't work either. So the stick is authorized — this awning actuator just doesn't execute absolute positioning. (For venetian blinds, blindMoveToPos does work over the same stick — that's the library's normal path.)

The fix: drive by JOG (hold-to-run)

When absolute moves no-op, the motor's jog / hold-to-run command — the basic up/down the calibration tools stream while you hold a direction — drives it:

It's dead-man: the motor runs only while frames keep arriving (~5–7 Hz), and an explicit stop frame halts it. Stream 06/07 to drive, poll position, send 01 to stop — and a read-only stick becomes a fully drivable one. Verified 2026-06 on a WMS-MM balcony awning whose absolute moves no-op'd; jog drove it cleanly in both directions (confirmed by position read-back and by eye). See docs/PROTOCOL.md for the byte-level evidence.

⚠️ Safety — read before you drive

Jog has no soft-limit enforcement. In particular the extend / "open" direction of an awning may have NO hard stop — keep streaming and the fabric runs off the end. The retract / "close" direction usually has a hard mechanical stop at fully-closed.

• Never run-to-limit on the extend side. Bound every open by time AND/OR position, poll the position mid-travel, and stop in time.
• If your end positions were ever mis-taught (e.g. a botched calibration), redo them on the handheld first.
• Test from a known position, watch the blind, keep a panic-stop ready (warema-wms-jog --stop-only).

Two ways to use it

Install from PyPI:

pip install warema-wms-jog

It ships two console commands: warema-wms-cover (the HA cover service) and warema-wms-jog (the CLI primitive). The modules are also importable as warema_wms_cover and warema_wms_jog.

1. Home Assistant cover (recommended — battle-tested)

warema-wms-cover (module warema_wms_cover) is a self-contained service that owns the stick's serial port, publishes an MQTT-discovery cover to Home Assistant, and maps open / close / stop and a position slider to bounded jog runs. It drives toward the target, polls position live, and stops with coast-anticipation so it lands on target — with a hard position cap on the extend side so it can never run past your calibrated full-extend. It also polls while idle so moves from your handheld remote are tracked, and emits a remote_move event you can use as a manual-override trigger.

pip install warema-wms-jog
WMS_KEY=<your-network-key> WMS_SNR=<device-serial> \
MQTT_HOST=<broker> MQTT_USER=<u> MQTT_PASSWORD=<p> \
MAX_OPEN_RAW=<your-full-extend-raw> \
warema-wms-cover

Docker (e.g. as a Home Assistant compose service driving the stick):

  warema:
    image: python:3-slim
    devices: ["/dev/ttyUSB0:/dev/ttyUSB0"]
    command: ["sh", "-c", "pip install -q warema-wms-jog && exec warema-wms-cover"]
    environment:
      - WMS_KEY=${WMS_KEY}
      - WMS_SNR=<device-serial>
      - MQTT_HOST=<broker>
      - MAX_OPEN_RAW=<your-full-extend-raw>

The stick's serial port must be free (stop the stock add-on/bridge first if it holds it). All knobs are env vars — see the docstring at the top of warema_wms_cover.py (WMS_PORT, WMS_BAUD, WMS_CHAN, WMS_PAN, MAX_OPEN_RAW, OPEN_SECS, POS_LEAD, …). Find your full-extend raw value with the CLI tool below (--getpos-only) at the fully-open position.

Radio self-heal (0.1.1). The stick's WMS session ({G} / {M#} / {K}) can be lost while the serial port stays open — no error, no exception, nothing in dmesg. Every position read then returns nothing and every drive aborts with no position read, so the cover silently stops moving. The bridge now replays the handshake itself after REINIT_AFTER (default 5) consecutive failed reads, escalating to a serial-port reopen if replays don't take, and publishes availability = offline while the radio is down — so a dead stick shows up in HA as an unavailable cover instead of one that just quietly ignores you. Tune with REINIT_AFTER / REINIT_MIN_GAP (default 30 s between attempts).

2. CLI primitive / proof tool

warema-wms-jog (module warema_wms_jog) is a minimal injector to validate jog on your hardware before wiring anything: it sends the network preamble, reads position, streams a bounded jog burst, then stops.

pip install warema-wms-jog
# just read position (find your full-extend raw):
WMS_KEY=<key> warema-wms-jog --snr <serial> --getpos-only
# jog ~1s in one direction (watch it move!), then auto-stop:
WMS_KEY=<key> warema-wms-jog --snr <serial> --code 07 --ms 1000
# panic stop:
WMS_KEY=<key> warema-wms-jog --snr <serial> --stop-only

3. Patch for the node add-on/library

patches/addon-warema-wms-jog.patch adds the jog primitive (blindJog encoder + vnBlindJogStart/vnBlindJogStop) to the vendored warema-wms-venetian-blinds library inside the add-on, as a non-breaking addition. See patches/README.md. Upstreamed as a PR to Marc-Berg/wms2mqtt.

Where to find your network key / serial / PAN / channel

These come from your existing add-on setup — the add-on logs print wms_key, wms_pan_id and wms_channel on first run after the handheld transfers network access data. Never commit your network key — these tools read it only from the WMS_KEY env var (or, for the warema-wms-jog CLI, from a capture trace), and redact it from any echo.

Credit

Built on the reverse-engineering in warema-wms-venetian-blinds by aemm (MIT) and the santam85/addon-warema-wms Home Assistant add-on by Marco Santarelli. The jog discovery + drivers here are MIT-licensed.

License

MIT — see LICENSE.