yihuai-gao / arx5-sdk

C++ and Python SDK for ARX5 robot arm develeoped by @yihuai-gao (@real-stanford)

C++ && Python SDK for ARX5 robot arm

Update (2024.08.15)

• Support EtherCAT-CAN adapter (follow the instructions in EtherCAT-CAN setup).
• Support arbitrary DoF robot arm (not only 6DoF); thoguh other DoF numbers are not tested yet.
• Allow setting up robot and controller configurations as arguments (see config.h and test_joint_control.py).

When updating the sdk to your codebase, please first remove the entire build folder and run the building process again.

Features

• Run without ROS
• No sudo requirement for building the library (all dependencies are managed under conda environment, thanks to Cheng Chi)
• Simple python interface with complete type hints (see python/arx5_interface.pyi)
• Joint controller runs at 500Hz in the background (motor communication delay ~0.4ms)
• Cartesian space controller with keyboard and SpaceMouse tele-operation and teach-replay (thanks to Cheng Chi)
• Control multiple arms in the same process through C++ multi-threading

Build & Install

We set up a conda environment for all the cmake dependencies, so no system package is required. If you want to run cmake and make after modifying the C++ source files, please make sure you are under the created conda environment (arx-py310 etc.).

We recommend mamba for creating conda environments, which takes only about 1min. You can also use conda, but it takes significantly longer (~10min).

mamba env create -f conda_environments/py310_environment.yaml
# if you do not have mamba, you can also use conda, which takes significantly longer
# Currently available python versions: 3.8, 3.9, 3.10, 3.11 
conda activate arx-py310
mkdir build && cd build
cmake ..
make -j
# At this point, you should be able to run test scripts below.

# To install the C++ package your system, run:
make install

EtherCAT-CAN setup

Use a USB cable to power the EtherCAT-CAN adapter and an ethernet cable to connect it to your computer. After running ip a in your terminal, you should find the interface name, usually eth. (existing ethernet port) or en.......... (additional USB-Ethernet adapters).

Then you should enable the ethernet access of your Python interpreter (usually in your bin folder). Note that which python usually gives you a symbolic link (say ~/miniforge3/envs/arx-py310/bin/python) and doesn't work in this case. You need to find out the actual file (usually python3.x).

mamba activate arx-py310
ls -l $(which python)
sudo setcap "cap_net_admin,cap_net_raw=eip" your/path/to/conda/envs/arx-py310/bin/python3.10

To run C++, you need to enable the executable every time after compiling. You also need to update the C++ scripts with the correct interface.

sudo setcap "cap_net_admin,cap_net_raw=eip" build/test_cartesian_controller
sudo setcap "cap_net_admin,cap_net_raw=eip" build/test_joint_controller

USB-CAN setup

You can skip this step if you have already set up the EtherCAT-CAN adapter.

sudo apt install can-utils
sudo apt install net-tools

There are 2 popular firmware types of usb-can adapter, SLCAN and candleLight. After plugging the adapter, you can find out the correct firmware type by the following rules:

• Run ls /dev/ttyACM*. If there is a new /dev/ttyACM* device (where * is a number), this adapter is using SLCAN firmware
• Run ip a. If there is a new can* interface (where * is a number), this adapter is using candleLight firmware.

For adapters using SLCAN framework

Get serial number by:

udevadm info -a -n /dev/ttyACM* | grep serial
# Replace the * by the actual number if there are multiple ttyACM devices connected to your computer.

You will get something like:

ATTRS{serial}=="209738924D4D"
ATTRS{serial}=="0000:00:14.0"

Then edit CAN rules file:

sudo vim /etc/udev/rules.d/arx_can.rules

Copy and paste the following, and replace the serial number with yours. If you are registering multiple adapters, you can use other SYMLINK names (e.g. arxcan1) and make sure the following commands are updated accordingly.

SUBSYSTEM=="tty", ATTRS{idVendor}=="16d0", ATTRS{idProduct}=="117e", ATTRS{serial}=="209738924D4D", SYMLINK+="arxcan0"

Finally, activate CAN connection by: (the second line should be run every time after connection)

