Support up to 3 SC ports per rail for phase 1

[kaushikbalasundar]

Support up to 3 SC ports per rail

Summary

• Expanded SC port support from 2 ports (one per rail) to 6 total (3 per rail)
• Added automatic 30 mm minimum gap enforcement between ports on the same rail
• Fixed sc_port_1 placement: was incorrectly positioned on RAIL_1, now correctly on RAIL_0
• Added test config demonstrating 2-port, 3-port (non-contiguous), and 5-port scenarios

Port naming convention

Rail	Ports
sc_rail_0	sc_port_0, sc_port_1, sc_port_2
sc_rail_1	sc_port_3, sc_port_4, sc_port_5

Port presence is independent: any subset across both rails is valid (e.g. [sc_port_0, sc_port_3, sc_port_5]).

Changes

aic_description/urdf/task_board.urdf.xacro

• Added xacro args and instantiation blocks for sc_port_2 through sc_port_5
• Fixed sc_port_1 Y offset: 0.0705 → 0.0295 (moves it from RAIL_1 to RAIL_0)

aic_engine/src/aic_engine.cpp

• Redesigned SC rail YAML structure: each rail now holds named port keys (sc_port_N) instead of a single flat entity_present flag, allowing independent presence per port
• Added enforce_sc_port_constraints(): enforces a 30 mm minimum center-to-center gap via a forward pass (push conflicting ports forward) followed by a backward pass (pull back if the last port exceeds the rail max). Logs a warning if positions are adjusted; errors if ports cannot physically fit within rail limits.
• Added ScPortAdjustStatus enum (None, Adjusted, Overflow, Overpacked) for structured status reporting from the constraint function
• Added MAX_SC_PORTS_PER_RAIL = 3 as a namespace-level constant

aic_engine/config/sample_config_multiple_sc_ports.yaml (new)

Test config covering three scenarios:

• Trial 1: sc_port_0 + sc_port_1 on RAIL_0, gap = 40 mm
• Trial 2: sc_port_0 on RAIL_0; sc_port_3 + sc_port_5 on RAIL_1, gap = 45 mm
• Trial 3: sc_port_0/1/2 on RAIL_0 (30 mm gaps); sc_port_3/4 on RAIL_1 (30 mm gap)

Testing Instructions

Build:

colcon build --packages-select aic_engine aic_description
source install/setup.bash

Run with the multi-port test config:

ros2 launch aic_bringup aic_gz_bringup.launch.py \
  config_file:=<path_to_ws>/src/aic/aic_engine/config/sample_config_multiple_sc_ports.yaml

Trial 1: 2 ports on RAIL_0:

• Verify sc_port_0 and sc_port_1 spawn on RAIL_0, nothing on RAIL_1

Trial 2: 3 ports, non-contiguous:

• Verify sc_port_0 on RAIL_0, sc_port_3 and sc_port_5 on RAIL_1
• sc_port_1, sc_port_2, sc_port_4 should not be present
• Confirm trial 1 ports are fully removed before trial 2 spawns

Trial 3: 5 ports:

• Verify 3 ports on RAIL_0 (sc_port_0, sc_port_1, sc_port_2) and 2 on RAIL_1 (sc_port_3, sc_port_4)
• All gaps should be exactly 30 mm

Buffer enforcement:

• Edit sample_config_multiple_sc_ports.yaml to place two ports on the same rail with translations only 10 mm apart
• Confirm the engine logs a WARN and adjusts them to 30 mm apart at spawn time

[iche033]

A couple of questions:

• Do we want to havesc_port_5?
  • Should we keep to having only 5 ports as described in the task board description doc (3 on rail 0 and 2 on rail 1)?
• I think we want all 5 SC ports to be present all the time to avoid ambiguity?
  • e.g. if rail 0 only has 2 ports present, the participant won't be able to tell if they are [sc port 0, sc port1], or [sc port 0, sc port 2], or [sc port 1 and sc port 2].

[kaushikbalasundar]

A couple of questions:

• Do we want to havesc_port_5?

  • Should we keep to having only 5 ports as described in the task board description doc (3 on rail 0 and 2 on rail 1)?

• I think we want all 5 SC ports to be present all the time to avoid ambiguity?

  • e.g. if rail 0 only has 2 ports present, the participant won't be able to tell if they are [sc port 0, sc port1], or [sc port 0, sc port 2], or [sc port 1 and sc port 2].

1. If we want to support spawning 2 on rail 0 and 3 on rail 1, we will need sc_port_5. If we want to keep it hardcoded to the diagram, this would not be needed.

2. I see what you mean. Another related issue then: the implementation allows sample_config.yaml to specify any position for the ports along the rail as long as there's a gap between them and they are within max/min limits of the rails. Basically, port_1 and port_3 can be juxtaposed if the config is defined in that manner. Are you suggesting we have a unique position +/- some buffer for each port rather than allowing the user to fully define the pose in the config.yaml as it is currently written? Basically, entity_present would not be exposed and we assume that all 5 exist (enforced at the aic_engine level) and you can specify some range of motion for each port for randomization. WDYT?

Note: This can either be enforced by the engine, or our implementation can be as is, but we make this assumption that all configs will have and participants could be notified about the assumption we've made.

cc: @Yadunund