CatHub.Protocol 0.2.0

CatHub

CatHub lets radio applications safely share one transceiver and one keyer. Clients can use CAT, Hamlib NET, virtual serial, or WinKeyer interfaces.

The daemon is the only owner of each physical device. It puts all changes in sequence and gives each client separate permissions. It also controls PTT. The daemon leaves the station unkeyed after shutdown or a client failure.

Current support

• First-class Kenwood TS-590 backend
• Broad rig support through an external rigctld backend
• Hamlib NET endpoints with per-endpoint permissions
• TS-590 and TS-2000 compatible virtual serial endpoints
• Single-VFO presentation for applications that cannot model the active VFO correctly
• Multi-client WinKeyer broker with typed gRPC and virtual serial endpoints
• Standalone and embedded [cat_hub] configuration layouts

Install

Install the daemon from crates.io with Rust 1.88 or newer:

cargo install cathub --version 0.2.0

You can also download the Windows or Linux archive from the GitHub Releases page. Download the adjacent SHA-256 checksum. Verify the archive with the checksum. Extract the archive. Put cathub or cathub.exe on PATH.

To build the daemon from source:

git clone https://github.com/treitforge/cathub.git
Set-Location cathub
cargo build --release -p cathub

The Windows executable is target\release\cathub.exe. The Linux executable is target/release/cathub. A daemon operator does not need the protocol development packages.

Build and test

The full repository gate requires PowerShell 7, a current stable Rust toolchain, the .NET 10 SDK, and Buf:

.\build.ps1 check

The principal checks can also be run directly:

cargo build --workspace
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
buf lint
dotnet build CatHub.slnx

The Rust protocol crate vendors protoc, so cargo build does not require a separate Protocol Buffers compiler installation.

Configuration

CatHub's default configuration path is:

• Windows: %APPDATA%\cathub\cathub.toml
• Linux: $XDG_CONFIG_HOME/cathub/cathub.toml, or ~/.config/cathub/cathub.toml

Set CATHUB_CONFIG_PATH or pass --config to use another file. The complete example is config/cathub.toml.

A standalone document uses top-level [radio], [winkeyer], and endpoint tables. CatHub also accepts these settings below [cat_hub] in a managed document. Use --section cat_hub to require the embedded layout.

Validate and inspect configuration without opening hardware:

cathub config validate --config config\cathub.toml
cathub config print-effective --config config\cathub.toml
cathub config print-effective --format json --config config\cathub.toml

Extract an embedded [cat_hub] section without changing the source file:

cathub config migrate `
  --from C:\station\managed-config.toml `
  --output "$env:APPDATA\cathub\cathub.toml"

Migration does not overwrite an existing destination unless you supply --force. Migration does not remove the source automatically. --remove-source-section creates a .bak copy before it changes the managed document.

Run

The repository helper builds the daemon when necessary. On first use, it copies the sample configuration to the default location. Then it starts CatHub:

.\scripts\Start-CatHub.ps1

For an installed binary:

cathub config validate
cathub

An orchestrator can request an available typed API port:

cathub --winkeyer-api-bind 127.0.0.1:0 --runtime-info .\cathub-runtime.json

CatHub publishes the selected endpoint after all configured listeners bind. The runtime file includes the CatHub process ID. Clients must validate that process ID before they use the endpoint.

Client interfaces

• Hamlib-aware clients connect to a configured [[hamlib_net]] TCP listener.
• Serial CAT clients connect to the application side of a dedicated virtual serial pair.
• Legacy WinKeyer clients connect to their own virtual serial pair.
• Typed WinKeyer clients connect to the loopback gRPC address in [winkeyer].api_bind.

A launcher-managed client uses the endpoint in CatHub's runtime file.

Each endpoint has its own permissions. Applications never open the physical radio or keyer port directly.

Protocol packages

The cathub crate builds and installs the daemon. cathub-protocol is the Rust client/server contract crate. CatHub.Protocol is the .NET client package project. Applications use these packages with the typed WinKeyer API. You do not need them to run the daemon.

The release workflow puts both protocol artifacts in a GitHub release. Published client packages are available as cathub-protocol for Rust and CatHub.Protocol for .NET. Registry publication is a separate authorized operation. See release and compatibility.

Documentation

• Documentation standard
• Architecture report
• Radio hub design
• WinKeyer broker design
• Operator setup
• Release and compatibility

License

MIT. See LICENSE.