Simulation

After build, verify the installed files match the source:

• Launch files: diff source vs install
• Config files: grep for the key parameter you just changed
• SDF/xacro: grep for the element you added

Known trap: This workspace has duplicate directories:

• src/franka_gazebo_bringup/ — the real colcon package (this is what gets built)
• src/franka_gazebo/franka_gazebo_bringup/ — git subdir, NOT a separate package

Always edit files in src/franka_gazebo_bringup/ (or whatever package.xml belongs to). After build, always verify the installed file has your changes.

Launch Commands — Packaged Run Mode (preferred)

Default: give the user a single script that:

1. Cleans residual processes
2. Creates a timestamped log folder in the current directory
3. Launches simulation with timeout auto-shutdown
4. Captures all relevant logs and topic samples
5. Prints a summary of what was collected

Log directory convention:

sim_logs/YYYYMMDD_HHMMSS/
├── launch.log          # Full launch stdout+stderr
├── ign_topics.log      # ign topic -l snapshot
├── ft_sensor.log       # FT sensor data sample (if applicable)
├── ros2_topics.log     # ros2 topic list snapshot
├── estimated_wrench.log # Controller wrench publisher (if applicable)
└── summary.txt         # Auto-generated: duration, exit code, key grep results

Template for packaged run script:

Every script MUST start with a build step. The user should never need to build separately.

#!/bin/bash
# — Auto-generated simulation test —
# Run from anywhere. Logs saved to sim_logs/<timestamp>/

set -e
LOG_DIR=<your_workspace>/sim_logs/$(date +%Y%m%d_%H%M%S)
mkdir -p "$LOG_DIR"
echo "Logs → $LOG_DIR"

# Build first (always)
source <ros_distro_path>/setup.bash
source <your_workspace>/install/setup.bash
colcon build \
  --build-base <your_workspace>/build \
  --install-base <your_workspace>/install \
  --base-paths <your_workspace>/src \
  --packages-select <PACKAGE_NAMES> \
  > "$LOG_DIR/build.log" 2>&1
source <your_workspace>/install/setup.bash  # re-source after build

# Clean residual processes
pkill -f "ign gazebo" 2>/dev/null || true
pkill -f "controller_manager" 2>/dev/null || true
pkill -f "robot_state_publisher" 2>/dev/null || true
sleep 2

source <your_workspace>/install/setup.bash

# Start simulation with timeout (background)
timeout <DURATION>s \
  ros2 launch <PACKAGE> <LAUNCH_FILE> <ARGS> \
  > "$LOG_DIR/launch.log" 2>&1 &
SIM_PID=$!

# Wait for controller to activate (poll launch.log)
echo "Waiting for controller activation..."
for i in $(seq 1 60); do
  if grep -q "Configured and activated" "$LOG_DIR/launch.log" 2>/dev/null; then
    echo "Controller active after ${i}s"
    break
  fi
  sleep 1
done

# Capture topic snapshots
ign topic -l > "$LOG_DIR/ign_topics.log" 2>&1 || true
ros2 topic list > "$LOG_DIR/ros2_topics.log" 2>&1 || true

# Capture topic data samples (run for a few seconds then kill)
# <ADD TOPIC-SPECIFIC CAPTURES HERE>

# Wait for simulation to finish (timeout auto-kills)
wait $SIM_PID 2>/dev/null || true
EXIT_CODE=$?

# Generate summary
{
  echo "=== Simulation Run Summary ==="
  echo "Time: $(date)"
  echo "Duration: <DURATION>s (timeout)"
  echo "Exit code: $EXIT_CODE"
  echo ""
  echo "=== Key Log Lines ==="
  grep -E "Configured and activated|Contact detected|Failed to load|\\[Err\\]|ft_sensor" \
    "$LOG_DIR/launch.log" 2>/dev/null || echo "(no key lines found)"
  echo ""
  echo "=== Ignition Topics ==="
  cat "$LOG_DIR/ign_topics.log" 2>/dev/null || echo "(empty)"
  echo ""
  echo "=== ROS 2 Topics ==="
  cat "$LOG_DIR/ros2_topics.log" 2>/dev/null || echo "(empty)"
} > "$LOG_DIR/summary.txt"

