Skip to content

Add opt-in current and fault telemetry - #552

Open
BanjoR wants to merge 1 commit into
DCC-EX:masterfrom
BanjoR:codex/commandstation-ex-commandstation-current-telemetry
Open

BanjoR wants to merge 1 commit into
DCC-EX:masterfrom
BanjoR:codex/commandstation-ex-commandstation-current-telemetry

Conversation

@BanjoR

@BanjoR BanjoR commented Aug 16, 2026

Copy link
Copy Markdown

Authoritative references

Bounded scope

This refresh changes exactly five source files:

  • CommandDistributor.cpp / CommandDistributor.h: add a client-safe current/fault broadcast using the existing CommandDistributor path.
  • DCCEXParser.cpp: add opt-in <JI 1> and <JI 0> controls while preserving the existing plain <JI> query.
  • TrackManager.cpp / TrackManager.h: add disabled-by-default, 100 ms-throttled telemetry from existing current and overload/fault state.

When enabled, events use <jI TRACK CURRENT_MA FAULT> with zero-based track number, measured milliamps, and 0/1 fault state. The implementation is opt-in and broadcasts through the client-safe distributor rather than retaining the parser's transient Wi-Fi/Ethernet stream.

Explicit exclusions:

  • No change to the established plain <JI> response.
  • No new <A> or <a> protocol command and no internal RMS/history-buffer design.
  • No motor-shield calibration changes.
  • No global diagnostic default changes or GPIO instrumentation.
  • No hardware, vendor, protocol, integration, or unrelated subsystem changes.

Validation

All results below refer to head commit 37cda773.

  • PASS — git diff --check.
  • PASS — clean-worktree, live upstream-ancestry, five-file allowlist, line-ending, generated-artifact, and forbidden-change checks.
  • PASS — focused host assertions covering <JI> backward compatibility, <JI 1>/<JI 0> gating, <jI> event formatting, default-disabled state, 100 ms throttling, current/fault sources, and safe broadcast routing.
  • PASS - the exact default PlatformIO matrix on this branch completed successfully for all five configured environments: mega2560, ESP32, Nucleo-F411RE, Nucleo-F446RE, and Nucleo-F429ZI.
  • CI unavailable in the upstream PR context because the firmware workflow is push-triggered; the exact local five-environment matrix above passed. Ancillary Docs and Label runs are not firmware validation results.
  • Host-side Ztest execution is not available in this repository; the exact firmware matrix above passed, but hardware/runtime coverage remains maintainer-only.

Hardware validation

Not run—no hardware available.

Maintainer bench criteria:

  1. Build and flash the validated firmware with a supported motor shield and a configured current-sense/fault-pin setup.
  2. Connect a command client, issue <JI 1>, and verify nominal approximately-100-ms <jI TRACK CURRENT_MA 0> events for every active track, with the reported milliamps matching an independent meter or known load within the board's expected accuracy.
  3. Trigger a supported fault-pin or overload condition and verify the affected track reports <jI TRACK CURRENT_MA 1> and enters the existing overload state; clear the condition and verify recovery behavior.
  4. Issue <JI 0> and verify asynchronous events stop, while a plain <JI> still returns the established one-shot current response.
  5. Repeat with Wi-Fi/Ethernet clients and multiple clients to confirm broadcasts do not corrupt or cross-contaminate client buffers.

This pull request is ready for maintainer review; hardware validation remains outstanding; local firmware compilation is complete.

Current exact-head CI status

N/A — No BanjoR fork Actions run exists for exact head 37cda773ff695da09f23ffa8e551e90650266b57; no hosted code-test result is claimed. Local validation above is the available evidence.

@BanjoR
BanjoR marked this pull request as ready for review August 17, 2026 09:32
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