v2.2.0 — WS-V2 protocol family

Highlights

• New WS-V2 protocol family for V2 firmware (≥ 40.51): F1, F1 Ultra, F1 Ultra V2 (GS003), F1 Lite, F2 family, M1 Ultra, P2S, P3, MetalFab, Apparel Printer.
• Full TLS WebSocket API on port 28900 — three concurrent channels (function=instruction JSON request/response + push events, function=file_stream binary uploads, function=media_stream camera frames). Replaces the legacy listener-only F1 V2 implementation.
• V1/V2 auto-detection at config-flow time. The integration probes port 28900, picks the WS-V2 family when the device answers, falls back to the legacy REST API otherwise. Same physical device behind one config entry.
• Push events: status (STATUS_CONTROLLER mode changes), cover (GAP), machine lock, button presses, work-result.
• Three-step V2 firmware flash via /v1/device/upgrade-mode + file_stream blob.
• First-class V1/V2 registry entries: XtoolDeviceModel gains protocol_version and discovery_match fields so V1/V2 siblings of one device coexist without ambiguity. Future V2-only models can be added with a single registry entry.

Removed

• Legacy f1v2 listener-only family (superseded by ws_v2).

Caveats

• WS-V2 is implemented from xTool Studio bundle reverse-engineering; the wire format has not been verified against live V2 hardware. Issue reports + traffic captures from V2 devices welcome.
• Existing config entries on V1 firmware keep working unchanged. After a major firmware upgrade to V2, re-add the device to switch families.

v2.1.0 — new models, firmware-flash audit, options polish

What's new

New device models (REST family)

8 additional devices auto-discovered + supported. Capabilities + firmware IDs extracted from the xTool Studio (Windows) extension bundles:

• P3 (P3) — multi-color printer + air-bottle + red-laser-head + security module
• F2 (GS006) — F1 successor
• F2 Ultra (GS004-CLASS-4) — Class-4 enclosed station
• F2 Ultra Single (GS007-CLASS-4) — single-laser variant
• F2 Ultra UV (GS009-CLASS-4) — UV laser variant
• F1 Ultra V2 (GS003) — Class-1 safe revision of F1 Ultra
• MetalFab (HJ003) — 1200 W fiber-laser welder/cutter
• Apparel Printer (DT001) — DTG/DTF printer

Existing models updated

• F1, F1 Ultra, F1 Lite (GS005), F2 family: has_machine_lock=True
• F1 Ultra firmware bundle bumped to xTool-f1-ultra-firmware-1.5
• D1 Pro 2.0: separate firmware bundle (xTool-d1pro-firmware-2.0); was wrongly mapped to D1 Pro 1.0 binaries
• All firmware content IDs migrated to atomm cloud namespace + xTool-*-firmware prefix

Firmware flash — full XCS / xTool Studio alignment

S1 flash flow rewritten to the actual two-step /upload + /burn?code= sequence used by both xTool apps. Previous single-step POST /burn was incorrect and likely never worked. Per-board filenames now match: motion_firmware / laser_firmware / network_firmware (was wifi_firmware per older XCS Android bundles).

D-series field name corrected to firmwareData. REST family /package?action=burn switched to raw blob (no multipart wrapping). New M1-specific four-step strategy (/upgrade_version → /script → /package → /burn?reboot=true).

Every flash step now validates the response body — HTTP 200 alone is not sufficient.

Firmware update entity

• Release notes (English) rendered inline in the entity dialog; release_summary mirrors the markdown so it's visible even when the device is on the latest version
• Fallback probe with contentVersion="0.0.0.0" when no real update is available — surfaces the latest published changelog regardless
• First cloud check kicks in on coordinator-data-ready instead of waiting up to 30 min for the next HA polling slot
• Markdown hard-breaks inserted into description so multi-line release notes render correctly

New entities

• Binary sensor: XCS compatibility mode (S1, diagnostic) — on when the integration detects XCS is holding the WebSocket and falls back to HTTP /cmd writes

Removed entities

• Z-probe trigger button + Z-probe reading sensor — the on-device measure flow could not be reliably reproduced via either the WebSocket or HTTP /cmd paths during testing on real hardware. M-code constants are kept in code for documentation; entity removed pending a working sequence.

Config flow options

Schema is now strictly model-aware — only options applicable to the device's protocol family appear. New polling-interval options:

• Main coordinator polling interval (1–60 s, default 5)
• Firmware-update check interval (1–24 h, default 6 h, only when the model has a firmware ID)
• AP2 air-cleaner polling (5–300 s, default 30) — S1 only
• Lifetime-stats polling (60–3600 s, default 300) — S1 only
• Bluetooth-dongle polling (10–600 s, default 60) — S1 only

