Setup & Teleop SO-101 Arm from Anywhere

As someone who's always been fascinated by robotic arms but intimidated by the $10K+ price tags and complex setup requirements, I was thrilled to discover the SO-ARM101 - a 3D-printable robotic arm that actually makes manipulation tasks accessible to hobbyists.

But when I got my hands on one, I hit the same frustrating wall that many makers face: setting up and using the arm was tied to a single library without a clear path to using it in a real project or integrating with other hardware.

So I built an integration for Viam that eliminates all that complexity. Instead of wrestling with cloning repos and Python scripts, you get a visual calibration tool and cross-language API that lets you focus on the fun part: actually making your arm do cool stuff.

To show what's possible, I'll walk you through setting up your SO-ARM101 and then demonstrate controlling it from the browser.

Prerequisites

• Sign up for a free Viam account, and then sign in to Viam
• Basic familiarity with SSH and command line operations
• Assembled SO-ARM101 robotic arm (assembly instructions)
• - Computer capable of running viam-server, such as a Mac, Raspberry Pi, or NVIDIA Jetson
• MicroSD card and power supply for your single-board computer, if needed
• USB data cable for connecting computer to arm control board
• Power supply for arm

Configure your machine

• In the Viam app under the LOCATIONS tab, create a machine by typing in a name and clicking Add machine.

• Once your machine is created, you are brought to your machine overview page. Click View setup instructions.

• To install viam-server on your device, select the appropriate platform, i.e. Linux/Aarch64 for a Raspberry Pi or NVIDIA Jetson. Leave the default installation method of viam-agent:

• Follow the instructions that are shown for your platform. If you are following along with a Pi or Jetson, you'll copy the command shown and run it in a SSH session on your device.
• The setup page will indicate when the machine is successfully connected.

With a machine configured, we now need to configure the arm calibration next!

Connect the SO-ARM101 to your machine

The SO-ARM101 communicates with your computer via USB connection. This section will guide you through the proper setup and verification.

Connect the USB cable:

• Use the provided USB cable to connect the SO-ARM101 control board to your computer
• You should see indicator LEDs on the control board

Verify USB detection:

• Check that the USB device is detected:

ls /dev/tty*

• Look for a device that appears when you connect the arm

Check USB serial device:

• You should see a device like /dev/ttyUSB0 or /dev/ttyACM0 on Linux, or /dev/tty.usbmodem58CD1767051 (the part after "usbmodem" is a unique ID for that control board) on MacOS

Note the path to that device on your computer, a.k.a "port". It will be used to configure your machine in the following steps.

Configure calibration sensor

Now you'll configure the calibration component that the SO-101 module provides.

This is used in tandem with a Viam App to provide convenient workflows for setting up your arm.

Add the calibration sensor

• Click the + icon in the left-hand menu and select Component or service.

• Select sensor, and find the so101:calibration model. This adds the so101-arm module for working with the SO-ARM101. Rename the default name to calibration

• Notice adding this module adds the sensor hardware component called calibration. Add the following JSON object under the CONFIGURE section of the new corresponding panel. Set the calibration_file to something descriptive for your arm, then set the `port` to the USB path connecting your arm to your computer.

{
  "calibration_file": "so101_follower.json",
  "port": "/dev/tty.usbmodem58CD1767051"
}

• Click Save in the top right to save and apply your configuration changes.

Connect to the setup app

• Open https://so101-setup_devrel.viamapplications.com/ in a new browser tab.
• Authenticate using your Viam login details.

• Select your organization, location, and machine from the relevant dropdown. This will allow the setup app to connect to viam-server running on your machine.

• Enter the name of your calibration sensor in the "Sensor Component Name" field: `calibration`

• You should see a list of available setup workflows for your arm.

Troubleshooting: If you get a 404 message after selecting your machine, please add a trailing slash `/` to the end of the URL, i.e. https://so101-setup_devrel.viamapplications.com/machine/so101-main.kw8sl6xdac.viam.cloud would become https://so101-setup_devrel.viamapplications.com/machine/so101-main.kw8sl6xdac.viam.cloud/.

Next up, you'll use this app to set up the motors and calibrate the joints of the arm.

Assign IDs to motors

Now you'll assign the expected ID to each motor of the robot arm.

If you've already completed this task when assembling the arm, skip ahead to the next step of calibration.

Walk through motor assignment

• Select "Motor Setup Only" from the list of workflows.
• Review the workspace requirements and safety requirements, then select "Begin Setup Process ->".

• Review the step by step instructions on the page, connect the gripper motor to the control board and select "Discover Motor" to find the current ID of the motor (may differ from the screenshot).

• Select "Configure Motor" to set the target ID of the motor.

• Repeat for rest of the motors (x5)
• Select "Next ->" to move on to the verification step
• Select "Verify All Motors" to confirm the motors were set up correctly.

• If verification is successful, select "Start Calibration ->" to continue to the next workflow. Otherwise, select "<- Previous" to go through the motor setup again.

Calibrate the joints of the arm

Now you'll set the home position of the arm and calibrate the range of each joint to ensure accurate movement within Viam.

If you've already completed this task when assembling the arm, you can configure the arm component to use the generated file in the next step.

Walk through joint calibration

