🚀 Quick Start Guide¶
This guide helps you complete the basic setup and first run of the OpenArmX bimanual robot.
⚠️ Read Before You Start
Please read this guide carefully before operating OpenArmX. Operate safely and at your own risk.
- Read the Safety Statement first
- Make sure a hardware emergency stop button is available
- First-time use should be supervised by professional personnel
- Do not use this product if the above requirements are not met
📞 If you encounter issues during operation, contact Technical Support.
📦 User-Provided Items¶
Prepare the following items before unboxing.
| No. | Item | Image | Notes |
|---|---|---|---|
| 1 | G Clamp |  |
At least 2 for fixing the robot arm to the desk |
| 2 | Monitor |  |
For debugging and visualization |
| 3 | HDMI Cable |  |
Connects the host computer and monitor |
| 4 | Keyboard & Mouse |  |
For operating the host computer |
🎯 Unboxing and Self-Check Guide¶
This section guides you through safe and systematic verification from unboxing to basic functional checks, confirming that the robot is ready for development.
⚠️ Safety Preparation and Unboxing¶
Principle: Inspect first, power on later; keep static first, then move step by step.
- Environment: Clean, dry, flat, and stable tabletop
- Handling: Hold the main robot structure while moving; do not pull cables or single joints
- Power: Do not connect power before completing this stage
📝 Accessory Inventory and Visual Inspection¶
Take out each item and inspect against the table below.
| No. | Item | Image | Qty | Inspection Points |
|---|---|---|---|---|
| 1 | Packaging Box |  |
1 | No outer damage, moisture, or crushing deformation |
| 2 | Robot Main Body |  |
1 | No deformation, cracks, or deep scratches |
| 3 | 48V Power Adapter |  |
1 | Correct voltage label, no cable damage |
| 4 | PCAN-USB Adapter |  |
1 | USB metal contacts not bent or corroded |
| 5 | CAN Communication Cable |  |
2 | Pre-installed on the robot body!! ⚠️ Handle carefully during removal; cables may tangle. End latches intact, cable body not squeezed |
| 6 | Power Cable |  |
1 | Pre-installed on the robot body!! Check plug for burn marks and insulation damage |
📦 Unboxing and Hardware Wiring Video¶
Video in production, coming soon!
ℹ️ Found an issue? Stop immediately and do not power on. Take photos of the problem area, outer box, and serial-number label, keep everything as-is, and contact Technical Support.
⚡ Step 2: Motor Test¶
This step verifies whether robot joints are functioning properly.
Video in production, coming soon!
🎯 Step 3: Launch MoveIt¶
This step verifies that the ROS 2 + MoveIt basic motion-planning pipeline is available, including:
- Whether the robot model (URDF / SRDF) is correct
- Whether the planner can generate an executable joint trajectory
- Whether the planned result can be sent correctly to drive robot motion
Recommended Real-Robot Launch: MIT + Gravity Compensation¶
Use the command below for the standard real-robot MoveIt workflow. enable_forward_effort:=true starts the effort controllers and gravity-compensation node; the feedforward torque changes with the robot posture and reduces MIT gravity sag.
cd ~/openarmx_ws
source install/setup.bash
ros2 launch openarmx_bimanual_moveit_config demo.launch.py \
control_mode:=mit \
enable_forward_effort:=true
Before launching, verify that the emergency stop is reachable, the workspace is clear, can0/can1 are configured, and all joints are near zero (within 30°).
MIT vs. CSP¶
Select the mode with control_mode. Stop the current program and relaunch when switching modes.
| Mode | Characteristics | Advantages | Important limitations |
|---|---|---|---|
mit (recommended) |
Motion control with position, velocity, KP, KD, and feedforward torque | Supports gravity compensation, torque control, and compliant teaching; suitable for MoveIt | Requires sensible KP/KD tuning; without compensation, static error may be about 6° |
csp |
CiA402 cyclic synchronous position control | Higher stiffness and position accuracy | Very low payload capability. Do not add an end-effector load; load or stall can quickly overheat or burn the motors. CSP does not use effort feedforward torque, so it does not provide the gravity-compensation behavior above |
For CSP testing (unloaded, low speed, short duration only):
ros2 launch openarmx_bimanual_moveit_config demo.launch.py control_mode:=csp
Use MIT whenever gravity compensation is required:
ros2 launch openarmx_bimanual_moveit_config demo.launch.py \
control_mode:=mit enable_forward_effort:=true
Video in production, coming soon!
Note:
The following notes about mild jitter, sag, and non-smooth motion apply to the MIT MoveIt configuration without gravity compensation (enable_forward_effort:=false). With pure PD control, gravity can produce noticeable steady-state error and jitter.
When MIT gravity compensation is enabled (enable_forward_effort:=true), posture-dependent feedforward torque is injected in real time, so gravity-induced sag and jitter should be significantly reduced. If jitter remains, inspect the trajectory and controller parameters below; it should not be treated as an inevitable behavior with gravity compensation enabled.
This is because MoveIt is not a low-level real-time controller. Instead, it:
- Discretizes planned trajectories into multiple time points
- Sends them to the robot controller at a fixed frequency
Without gravity compensation, poor speed / acceleration / jerk matching combines with gravity steady-state error and may cause frequent acceleration/deceleration, appearing as jitter or non-smooth motion.
Mitigation options include:
- Reducing speed and acceleration limits in MoveIt appropriately
- Tuning robot controller PID parameters to improve system stiffness
Please note:
This step only verifies that "basic motion planning is available". It does not mean motion quality, dynamic performance, or engineering-level smoothness has reached the optimum.
If you need higher smoothness or industrial-grade trajectory quality, consider specialized trajectory planning or time-parameterization solutions (for example, time-optimal planning or industrial-controller-based methods).
Or use our robot joint motion control plugin to control robot movement!
✅ Verification Checklist¶
Complete the checks below to confirm the system is running normally:
| Check Item | Simulation | Real Robot | Notes |
|---|---|---|---|
| CAN interface status | - | ✓ | Single-arm: can0/can1; bimanual: can0~can3 are all UP |
| Motor enable | - | ✓ | No error messages |
| Motor test | - | ✓ | Motor rotates smoothly |
| RViz display | ✓ | ✓ | Robot model displays correctly |
| Motion planning | ✓ | ✓ | Follows planned path |
| Gravity compensation | - | ✓ | With MIT, verify the effort controller is active |
| Control mode | - | ✓ | control_mode:=mit or control_mode:=csp |
| Emergency stop button | - | ✓ | Pressing it cuts motor power immediately |
🎉 Congratulations!¶
You have completed the OpenArmX basic function verification and can now explore more advanced features.
Technical Support¶
Place technical support details here, such as a WeChat QR code.