WidowX AI: setup and first move

Back to Resources

Use this guide for a Trossen WidowX AI arm with an Ethernet Arm Controller. First, check the label on the arm and controller. A WidowX-250 / wx250s is a different robot. For that model, use the Interbotix X-Series guide.

An end effector is the tool at the tip of the arm, such as a gripper. This lesson uses a Linux computer and the Python driver. You do not need ROS for this first test.

Hardware setup

1. Write down the arm model, controller serial number, gripper type, and controller IP address. Check whether the arm is Base, Leader, or Follower.
2. Open the matching assembly guide in Trossen Hardware Setup.
3. Fix the base firmly to the work table. Leave the arm’s movement area clear.
4. Keep the controller off while you connect power, arm, and Ethernet cables.
5. Connect the controller and the computer by Ethernet. Use only the equipment needed for this test.
6. Ask the lab supervisor to check the assembly before you turn on the controller.

Do not swap controllers between arms without checking their saved settings. Some settings are made for one arm only. Read the configuration guide.

Software installation

1. Prepare Linux and Python

Use a platform listed in the official software guide. For this guide, use Ubuntu 22.04 or 24.04 and its supported default Python. Check the Python versions listed for the driver release before installing it. Keep the robot environment separate from other projects.

sudo apt update
sudo apt install git python3-venv
python3 --version
mkdir -p ~/robot-work
cd ~/robot-work
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "trossen-arm[cli]" numpy
python -c "import trossen_arm; print('Driver import OK')"

Check: the last command prints Driver import OK. If Python is outside the supported versions for that driver release, stop and use a supported setup. Do not replace the Linux system Python.

2. Set the Ethernet address

Open the computer’s wired-network settings. Use the actual addresses recorded for your lab arm. For a controller with the factory address, enter:

Keep the computer’s Wi-Fi connection for Internet access. Do not give the computer the same IP address as the arm.

Turn on the controller and check the connection:

ping -c 4 192.168.1.2
trossen-arm discover --start 2 --end 2

The discovery command checks only 192.168.1.2. If your lab uses another address, change the network settings and discovery range to match it. For a different subnet, also set --subnet, for example trossen-arm discover --subnet 192.168.2 --start 2 --end 2 for a controller at 192.168.2.2. Read the CLI guide.

3. Match the driver and firmware

Record the firmware version shown by discovery. The driver and controller firmware must have the same major and minor version. For example, a 1.9.x controller needs a 1.9.x driver.

Only if the controller reports 1.9.x, use:

python -m pip install "trossen-arm[cli]==1.9.*"
python -m pip show trossen-arm

For another firmware series, replace 1.9 with that series. Do not upgrade or downgrade firmware only to copy this example. Ask the supervisor to check any firmware change and back up the arm settings first. See firmware compatibility.

Safety

Before a real movement:

• Ask the supervisor to check the first run with you.
• Clear people, hands, tools, and loose cables from the full movement area. Keep the gripper empty.
• Find the lab’s stop control and learn how to use it before starting.
• Check the arm’s start position and the full path to every target. A small target change can still move a long arm through nearby objects.
• Keep the existing joint limits. Do not raise force or speed limits for this lesson.

Do not use a general example until its model, gripper, IP address, and target positions match the physical setup.

First run

1. Get the official examples

cd ~/robot-work
git clone https://github.com/TrossenRobotics/trossen_arm.git
cd trossen_arm
git tag --sort=-v:refname

Choose the release tag that matches the installed driver. Open the official releases to check it. For example, only when the installed driver is 1.9.3, select:

git checkout v1.9.3

Keep the driver and examples from the same release when possible.

2. Read the movement before running it

Open demos/python/simple_move.py in VS Code. The official simple-move example assumes:

• model wxai_v0;
• a Leader end effector;
• controller IP 192.168.1.2.

It opens the gripper, moves the arm between preset positions, closes the gripper, and moves again. The current example uses gripper effort commands of 20 N and -20 N. Treat it as a real multi-joint movement, not a small jog or a no-motion test. Review the actual file from your selected release before you run it.

For a Base or Follower arm, ask the supervisor to select the matching StandardEndEffector entry in driver.configure(...). Check the hardware revision too. Do not keep the Leader value on a different arm. Change the IP address if your controller uses another address. Read the end-effector settings.

3. Run the checked example

After the hardware and path checks, activate the environment and run:

source ~/robot-work/.venv/bin/activate
cd ~/robot-work/trossen_arm
python demos/python/simple_move.py

Check: the arm follows the reviewed moves, then the program ends without a driver error. Use the hardware stop if the arm moves in an unexpected way; Ctrl+C is not a hardware stop. Keep the work area clear after the program ends because the driver releases control and puts motors into idle. Follow the hardware shutdown steps before touching the arm. Save the terminal output, driver version, firmware version, and selected arm settings in your meeting note.

For later lessons, use the demo list and Python scripting guide.

Troubleshooting

Finish this lesson: show the supervisor the connected arm, one checked movement, and your saved version and setup notes.