Agile Leader Arm ROS API

1. Overview

This ROS API (alicia_duo_driver) is designed to implement serial communication with the robotic arm's low-level hardware. It is responsible for parsing received raw data and publishing the robotic arm's operating status (such as joint angles, gripper status, button information) in standard ROS message format for use by upper-level systems.

The driver consists of multiple collaborating nodes, each handling different functional modules:

• Serial Server Node (serial_server_node): Implemented in C++, responsible for serial data read/write operations with low-level hardware, including receiving, verifying, parsing, and forwarding raw data frames, while also receiving serial write requests from ROS;

• Data Type Distribution Node (serial_data_type_node.py): Implemented in Python, subscribes to raw data published by serial_server_node, classifies and parses based on Command ID in the data frame, and publishes different types of data to corresponding ROS topics;

• Servo State Processing Node (servo_states_node.py): Also implemented in Python, subscribes to servo and gripper status data published by serial_data_type_node.py, and converts it to standard ArmJointState ROS messages (in radians) for use by controllers or visualization tools.

2. System Dependencies

Before starting deployment, please ensure your system meets the following requirements:

• Operating System: Ubuntu 18.04 (Melodic) or Ubuntu 20.04 (Noetic), Ubuntu 20.04 / ROS Noetic recommended;

• ROS: ROS Melodic or ROS Noetic (Desktop-Full installation recommended);

• ROS serial library: For serial communication (sudo apt-get install ros-$ROS_DISTRO-serial).

3. Installation and Deployment

The following steps will guide you through the installation and deployment of alicia_duo_driver. This guide assumes you have ROS correctly installed and basic Linux command line operation experience.

3.1 Environment Preparation

Please ensure your ROS environment is correctly installed and initialized. If ROS is not yet installed, it's recommended to refer to the official installation guide or use the more convenient Fish-flavored ROS installation tutorial for quick deployment.

3.2 Create and Enter Catkin Workspace

# Create workspace directory
mkdir -p ~/alicia_ws/src
cd ~/alicia_ws
# Download related ROS libraries
git clone https://github.com/Xianova-Robotics/Alicia_duo_leader_ros.git ./src/
# Install and compile libraries
rosdep install --from-paths src --ignore-src -r -y
catkin_make

Note: The compilation process may take some time. If you encounter errors, please check if dependencies are correctly installed and if the code is complete.

3.3 Configure Environment

Run the following command to add workspace environment to terminal environment:

echo "source ~/alicia_ws/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

Note:

If you're using 'zsh', replace '.bashrc' with '.zshrc'.

3.4 Serial Port Permissions

Set serial port permissions:

# Method 1: Add user to dialout group (recommended, permanent)
sudo usermod -a -G dialout $USER
# Note: Logout and login again for group permissions to take effect

# Method 2: Temporarily set serial port permissions, needs to be run each terminal startup
sudo chmod 666 /dev/ttyUSB*

Hardware Connection Verification

1. Connect the robotic arm to the computer via USB;

2. Check if the serial port is recognized by the system;

ls -l /dev/ttyUSB*

• Confirm the serial port device name (e.g., ttyUSB0, ttyUSB1, etc.).

3.5 Usage Instructions

3.5.1 Launch ROS Driver

To start the robotic arm's driver and all related nodes, run the serial_server.launch file. Ensure the robotic arm is connected to the computer via USB.

roslaunch alicia_duo_leader_driver serial_server.launch 

This command will launch the following nodes:

1. serial_server_node: Handles low-level serial communication;

2. serial_data_type_node.py: Classifies and forwards serial data;

3. servo_states_node.py: Processes status data and publishes /arm_joint_state;

4. servo_control_node.py: Leader arm zeroing;

You can modify launch behavior by adding parameters, for example, enabling debug mode or specifying serial port:

# Enable debug mode
roslaunch alicia_duo_leader_driver serial_server.launch debug_mode:=true

# Specify serial port as ttyUSB0
roslaunch alicia_duo_leader_driver serial_server.launch port:=ttyUSB0

# Specify both port and enable debug
roslaunch alicia_duo_leader_driver serial_server.launch port:=ttyUSB0 debug_mode:=true

3.5.2 Running Status Reading Example

This project provides a simple Python example script (arm_read_demo.py) to demonstrate how to subscribe to and print the robotic arm's status information. Before running the example script, please complete the following preparations:

1. Press the sync button on the left side of the leader arm handle: to start status synchronization;

2. Core services are running: confirm that serial_server.launch is running;

3. Open a new terminal window: (ensure setup.bash has been sourced);

Then, run the example script:

rosrun alicia_duo_leader_driver arm_read_demo.py

The terminal will continuously print the robotic arm's joint angles (degrees and radians), gripper angle, and button states:

[INFO] [1747805831.447121]: --- Received Arm Joint State ---
[INFO] [1747805831.448002]:   Timestamp: 1747805831446895837
[INFO] [1747805831.448727]:   Joint 1: 0.70 deg (0.0123 rad)
[INFO] [1747805831.449427]:   Joint 2: -9.84 deg (-0.1718 rad)
[INFO] [1747805831.450081]:   Joint 3: 8.53 deg (0.1488 rad)
[INFO] [1747805831.450709]:   Joint 4: 0.44 deg (0.0077 rad)
[INFO] [1747805831.451373]:   Joint 5: -38.58 deg (-0.6734 rad)
[INFO] [1747805831.452103]:   Joint 6: -6.24 deg (-0.1089 rad)
[INFO] [1747805831.452744]:   Gripper: 0.00 deg (0.0000 rad)
[INFO] [1747805831.453342]:   Button 1: 1
[INFO] [1747805831.453917]:   Button 2: 0

4. Leader Arm Zeroing Method

Note:

1. This method demonstrates the standard operation method for re-zeroing the leader arm based on XuanYa's factory default zero pose. If you need to zero to another pose, please refer to Chapter 5 for related instructions;

2. Do not perform zeroing operations without necessity to avoid affecting system accuracy and operational stability.

Before resetting the robotic arm's initial position, please position the leader arm in the specified initial pose shown in the image below (XuanYa's factory default zero pose). After confirming the pose is correct, follow these steps:

1. Connect power and Type-C data cable;

2. Press the leader arm's power button to start the device.

Correct pose reference: Joint 1 maintains vertical, Joint 2 maintains 45 degrees, Joint 3 scale line aligns, Joint 4 keeps buttons facing up.

With both buttons not pressed (no blue light on), run the following code:

# In terminal 1
roslaunch alicia_duo_leader_driver serial_server.launch 
# In terminal 2
cd ~/alicia_ws/src/examples/
python3 alicia_duo_zero_calibration.py

After successful zeroing, the leader arm's pose will be fixed (motors at full torque state). Press the right button twice to restore to torque-free state.

5. ROS API Description

5.1 Main Nodes

Node Name	Type	Package	Description
serial_server_node	C++	alicia_duo_leader_driver	Responsible for low-level serial communication, data frame verification, and raw data transmission.
serial_data_type_node	Python	alicia_duo_leader_driver	Subscribes to raw serial data, forwards to different topics based on Command ID.
servo_states_node	Python	alicia_duo_leader_driver	Processes servo/gripper status, publishes standard ArmJointState messages (radians).

5.2 Important Topics

| Topic Name | Message Type | Publisher | Subscriber | Description |