If a robot crosses a configured speed zone without the expected limit, trace the restriction from the mask to the controller before changing LiDAR settings. The mask value, its interpretation metadata, the published SpeedLimit message and the controller subscription must describe the same intended restriction. A visible colored zone alone proves none of those downstream connections.
This workflow concerns software speed restrictions in a Nav2 deployment. It does not qualify a protective field or replace an independently designed stopping function. Keep commissioning motion inside the team’s authorized test procedure. The swept-footprint workflow addresses physical clearance, which remains a separate acceptance question.
Begin with the installed ROS distribution and exact Nav2 package revision. The Jazzy SpeedLimit message distinguishes percentage limits from absolute limits, and uses zero for no restriction. This is a critical interpretation detail: publishing zero is not a request to stop the robot.
Write the expected restriction before testing
Record the map revision, mask revision, mask origin, resolution, dimensions, coordinate frame and intended zone boundary. State whether the restriction is a percentage of the controller’s maximum speed or an absolute linear speed. A note saying only that a cell is fifty leaves an important unit question unresolved.
Record the controller plugin, its normal velocity settings and every downstream component that can modify commands. Include velocity smoothing, arbitration and the base interface where applicable. The observed robot motion follows the whole command chain, not only one topic carrying a speed recommendation.
Separate the expected controller output from measured base motion. A controller accepting a limit does not establish actual deceleration, wheel traction or braking distance. The initial investigation should use stationary observation and controlled signal-path checks before the team’s approved motion acceptance trial.
Pair the mask with the correct interpretation
The CostmapFilterInfo message carries the mask topic, conversion coefficients and interpretation type. Preserve the actual received message alongside the mask. A similarly named publisher from an older configuration can supply valid messages with the wrong meaning.
Inspect the resolved namespace and topic name of both publishers and subscribers. Confirm the filter receives the intended metadata and the mask named by that metadata. Topic discovery establishes endpoint presence; use message observations to establish that the required values arrive. Apply the QoS compatibility checks if an endpoint exists but its consumer remains silent.
The versioned filter constants help distinguish speed interpretations from other filter types. Do not transfer a keepout mask’s numeric meaning into a speed mask simply because both use OccupancyGrid as their container.
| Boundary | Read-only evidence | Common interpretation error |
|---|---|---|
| Mask | Cell value and world location | Assuming a displayed color is the encoded value |
| Filter metadata | Type, base, multiplier and mask topic | Confusing percent with metres per second |
| Limit publication | Percentage flag and speed_limit | Reading zero as a stop command |
| Controller input | Resolved topic and received message | Observing the wrong namespace |
| Command output | Controller and downstream commands | Equating receipt with physical compliance |
Calculate one known cell by hand
Choose a cell well inside the intended zone, away from an ambiguous boundary. Record its world position and encoded value. Calculate the expected converted limit using the actual base and multiplier, then attach the unit interpretation. This small worksheet exposes a mismatch that can remain hidden in a large visual mask.
The Jazzy SpeedFilter implementation is the appropriate reference for the installed behavior being investigated. Its metadata handling and cell conversion should be checked together. Special mask values and no-restriction cases must be interpreted through that revision rather than through an assumed universal formula.
Repeat the calculation for an unrestricted cell and a boundary-adjacent cell. Preserve invalid or unknown cells as separate cases. Do not recolor the mask merely to make a demonstration pass before establishing how the original file was encoded and loaded. A change in image conversion can alter values without moving the visible outline much.
If the restriction appears in the wrong location, compare map geometry and transforms first. The map-artifact guide separates saved occupancy maps from other mapping artifacts; neither a correct filename nor a plausible image establishes that its origin and resolution match this deployment.
Follow the message into the controller
Observe the filter’s resolved speed-limit output topic, message type and publisher identity. Then inspect the controller’s configured subscription. Similar names with different namespaces are separate topics. Save the received percentage flag and numerical value rather than reporting only that the topic has traffic.
The controller-server source provides a versioned route from the subscription callback toward controller plugins. Check the actual plugin’s support and implementation before assuming that every third-party controller interprets a limit identically. Keep upstream receipt, plugin application and output commands as separate observations.
Identify all publishers on the limit topic. A second publisher can replace a restriction with a no-limit message or a differently interpreted value. Record ownership explicitly. Do not solve conflicting ownership by increasing message rates, because that creates a timing competition rather than a clear source of authority.
Review startup activation and mask availability. A running process can exist before its managed components are ready. Use the managed-node recovery checklist when the failure appears only after startup or restart. Preserve the original order and received states before introducing delays.
Validate entry, exit and configuration changes
Create a bounded test matrix covering a restricted interior location, an unrestricted interior location, entry, exit and restart. State the expected message sequence and controller response in advance. Include the case where metadata changes or a publisher disappears, using the behavior documented for the deployment rather than inventing an assumed fallback.
Compare controller output with downstream command topics and base feedback using identified clocks. Report observations without attributing physical speed solely to the filter. The base may apply its own limits, and the vehicle’s response depends on operating conditions outside this software interface.
Do not copy a newer distribution’s optional lookahead parameters into an older installation without checking support. A current tutorial can contain capabilities absent from the deployed revision. Preserve a working configuration and make one documented change at a time so the causal boundary remains visible.
Keep the mask, metadata, topic identities, controller revision, input and output observations in a reproducible support bundle. Mark what was checked while stationary and what was established during authorized physical trials. Neither should be described as the other.
Give every test row an explicit stop condition. If the received units disagree with the design note, preserve that evidence and resolve the conversion before attempting motion. If different publishers alternate on the limit topic, resolve ownership first. These decisions prevent an apparently successful low-speed demonstration from hiding a configuration conflict that returns after another node starts.
Finally, repeat a normal startup using the saved artifacts. Check that the same mask revision, metadata and controller configuration are actually loaded. A manually corrected running session is useful for diagnosis, but it is not a reproducible deployment until the intended configuration survives the documented startup procedure.
Frequently asked questions
Does zero mean stop?
Not in the referenced SpeedLimit contract: zero denotes no restriction. A stop function needs its own verified interface and system design.
Can the same image serve as a keepout and speed mask?
The container may be similar, but the interpretation differs. Validate the values, metadata type and intended behavior separately before reuse.
Does seeing the limit topic prove success?
No. Confirm the controller receives and applies the intended value, inspect downstream commands, and complete the deployment’s physical acceptance checks.
