The complete kit uses an 8 × 8 ToF module to measure the area in front of Duck. It provides a configurable forward speed limit; it is not a navigation or fall-prevention system.

Check live ranging

  • Open the cockpit ranging view and move a large, opaque object in front of the sensor. Confirm the grid changes.

  • The sensor publishes new frames at about 5 Hz. The displayed central distance is the median of four central zones; the motion limit uses the minimum valid distance in the central 4 × 4 area. Those values need not match.

  • For a software check, request /api/tof/status repeatedly: state should be ranging, fresh should be true, seq should increase and valid_zones should be above zero. An HTTP 200 response alone is insufficient.

Understand the thresholds

Forward speedSlow distanceStop distance
Up to 0.2 m/s15 cm10 cm
0.3 m/s22.5 cm17.5 cm
0.4 m/s30 cm25 cm

Above 0.2 m/s, each additional 0.1 m/s adds 7.5 cm to both thresholds. When an obstacle blocks forward travel, center the movement control and issue a fresh command after the path is clear; do not assume a held command will resume safely.

Limits of the feature. It limits forward commands in walking and skating. It does not protect reverse or sideways movement, preset actions, stairs or transparent/reflective obstacles. Missing, offline or stale sensor data (over 600 ms), or no valid zones, can allow forward motion; sensor failure is not a guaranteed stop. An invalid configuration can pause operation until corrected.

Adjust only after checking the sensor

Settings are stored in data/obstacle-avoidance.json. Back up the file before editing and use the runtime’s supported settings and validation. Start with the supplied thresholds and a clear test area; lowering them reduces room to stop.

If the grid does not update

ToF still undetected after reboot: If the connected ToF is still missing after the acceptance reboot, mark it “pending retest.” Manually turn Duck’s power switch off and on once. After startup, check /api/tof/status again for state=ranging, fresh=true, an increasing seq and valid_zones > 0. Do not mark the sensor as passed before retesting.

  • Power off and check the ToF cable, 3.3 V supply and Wire1 connection in the wiring chapter.

  • Check the App status and fresh frame counters. Compare with python /app/tools/read-tof.py --seconds 4 inside the existing App container if needed.

  • Do not run a second sensor process continuously alongside the App or replace working wiring merely because the grid has no valid target.