cat "$LOG_DIR/summary.txt"
echo ""
echo "Full logs: $LOG_DIR/"

When generating this script, always fill in <DURATION>, <PACKAGE>, <LAUNCH_FILE>, and add test-specific topic captures.

After the user says "跑完了", read sim_logs/ for the latest run's summary.txt and relevant logs.

Launch Commands — Manual Mode (fallback)

Only use when the user explicitly wants interactive control. Always give full blocks:

# Terminal 1 — start simulation
source <your_workspace>/install/setup.bash
ros2 launch franka_gazebo_bringup gazebo_hybrid_circle_force.launch.py

For topic inspection:

# Terminal 2
source <your_workspace>/install/setup.bash
ros2 topic list | grep <PATTERN>
ros2 topic echo <FULL_TOPIC_NAME>

For Ignition-side topics:

ign topic -l | grep <PATTERN>
ign topic -e -t <FULL_TOPIC_PATH>

Output Specification

After giving commands, always tell the user:

1. Success indicators — what lines in the log mean it worked
   • Example: "should see Configured and activated hybrid_circle_force_controller"
   • Example: "should NOT see Failed to load system plugin"
2. Failure indicators — what to watch for
   • Example: "if you see timed out, wait 10 more seconds, it's normal for large URDFs"
3. Data to paste back — what output to copy if something goes wrong
   • Example: "if it fails, paste the first error line with [Err]"

Ignition Fortress Rules

This workspace uses Ignition Gazebo Fortress (version 6). Critical naming differences:

Before writing any Gazebo plugin/sensor/system XML:

1. Find the actual .so file: ls /usr/lib/x86_64-linux-gnu/ign-gazebo-6/plugins/
2. Check the registered name: strings <file>.so | grep "ignition::gazebo"
3. Cross-reference with official franka_ros2 source (jazzy branch has Fortress examples)

Reference Official Code First

For any Gazebo/ROS integration (plugins, sensors, bridges, URDF extensions):

1. Check franka_ros2 official repo — same branch first, then jazzy
2. Check franka_ros (ROS 1) — has mature Gazebo Classic implementations
3. Check ros_gz examples — for bridge syntax and message type mappings
4. Only then write new code

Batch Experiment Script

For the standard force-control experiment:

cd <your_workspace>/src
source <your_workspace>/install/setup.bash
bash run_hybrid_circle_force_experiment.sh

This runs 1 sim (15s), collects data, generates report.md.

Process Cleanup

Before starting a new simulation, always clean residual processes:

# Kill leftover Gazebo / controller processes
pkill -f "ign gazebo" 2>/dev/null
pkill -f "controller_manager" 2>/dev/null
pkill -f "robot_state_publisher" 2>/dev/null
sleep 2

Shutdown Crash

The terminate called ... Node needs to be associated with an executor crash on Ctrl+C is a known bug in IgnitionROS2ControlPlugin destructor. It is harmless — ignore it.

Clipboard Auto-Copy

After generating a simulation run command or script, always copy it to the user's clipboard:

echo "<command>" | xclip -selection clipboard

Then tell the user: "已复制到剪切板，直接粘贴运行。"

This applies to both one-liner commands and script paths (e.g., bash <your_workspace>/run_ft_sensor_test.sh).

Checklist Before Handing Off to User

Before giving the user any simulation command:

• Did I run colcon build myself?
• Did I verify the installed files have my changes?
• Did I give complete copy-paste commands with source included?
• Did I explain what success/failure looks like in the output?
• Did I check official source code for any Gazebo plugin/sensor syntax?
• Did I copy the command to clipboard via xclip?