AR4 ROS Driver

ROS 2 driver of the AR4 robot arm from Annin Robotics. Tested with ROS 2 Jazzy on Ubuntu 24.04. Supports:

• AR4 MK1 (Original version), MK2, MK3, MK4
• AR4 servo gripper

Features:

• MoveIt control
• Gazebo simulation

Video Demo

AR4 ROS2 Tutorial

Add-on Features and Capabilities

The following projects showcases additional features and capabilities built on top of this driver:

• Hand-Eye calibration
• Teleoperation using Xbox controller
• Multi-arm control
• Voice controlled pick and place

Overview

• annin_ar4_description
  • Hardware description of arm & servo gripper urdf.
• annin_ar4_driver
  • ROS interfaces for the arm and servo gripper drivers, built on the ros2_control framework.
  • Manages joint offsets, limits and conversion between joint and actuator messages.
  • Handles communication with the microcontrollers.
• annin_ar4_firmware
  • Firmware for the Teensy and Arduino Nano microcontrollers.
• annin_ar4_moveit_config
  • MoveIt module for motion planning.
  • Controlling the arm and servo gripper through Rviz.
• annin_ar4_gazebo
  • Simulation on Gazebo.

Usage

There are two modules that you will always need to run:

1. Arm module - this can be for either a real-world or simulated arm

   • For controlling the real-world arm, you will need to run the annin_ar4_driver module
   • For the simulated arm, you will need to run the annin_ar4_gazebo module
   • Either of the modules will load the necessary hardware descriptions for MoveIt

2. MoveIt module - the annin_ar4_moveit_config module provides the MoveIt interface and RViz GUI.

The various use cases of the modules and instructions to run them are described below:

---

MoveIt Demo in RViz

If you are unfamiliar with MoveIt, it is recommended to start with this to explore planning with MoveIt in RViz. This contains neither a real-world nor a simulated arm but just a model loaded within RViz for visualisation.

The robot description, moveit interface and RViz will all be loaded in the single demo launch file

ros2 launch annin_ar4_moveit_config demo.launch.py ar_model:=mk4

---

Control real-world arm with MoveIt in RViz

Start the annin_ar4_driver module, which will load configs and the robot description:

ros2 launch annin_ar4_driver driver.launch.py ar_model:=mk4 calibrate:=True include_gripper:=True

Available Launch Arguments:

• ar_model: The model of the AR4. Options are mk1, mk2, mk3 or mk4. Defaults to mk4.
• calibrate: Whether to calibrate the robot arm (determine the absolute position of each joint).
• include_gripper: Whether to include the servo gripper. Defaults to: include_gripper:=True.
• serial_port: Serial port of the Teensy board. Defaults to: serial_port:=/dev/ttyACM0.
• arduino_serial_port: Serial port of the Arduino Nano board. Defaults to arduino_serial_port:=/dev/ttyUSB0.

⚠️📏 Note: Calibration is required after flashing firmware to the Teensy board, and power cycling the robot and/or the Teensy board. It can be skipped in subsequent runs with calibrate:=False.

Start MoveIt and RViz:

ros2 launch annin_ar4_moveit_config moveit.launch.py

You can now plan in RViz and control the real-world arm. Joint commands and joint states will be updated through the hardware interface.

NOTE: At any point you may interrupt the robot movement by pressing the E-Stop button on the robot. This would abruptly stop the robot motion! To reset the E-Stop state of the robot use the following command

ros2 run annin_ar4_driver reset_estop.sh <AR_MODEL>

where <AR_MODEL> is the model of the AR4, one of mk1, mk2, or mk3

---

Control simulated arm in Gazebo with MoveIt in RViz

Start the annin_ar4_gazebo module, which will start the Gazebo simulator and load the robot description.

ros2 launch annin_ar4_gazebo gazebo.launch.py

Start Moveit and RViz:

ros2 launch annin_ar4_moveit_config moveit.launch.py use_sim_time:=true include_gripper:=True

You can now plan in RViz and control the simulated arm.

---

Manual & Terminal Calibration Commands

The following ROS 2 commands are useful during setup, testing, and manual calibration.
All commands assume your ROS workspace has been sourced.

Open Gripper

ros2 action send_goal /gripper_controller/gripper_cmd \
  control_msgs/action/GripperCommand \
  "{command: {position: 0.012, max_effort: 0.0}}"

Close Gripper

ros2 action send_goal /gripper_controller/gripper_cmd \
  control_msgs/action/GripperCommand \
  "{command: {position: 0.000, max_effort: 0.0}}"

