Configuración del software
Instalación del SDK, interfaz de control de cuerpo completo ROS2, lectura y comando del estado de las articulaciones, conceptos básicos de la API de locomoción, simulación de humanoides MuJoCo y los 3 principales problemas de solución de problemas.
Ir a una sección:
Instalación del SDK de Booster
El SDK de Booster se distribuye como booster_robotics_sdk_python en PyPI. Proporciona enlaces de Python a la interfaz de control de red del K1.
Crea un entorno virtual (recomendado)
python3 -m venv ~/.venvs/booster-k1
source ~/.venvs/booster-k1/bin/activateInstala el SDK
pip install booster_robotics_sdk_pythonVerifica la instalación
python3 -c "import booster_robotics_sdk; print('SDK ready')"Configuración de red
El K1 se comunica a través de Ethernet por cable. Configura la interfaz de red de tu PC host antes de conectar:
# Set your PC's Ethernet interface to 192.168.10.10
sudo ip addr add 192.168.10.10/24 dev eth0
sudo ip link set eth0 up
# Verify connectivity to the K1
ping 192.168.10.102Interfaz de control de cuerpo completo de ROS2
El K1 se envía con un nodo de puente ROS2 que expone todas las articulaciones como una interfaz de hardware estándar. ros2_control Esto permite la integración con MoveIt2, planificadores de trayectorias y controladores personalizados.
Instalada ROS2 Humilde
sudo apt update && sudo apt install software-properties-common curl -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | \
sudo apt-key add -
sudo sh -c 'echo "deb http://packages.ros.org/ros2/ubuntu jammy main" \
> /etc/apt/sources.list.d/ros2.list'
sudo apt update
sudo apt install ros-humble-desktop ros-humble-ros2-control \
ros-humble-ros2-controllers ros-humble-joint-state-publisher-gui -yClona y construye el paquete K1 de ROS2
mkdir -p ~/k1_ws/src && cd ~/k1_ws/src
git clone https://github.com/BoosterRobotics/booster_ros2.git
cd ~/k1_ws
source /opt/ros/humble/setup.bash
colcon build --symlink-installLanza el puente K1
source ~/k1_ws/install/setup.bash
ros2 launch booster_ros2 k1_bringup.launch.py \
robot_ip:=192.168.10.102Inspecciona los estados de las articulaciones
# List all available topics
ros2 topic list
# Stream joint states (22 joints at 500 Hz)
ros2 topic echo /joint_statesLectura y comando de estados de articulaciones
El SDK de Python proporciona acceso directo a las 22 articulaciones. Siempre comienza en modo DAMP antes de comandar movimiento.
Conecta y lee los estados de las articulaciones
from booster_robotics_sdk import BoosterRobot, RobotMode
# Connect to the robot
robot = BoosterRobot(ip="192.168.10.102")
robot.connect()
# Enter DAMP mode (safe, low impedance)
robot.set_mode(RobotMode.DAMP)
# Read full joint state
state = robot.get_state()
print(f"Mode: {state.mode}")
print(f"Joint positions (rad): {state.joint_positions}")
print(f"Joint velocities (rad/s): {state.joint_velocities}")
print(f"Joint torques (Nm): {state.joint_torques}")
print(f"IMU euler (deg): {state.imu_euler}")
robot.disconnect()Comanda las posiciones de las articulaciones del brazo (modo PERSONALIZADO)
El modo PERSONALIZADO permite el control directo a nivel de articulación del brazo. Requiere un dispositivo de elevación: el robot no debe estar soportando su propio peso. Ver la página de Seguridad.
from booster_robotics_sdk import BoosterRobot, RobotMode, ArmCommand
import numpy as np
robot = BoosterRobot(ip="192.168.10.102")
robot.connect()
# Transition: DAMP -> PREP -> CUSTOM
robot.set_mode(RobotMode.DAMP)
robot.set_mode(RobotMode.PREP)
import time; time.sleep(3) # Wait for PREP stabilization
robot.set_mode(RobotMode.CUSTOM)
# Command right arm to a target configuration (7 DOF)
# Joints: shoulder_pitch, shoulder_roll, shoulder_yaw,
# elbow_pitch, wrist_pitch, wrist_roll, wrist_yaw
target = [0.0, -0.3, 0.0, 0.8, 0.0, 0.0, 0.0]
cmd = ArmCommand(side="right", joint_positions=target, kp=60, kd=2)
robot.send_arm_command(cmd)
robot.disconnect()Control de la posición de la cabeza
from booster_robotics_sdk import BoosterRobot, HeadCommand
robot = BoosterRobot(ip="192.168.10.102")
robot.connect()
robot.set_mode(RobotMode.PREP)
# Head: yaw in [-90, 90] deg, pitch in [-40, 30] deg
cmd = HeadCommand(yaw_deg=15.0, pitch_deg=-10.0)
robot.send_head_command(cmd)
robot.disconnect()Fundamentos de la API de Locomoción
El controlador de locomoción del K1 gestiona el equilibrio y la marcha de forma autónoma. Usted ordena los objetivos de velocidad; el controlador a bordo maneja la estabilidad. Siempre tenga un observador presente.
Secuencia de transición de modo
from booster_robotics_sdk import BoosterRobot, RobotMode, LocomotionCommand
import time
robot = BoosterRobot(ip="192.168.10.102")
robot.connect()
# Step 1: Enter DAMP (zero torque, safe to handle)
robot.set_mode(RobotMode.DAMP)
time.sleep(1)
# Step 2: Enter PREP (stand up to PREP posture)
robot.set_mode(RobotMode.PREP)
time.sleep(5) # Wait for full PREP stabilization — do not skip
# Step 3: Enter WALK
robot.set_mode(RobotMode.WALK)
time.sleep(2)Comando de locomoción (modo de velocidad)
# Walk forward at 0.3 m/s
cmd = LocomotionCommand(
vx=0.3, # forward/back (m/s), range: [-0.5, 0.5]
vy=0.0, # lateral (m/s), range: [-0.3, 0.3]
vyaw=0.0 # rotation (rad/s), range: [-1.0, 1.0]
)
robot.send_locomotion_command(cmd)
time.sleep(2)
# Stop
robot.send_locomotion_command(LocomotionCommand(vx=0, vy=0, vyaw=0))
time.sleep(1)
# Return to PREP then DAMP
robot.set_mode(RobotMode.PREP)
time.sleep(3)
robot.set_mode(RobotMode.DAMP)
robot.disconnect()Parada de emergencia en software
# Call from any thread — immediately enters DAMP mode
robot.emergency_stop()Siempre prefiera el botón de parada de emergencia de hardware para emergencias. La parada de emergencia en software es solo una copia de seguridad.
Simulación Humanoide de MuJoCo
El modelo URDF del K1 está incluido en el SDK. Use MuJoCo para desarrollar y probar políticas de locomoción y manipulación antes del despliegue en hardware.
Instalar MuJoCo
pip install mujocoClonar el entorno de gimnasio K1
git clone https://github.com/BoosterRobotics/booster_gym.git
cd booster_gym
pip install -e .Ejecutar la simulación de caminata
python examples/walk_sim.py --renderIsaac Sim (avanzado)
NVIDIA Isaac Sim proporciona simulación paralela acelerada por GPU para entrenamiento de políticas a gran escala. El URDF del K1 se importa de manera limpia en Isaac Sim 4.x. Requiere una GPU NVIDIA (se recomienda 16 GB de VRAM) y licencia de Isaac Sim. Ver los Artículo de Comparación Humanoide benchmarks de simulación.
Alineación de Sim-a-Real — El modelo MuJoCo del K1 incluye parámetros de inercia calibrados y límites de articulación que coinciden con el hardware real. Las políticas entrenadas en simulación pueden ser desplegadas con un ajuste mínimo de ganancia.
Principales 3 problemas para la configuración del humanoide
Connection refused / ping timeout
El problema más común. Casi siempre es una mala configuración de red en el lado del PC host.
Solución:
# 1. Verify your PC's interface is on the correct subnet
ip addr show eth0
# Should show 192.168.10.10/24
# 2. Set it if not configured
sudo ip addr flush dev eth0
sudo ip addr add 192.168.10.10/24 dev eth0
sudo ip link set eth0 up
# 3. Ping the robot
ping -c 4 192.168.10.102
# 4. If ping fails, verify the K1 is fully booted
# The K1 takes ~60 seconds to boot. Look for the LED sequence
# to complete before attempting connection.El K1 requiere al menos 3 segundos en PREP para que el controlador de equilibrio se inicialice. Transicionar demasiado rápido es la causa más común de caídas durante la primera configuración.
Solución:
# Always wait at least 5 seconds in PREP before WALK
robot.set_mode(RobotMode.PREP)
time.sleep(5) # Do not reduce this
# Verify PREP is fully active before proceeding
state = robot.get_state()
assert state.mode == RobotMode.PREP, "PREP not confirmed"
# Have your spotter positioned with the e-stop
robot.set_mode(RobotMode.WALK)hardware interface not found
El puente ROS2 no puede encontrar la interfaz de hardware del K1. Generalmente causado por paquetes faltantes o una IP de robot incorrecta en el archivo de lanzamiento.
Solución:
# 1. Install missing ros2_control packages
sudo apt install ros-humble-ros2-control \
ros-humble-ros2-controllers -y
# 2. Rebuild the workspace
cd ~/k1_ws && colcon build --symlink-install
# 3. Source both ROS2 and your workspace
source /opt/ros/humble/setup.bash
source ~/k1_ws/install/setup.bash
# 4. Verify robot_ip matches actual K1 IP
ros2 launch booster_ros2 k1_bringup.launch.py \
robot_ip:=192.168.10.102
# 5. Check the K1 is connected and responding
ping 192.168.10.102¿Aún atascado? Publica en el Foro SVRC con tu versión de Ubuntu, mensaje de error exacto y versión del SDK (pip show booster_robotics_sdk_python).