API & SDK Reference

Conventions

Every interface lives under the /buildo namespace. Per-arm interfaces are further scoped: /buildo/left_arm/..., /buildo/right_arm/.... All custom types live in the buildo_msgs package (buildo_msgs/msg, /srv, /action) — inspectable on-robot with ros2 interface show.

Topics

Topics are listed exactly as published — the /buildo prefix is the robot's namespace, not a remap. On a multi-robot network, separate units by ROS_DOMAIN_ID rather than renaming topics.

Services & actions

Services

Actions

follow_joint_trajectory and navigate_to_pose are deliberately stock ROS 2 types with no Buildo-specific fields — any MoveIt or Nav2 client code you already have targets them unmodified. Grasp and ExecuteSkill are the two places the API extends past the ROS 2 standard, because no standard type covers force-closed-loop grasping or language-conditioned task execution.

Message definitions

buildo_msgs/msg/HandState.msg

float64[5] finger_position     # radians, per finger
float64[5] finger_velocity     # rad/s
float64[5] fingertip_force     # newtons
std_msgs/Header header

buildo_msgs/msg/SystemMode.msg

uint8 STANDBY = 0
uint8 TELEOP = 1
uint8 AUTONOMOUS = 2
uint8 mode
string active_tier             # "system2" | "system1" | "system0"

buildo_msgs/action/Grasp.action

# Goal
string preset_name
float64 target_force           # newtons
---
# Result
bool success
float64 final_force
---
# Feedback
float64 current_force

SDK quickstart

There's one official SDK, and it's Python. C++ clients talk to the same topics, services, and actions directly through rclcpp — there's no separate C++ convenience layer to install.

Python

The Buildo SDK is a thin Python convenience layer over rclpy — every call below maps directly to the topics and actions above, so dropping to raw rclpy at any point works the same way it would for any ROS 2 node.

from buildo_sdk import BuildoClient

client = BuildoClient()
client.set_control_mode("AUTONOMOUS")

# Read joint state
state = client.get_joint_states()
print(state.left_shoulder_pitch.position)

# Command a grasp
result = client.right_hand.grasp(preset="pinch", target_force=4.0)
print(result.success, result.final_force)

# Drive the base
client.drive(linear_x=0.3, angular_z=0.0, duration_s=2.0)

# Hand off a high-level task
client.execute_skill("pick up the red cup")

C++ (rclcpp)

The same two calls directly against the generated buildo_msgs bindings — this is the pattern every other call in this reference follows from C++:

#include <rclcpp/rclcpp.hpp>
#include <rclcpp_action/rclcpp_action.hpp>
#include "buildo_msgs/srv/set_control_mode.hpp"
#include "buildo_msgs/action/grasp.hpp"

using Grasp = buildo_msgs::action::Grasp;

auto node = rclcpp::Node::make_shared("buildo_client_example");

// Set control mode
auto mode_client = node->create_client<buildo_msgs::srv::SetControlMode>(
    "/buildo/set_control_mode");
auto mode_req = std::make_shared<buildo_msgs::srv::SetControlMode::Request>();
mode_req->mode = "AUTONOMOUS";
mode_client->async_send_request(mode_req);

// Command a grasp
auto grasp_client = rclcpp_action::create_client<Grasp>(node, "/buildo/right_hand/grasp");
Grasp::Goal goal;
goal.preset_name = "pinch";
goal.target_force = 4.0;
grasp_client->async_send_goal(goal);

rclcpp::spin(node);

Parameters & versioning

buildo_hardware_interface node parameters:

buildo_msgs follows semantic versioning and is pinned per firmware release — check ros2 pkg xml buildo_msgs against your robot's firmware version before upgrading a client in the field. Breaking changes to any interface on this page land in a major version bump and a note in the release changelog, never silently.