Harden motor direction handling + document inverted-wiring gotcha#1
Open
JakeTheRabbit wants to merge 2 commits into
Open
Harden motor direction handling + document inverted-wiring gotcha#1JakeTheRabbit wants to merge 2 commits into
JakeTheRabbit wants to merge 2 commits into
Conversation
The direction switches are optimistic templates with RESTORE_DEFAULT_ON, so on boot the ESP sends "Motor N FWD" exactly once, during switch setup. The motor driver MCU boots slower than the ESP and misses that command, leaving it at its power-on default (reverse) while Home Assistant shows Forward. The "Motor N ON" command carries only speed, so the first dose runs in reverse until a manual direction toggle happens to re-send FWD. Two changes make the desync impossible to dose with: - Each Motor Power turn_on_action now writes the current direction line immediately before the ON line, so every start asserts the direction the UI shows. - An on_boot hook (10s after boot, once the driver is listening) re-sends all six directions so the driver matches the restored switch states even before the first dose. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Field testing on a hw2.1 unit showed the direction line can still be lost when sent immediately before the ON command: the driver's UART RX handler re-arms its DMA reception after each event, and bytes arriving in that window are silently dropped, so a run can start with a stale direction pin. Sending the direction 500 ms after the ON command gives every start a freshly delivered direction command once the driver is out of its start-of-run parsing burst, so each run's direction matches the switch state even if an earlier direction command was lost. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
JakeTheRabbit
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
Two related improvements to how the ESPHome config drives motor direction, plus a troubleshooting note. No behavior change for correctly-wired units — this is defensive hardening, not a polarity change.
Background (honest version)
I chased this as a "direction command lost at boot" bug. On the reference unit it turned out the motors were wired opposite to the protocol — wire
REVspins the pumps in the physical dosing direction. That fully explained "doses in reverse even though the toggle shows Forward," with no lost command involved. The wiring fix is unit-specific, so it is deliberately NOT in this PR (inverting FWD/REV upstream would reverse every correctly-wired ABD).What remains here is the genuinely generic part.
1. Re-assert direction on every start (hardening)
Currently direction is sent once, at boot, via
RESTORE_DEFAULT_ON.Motor N ON <speed>carries no direction, so the driver relies on that single boot-time command still being in effect. This adds, to each Motor Powerturn_on_action, a re-send of the current direction 500 ms after the ON command — so every run's direction provably matches the switch state, independent of anything that happened at boot.2. Boot re-sync
An
on_boothook re-sends all six directions 10 s after boot (once the driver MCU is up), so an ESP reboot while the driver stays powered can't leave them out of sync.3. Troubleshooting note for inverted wiring
If a unit doses in reverse while the Direction entity shows Forward, and toggling direction "fixes" it: check motor wiring polarity before assuming a firmware/config bug. Some builds are wired opposite; the remedy is to swap the FWD/REV strings in that unit's config only, not upstream.
Validated with
esphome config(2026.6.5). Hardening (items 1–2) running in production on a hw2.1 6-channel unit; a full 3,200 mL dose sequence ran clean after the wiring correction.