Skip to content

Add logging to VehiclePositionResolver to aid position-resolution diagnosis #270

Description

@smartooltop

Component / Module: openTCS kernel (org.opentcs.kernel.vehicles.VehiclePositionResolver)

Background

VehiclePositionResolver#resolveVehiclePosition(Pose, String lastKnownPosition) silently resolves a vehicle's precise pose into a logical position. Its current implementation contains no logging at all — it only performs calculations and returns a result (Optional<String>).

This makes troubleshooting extremely difficult in production: when a vehicle's position is resolved unexpectedly (e.g. it keeps falling back to lastKnownPosition instead of being matched to the nearest point, or it jumps to a wrong point), operators have no trace of why the resolver made that decision.

Key silent behavior worth logging

  1. resolveVehiclePosition almost never returns Optional.empty(). When lastKnownPosition != null, the method falls back to lastKnownPosition (via .or(() -> Optional.ofNullable(lastKnownPosition))) whenever no point lies within the deviation tolerance. So an "empty" result only happens when lastKnownPosition == null.
  2. When no point matches the precise pose within tolerance, the resolver returns the old lastKnownPosition rather than the geometrically nearest point — this is a silent fallback that operators cannot observe.
  3. The deviation check (isCurrentLogicalPositionCorrect / isPrecisePositionWithinTolerance) compares distance and orientation against per-point thresholds, but neither the chosen point, the computed deviation, nor the threshold is ever logged.

Proposed change

Add DEBUG-level logging (consistent with the rest of the kernel) to VehiclePositionResolver, e.g.:

  • Log when the precise pose is matched to lastKnownPosition directly.
  • Log when no point is within tolerance and the resolver falls back to lastKnownPosition (including the nearest point's name and its deviation vs. threshold).
  • Log when a different point is selected (the matched point, its distance/angle deviation, and the threshold).
  • Optionally log at TRACE the per-point deviation scan.

This lets integrators confirm whether a position is "really matched" or merely "fallen back", without re-implementing the scan logic in their own code (as many integration projects currently must).

Acceptance Criteria

  • Logging is DEBUG (or lower) so default deployments are unaffected.
  • No logging while holding the kernel globalSyncObject / object-repository lock.
  • Logs clearly distinguish: matched-to-last-known / fallen-back-to-last-known / matched-to-different-point.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions