rusthinq 0.2

rusthinq is a local LG ThinQ device server and optional LG cloud bridge written in Rust. It accepts appliance connections, runs Rhai device drivers, and exposes a management API, web dashboard and MQTT output.

How 0.2 differs

Area	TypeScript rethink	Rust 0.1	Rust 0.2
Structure	Object/event-driven server with device, cloud and Home Assistant components	Rust port organized around core, devices, cloud, bridge and GUI components	Protocol and lifecycle decisions separated from transport I/O, adapters and application orchestration
Device semantics	Built-in TypeScript model drivers and Home Assistant entity mappings	Rhai drivers and external raw-bus consumers; host also provides IL descriptors and property helpers	Rhai owns model semantics, descriptors, validation and integration output; host carries opaque publications
Management	Web management alongside built-in integrations	MQTT control/state topics plus optional GUI	HTTP/WebSocket API and GUI operate independently of external MQTT
Runtime ownership	Callbacks and event emitters connect components	Shared services and device callbacks connect components	Explicit task ownership, session generations and durable device identity fence stale work
Compatibility	Upstream implementation and model catalog	Archived migration source	Selectively reimplemented contracts with replay, integration and feature checks; full upstream parity is not claimed

The comparison describes architectural boundaries, not model coverage. Upstream references are rethink and its model/HA bridge.

Runtime boundaries

• Protocol and lifecycle: parsing, encoding and state transitions can be tested without sockets or an LG account.
• Transport and adapters: ThinQ1 TLS/XML, ThinQ2 device MQTT/provisioning, LG cloud communication and external MQTT handle I/O around those decisions.
• Application: owns devices, sessions, task shutdown, durable checkpoints and coordination between adapters, scripts and management. Session and script generations prevent obsolete connections or drivers from issuing current work.
• Scripts: translate appliance packets into properties and commands. IL and Home Assistant semantics belong here, rather than in the host. Drivers and IL helpers live in rusthinq-scripts.

This makes an integration change a script concern where the existing host APIs cover it. The current MQTT command route is {prefix}/{device}/{property}/set; see operations for its limits and delivery semantics.

Workspace

Crate	Responsibility
rusthinq-protocol	Device wire formats and protocol decisions
rusthinq-lifecycle	Device lifecycle, identity and generation transitions
rusthinq-server	Local device transports and provisioning services
rusthinq-bridge	LG account, cloud protocol and relay adapters
rusthinq-scripting	Rhai execution and generic host effects
rusthinq-app	Composed daemon, durable ownership, management, GUI and external MQTT
rusthinq-tools	CLI, MCP, capture/replay, setup and migration utilities

Build and run

cargo build --release -p rusthinq-app --bin rusthinq
cargo run --release -p rusthinq-app --bin rusthinq -- ./config.toml

A local configuration example:

thinq1_bind = "127.0.0.1:5502"
mqtt_bind = "127.0.0.1:8883"
https_bind = "127.0.0.1:8443"
hostname = "local.example"
ca_certificate = "ca.pem"
ca_key = "ca-key.pem"
device_ledger = "devices.json"
legacy_tls = false

[management]
bind = "127.0.0.1:44401"
gui = true

Prepare an existing valid CA and its private key before starting. Paths are relative to the configuration file, and parent directories must exist. This loopback example is for local use; connecting appliances also requires reachable listeners and device hostname routing. Follow the runtime guide for endpoint configuration.

Open http://127.0.0.1:44401/ for the dashboard. Its Devices, LG cloud, Activity and System views share the management API. The dashboard guide covers packet monitoring and analysis.

Add drivers, external_mqtt and cloud_account as needed using operations.

Normal ThinQ2 commands can use POST /api/devices/{id}/packet (hex bytes) or POST /api/devices/{id}/clip (cmd, type, data); the core generates did/mid. These authenticated, session-scoped APIs work without Rhai or external MQTT and are independent of diagnostic injection. See the request examples and delivery contract.

External MQTT is optional: management and local script-output observation continue without it. LG authentication is also optional for local device service.

Daemon logs default to info; use RUST_LOG for diagnostics. See logging for levels and systemd configuration.

For deployment use --release; the build guide explains size optimization and debugging tradeoffs.

Build variants

The default build enables bridge, scripting and gui.

# LG bridge and Rhai, without dashboard assets
cargo build --release -p rusthinq-app --bin rusthinq --no-default-features --features bridge,scripting

# Local transports and management, without LG bridge or Rhai
cargo build --release -p rusthinq-app --bin rusthinq --no-default-features

Tools and diagnostics

cargo build --release -p rusthinq-tools --bins

The tool suite includes CLI management, an MCP server, device/cloud capture, packet encode/decode, replay, SoftAP setup, migration and retained-output cleanup. MCP supports live device observation through device_start, read_device and device_stop, with bounded capture buffers, cursors, loss reporting and session snapshots. See tool migration for commands and configuration.

Model-specific Rhai drivers, shared helpers and their tests are maintained in rusthinq-scripts. This repository tests the Rust host and transport using synthetic scripts and provides the runner for the scripts repository's CI. The runner accepts the checkout being tested without requiring a fixed scripts revision.

# Run the device-driver compatibility suite from a separate scripts checkout
rusthinq-script-test /path/to/rusthinq-scripts

# Replay recorded receive packets through explicit management injection
rusthinqctl replay DEVICE CAPTURE.jsonl --inject-ok

Replay requires the management injection capability to be enabled. Command admission, transport write and appliance acknowledgement are distinct results; management events expose them separately where supported.

Upgrading from 0.1

Read the release notes, compatibility inventory and tool migration guide before switching runtimes. Configuration, management contracts and script host APIs have changed; this is not a drop-in binary replacement.

rusthinq-migrate OLD_CONFIG NEW_DIRECTORY

The migrator stages configuration and saved device/retained state without modifying the 0.1 source. Follow the migration guide for validation and rollback. Model porting and deployment packaging are deferred until the host is complete; they are separate from the runtime architecture work.

The documentation index separates operating guides, architecture contracts and dated implementation evidence.

Development and verification

GitHub Actions runs scripts/check-0.2.sh on pushes to dev/0.2 and on pull requests targeting that branch. Local commits trigger CI after they are pushed.

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
scripts/check-0.2.sh

The check script runs formatting, workspace tests, strict Clippy, eight feature combinations and GUI JavaScript checks. These checks do not establish live appliance compatibility. Refactoring, milestones and the polling audit record implementation decisions, verification evidence and outstanding work.

Credits and license

Based on the LG ThinQ protocol work in anszom/rethink by Andrzej Szombierski and contributors, and the initial Rust port in BluSyn/rethink. 0.2 reorganizes that work into an independent runtime. Licensed under GPL-2.0-or-later.