• Select "Calibration Only" from the list of workflows (if you've skipped the motor setup).
• Review the workspace requirements and safety requirements, then select "Begin Setup Process ->".

• Review the additional safety instructions and select "Start Calibration" when ready.

• Review the positioning guidelines and arrange the arm into the home position. While holding the arm in place with one hand, select "Set Homing Position" to record the position.

• Review the recording process instructions, then select "Start Recording" to step through the range of motion for each joint of the arm. Select "Stop Recording" once you've completed this process.

• Select "Save Calibration Data" to create the required calibration file on the robot and write the relevant data to each servo motor.

• Select "Complete Setup" to review what you've accomplished.

You can now close the application and return to your machine configuration to set up the arm and gripper components in Viam.

Configure your so101 arm

Configure the arm component

• Click the + icon in the left-hand menu and select Component or service.

• Search for the so101:arm module and select it.

• Change the name to something descriptive, like follower-arm, then click Create. This adds the component for working with the first five joints of the robot.

• Notice adding this module adds the arm hardware component called follower-arm. You'll see a collapsible card on the right, where you can configure the arm component, see any errors originating from the component, and test the component directly, and the corresponding follower-arm part listed in the left sidebar. Copy the configuration from the calibration sensor and paste it into the configuration area for the arm component.

{
  "calibration_file": "so101_follower.json",
  "port": "/dev/tty.usbmodem58CD1767051"
}

• Delete the calibration sensor component to prevent conflicts with using the arm component at the same port.

• To give the arm a reference to its position and orientation within the machine's spatial environment, we'll need to add a frame. Within the Configure panel within the arm component, click Add Frame.

• Click Save in the top right to save and apply your configuration changes.

We now have a connection to the arm (and its joints). Last thing to add is the gripper.

Configure the gripper component

• Click the + icon in the left-hand menu and select Component or service.
• Search for the so101:gripper module and select it.

• Change the name to something descriptive, like follower-gripper, then click Create. This adds the module for working with the last joint of the arm, which controls the gripper.

• Notice adding this module adds the gripper hardware component called follower-gripper. You'll see a collapsible card on the right, where you can configure the gripper component, see any errors originating from the component, and test the component directly, and the corresponding follower-gripper part listed in the left sidebar. Copy the configuration from the arm component and paste it into the configuration area for the gripper.

{
  "calibration_file": "so101_follower.json",
  "port": "/dev/tty.usbmodem58CD1767051"
}

• To give the gripper a reference to its position and orientation within the machine's spatial environment, we'll need to add a frame. In the Configure panel (within the gripper component), click Add Frame. For the parent key, change the value to the name of your arm, so follower-arm:

• Click Save in the top right to save and apply your configuration changes.

Now that all of your arm's components are configured in Viam, it's time to test them out.

Test your arm

Click the CONTROL tab. If properly configured, you'll find testing panels for your arm and gripper. You should see a set of Joint Position Movement panels for the arm, and an Open/Close testing panel for the gripper.

Test the arm component

• Expand the arm's TEST panel. Here, you can test the movement of your arm's joints in different ways.

• To test the movement of specific joints, you can use the MoveToJointPositions panel. For example, to move joint 0 (the lowest on the arm), change the angle for joint 0's input, the press Execute. To test the top-most joint (in our case, where the gripper is mounted), change the angle for joint 4, then press Execute:

• Try also testing the movement to specific positions using the MoveToPosition panel. For example, to move the arm forward and backward (relative to its orientation in the world and known coordinate system), change the Y input value, then press **Execute**. To move the arm up, change the Z input value to a higher number. To move it back down, change the Z input value to a lower number. To test the rotation of the wrist, try changing the θ's input value:

Test the gripper component

• Expand the gripper's TEST panel. Here, you can test opening and closing the gripper.

• Assuming the gripper is in the default open state, test the Grab action by selecting the Grab button. To test the open action, select the **Open** button:

Conclusion and Wrap-up

🎉 Congratulations! You've successfully transformed your SO-ARM101 from a collection of servo motors into a sophisticated, controllable robotic arm. You've mastered the essential skills of robotic arm configuration, calibration, and control through Viam's powerful platform.

What You've Accomplished

✅ Motor ID Assignment: Each servo now has a unique identifier for precise control

✅ Joint Calibration: Your arm knows its exact position and movement limits

✅ Component Configuration: Both arm and gripper are ready for coordinated operation

✅ Web-Based Control: Full manual control from anywhere

✅ Foundation for Automation: Your arm is SDK-ready for programmatic control

Your Robotic Journey Continues

This tutorial marks the beginning of your exploration into advanced robotics. Your SO-ARM101 is now equipped with the intelligence and connectivity to tackle real-world automation challenges. Whether you're interested in industrial applications, research projects, or creative installations, you have the foundation to build something remarkable.

Project Ideas

Take your SO-ARM101 to the next level with these project ideas:

• PickandPlaceAutomation: Create automated sorting systems
• VisionIntegration: Add a camera for object detection and tracking
• IoTIntegration: Control your arm remotely through a custom web or mobile app
• Multi-ArmCoordination: Control multiple arms in coordinated operations

Share Your Success

We'd love to see what you build! Share your projects:

• - Tag @viamrobotics on social media
• - Submit project showcases to the community in the Viam Discord

Get Help When You Need It

Remember, you're not alone in this journey:

• Documentation: docs.viam.com for comprehensive guides
• CommunitySupport: Discord for real-time help
• IssueTracking: GitHub Issues for module-specific problems

Your SO-ARM101 is now ready to help you explore the fascinating world of robotics automation. The only limit is your imagination! 🤖✨

👉 This tutorial was originally published as a Viam codelab.