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
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.
- 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.
- 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.
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
lastKnownPositioninstead 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
resolveVehiclePositionalmost never returnsOptional.empty(). WhenlastKnownPosition != null, the method falls back tolastKnownPosition(via.or(() -> Optional.ofNullable(lastKnownPosition))) whenever no point lies within the deviation tolerance. So an "empty" result only happens whenlastKnownPosition == null.lastKnownPositionrather than the geometrically nearest point — this is a silent fallback that operators cannot observe.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) toVehiclePositionResolver, e.g.:lastKnownPositiondirectly.lastKnownPosition(including the nearest point's name and its deviation vs. threshold).TRACEthe 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
DEBUG(or lower) so default deployments are unaffected.globalSyncObject/ object-repository lock.