Skip to content

Release v7: complete Z21 LAN protocol, docs, CI/CD, and tooling#3

Merged
jaak0b merged 1 commit into
mainfrom
Release/7.0.0
Jun 5, 2026
Merged

Release v7: complete Z21 LAN protocol, docs, CI/CD, and tooling#3
jaak0b merged 1 commit into
mainfrom
Release/7.0.0

Conversation

@jaak0b

@jaak0b jaak0b commented Jun 5, 2026

Copy link
Copy Markdown
Owner

Summary

The v7 release of the Z21 client library.

  • Protocol completeness — implement all remaining Z21 LAN protocol V1.13 features (CV/POM programming, R-BUS feedback, RailCom, LocoNet gateway, CAN, fast clock, and the zLink booster/decoder/adapter messages) as commands and response handlers, with neutral capability interfaces for programming, feedback, and fast clock. TDD test-first throughout and verified with Stryker mutation testing.
  • Documentation — a DocFX site generated from the source XML doc comments: the API reference for the five shippable assemblies plus a short landing/getting-started page, with built-in search. Published to GitHub Pages via the native Actions deployment (nothing committed). The five packable projects also emit XML docs for consumer IntelliSense.
  • Versioning & CI/CD — replace GitVersion with Nerdbank.GitVersioning (version.json + git height); split CI (Build.yml: build/test) from CD (Release.yml: publish to NuGet on push to main, with --skip-duplicate).
  • Tooling — add the Z21.SmokeTest manual hardware harness.
  • Bug fixUdpTransport now implements IDisposable, so synchronous DI container disposal no longer throws.

Testing

  • Unit and Stryker mutation suites green.
  • Verified end-to-end against a physical Z21 (firmware 1.43): connect, system info, track power, driving, and turnout switching all work.

Notes

  • Merging this PR triggers Release.yml, which packs and publishes all five NuGet packages (Z21, Z21.DependencyInjection, Z21.Autofac, CommandStation.Abstractions, CommandStation.Transport.Udp) at the nbgv-computed 7.0.x version.
  • The NuGet API key scope must include the two new CommandStation.* package IDs.
  • Documentation publishing requires Settings -> Pages -> Source = "GitHub Actions".

Code review fixes (commit efe80fa)

A max-effort review of this branch against the LAN protocol spec found and fixed the following.

Correctness

  • LocoInfo decode dropped the last function group (F21–F28, and F29–F31 on FW ≥ 1.42 frames) — an off-by-one in the function-byte loop.
  • A throwing handler CanHandle or OnBytesReceived subscriber could permanently kill all inbound handling; the dispatcher and the UDP receive loop now contain it.
  • The keep-alive timer is now stopped on a lost connection, not only on an explicit DisconnectAsync.
  • 28-step speed decode returns 0 instead of throwing KeyNotFoundException on out-of-range wire values.
  • The frame reader rejects a DataLen of 0 or above the 1472-byte limit, preventing unbounded buffering on a corrupt length prefix.

Validation & diagnostics

  • SetLocoFunction rejects a function index above the 6-bit field (0–63).
  • LAN_GET_HWINFO now surfaces the firmware version alongside the hardware type.
  • LocoSpeedOutOfRange messages corrected to 14 / 28 / 126.

Cleanup

  • Centralised the big-endian address split in IAddressCodec and used it across the four settings commands; renamed the accessory-mode parameter.
  • Added a shared length-safe MatchesFrame guard on IZ21ResponseHandler; migrated handlers off try/catch (IndexOutOfRangeException) and removed the tautological XOR checks while keeping the real checksums.
  • AccessoryModeResponseHandler now implements IZ21ResponseHandler, so LAN_GET_TURNOUTMODE responses are discovered and dispatched.

All 678 unit tests pass; Debug and Release builds are clean.

@jaak0b jaak0b merged commit 7efc542 into main Jun 5, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant