SO-100 getting started: from the box to the first movement

What you need

• An assembled SO-100 or SO-ARM100 arm with STS3215 servos
• The matching power supply for your servo variant
• A USB-to-serial adapter and cable to your computer
• At least one USB camera
• A computer running macOS 12+, Windows 10+ or Ubuntu 22.04+

Install the client

The client bundles the robot driver, so there is no Python environment to create and no dependencies to resolve. Download the installer for your platform and run it.

The builds are not code-signed yet. On macOS, right-click the app and choose Open rather than double-clicking. On Windows, SmartScreen will show a blue box, click More info and then Run anyway.

# Or install the CLI instead, if you prefer the terminal
curl -fsSL https://www.ay-robots.com/install.sh | sh
ay-robots --version

Pair the client with your account

1. 1
   Open the pairing screen

   In your dashboard on the web, open Environments, open the environment this arm belongs to, add a robot there and follow the link to pair a real robot. The direct address is /dashboard/client/robots/new. There is no separate robots list to visit first; robots are managed under their environment.

2. 2
   Let the screen issue the code

   The pairing screen requests a one-time code while it loads, so there is nothing to press, and the code stays valid for fifteen minutes. It also tries to hand the code to a client running on the same machine straight away. If you already installed the client here, pairing finishes on its own and the screen moves to the connected state.

3. 3
   Enter the code yourself if the client sits elsewhere

   A client on another host cannot be reached from your browser, so the screen keeps the code on display for you to type. The setup wizard in the desktop client asks for it on the first screen, and the CLI takes it as an argument. Either route exchanges the code once for a permanent credential that is stored on that machine.

   bash

   ay-robots pair 7K2M-9QXR-4T8N

4. 4
   Confirm it appears online

   The pairing screen polls for the redemption and switches to a connected state within a few seconds, and a robot you started from an environment is attached to that environment for you. If nothing changes, the client is not reaching the platform; check your firewall before anything else.

Find the arm

The driver the client installs scans serial ports on its own, and you read the result in the terminal. On macOS the arm turns up as a /dev/cu.usbserial or /dev/cu.usbmodem device, on Linux as /dev/ttyUSB0 or /dev/ttyACM0. The listing prints the id the driver keeps for each device rather than that path, and the name column for the arm reads unknown, because the listing carries no name field for a serial port. Windows is the exception, see the note below.

ay-robots devices

# SERIAL PORTS
#   robot_1   unknown
# CAMERAS
#   camera_1  USB 2.0 Camera
#   camera_2  HD Webcam (gripper)

On macOS the built-in FaceTime camera and a Continuity iPhone are left out of that list on purpose, so that no camera switches itself on behind your back. What you should expect to see there are the USB cameras you plugged in yourself.

Calibrate

Calibration teaches the software where each joint physically sits. Without it, a commanded position means something different on your arm than on anyone else’s, and recorded data will not transfer.

1. 1
   Open the calibration in your dashboard

   There is no calibration screen in the desktop client. Calibration lives in the web interface: open the Hardware page for your robot in the dashboard and start it there. The wizard releases the torque on all six servos the moment it opens, so the arm goes limp straight away. Take its weight with your free hand before you begin, because an arm that was holding itself up will drop.

2. 2
   Hold the pose and capture it

   Guide each joint by hand into the pose the wizard shows, arm extended straight forward with the gripper closed, then capture. Nothing moves during a capture: the wizard reads the six servo positions and does no more than that. It then asks for a second pose with the base rotated to the left, and saves. What ends up in the calibration file is the first pose, one raw servo reading per joint plus its offset from the servo center, and that zero is what every angle you command from now on is measured against.

3. 3
   Check where that zero landed

   A calibration that is done the moment you press save has worked rather than hung, because a capture is a single read and not a sweep through the range. What matters is where the zero sits on the servo scale. A zero captured near one end leaves nothing in that direction: commands run off the end of the scale, saturate, and press the joint into its mechanical stop instead of stopping short of it. That is what the forward pose is for: it is the one meant to leave every joint near the middle of its travel. If a joint ended up far from the middle, recapture from a more neutral pose rather than living with it.

Move it

The dashboard tab in the client only reports: camera image, robot info, connection state, live values. Driving the arm happens in the web interface. In your dashboard, open Environments, pick the environment your robot sits in, and go to Manual Control. Choose the arm at the top of the control panel, switch the panel to Sliders, and move one joint a few degrees.

The sliders send a target the moment you drag one, which is why that panel has no start button, and the numbers beside them are calibrated degrees, so this is also your first honest read on the zero you just captured. Small movements first. The arm should track smoothly without buzzing or hunting around the target. Home, at the top of the slider panel, drives every joint back to that zero in one go, which is the fastest way to see whether the pose you captured is the pose you meant.

ay-robots home