Documentation
Docs Quickstart
quickstart

Quickstart

From a powered-on robot to a command you wrote yourself, in under ten minutes. This assumes Buildo is already on your network — if it isn't yet, do the bring-up steps in Overview first.

Before you start

  • Buildo is powered on, connected to your network, and you can ping buildo.local.
  • Your workstation's ROS_DOMAIN_ID matches the robot's (factory default is 0).
  • Python 3.10+ on your workstation. ROS 2 itself is not required for this page — the SDK talks to the robot directly.
Warning

This walkthrough commands a real grasp. Clear the area around both hands before running the second script.

Connect and check status

Confirm the SDK can reach the robot and see what control tier currently owns motion:

from buildo_sdk import BuildoClient

client = BuildoClient()
print(client.get_system_mode())

Expected output on a freshly booted unit:

SystemMode(mode='STANDBY', active_tier='system2')

STANDBY means actuators are backdrivable but won't accept motion commands yet — see the note on control modes in API & SDK Reference.

Your first motion: a grasp test

This script hands motion control to your process, reads one joint's position, commands a light pinch grasp on the right hand, and hands control back to STANDBY when it's done:

from buildo_sdk import BuildoClient

client = BuildoClient()

# Hand off motion control to this process
client.set_control_mode("AUTONOMOUS")

# Read the current right-arm shoulder position
state = client.get_joint_states()
print("right_shoulder_pitch:", state.right_shoulder_pitch.position, "rad")

# Command a light pinch grasp and confirm it closed
result = client.right_hand.grasp(preset="pinch", target_force=2.0)
print("grasp success:", result.success, "final_force:", result.final_force, "N")

# Hand control back when you're done
client.set_control_mode("STANDBY")

Run it

python3 first_grasp.py

Expected output:

right_shoulder_pitch: -0.042 rad
grasp success=True final_force=2.01 N

If grasp success comes back False, check /buildo/diagnostics for an ACTUATOR_OVERCURRENT or ENCODER_FAULT on the hand — see the error code table in Safety & Support.

Next steps

  • ROS 2 Integration — bring up the full stack, drive the base with Nav2, and plan multi-waypoint arm motion with MoveIt 2 instead of single preset grasps.
  • API & SDK Reference — every topic, service, and action behind the SDK calls above, plus the raw rclpy/rclcpp equivalents if you're not using Python.
  • Safety & Support — read this before you script anything that runs unattended.
  • FAQ & Troubleshooting — fixes for the connectivity and motion issues people hit most often at this stage.