Distribute Harp device GUI applications via .NET tool packages and a unified launcher

[glopesdev]

• Proposed
• Prototype: In Progress
• Implementation: Not Started
• Specification: Not Started

Summary

Distribute Harp device GUI applications as dotnet tool packages published to NuGet, and provide a single cross-platform launcher (Harp Regulator) responsible for discovering devices, installing the matching GUI tool, and launching it. Solve the per-platform installer problem once, for one application, and use that one application to manage every Harp device GUI thereafter.

Motivation

harp-tech/protocol#145 establishes a single version number per device repository, with all components — hardware, firmware, software interface, GUI — released together at the same version. The proposal does not specify a distribution channel for GUI applications, leaving the install story for end users ambiguous.

The first attempt at a unified GUI distribution, in harp-tech/device.behavior#32, shipped per-platform self-contained installers (NSIS for Windows, .app bundle for macOS, tar.gz for Linux). harp-tech/device.behavior#39 began moving toward dotnet tool packaging, motivated by the recognition that per-platform installers do not scale: as the catalog of Harp devices with GUIs grows, the cost of maintaining N × 3 installer pipelines, signing certificates, auto-update channels, and version-coupling stories grows linearly with each new device.

This proposal closes the GUI distribution gap left by harp-tech/protocol#145 and resolves the architectural ambiguity in harp-tech/device.behavior#39.

Detailed Design

Distribution channel: dotnet tool on NuGet

Each Harp device GUI is packaged as a dotnet tool (PackAsTool=true) and published to NuGet.org as part of the device's unified release. Users install via:

• End-user flow — open Harp Regulator, click on a connected device, Regulator installs and launches the matching GUI tool.
• Developer flow — dotnet tool install -g <DeviceApp> and run the resulting command (e.g. harp.behavior).

The .NET SDK installer is the only platform-specific installation an end user needs. It is signed, available for Windows, Linux, and macOS, and distributed by a verified Microsoft publisher, sidestepping the code-signing infrastructure that per-platform installers would otherwise require.

Disk economics: with N Harp devices installed, self-contained installers cost N × ~80 MB of duplicated .NET runtime; the dotnet tool channel costs ~250 MB (shared SDK) + N × ~5 MB (tool packages). Break-even at N = 2; the advantage grows with N. For research environments running multiple Harp devices, this is the common case.

Harp device GUIs target .NET 8, the previous LTS release with support through November 2026. The dotnet tool channel allows each GUI to pin a target framework independent of newer .NET releases, which matters in practice because newer versions can drop support for older OS hardware. macOS testing surfaced that .NET 10 cannot install on older Macs where .NET 8 does, and research labs routinely depend on older hardware. Anchoring on .NET 8 LTS preserves the broadest install reach without forcing users to upgrade hardware.

Launcher: Harp Regulator

Harp Regulator is a small Avalonia .NET 8 application that acts as the entry point for end users.

v1 scope

• List available COM ports cross-platform.
• On user selection, probe the selected port for the Harp WhoAmI register, with explicit fail-safe handling for ports already in use by another application and ports connected to non-Harp serial devices (Arduinos, FTDI bridges, etc.).
• Install the matching device tool package from the configured NuGet feed (NuGet.org by default; local feed configurable for offline labs).
• Launch the installed tool.

Out of v1 scope

Auto-update of installed tools, hot-plug device detection, multi-port concurrent launches, settings/preferences UI, log capture, .NET SDK orchestration, firmware updates. These are deferred to later iterations.

Side-by-side device versions

Multiple versions of the same device tool must coexist (e.g. Harp Behavior v3 on COM4 and v4 on COM5). Regulator manages this with per-(device, version) local tool manifests, restored on demand into a per-version directory under ~/.harp/tools/<device>/<version>/. Regulator routes launches to the matching manifest.

This is an internal implementation detail that can later be replaced with custom NuGet resolution and direct dotnet exec invocation if profiling or operational experience justifies it.

Implementation plan

• Owner: @harp-tech/neurogears.
• v1 ship target: 2026-06-30 (approximately 8 weeks from this proposal).
• Public midpoint check-in: 2026-06-04, posted as a comment on this issue with progress visible to reviewers (draft repository, working serial enumeration, screenshots).
• Rollback commitment: if Regulator v1 has not shipped by 2026-06-30, @harp-tech/maintainers convenes a checkup meeting to decide whether to roll back to per-device self-contained installers as a stop-gap until Regulator is ready, accepting the per-platform maintenance cost in the interim.

The CI infrastructure prototyped in harp-tech/device.behavior#39 for per-platform self-contained installers (NSIS, .app bundling, tar.gz packaging) is the same infrastructure Regulator reuses for its own distribution. The work is not discarded; it is repurposed for the one application that owns the per-platform installer story.

Versioning policy

