Skip to main content

Agile Python SDK User Guide

1. Introduction​

The Agile Python SDK (https://github.com/Xuanya-Robotics/Alicia_duo_sdk) is a Python toolkit for controlling six-axis robotic arms (with gripper). It provides functionality for serial communication with the robotic arm, joint motion control, gripper operation, and status information reading.

1.1 Main Features​

  • Joint Control: Set and read angles of six joints.

  • Gripper Control: Control the opening and closing angle of the gripper.

  • Torque Control: Enable or disable robotic arm joint torque, allowing free dragging or position locking.

  • Zero Point Setting: Set the current position of the robotic arm as the new zero point.

  • Status Reading: Get real-time data of joint angles, gripper angle, and button states.

  • Serial Communication: Automatic port finding or specified port connection.

  • Data Parsing: Parse feedback data frames from the robotic arm.

2. Installation​

Clone the Agile Python SDK library:

git clone https://github.com/Xianova-Robotics/Alicia_duo_sdk.git
cd Alicia_duo_sdk

Install dependencies:

pip install pyserial
conda install -c conda-forge python-orocos-kdl
pip install -r requirements.txt

Hardware connection:

2.1 Verify Installation​

After connecting the robotic arm, run the following code in the terminal:

cd examples
python3 read_angles.py

If successfully installed and configured, you will see continuous output of the robotic arm's joint angles, gripper angle, and button states in the terminal. Press Ctrl+C to exit the program.

2.2 Troubleshooting​

If unable to connect to the robotic arm / no available serial port found, please refer to the following:

  • Check if the USB cable is firmly connected.

  • Ensure the robotic arm is powered on.

  • Confirm that your user has permission to access serial port devices (on Linux, you may need to add the user to the dialout group, e.g., sudo usermod -a -G dialout $USER, then log out and log back in).

  • If the SDK cannot automatically find the port, you can manually specify the port when initializing ArmController, for example:

# filepath: examples/your_script.py
# ...existing code...
# controller = ArmController() # Auto search
controller = ArmController(port="/dev/ttyUSB0") # Linux example
# controller = ArmController(port="COM3") # Windows example
# ...existing code...

  • Permission denied error:

    • On Linux, try running with sudo python3 your_script.py, or add the user to the dialout group as mentioned above.

3. Example Code Description​

The examples directory contains Python scripts demonstrating how to interact with the robotic arm using the Alicia Duo SDK.

3.1 read_angles.py​

This example connects to the robotic arm and continuously reads and displays the angles of all six joints (in degrees), the gripper opening angle (in degrees), and the states of two buttons on the gripper. It also includes how to enable debug mode for more detailed log output.

  • Main Functions:

    • Initialize ArmController (can include debug_mode=True).

    • Connect to the robotic arm (controller.connect()).

    • Loop to read complete joint state (controller.read_joint_state()).

    • Extract angles and button information from the JointState object.

    • Convert radians to degrees (controller.RAD_TO_DEG).

    • Gracefully handle KeyboardInterrupt (Ctrl+C) to disconnect.

    • Disconnect from the robotic arm (controller.disconnect()).

3.2 arm_movement.py​

Demonstrates how to control the robotic arm for various types of movements, including moving all joints to zero position, individual joint testing, simulated wave motion, torque control (enable/disable), setting current position as zero point, and a complete simulated pick-and-place process.

  • Main Functions:

    • Read initial joint state.

    • Set all joints to specified angles (controller.set_joint_angles()).

    • Angle unit conversion (controller.DEG_TO_RAD, controller.RAD_TO_DEG).

    • Disable and enable joint torque (controller.disable_torque(), controller.enable_torque()).

    • Set current position as zero point (controller.set_zero_position()).

    • Control gripper opening and closing (controller.set_gripper()).

    • Add delays between actions using time.sleep().

3.3 gripper_control.py​

  • File: examples/gripper_control.py

  • Description: This example focuses on controlling the robotic arm's gripper. It demonstrates how to set the gripper to fully open, half-closed, and fully closed positions, and read the actual gripper angle and button states. Additionally, it provides an interactive mode allowing users to control the gripper angle through keyboard input.

  • Main Functions:

    • Set gripper angle (controller.set_gripper()).

    • Read gripper data (angle and button states) (controller.read_gripper_data()).

    • Interactive user input handling.

    • Reset gripper to open position before program end.