BB SO-101

Beam Bots installer and operator tools for TheRobotStudio's SO-101 — a 6-DOF desktop robot arm built around Feetech STS3215 serial bus servos.

Features

• Single-command bootstrap — mix igniter.install bb_so101 scaffolds a complete robot module, supervisor wiring, and SIMULATE-aware boot options
• Full SO-101 topology — kinematic chain matches the official URDF; six revolute joints with calibrated limits and visual geometry
• Feetech wiring out of the box — composes bb_servo_feetech.install to set up controller, parameter bridge, and serial port config
• Operator mix tasks — interactive wizards for assigning servo IDs and calibrating mechanical zeroes
• Hardware-free development — run the generated project in simulation mode with SIMULATE=1

Installation

In an existing project:

mix igniter.install bb_so101

Or scaffold a new project with the dashboard included:

mix igniter.new my_robot --install bb_so101,bb_liveview

The Getting Started tutorial walks the rest of the way through powering up the arm, setting servo IDs, calibrating, and driving the dashboard.

Installer Options

The generated config/runtime.exs reads the device path from FEETECH_DEVICE, falling back to --device. The generated application.ex boots the robot in :kinematic simulation mode when SIMULATE=1 is set in the environment.

Operator Tasks

Once your project is generated and your servos are wired, two mix tasks help you bring the arm up:

# One-time: assign servo IDs 1-6 to each servo in turn
mix bb_so101.setup_servos /dev/ttyUSB0

# Per-arm: write mechanical-zero offsets so `0 rad` is the joint centre
mix bb_so101.calibrate /dev/ttyUSB0

See the Set Up Servo IDs and Calibrate the Arm how-to guides for detail.

Upgrading

mix bb_so101.upgrade

Robots generated before the joint limits were corrected declare speeds and accelerations the servos cannot reach — and since BB.Servo.Feetech.Actuator now refuses to start when the servo will not accept the acceleration it is given, such a robot will not boot. The upgrader rewrites the limits of every joint driven by a Feetech actuator, leaving joints driven by anything else alone.

The gripper's transmission offset is not something the upgrader can decide for you. Robots generated before 0.4.0 declare a 45° offset on gripper_servo, which compensated for calibration zeroing the gripper at the midpoint of its sweep. Since 0.3.0 calibration anchors that zero to the closed stop instead, so an arm recalibrated on 0.3.0 or later has the correction applied twice and its gripper sits about 45° out. Which of the two is right depends on when the arm was last calibrated, not on which version generated it, so recalibrate the gripper and drop the offset together:

mix bb_so101.calibrate /dev/ttyUSB0 --joint gripper

then delete the transmission block from the gripper_servo actuator in your robot module.

Requirements

• Elixir ~> 1.19
• An SO-101 arm (or run in simulation mode)
• A USB-to-TTL serial adapter (Feetech URT-1 or compatible) for hardware mode
• 6–7.4 V DC power for the servos

Documentation

Tutorials

• Getting Started — bootstrap a project, set servo IDs, calibrate, and drive the dashboard

How-to Guides

• Set Up Servo IDs
• Calibrate the Arm
• Run in Simulation

Full API documentation is available at HexDocs.

Related Packages

• bb — core Beam Bots framework
• bb_liveview — Phoenix LiveView dashboard
• bb_servo_feetech — Feetech STS servo driver
• feetech — Feetech serial protocol library

Acknowledgements

• TheRobotStudio for the SO-ARM100 open-source design and reference URDF
• Feetech for the STS series servos