Extract Harp.Toolkit.Core and report stages - #46
Merged
Merged
Conversation
The ATxmega bootloader, firmware image and metadata sources move unchanged into a new Harp.Toolkit.Core package that is released alongside the tool.
UpdateFirmwareAsync now reports a stage with each progress update, and the update command shows that stage in a fixed-width column. A retry still lowers the percentage, and that decrease is now the documented signal for a retry. The command uses the Bootloader stage instead of a percentage threshold to decide whether an update left the device in bootloader mode. ImmediateProgress moves into the library as a public type and replaces an equivalent class in the hardware test.
The update now waits for the device to answer Harp again before it reports success, so exit 0 means the device is back. If the device stays silent for 20 seconds, the command exits 1 and says that the image was written. UpdateFirmwareAsync takes a cancellation token and checks it only until it resets the device, because a device in the bootloader stays there until an update completes. The update command passes the token that System.CommandLine raises on Ctrl+C. WaitUntilReadyAsync sits in a new FirmwareUpdate class rather than in Bootloader, because it needs nothing specific to the ATxmega core, and it replaces the poll loop in the hardware test.
The article now states that the command waits for the device to answer before it reports success, and that exit 0 means the device is back. A new section describes what Ctrl+C does before and after the reset. The progress description covers stages as well as the percentage, and the timeout option now says it governs neither the bootloader protocol nor the wait after an update.
Every command block is now labeled text, because the blocks contain no syntax any highlighter recognizes.
PortDiscovery.GetCandidatePortNames returns the serial ports that can connect to a Harp device, and the list command calls it instead of SerialPort.GetPortNames. macOS lists each device twice, once as a tty device and once as a callout device, and only the callout device opens without a carrier signal, so list offered half its entries as unusable. It also listed the Bluetooth port that macOS reports when nothing is paired. Windows and Linux are unaffected.
glopesdev
changed the title
Contributor
|
Tested firmware update with a Timestamp Generator on Windows. The progress stages, incompatible firmware, cancellation, recovery comments, docs, all LGTM! |
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
2 participants
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.
The firmware update path and port discovery move into a shared package, so other Harp tools can use them directly. An update now reports each stage when it starts. It accepts cancellation while cancellation is still safe. It also waits for the device before the command reports success.
The shared library
Harp.Toolkit.Coreis a new package, holding the ATxmega firmware update path, so a graphical tool can run an update without the command-line tool. The package README documents its public API as unstable, since the package shares code between Harp ecosystem tools, and the API follows the needs of those tools.PortDiscovery.GetCandidatePortNamesalso moves into the package, and thelistcommand calls it. macOS lists each serial device twice, once as a tty device and once as a callout device, and only the callout device opens without a carrier signal, solistwould offer half of its entries as unusable.Progress by stage
Bootloader.UpdateFirmwareAsyncnow reports anUpdateProgress, so each report now carries the current stage alongside the percentage.UpdateStageandUpdateProgresssit outside theATxmeganamespace, and the documentation states that the core implementation controls both the order of the stages and the set of stages in an update.That constraint is built around the Pico update flow, which checks that firmware is applicable after it enters the bootloader. ATxmega must check before the reset, because a device held in bootloader mode reports no identity.
Cancellation
UpdateFirmwareAsyncnow takes a cancellation token but checks it only until the device resets. This means cancellation is allowed during the first seconds of an update, but nothing after that point can be cancelled, since an abandoned write leaves the device in bootloader mode.The update command now passes the token raised by
System.CommandLineon Ctrl+C.Waiting for the device
FirmwareUpdate.WaitUntilReadyAsyncwaits for the device to answer Harp after the firmware update, so Exit 0 therefore means that the device is ready, and not only that the command finished writing the image.The wait ends after twenty seconds, and exits 1 if the device remains silent.
Documentation
The firmware update article documents the readiness wait, the new exit code contract, and the effect of Ctrl+C before and after the reset.
Every command block now uses the
textlabel. No highlighter recognizes any syntax in these blocks, since the PowerShell grammar splits hyphenated image names and subcommands at every hyphen.