sudo udevadm control --reload-rules && sudo udevadm trigger
sudo slcand -o -f -s8 /dev/arxcan0 can0 && sudo ifconfig can0 up

For adapters using candleLight framework

After plugging the adapter and running ip a, you should immediately find a can interface (usually can0). If you only have one arm, simply run

sudo ip link set up can0 type can bitrate 1000000

and you are good to go. You should run it every time after connecting a usb-can adaptor. If you have multiple arms and you want to fix the CAN interface name mapping for each arm, you need to register the adapter to the CAN rules:

sudo dmesg # Find the idVendor, idProduct and serial number of your adapter
sudo vim /etc/udev/rules.d/arx_can.rules

and then append the following line to your arx_can.rules. Make sure you've replaced the serial number of your adapter and your desired CAN name.

SUBSYSTEM=="net", ATTRS{idVendor}=="1d50", ATTRS{idProduct}=="606f", ATTRS{serial}=="0040001E3730511620323746", NAME="can0"

Run the following line to update the changes

sudo udevadm control --reload-rules && sudo systemctl restart systemd-udevd && sudo udevadm trigger

Finally, reconnect your adapter and run (This line should be run every time after plugging the usb-can adaptor)

sudo ip link set up can0 type can bitrate 1000000

Spacemouse setup (for Cartesian control)

All the configurations are tested using 3Dconnexion spacemouse. You can skip this step and use keyboard to test Cartesian control.

sudo apt install libspnav-dev spacenavd
sudo systemctl enable spacenavd.service
sudo systemctl start spacenavd.service

Test scripts

Arguments for test_joint_control.py, keyboard_teleop.py, spacemouse_teleop.py and teach_replay.py:

• (required) model: X5 (silver and black) or L5 (all black metal with blue or red LED light). Choosing the wrong model may lead to dangerous movements!
• (required) interface: can0, enx6c1ff70ac436 etc. (run ip a to check your interface name)
• (optional) urdf_path -u: by default ../models/arx5.urdf

cd python
python examples/test_joint_control.py X5 can0 # replace X5 with L5 for the other model 
python examples/test_bimanual.py # For two X5 arms using can0 and can1, each arm will act the same as test_joint_control.py
python examples/keyboard_teleop.py X5 can0
python examples/spacemouse_teleop.py X5 can0
python examples/teach_replay.py X5 can0

To use python sdk from other directories, please make sure ./python is in $PYTHONPATH and ./lib/x86_64 or ./lib/aarch64 (depend on your computer system) is in $LD_LIBRARY_PATH.

export PYTHONPATH=$PYTHONPATH:/path/to/your/arx5-sdk/python
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/your/arx5-sdk/lib/your_arch

After compiling the arx5_interface pybind dynamic library (usually python/arx5_interface.cpython-version-arch-linux-gnu.so), you can run it under other python environments (need to be the same python version as the one you built).

arx5-sdk's Issues

about can setup

hello yihuai,

After connecting the arx arm with my laptop. i follow your CAN setups to find out the correct firmware type. I firstly run ls /dev/ttyACM*, the terminal outputs: "Unknown device "/dev/ttyACM*": No such file or directory", then i try the second option and run ip a and there is no can* interface. All the two options fail, what is the reason? I'm sure the connection is ok.

thank you very much!

ERROR about the initialization of the ARX-X5 motors

Question Description

python examples/test_joint_control.py X5 can0

Running the above code results the following error：

All motors are not initialized. Please check the connection or power of the arm.

Error: The initialization function of the Arx5JointController class in src/app/joint_controller.cpp reports the above error when calling _init_robot().

Wish to get your help. Thanks a lot!

EtherCAT shared memory issue when controlling multiple arms

Hi Yihuai, ran into this while testing the new Ecat connection.

When attempting to control multiple arms in one Python process, the started connections interfere with each other in unpredictable ways. Sometimes this is with the second connection overriding the first one, sometimes the second connection fails to start up. I believe this can be dangerous to the robots if it leads to invalid commands sent to the motors (my arms are ok though so no harm caused).