Command Robot to Vertical Rest / Park Position

This is the recommended pose when powering off the robot.

ros2 service call /park std_srvs/srv/Trigger "{}"

Manually Calibrate Selected Joints

ros2 service call /calibrate_mask annin_ar4_driver/srv/CalibrateMask "{mask: '000011'}"

Calibration Mask Explanation

The calibration mask is a 6-character string, one character per joint, ordered as:

[J1][J2][J3][J4][J5][J6]

Each character may be:

• 1 → Calibrate this joint
• 0 → Skip this joint

Examples:

• 000011 → Calibrate J5 and J6 only
• 111111 → Calibrate all joints
• 100000 → Calibrate J1 only
• 001100 → Calibrate J3 and J4 only

This allows selective recalibration when only certain joints have been mechanically adjusted.

---

Tuning Joint Offsets (Firmware-Level)

If your robot joints appear slightly misaligned after calibration (for example, a joint that is not perfectly vertical or horizontal when commanded to zero), joint offsets should be adjusted directly in the Teensy firmware, not in ROS configuration files.

Near the top of the Teensy sketch file, locate the following array:

float CAL_OFFSET_DEG[NUM_JOINTS] = { 1.2, -0.8, 0, 0, 0, 0 };

This array defines a per-joint angular offset in degrees that is applied after calibration to compensate for small mechanical and assembly tolerances.

Joint index mapping:

• Index 0 → J1
• Index 1 → J2
• Index 2 → J3
• Index 3 → J4
• Index 4 → J5
• Index 5 → J6

How to Tune Joint Offsets

1. Perform a normal calibration sequence.
2. Command the robot to the vertical rest / park position.
3. Using a digital level or angle gauge, measure each joint.
4. If a joint is not aligned as expected:
   • Add a positive value if the joint must rotate further in the positive direction.
   • Add a negative value if the joint must rotate back in the negative direction.
5. Update the corresponding value in CAL_OFFSET_DEG.
6. Reflash the Teensy firmware and re-run calibration.

Example

If Joint 1 requires a +1.2° correction and Joint 2 requires a −0.8° correction:

float CAL_OFFSET_DEG[NUM_JOINTS] = { 1.2, -0.8, 0, 0, 0, 0 };

Notes:

• Any change to CAL_OFFSET_DEG requires reflashing the Teensy
• These offsets are intended for fine-tuning only
• Large errors usually indicate a mechanical alignment issue

---

Switching to Position Control

By default this repo uses velocity-based joint trajectory control. It allows the arm to move a lot faster and the arm movement is also a lot smoother. If for any reason you'd like to use the simpler classic position-only control mode, you can set velocity_control_enabled: false in driver.yaml. Note that you'll need to reduce velocity and acceleration scaling in order for larger motions to succeed.

---

Gripper Overcurrent Protection

See the Gripper Overcurrent Protection page.

---

Simple Node Example (C++ / MoveIt)

This example demonstrates a minimal C++ ROS 2 node using MoveIt’s MoveGroupInterface to perform a simple pick-style motion sequence:

• open the gripper
• move the arm to a safe joint pose
• move to a pick pose
• close the gripper
• return to the safe pose

This example is intended as a starting point for writing custom ROS 2 nodes that command the AR4 through MoveIt.

---

1. Create the demo package

cd ~/ros2_ws/src

ros2 pkg create ar4_moveit_cpp_demo --build-type ament_cmake \
  --dependencies rclcpp moveit_ros_planning_interface

---

2. Add the example source files

Copy the example source file:

• simple_pick_place_mgi.cpp

into:

• ar4_moveit_cpp_demo/src/

Replace the generated CMakeLists.txt in:

• ar4_moveit_cpp_demo/

with the CMakeLists.txt provided in the example folder.

---

3. Build the workspace

cd ~/ros2_ws
colcon build
source install/setup.bash

---

4. Launch the AR4 driver

ros2 launch annin_ar4_driver driver.launch.py \
  ar_model:=mk4 calibrate:=True include_gripper:=True

---

5. Launch MoveIt

ros2 launch annin_ar4_moveit_config moveit.launch.py

---

6. Run the demo node

ros2 run ar4_moveit_cpp_demo simple_pick_place_mgi

---

Notes

• MoveIt must already be running before launching the demo node.
• The demo uses joint-space targets for the arm and named states for the gripper (open / closed) as defined in the SRDF.
• The code is intentionally minimal and designed to be easily extended for more advanced behaviors such as pose targets, collision objects, or service-based command interfaces.