Mid-task pause from empty clean-water tank: errorCode and FAULTS_STR stay empty (r2532a fw 4.3.9_2199)

[malard]

Summary

Issue #3 (closed) covered the start-refusal case where an empty clean-water tank rejects vacuum.start() and surfaces as MiotError.CleanWaterTankEmpty = 107. That path works.

This issue is about the sibling case the closing comment didn't cover: the tank running empty mid-task, where the device pauses an in-progress clean. In that scenario Vacuum.state doesn't expose anything actionable — neither errorCode nor faults[] populate, and the taskLifecycle event does not fire aborted.

Net effect on a consumer: a scheduled clean silently fails to complete, the robot sits paused for hours, and the lib provides no signal that a user-actionable condition exists.

Observed live (verified)

Device: dreame.vacuum.r2532a, fw 4.3.9_2199, node-dreame 0.4.1.

The Dreamehome app shows: paused, low water level in clean water tank.

Vacuum.state from the live MQTT subscription (state_age fresh ~8s after a refresh ACK):

{
  "miotState": 21,
  "miotStateRaw": 21,
  "errorCode": null,
  "faults": [],
  "stuck": false,
  "battery": 100,
  "charging": null,
  ... (most fields null) ...
}

miotState: 21 is MiotState.PausedCleaning. The pause is real, the cause is real, but neither errorCode nor faults[] carries 107 (or any code) for the duration of this paused-mid-task condition.

No taskLifecycle: aborted event fired either — likely because the task hasn't been aborted from the device's point of view, it's been paused pending user action. From the consumer's point of view it's identical (schedule will not complete until intervention) but the event taxonomy doesn't reflect that.

What the consumer needs

A signal — any of these would suffice — that distinguishes a normal user-initiated pause from a paused-because-needs-attention state:

1. errorCode populated on the paused-mid-task transition (matching the start-refusal behaviour). Simplest and consistent.
2. taskLifecycle event with a new phase: \"paused\" (or \"halted\") carrying a reason field, mirroring the aborted envelope.
3. A separate pauseReason field on Vacuum.state populated when miotState === PausedCleaning and the underlying cause is known.

Investigation hints

• The Dreamehome app clearly knows the cause, so the signal is reaching the cloud — question is which MIoT property carries it.
• The tank-fill request in Expose clean-water tank fill state (and dirty-water tank, optionally) #3 was deferred for lack of a graded fill code; this case may be the same signal observed from a different angle. If a WATER_TANK_LEVEL (or similar) property turns up in the dock cluster (siid 27/28 was suggested), it may flip 0→1 at this pause boundary.
• FAULTS_STR (siid 4 piid 18) co-fires with ERROR for the start-refusal case per the existing docs — worth confirming whether it stays empty for the paused-mid-task case (we observed it empty here).

Reproduction

1. Start a clean while the clean-water tank has just enough to run partway.
2. Wait for the device to pause itself mid-task.
3. Observe Vacuum.state — miotState: 21, errorCode: null, faults: [].

Happy to capture MQTT/HTTP traces from this device if a candidate siid/piid is identified.

Workaround in the consumer

For now, the dunbar-os consumer treats miotState === PausedCleaning lasting longer than N minutes with no progress as a heuristic "needs attention" signal, but that's heuristic — a typed signal from the lib is preferable.

[malard]

🤖 AI-generated investigation (Claude Code, on behalf of @malard). Findings below are from code analysis plus a live read against the device; the resume-refusal mechanism is a hypothesis not yet confirmed live. Flagged inline.

Diagnosis

The mid-task pause is a state, not a fault. On the start-refusal path (#3) the device actively rejects an action and latches CleanWaterTankEmpty = 107 on ERROR (siid 2 piid 2) + FAULTS_STR (siid 4 piid 18). Mid-task it instead transitions to MiotState.PausedCleaning = 21 and waits — so there's nothing on the error register to read, which is exactly what the report shows (errorCode: null, faults: []).

Two facts narrow the search:

• stuck: false in the capture rules out the stuck flag (siid 14 piid 4). Confirmed live: siid 14.4 reads 0 and is the only property the device pushes spontaneously while idle — so it is not the carrier.
• The capture omitted taskStatusRaw (siid 4 piid 1). That's the most important missing data point (see candidate Decode per-room Custom-mode schedule packed-int format #1).

Candidate properties, ranked

1. TASK_STATUS (siid 4 piid 1) — already read into state.taskStatusRaw. The TaskStatus enum has NeedsIntervention = 14 (documented "long-stall / sticky error") vs InterruptedOrPaused = 1 (normal user pause). If this pause sets 14, the signal is already captured today and the fix is just to surface it as a derived needsAttention flag. Cheapest possible resolution — and the repro didn't record it.
2. MESSAGE_PROMPT (siid 4 piid 57) / NUMERIC_MESSAGE_PROMPT (siid 4 piid 56) — documented as the "general-purpose prompt the device home page uses to display arbitrary messages." The app's "low water level in clean water tank" banner is the kind of thing this channel drives. Strong candidate for a textual/coded reason.
3. A graded clean-water-level property in the dock cluster (siid 27/28) — the Expose clean-water tank fill state (and dirty-water tank, optionally) #3-deferred "graded fill code." Less certain it exists; worth a sweep.

Hypothesis — the reason is recoverable via resume-refusal

vacuum.resume() is the same wire call as start() (src/vacuum.ts:837). So attempting to resume a tank-empty pause should re-trigger the #3 refusal path and surface 107 on ERROR/FAULTS_STR within ~1s — the device refuses and stays paused because the tank is still empty. If it holds, this connects #11 to #3 and gives the consumer an on-demand "why is it paused?" answer even when no passive property carries it. Not yet confirmed live.

Probe + baseline

Added examples/probe-pause-reason.ts (reads the 9 candidate properties by name, sweeps the dock cluster, and with --trigger fires the resume-refusal and captures the MQTT response with a stop() safety net).

A read-only baseline run (device docked) behaved exactly as the prior action-trigger findings predicted: every idle HTTP read no-ack'd (80001); only STUCK=0 came through MQTT. So a baseline-vs-repro HTTP diff is a dead end while idle — the useful capture must happen during the live pause (device more responsive), and --trigger is the most reliable mechanism.

Repro to confirm

1. Drain the clean-water tank, start a partial clean, let it pause mid-task.
2. Capture the passive paused state — does TASK_STATUS go to 14? does MESSAGE_PROMPT carry text?

   npx tsx examples/probe-pause-reason.ts paused-tank-empty | Tee-Object paused.jsonl
   

3. Confirm the resume-refusal hypothesis:

   npx tsx examples/probe-pause-reason.ts paused-tank-empty --trigger | Tee-Object paused-trigger.jsonl
   

Likely fix, depending on what the capture shows

• TASK_STATUS == 14 → surface a derived state.needsAttention boolean (no extra round-trip). Cheapest.
• MESSAGE_PROMPT/NUMERIC_MESSAGE_PROMPT carries the reason → surface as state.messagePrompt / map to a pauseReason.
• Only the resume-refusal surfaces it → add a guarded diagnosePause() that re-reads the refusal code, and/or a taskLifecycle phase: "paused" event carrying the recovered reason.