I noticed this problem does not occur when controlling the arms separately from separate processes. I managed to replicate the issue by the following code - start the arm connections either in separate threads or in separate processes:

separate threads - issue occurs

def run_1():
    arx5_0 = arx5.Arx5JointController("L5", "enx____1")
    arx5_0.enable_background_send_recv()
    arx5_0.reset_to_home()
    arx5_0.enable_gravity_compensation("../models/arx5.urdf")
    time.sleep(5)

def run_2():
    arx5_1 = arx5.Arx5JointController("L5", "enx____2")
    arx5_1.enable_background_send_recv()
    arx5_1.reset_to_home()
    arx5_1.enable_gravity_compensation("../models/arx5.urdf")
    time.sleep(5)


def main():
    np.set_printoptions(precision=3, suppress=True)
    
    # robot_config = arx5_0.get_robot_config()
    # controller_config = arx5_0.get_controller_config()
    import threading
    t1 = threading.Thread(target=run_1)
    t2 = threading.Thread(target=run_2)

    t1.start()
    time.sleep(2)
    t2.start()
    
    time.sleep(5)
    t1.join()
    t2.join()
    exit()

separate processes - ok, no issues

def run_1():
    arx5_0 = arx5.Arx5JointController("L5", "enx____1")
    arx5_0.enable_background_send_recv()
    arx5_0.reset_to_home()
    arx5_0.enable_gravity_compensation("../models/arx5.urdf")
    time.sleep(5)

def run_2():
    arx5_1 = arx5.Arx5JointController("L5", "enx____2")
    arx5_1.enable_background_send_recv()
    arx5_1.reset_to_home()
    arx5_1.enable_gravity_compensation("../models/arx5.urdf")
    time.sleep(5)


def main():
    np.set_printoptions(precision=3, suppress=True)
    
    # robot_config = arx5_0.get_robot_config()
    # controller_config = arx5_0.get_controller_config()
    import multiprocessing
    t1 = multiprocessing.Process(target=run_1)
    t2 = multiprocessing.Process(target=run_2)

    t1.start()
    time.sleep(2)
    t2.start()
    
    time.sleep(5)
    t1.join()
    t2.join()
    exit()

Because separate processes fixes the issue (and is a workaround) I suspect there is an issue with shared memory somewhere in the c++ code or in the CAN / ECAT libraries. The issue might also occur with CAN connections, I just haven't been able to test it.

Again, thanks for the good work with this library!

ARX X5 arm communication protocols - CAN vs EtherCAT

Hey Yihuai,

Thanks for publishing this SDK, it's been a useful resource so far. I am working with the AgileX Cobot Magic robot, it comes with ARX X5 arms, but there is a catch - the arms in that robot use a protocol called EtherCAT for communication, which I believe is CAN over Ethernet.

I believe you have been in touch with ARX during this project? I wonder id you know whether they are planning to use EtherCAT for future development, or the standard CAN-based interface? It would be really useful to be able to support the EtherCAT interface as well, as I've had a lot of trouble trying to get the standard C++ code working.

To support EtherCAT, I believe some changes to the CAT libraries will be needed. The EtherCAT CAN header file looks like this:

class can
{
public:
    can();
    ~can();

    void can0_ReceiveFrame(ecat::EcatBase ecat_base);
    void Enable_Moto(ecat::EcatBase ecat_base,uint16_t ID);
    void Send_moto_Cmd1(ecat::EcatBase ecat_base, uint16_t motor_id, float kp, float kd, float pos, float spd, float tor);
    void Send_moto_Cmd2(ecat::EcatBase ecat_base, uint16_t motor_id, float kp, float kd, float pos, float spd, float tor);

};

I believe here Send_moto_Cmd1 is for the EC_A4310 joints at the base, shoulder, and elbow, while Send_moto_Cmd2 is for the wrists (I have not yet managed to get the Cmd1 working reliably). So changes to the libraries from which the shared objects are compiled to would be required.

Questions

1. Have you heard of the EtherCAT based controls for the ARX arm before, and would you consider supporting them in this library?
2. Do you know where the libhardware.so shard objects are compiled from?

Thanks!