Skip to content

Give the port timeout a finite default - #36

Merged
glopesdev merged 1 commit into
harp-tech:mainfrom
glopesdev:port-timeout-default
Sep 2, 2026
Merged

Give the port timeout a finite default#36
glopesdev merged 1 commit into
harp-tech:mainfrom
glopesdev:port-timeout-default

Conversation

@glopesdev

Copy link
Copy Markdown
Contributor

--timeout had no default, so omitting it awaited the read with no bound at all and a device that never replied blocked until the process was terminated by hand. Neither that nor requiring an arbitrary number on every invocation is reasonable for a simple device query, so the option now defaults to 2000 milliseconds, -1 waits indefinitely, and values below -1 are rejected. The option is also applied to all five reads in the root command rather than to the identity read alone.

Main now returns what InvokeAsync gives it. The tool previously exited 0 for every outcome, so a timeout, a missing port and a successful read were indistinguishable to anything scripted. A bounded failure nothing can detect is not much better than a hang.

Why 2000 milliseconds

The number is not justified by steady-state latency, and it is worth recording why so nobody later reduces it on that basis. Measured against a Behavior device on this branch, five sequential register reads complete inside the smallest expressible timeout: --timeout 1 succeeds, as do 2, 3, 5 and 10. Total command time is 373 to 420 milliseconds across runs, dominated by process startup and opening the port rather than by device traffic.

What the default has to cover is the post-reset window instead. Hardware measurements during the firmware update work found a device enumerated and openable at roughly 130 milliseconds but not answering Harp until 300 to 800. Against that, 2000 gives about 2.5x margin where 1000 would give 1.25x.

Verified against hardware

A continuous probe at --timeout 100 across a power cycle caught four distinct device states, which between them exercise every path this change touches.

  • Device answering: succeeds in about 420 ms, exit 0.
  • Port absent from enumeration after the power cycle: fails in about 250 ms, exit 1.
  • Port present but held: Access to the path 'COM3' is denied, once in 40 attempts, exit 1.
  • Device in the bootloader, port open and not answering Harp: times out, exit 1.

The timeout case is the one that could not be tested before and it clustered at 486 to 555 milliseconds, which is startup plus a single timeout. That confirms the exception propagates out of the first read and the remaining four never run, so the worst case for the whole command is one timeout period rather than one per read.

The other reason to fail early

Beyond not making the user wait, there is a device-side argument. The ATxmega bootloader's receive path enters a busy-wait that spins until it has taken 522 further bytes, with no timeout and no escape, so a client that keeps feeding a port whose device state it does not know can park the device in a loop that only a reset clears. Its header matcher does self-clear after about a second of silence, so a partial header does not persist, but the data state has no such protection. Short-lived commands that close the port on failure are the right posture for that reason as much as for the user's.

Closes #35

The timeout now defaults to 2000 milliseconds and applies to every
read rather than only the first, so a device that stops responding
fails the command instead of blocking indefinitely. Passing -1 waits
indefinitely, and values below -1 are rejected.

Main now returns the exit code from the parse result, so a failed
command reports non-zero instead of always reporting success.
@glopesdev glopesdev added the feature New planned feature label Sep 1, 2026

@banchan86 banchan86 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested and LGTM!

@glopesdev
glopesdev merged commit 2c2326f into harp-tech:main Sep 2, 2026
9 checks passed
@glopesdev
glopesdev deleted the port-timeout-default branch September 2, 2026 07:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature New planned feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Give the port timeout a finite default and apply it to every read

2 participants