Bug fixes

• detect_model now prefers longer model_id substrings — fixes F1Ultra / F2Ultra collisions where the shorter F1 / F2 entry would match first
• S1 task_time sensor pinned to 0 outside of active job states (firmware counter kept incrementing forever during idle)
• M1 four-step flash now feeds both .script and .bin to the protocol in the right order

Documentation

• docs/PROTOCOL.md is now a pure wire-protocol reference. Integration internals (capability matrix, file-tree references, "the integration does X" prose) removed. Per-family auto-extracted xTool Studio api inventory tables are included: S1 (239 unique APIs), D-series (226), REST (1127). Each row has method / cmd / url / params / body / transformResponse hints.
• README.md updated with full model list (16 REST devices), corrected per-entity model footers (e.g. UV fire sensor on F1U / F1UV2 / F2UUV / M1U / P2S), all 7 ports/transports listed in technical details.

Live-tested findings (xTool S1)

• M1109 getRedCrossInfo → A<bottomX> B<bottomY> C<topX> D<topY> E<maxZ>
• M1113 getZOffset (xtouchOffsetStr) → X<x> Y<y> — laser-head ↔ Z-probe-pin offset
• M2240 lightInterference → A B C D M P I PID-style flame-detection coefficients

Compatibility

• Home Assistant 2025.1.0 or newer
• Existing v2.0.0 config entries upgrade automatically — no migration needed

v2.0.0

Architectural overhaul: per-family protocol / coordinator / entities

The integration is now split along protocol-family lines. S1, D-series, REST (F1 / F1 Ultra / F1 Lite / M1 / M1 Ultra / P1 / P2 / P2S) and F1 V2 each own their protocol, coordinator, models and entity factories. Added new entities and improved compatibility for all protocols.

v1.2.0

What's new

• Update entity now shows installed and latest firmware for all three S1 boards (Main / Laser / WiFi). HA flags an update if any board is behind, install flashes all of them.
• New diagnostic sensor: Workspace size (e.g. 498 × 330 × 58 mm).
• Real firmware flash progress polled from the device (/system?action=get_upgrade_progress), replacing the previous 50/50 heuristic.

Bug fixes

• Lifetime statistics (working time, jobs, standby, tool runtime) were never populated. The device needs M2008 A1, not bare M2008.
• The main MCU firmware version shown in HA was actually the ESP32/Wi-Fi firmware. Now reads M99 from M2003 correctly.

Under the hood

• Trigger M2211 (full-state push) on every WebSocket reconnect — no more expensive M2003 round-trip to refresh entities.
• Parse extra fields from M116 (laser process type and tube).
• Try POST /upgrade single-blob upload for REST models before falling back to the legacy /upgrade_version + /package handshake.
• All M-codes and HTTP paths centralised in const.py — no more magic strings in the protocol layer.

Documentation

New docs/PROTOCOL.md with a complete reference of all three protocol families, M-code tables, push frames, XCS Compatibility Mode, HTTP endpoints, the cloud firmware-update API, and dangerous codes to avoid. Linked from the README.

v1.1.0

What's new

• New Firmware update entity checks the xTool cloud for available firmware on reconnect and every 6 hours (all supported models).
• Installs are off by default — the entity only reports whether an update is available.
• A new Enable firmware updates option in the integration settings arms the install action, guarded by a confirmation menu that warns about flash risks (do not power off during an update).
• Download and flash progress are reported as a percentage in the Update entity.

v1.0.0

Initial Release

Home Assistant integration for xTool laser cutters and engravers.

Supported Models

• S1 (WebSocket M-code) — fully tested
• D1, D1 Pro, D1 Pro 2.0 (HTTP M-code)
• F1, F1 Ultra, F1 Lite, M1, M1 Ultra, P1, P2, P2S (REST API)

Features

• Multi-model support with automatic protocol detection
• UDP network discovery for easy setup
• Status monitoring (idle, processing, paused, finished, error, ...)
• Fill light control (dimmable)
• Switches: flame alarm, buzzer, move stop, exhaust fan
• Numbers: air assist delay, exhaust fan duration
• Select: flame alarm sensitivity (high/low)
• Buttons: pause, resume, cancel job, home axes (all/XY/Z)
• Laser position tracking (X/Y/Z)
• Lifetime statistics (working time, sessions, standby, tool runtime)
• Laser module detection (type, power, producer)
• Accessory detection (air pump, fire extinguisher, riser base)
• Camera support for P2/P2S (overview + close-up)
• Optional power switch linking (smart plug)
• XCS Compatibility Mode (works alongside XCS desktop app)
• English and German translations