Team E 2025 wiki contribution

wiki/planning/chomp-planning.md

@@ -0,0 +1,96 @@
+---
+date: 2025-04-30
+title: CHOMP Path Planning for xArm in ROS
+---
+
+CHOMP (Covariant Hamiltonian Optimization for Motion Planning) is a powerful trajectory optimization algorithm that is well-suited for smooth, continuous path planning in robotic manipulators. In the `xarm_ros` framework, CHOMP serves as a plugin within MoveIt! to optimize planned trajectories for xArm robots. It minimizes a cost function that penalizes collisions and trajectory acceleration, allowing for fluid, human-like movements. This article explains how CHOMP works, how it is used in `xarm_ros`, and the practical dos and don'ts when configuring or deploying it.
+
+This article will help you understand the internals of CHOMP, how to enable and configure it for xArm in a MoveIt! planning context, and how to troubleshoot or tune it for improved performance. It is intended for intermediate ROS users who are integrating motion planning with industrial robotic arms.
+
+## Introduction to CHOMP
+
+CHOMP is a trajectory optimization-based planner introduced as an alternative to sampling-based methods like RRT and PRM. While sampling-based methods are probabilistically complete and effective in high-dimensional configuration spaces, they often yield jerky or suboptimal trajectories. CHOMP addresses this by performing gradient-based optimization over an initial trajectory to minimize a cost function that balances smoothness and obstacle avoidance.
+
+In `xarm_ros`, CHOMP can be selected as the motion planner within the MoveIt! planning pipeline. It operates in continuous space and iteratively refines trajectories by considering velocity and acceleration costs, as well as signed distance fields from the planning scene.
+
+### How CHOMP Works
+
+At its core, CHOMP minimizes a functional:
+$$
+\mathcal{F}(\xi) = \mathcal{F}_{\text{smooth}}(\xi) + \lambda \mathcal{F}_{\text{obstacle}}(\xi)
+$$
+Where:
+- $\mathcal{F}_{\text{smooth}}$ penalizes high accelerations,
+- $\mathcal{F}_{\text{obstacle}}$ penalizes configurations close to obstacles using signed distance fields (SDF),
+- $\lambda$ is a weighting parameter that controls the trade-off between smoothness and collision avoidance.
+
+CHOMP uses precomputed gradient information and operates on a discretized version of the trajectory (a sequence of waypoints in time). The optimization iteratively updates the trajectory to reduce total cost using gradient descent.
+
+### Enabling CHOMP in xarm_ros
+
+In MoveIt!, CHOMP is integrated as a planning plugin. To use CHOMP in your xArm robot configuration:
+
+1. Ensure `moveit_chomp_optimizer_adapter` is installed.
+2. Update your `ompl_planning.yaml`:
+
+
+3. Set CHOMP as your default planner in `moveit_config`'s `planning_pipeline_config`:
+
+
+> This is a note. CHOMP relies on well-defined signed distance fields. Use OctoMap or preprocessed collision geometries for reliable performance.
+
+## Pros and Cons
+
+**Strengths**
+- Produces smooth, natural paths.
+- Gradient-based and efficient for medium-complexity scenes.
+- Deterministic: same result for same input.
+
+**Weaknesses**
+- Local optimizer: may get stuck in local minima.
+- Requires a good initial guess.
+- Computationally heavier than RRT for very high DOF or highly constrained spaces.
+
+## Dos and Don’ts
+
+### ✅ DOs
+- **Provide a valid seed trajectory**: Use a straight-line interpolation or a quick sample-based plan.
+- **Tune weights**: Balance between obstacle avoidance and smoothness.
+- **Use OctoMap or accurate collision models**: CHOMP depends on distance fields.
+- **Use for precision tasks**: Ideal when smooth, safe motion is critical.
+- **Combine with Rviz visualizations**: Observe the planned trajectory before execution.
+
+### ❌ DON’Ts
+- **Don’t use with highly dynamic environments**: CHOMP does not replan quickly in real-time.
+- **Avoid poor initial guesses**: CHOMP needs a decent seed to converge well.
+- **Don’t ignore planning time**: Large trajectories and high-resolution scenes take time.
+- **Don’t expect global optimality**: CHOMP is a local method.
+- **Avoid using CHOMP alone for dynamic motion**: It’s not ideal for high-speed, reactive tasks.
+
+## Practical Tips for Using CHOMP with xArm
+
+- **Resolution**: More waypoints yield smoother results but increase compute time.
+- **Visualization**: Always simulate in RViz before executing on hardware.
+- **Hybrid planning**: Use RRTConnect to find a path, then refine with CHOMP.
+- **Benchmark**: Use MoveIt benchmarking tools to compare planners.
+- **Constraint tuning**: Avoid overly tight constraints unless absolutely necessary.
+
+## Summary
+
+CHOMP is a highly effective local trajectory optimizer that enhances motion planning for xArm by generating smooth and safe paths. Its deterministic and gradient-based nature makes it ideal for precision applications. However, it must be used with good initial trajectories and accurate environment models to work well. By combining CHOMP with robust environment sensing and hybrid planning strategies, it becomes a valuable tool for both industrial and research robotics.
+
+## See Also:
+- [MoveIt! Planning Pipelines](/moveit/planning_pipelines/)
+- [xarm_ros Setup Guide](/xarm/setup/)
+- [ROS Navigation Planning Concepts](/ros/navigation/)
+
+## Further Reading
+- [CHOMP: Gradient Optimization Techniques for Efficient Motion Planning](https://homes.cs.washington.edu/~joschu/docs/chomp.pdf)
+- [MoveIt CHOMP Plugin Documentation](https://moveit.picknik.ai/humble/doc/chomp_planner/chomp_planner_tutorial.html)
+- [xArm GitHub Repository](https://github.com/xArm-Developer/xarm_ros)
+
+## References
+- M. Kalakrishnan, S. Chitta, E. Theodorou, P. Pastor, and S. Schaal, “STOMP: Stochastic trajectory optimization for motion planning,” *IEEE ICRA*, 2011.
+- N. Ratliff, M. Zucker, J. A. Bagnell, and S. Srinivasa, “CHOMP: Gradient optimization techniques for efficient motion planning,” *IEEE ICRA*, 2009.
+- MoveIt! Documentation: https://moveit.picknik.ai
+- xArm SDK & ROS support: https://github.com/xArm-Developer/xarm_ros

wiki/tools/xarm_ros_guide.md

@@ -0,0 +1,103 @@
+---
+date: 2025-04-30 # YYYY-MM-DD
+title: Using xarm_ros with XArm 7 in ROS
+---
+
+This article covers the `xarm_ros` package, a valuable tool for controlling xArm robots using ROS 1 or ROS 2. It provides a low-friction setup for motion planning, Cartesian control, and basic manipulations. This entry explains how to integrate the package with your system, key components, and configurations to optimize usage for industrial, academic, or research tasks. Additionally, it discusses common pitfalls and configuration tips for reliable performance.
+
+## Introduction
+
+The `xarm_ros` package offers an easy-to-use interface for controlling the xArm 7 robot within ROS environments. By connecting directly to the hardware or a simulated robot, `xarm_ros` provides essential tools like launch files, URDF/XACRO models, and MoveIt configurations, making it easier to get started with robotics control. The goal is to minimize the complexity of setting up your robot, letting users focus on developing high-level functionalities rather than dealing with hardware details.
+
+## First Steps for Using xarm_ros
+
+To begin using `xarm_ros`, ensure the `xarm_sdk` is properly configured. This SDK is responsible for communicating with the xArm hardware, and proper configuration is essential for smooth operation. The `cxx` folder within the SDK contains important C++ files that must be correctly set up. You can find the files listed on the following [GitHub page](https://github.com/xArm-Developer/xArm-CPLUS-SDK/tree/30640642a40963d93c1cfad417469f6819ff882d).
+
+Once the SDK is set up, you can start integrating it with ROS by installing the `xarm_ros` package.
+
+## xarm_ros Directory Structure
+
+The `xarm_ros` package includes several key directories:
+
+1. **xarm_api**
+   - **Purpose:** This is the core API module that facilitates communication between ROS and the xArm controller. It wraps the xArm C++ SDK into ROS services and messages.
+
+2. **xarm_controller**
+   - **Purpose:** Contains custom controllers for the xArm robots within the ROS control framework.
+
+3. **xarm_description**
+   - **Purpose:** Contains the URDF models for the xArm robots.
+
+4. **xarm_gazebo**
+   - **Purpose:** Provides Gazebo simulation capabilities for the xArm.
+   - **Launch Command:**  
+     `roslaunch xarm_gazebo xarm[5/6/7]_gazebo.launch`
+
+5. **xarm_gripper**
+   - **Purpose:** Adds support for the xArm gripper.
+
+6. **xarm_msgs**
+   - **Purpose:** Custom ROS message and service definitions specific to xArm.
+
+7. **xarm_planner**
+   - **Purpose:** Motion planning capabilities for xArm using MoveIt.
+   - **Launch Command:**  
+     `roslaunch xarm_planner xarm_planner.launch robot:=xarm[5/6/7]`
+
+8. **xarm_vision**
+   - **Purpose:** Provides support for vision-related functionality with xArm robots.
+
+9. **xarm_moveit_config**
+   - **Purpose:** MoveIt configuration packages for xArm robots.
+   - **Launch Command:**  
+     `roslaunch xarm[5/6/7]_moveit_config demo.launch`
+
+10. **xarm_controller**
+    - **Purpose:** Implements `ros_controllers` for xArm.
+
+## Technical Caveats and Configuration Details
+
+When using the `xarm_ros` package in ROS 1, be aware of several technical caveats that could affect performance, particularly when aiming for reliable, deterministic control or robust trajectory planning.
+
+### SDK and ROS Integration
+
+The `xarm_sdk` serves as the hardware driver layer, and improper configuration can lead to inconsistencies in higher-level nodes like `xarm_api` and `xarm_controller`. Pay special attention to firmware versions to avoid subtle bugs, especially during trajectory streaming. Mismatches may cause the robot to halt or enter protective stop modes unexpectedly.
+
+### Ethernet Configuration
+
+Ensure that the correct Ethernet interface is used during the ROS launch process. Multi-interface machines or virtualized systems can sometimes cause issues, so verify your network settings with `ifconfig` or `ip link`. Ensure that the hardware MAC address aligns with the ROS parameters, and check for firewall issues that might block UDP traffic.
+
+### MoveIt Configuration
+
+It’s crucial to reference the correct manipulator planning group names in the `xarm_planner` and `xarm_moveit_config` packages. If MoveIt throws errors about mismatched planning groups or joint states, double-check your URDF and SRDF definitions, as well as the controller configuration YAML files in `xarm_controller`. Incorrect inertial or collision parameters in XACRO files can mislead the planning pipeline, potentially resulting in self-collisions or infeasible trajectories.
+
+### Debugging and Testing
+
+Test the planning scene in RViz, ensuring that planning request visualization is turned on. Use `tf_monitor` or `rqt_tf_tree` to check for discrepancies in TF frames, as delayed or missing transformations can cause issues in time-critical Cartesian control loops.
+
+Ensure proper sequencing of service calls when using the `xarm_api` service interfaces. Calls to `set_mode` and `set_state` should precede executing joint or Cartesian commands. A common failure is executing `set_mode` without first setting the state to `READY`, which will result in no feedback or errors.
+
+### Gripper Operations
+
+For gripper operations, do not rely solely on joint state publications. The gripper controller uses internal state variables, so it's crucial to initialize the gripper via the corresponding service call to ensure proper operation.
+
+### Controller Spawner Issues
+
+Be cautious of hardcoded parameters in `roslaunch` files, especially in `xarm_moveit_config`. If you are dynamically generating URDFs or modifying controller configurations, ensure that you remap the relevant parameters to avoid node startup crashes or MoveIt planning failures. Additionally, reorder the launch sequence to ensure the `joint_state_publisher` starts before MoveIt to prevent stale joint data.
+
+## Summary
+
+The `xarm_ros` package provides an efficient and straightforward method for controlling xArm robots in ROS, but attention to configuration and sequencing is critical to avoid common pitfalls. Careful setup of the SDK, Ethernet interface, and MoveIt configurations ensures reliable performance and smooth integration.
+
+## See Also:
+- [xArm ROS Documentation](https://github.com/xArm-Developer/xArm-ROS)
+- [MoveIt Documentation](https://moveit.ros.org/)
+
+## Further Reading
+- [xArm C++ SDK GitHub](https://github.com/xArm-Developer/xArm-CPLUS-SDK)
+- [ROS Control Tutorials](http://wiki.ros.org/ros_control)
+
+## References
+- [XArm ROS Package GitHub](https://github.com/xArm-Developer/xArm-ROS)
+- [ROS Wiki](http://wiki.ros.org/)
+