Regulator installs the device tool whose published version exactly matches the device firmware version reported via the device interface. This aligns with harp-tech/protocol#145: every unified release publishes all components at the same version, even when individual components are unchanged.

When no exact-match tool exists on the configured feeds, Regulator surfaces the mismatch to the user rather than silently falling back to a near version. Implicit fall-back would defeat the version-coupling guarantee that exact-match enables.

CI obligations (normative)

Every device repository participating in this proposal must publish a tool package to NuGet for every unified release tag, regardless of whether the GUI App's source has changed since the previous release. This is a CI invariant, not a convention: omitting a release silently breaks the exact-match contract for any user whose device reports the omitted version.

This requirement extends harp-tech/protocol#145 by making the "rebuild and repackage unchanged artifacts" guidance normative for the GUI tool channel.

Regulator's own distribution

Regulator is distributed as self-contained per-platform installers: NSIS for Windows, .app bundle (zipped or .dmg) for macOS, tar.gz for Linux. winget and brew packages are nice-to-haves, not required for v1.

This concentrates the per-platform installer problem into a single application, maintained once. Whatever per-platform complexity remains — code signing, notarization, package manager submission — applies to one binary, not to every Harp device GUI.

Bonsai boundary

Regulator complements Bonsai. Bonsai users continue to use Harp through Bonsai workflows; Regulator targets users who want a GUI launcher without committing to a Bonsai workflow. The two projects are independent and address different audiences.

Future direction

Out of v1 scope, but documented here for trajectory:

• Integration with harp-tech/toolkit to expose unified firmware update through Regulator, turning it into a true universal GUI for every Harp device.
• Compatibility with Bonsai.config environment files, so that Regulator can align connected device versions with the requirements of a Bonsai workflow — for example, warning when a device's firmware version differs from the version pinned by a workflow's environment, or driving the toolkit-based firmware update needed to bring the device into alignment with the workflow it will run.
• winget and brew packages for Regulator itself.
• Hot-plug device detection.
• Self-update for Regulator.

Drawbacks

• Worse first-touch install experience until Regulator ships. Until v1 lands, end users without the .NET SDK installed experience a developer-tier install flow (install SDK, then run two commands in a terminal). The 8-week timeline and rollback commitment are intended to bound this regression.
• Regulator becomes a single point of failure. A launcher bug blocks every Harp device GUI from launching, not just one. Mitigated by clean Regulator versioning and the ability to roll back to a prior Regulator release.
• .NET SDK install is a precondition. ~250 MB, may require administrative permissions in some institutional environments, and may be unfamiliar to non-developer scientific users.
• Exact-match versioning is brittle if CI breaks the lockstep. A missed publication silently breaks Regulator for users on that version. Mitigated by the normative CI invariant.
• Side-by-side per-version local tool manifests are not yet validated end-to-end. This is implementation risk, not architectural risk; to be validated by the Regulator v1 prototype.

Alternatives

• Per-device self-contained installers (the alternative initially favoured in PR review of harp-tech/device.behavior#39). Each Harp device GUI ships its own NSIS installer, .app bundle, and Linux package. Solves the install UX at first touch, but introduces 3N installer pipelines as Harp devices proliferate, duplicates the .NET runtime per device on disk, and pushes per-platform code-signing into every repository.
• Hybrid: dotnet tool channel plus per-device installers. Ship both. Doubles CI maintenance for unclear gain, requires telling users which channel to choose, and does not eliminate the per-platform installer cost for any individual device.
• Status quo, established by harp-tech/device.behavior#32. Continue with per-device per-platform installers. Works today but does not scale to a growing Harp device catalog.

Unresolved Questions

• macOS x64 end-to-end testing of the existing dotnet tool package shipped by harp-tech/device.behavior#39 has passed. macOS arm64 testing is still pending. This proposal is conditional on the arm64 test also succeeding. The arm64 result will be posted as a comment on this issue before any device repo merges harp-tech/device.behavior#39 or its equivalent.
• Does the side-by-side per-version local tool manifest approach hold up under realistic load (multiple devices on multiple ports, multiple coexisting versions)?
• What is the right user surface when a device on a port reports a firmware version with no matching tool on the configured feeds (auto-prompt to add a feed, refuse-to-launch, suggest nearest)?

Design Meetings

• Pending: targeted for discussion at the next standard review board meeting.

[banchan86]

• Hmm, how about "Harp Launcher" or "Harp Manager" for the name? IMO, those alternatives sound a bit more user-friendly.
• (edit) Ah, now I was wondering why it sounded familiar - will it be an expansion of https://github.com/harp-tech/harp-regulator?

[glopesdev]

• (edit) Ah, now I was wondering why it sounded familiar - will it be an expansion of https://github.com/harp-tech/harp-regulator?

@banchan86 that's right, it is an homage to @PathogenDavid. We will fold the pico firmware update and protocol bits together with toolkit, but I really liked the name so reusing it for this.