toddlerbot.tools package

Submodules

toddlerbot.tools.audio_player_async module

toddlerbot.tools.calibrate_zero module

toddlerbot.tools.edit_keyframe module

toddlerbot.tools.joystick module

Joystick controller interface supporting multiple gaming controllers.

This module provides a unified interface for handling input from various gaming controllers including Xbox, Steam Deck, Google Stadia, and ROG Ally controllers. It maps controller inputs to robot walking commands and actions.

class toddlerbot.tools.joystick.AsusAxis(*values)

Bases: Enum

ROG Ally X Controller axis mapping.

L2 = 4
LEFT_JOYSTICK_HORIZONTAL = 0
LEFT_JOYSTICK_VERTICAL = 1
R2 = 5
RIGHT_JOYSTICK_HORIZONTAL = 2
RIGHT_JOYSTICK_VERTICAL = 3
class toddlerbot.tools.joystick.AsusButton(*values)

Bases: Enum

ROG Ally X Controller button mapping.

A = 0
B = 1
DPAD_DOWN = (0, -1)
DPAD_LEFT = (-1, 0)
DPAD_RIGHT = (1, 0)
DPAD_UP = (0, 1)
L1 = 4
MENU = 7
R1 = 5
VIEW = 6
X = 2
Y = 3
class toddlerbot.tools.joystick.DeckAxis(*values)

Bases: Enum

Steam Deck Controller axis mapping.

L2 = 9
LEFT_JOYSTICK_HORIZONTAL = 0
LEFT_JOYSTICK_VERTICAL = 1
R2 = 8
RIGHT_JOYSTICK_HORIZONTAL = 2
RIGHT_JOYSTICK_VERTICAL = 3
class toddlerbot.tools.joystick.DeckButton(*values)

Bases: Enum

Steam Deck Controller button mapping.

A = 3
B = 4
DPAD_DOWN = 17
DPAD_LEFT = 18
DPAD_RIGHT = 19
DPAD_UP = 16
L1 = 7
L4 = 20
L5 = 22
MENU = 12
R1 = 8
R4 = 21
R5 = 23
VIEW = 11
X = 5
Y = 6
class toddlerbot.tools.joystick.Joystick(dead_zone: float = 0.1)

Bases: object

Joystick controller class for handling input from a connected joystick.

get_controller_input() → Dict[str, float]

Retrieves and processes input from a connected joystick, mapping it to control actions.

This function reads the current state of the joystick, including button presses and axis movements, and translates these inputs into a dictionary of control actions with corresponding float values. It handles both button and axis inputs, applying a dead zone threshold to filter out minor movements. Special handling is applied for D-pad directions and trigger buttons (L2, R2).

Returns:

A dictionary where keys are control action names and values are the processed input values from the joystick.

Return type:

Dict[str, float]

update_walk_command(control_inputs: Dict[str, float])

Updates the walk command inputs by interpolating control values to specified ranges.

Parameters:

control_inputs (Dict[str, float]) – A dictionary containing control tasks as keys (‘walk_x’, ‘walk_y’, ‘walk_turn’) and their corresponding input values. The input values are expected to be in the range [-1, 1].

Modifies:

control_inputs: The input values for each task are updated by interpolating them to the respective ranges defined by self.walk_x_range, self.walk_y_range, and self.walk_turn_range.

class toddlerbot.tools.joystick.JoystickAction(*values)

Bases: Enum

Joystick action mapping.

A = 'look_down'
B = 'look_right'
DPAD_DOWN = 'lean_right'
DPAD_LEFT = 'twist_left'
DPAD_RIGHT = 'twist_right'
DPAD_UP = 'lean_left'
L1 = 'hug'
L2 = 'push_cart'
L4 = 'push_up'
L5 = 'dance_2'
LEFT_JOYSTICK_HORIZONTAL = 'walk_y'
LEFT_JOYSTICK_VERTICAL = 'walk_x'
MENU = 'teleop'
R1 = 'pick'
R2 = 'cuddle'
R4 = 'dance_1'
R5 = 'dance_3'
RIGHT_JOYSTICK_HORIZONTAL = 'walk_turn'
RIGHT_JOYSTICK_VERTICAL = 'squat'
VIEW = 'reset'
X = 'look_left'
Y = 'look_up'
class toddlerbot.tools.joystick.StadiaAxis(*values)

Bases: Enum

Google Stadia Controller axis mapping.

L2 = 4
LEFT_JOYSTICK_HORIZONTAL = 0
LEFT_JOYSTICK_VERTICAL = 1
R2 = 5
RIGHT_JOYSTICK_HORIZONTAL = 2
RIGHT_JOYSTICK_VERTICAL = 3
class toddlerbot.tools.joystick.StadiaButton(*values)

Bases: Enum

Google Stadia Controller button mapping.

A = 0
B = 1
DPAD_DOWN = 12
DPAD_LEFT = 13
DPAD_RIGHT = 14
DPAD_UP = 11
L1 = 9
MENU = 6
R1 = 10
VIEW = 4
X = 2
Y = 3
class toddlerbot.tools.joystick.XboxAxis(*values)

Bases: Enum

Xbox Controller axis mapping.

L2 = 2
LEFT_JOYSTICK_HORIZONTAL = 0
LEFT_JOYSTICK_VERTICAL = 1
R2 = 5
RIGHT_JOYSTICK_HORIZONTAL = 3
RIGHT_JOYSTICK_VERTICAL = 4
class toddlerbot.tools.joystick.XboxButton(*values)

Bases: Enum

Xbox Controller button mapping.

A = 0
B = 1
DPAD_DOWN = (0, -1)
DPAD_LEFT = (-1, 0)
DPAD_RIGHT = (1, 0)
DPAD_UP = (0, 1)
L1 = 4
MENU = 7
R1 = 5
VIEW = 6
X = 2
Y = 3

toddlerbot.tools.keyboard module

Keyboard input handler for robot control actions.

This module provides a simple keyboard interface for triggering specific actions via key presses. It uses pynput to capture keyboard events and map them to registered callback functions.

class toddlerbot.tools.keyboard.Keyboard

Bases: object

A class for handling keyboard input events.

check(name: str, **kwargs)

Checks and updates the state of a key input, triggering associated functions.

This method evaluates the current state of a specified key input. If the key input is active and has not been flagged, it triggers the associated function and updates the flag. If the key input is inactive and has been flagged, it resets the flag.

Parameters:

  • name (str) – The name of the key input to check.

  • **kwargs – Additional keyword arguments to pass to the associated function.

get_keyboard_input() → Dict[str, float]

Retrieve the current state of keyboard inputs.

Returns:

A dictionary mapping key identifiers to their respective input values.

Return type:

Dict[str, float]

on_press(key)

Handle key press events to update key input states.

This method updates the key_inputs dictionary based on the character of the key pressed. Specifically, it sets the value to 1.0 for the ‘save’ key when ‘s’ is pressed and for the ‘next’ key when ‘n’ is pressed. Special keys are ignored.

Parameters:

key – The key event object containing information about the key press.

on_release(key)

Handle key release events to update key input states.

This method is triggered when a key is released. It specifically checks for the ‘s’ and ‘n’ keys and resets their corresponding states in the key_inputs dictionary to 0.0. If the released key does not have a character attribute, the exception is caught and ignored.

Parameters:

key – The key event object containing information about the released key.

register(name: str, func: Callable)

Registers a function to a specified key if the key is already present in key_inputs but not in key_funcs.

Parameters:

  • name (str) – The key associated with the function to be registered.

  • func (Callable) – The function to be registered under the specified key.

toddlerbot.tools.overlay_eval module

Evaluation tool with overlay visualization.

toddlerbot.tools.overlay_eval.extract_pair_fields(data: Dict[str, Dict[str, ndarray]], pair: Tuple[str, str]) → Tuple[Dict[str, List[float]], Dict[str, List[float]]]
toddlerbot.tools.overlay_eval.load_data(path: str, robot: Robot) → Dict[str, Dict[str, ndarray]]
toddlerbot.tools.overlay_eval.main()

toddlerbot.tools.run_sysID module

System identification tool for robot parameter estimation.

toddlerbot.tools.run_sysID.evaluate(robot: Robot, sim_name: str, obs_pos_dict: Dict[str, List[ndarray[Any, dtype[float32]]]], action_dict: Dict[str, List[ndarray[Any, dtype[float32]]]], kp_dict: Dict[str, List[float]], opt_params_dict: Dict[str, Dict[str, float]], opt_values_dict: Dict[str, float], exp_folder_path: str)

Evaluates the performance of a robot simulation by comparing simulated and real joint positions, and logs the results.

Parameters:

  • robot (Robot) – The robot object containing joint and motor configurations.

  • sim_name (str) – The name of the simulator to use, e.g., “mujoco”.

  • obs_pos_dict (Dict[str, List[npt.NDArray[np.float32]]]) – Dictionary mapping joint names to lists of observed position arrays.

  • action_dict (Dict[str, List[npt.NDArray[np.float32]]]) – Dictionary mapping joint names to lists of action arrays.

  • kp_dict (Dict[str, List[float]]) – Dictionary mapping joint names to lists of proportional gain values.

  • opt_params_dict (Dict[str, Dict[str, float]]) – Dictionary of optimized parameters for each joint.

  • opt_values_dict (Dict[str, float]) – Dictionary of optimized values for each joint.

  • exp_folder_path (str) – Path to the folder where experiment results will be saved.

Raises:

ValueError – If an invalid simulator name is provided.

toddlerbot.tools.run_sysID.load_datasets(robot: Robot, data_path: str)

Loads and processes datasets from a specified path for a given robot, extracting observation positions, actions, and motor gains.

Parameters:

  • robot (Robot) – The robot instance containing motor and joint configurations.

  • data_path (str) – The directory path where the dataset files are located.

Returns:

A tuple containing three dictionaries:

  • obs_pos_dict: Maps joint names to lists of observation position arrays.

  • action_dict: Maps joint names to lists of action arrays.

  • kp_dict: Maps joint names to lists of motor gain values.

Return type:

Tuple[Dict[str, List[npt.NDArray[np.float32]]], Dict[str, List[npt.NDArray[np.float32]]], Dict[str, List[float]]]

Raises:

ValueError – If no data files are found at the specified path.

toddlerbot.tools.run_sysID.main()

Executes the SysID optimization process for a specified robot and simulator.

This function parses command-line arguments to configure the optimization process, validates the experiment folder path, and initializes the robot and experiment settings. It then loads datasets, optimizes hyperparameters, and evaluates the optimized parameters in the simulation.

Raises:

ValueError – If the specified experiment folder path does not exist.

toddlerbot.tools.run_sysID.optimize_all(robot: Robot, sim_name: str, obs_pos_dict: Dict[str, List[ndarray[Any, dtype[float32]]]], action_dict: Dict[str, List[ndarray[Any, dtype[float32]]]], kp_dict: Dict[str, List[float]], n_iters: int, early_stop_rounds: int)

Optimizes parameters for each joint of a robot using provided observation and action data.

Parameters:

  • robot (Robot) – The robot instance for which parameters are being optimized.

  • sim_name (str) – The name of the simulation.

  • obs_pos_dict (Dict[str, List[npt.NDArray[np.float32]]]) – A dictionary mapping joint names to lists of observed positions.

  • action_dict (Dict[str, List[npt.NDArray[np.float32]]]) – A dictionary mapping joint names to lists of actions taken.

  • kp_dict (Dict[str, List[float]]) – A dictionary mapping joint names to lists of proportional gain values.

  • n_iters (int) – The number of iterations for the optimization process.

  • early_stop_rounds (int) – The number of rounds for early stopping criteria.

Returns:

A tuple containing two dictionaries. The first dictionary maps joint names to their optimized parameters, and the second dictionary maps joint names to their optimized values.

Return type:

Tuple[Dict[str, Dict[str, float]], Dict[str, float]]

toddlerbot.tools.run_sysID.optimize_parameters(robot: Robot, sim_name: str, joint_name: str, obs_list: List[ndarray[Any, dtype[float32]]], action_list: List[ndarray[Any, dtype[float32]]], kp_list: List[float], n_iters: int = 1000, early_stop_rounds: int = 200, freq_max: float = 10, sampler_name: str = 'CMA', damping_range: Tuple[float, float, float] = (0.0, 0.5, 0.001), armature_range: Tuple[float, float, float] = (0.0, 0.01, 0.0001), frictionloss_range: Tuple[float, float, float] = (0.0, 1.0, 0.001), q_dot_tau_max_range: Tuple[float, float, float] = (0.0, 5.0, 0.01), q_dot_max_range: Tuple[float, float, float] = (5.0, 10.0, 0.1))

Optimize the parameters of a robot joint using simulation and Optuna.

This function performs parameter optimization for a specified joint of a robot using a simulation environment. It utilizes Optuna for hyperparameter tuning to minimize the error between simulated and observed joint positions.

Parameters:

  • robot (Robot) – The robot object containing joint and motor information.

  • sim_name (str) – The name of the simulation environment, currently supports “mujoco”.

  • joint_name (str) – The name of the joint to optimize.

  • obs_list (List[npt.NDArray[np.float32]]) – List of observed joint positions.

  • action_list (List[npt.NDArray[np.float32]]) – List of actions applied to the joint.

  • kp_list (List[float]) – List of proportional gains for the motor.

  • n_iters (int, optional) – Number of optimization iterations. Defaults to 1000.

  • early_stop_rounds (int, optional) – Number of rounds for early stopping. Defaults to 200.

  • freq_max (float, optional) – Maximum frequency for filtering in Fourier Transform. Defaults to 10.

  • sampler_name (str, optional) – Name of the Optuna sampler to use. Defaults to “CMA”.

  • damping_range (Tuple[float, float, float], optional) – Range for damping parameter. Defaults to (0.0, 0.5, 1e-3).

  • armature_range (Tuple[float, float, float], optional) – Range for armature parameter. Defaults to (0.0, 0.01, 1e-4).

  • frictionloss_range (Tuple[float, float, float], optional) – Range for friction loss parameter. Defaults to (0.0, 1.0, 1e-3).

  • q_dot_tau_max_range (Tuple[float, float, float], optional) – Range for q_dot_tau_max parameter. Defaults to (0.0, 5.0, 1e-2).

  • q_dot_max_range (Tuple[float, float, float], optional) – Range for q_dot_max parameter. Defaults to (5.0, 10.0, 1e-1).

Returns:

The best parameters found and the corresponding error value.

Return type:

Tuple[Dict[str, float], float]

Raises:

ValueError – If an invalid simulator or sampler is specified.

toddlerbot.tools.sim2real_eval module

Simulation-to-real evaluation tool for robot motor control analysis.

This module evaluates the gap between simulation and real-world robot performance by comparing motor positions, velocities, torques, and IMU data. It generates comprehensive plots and analysis to assess sim-to-real transfer quality.

toddlerbot.tools.sim2real_eval.evaluate(robot: Robot, sim_data: Dict[str, Dict[str, ndarray[Any, dtype[float32]]]], real_data: Dict[str, Dict[str, ndarray[Any, dtype[float32]]]], exp_folder_path: str)

Evaluates the performance of a robot by comparing simulated and real-world data, and generates plots to visualize the differences.

Parameters:

  • robot (Robot) – The robot object containing motor ordering and joint limits.

  • sim_data (Dict[str, Dict[str, npt.NDArray[np.float32]]]) – Simulated data for each motor, including position, velocity, action, and time sequences.

  • real_data (Dict[str, Dict[str, npt.NDArray[np.float32]]]) – Real-world data for each motor, including position, velocity, action, and time sequences.

  • exp_folder_path (str) – The path to the folder where the evaluation plots will be saved.

toddlerbot.tools.sim2real_eval.load_datasets(robot: Robot, sim_data_path: str, real_data_path: str)

Loads and processes simulation and real-world datasets for a robot.

This function reads simulation and real-world data from specified file paths, processes the data, and returns it in a structured format. The data includes observations and motor angles, which are organized into dictionaries for easy access.

Parameters:

  • robot (Robot) – The robot object containing motor ordering information.

  • sim_data_path (str) – The file path to the simulation data.

  • real_data_path (str) – The file path to the real-world data.

Returns:

A tuple containing two dictionaries. The first dictionary contains the processed simulation data, and the second contains the processed real-world data. Each dictionary is structured with keys for IMU data and motor data, organized by motor name.

Return type:

Tuple[Dict[str, Dict[str, npt.NDArray[np.float32]]], Dict[str, Dict[str, npt.NDArray[np.float32]]]]

toddlerbot.tools.sim2real_eval.main()

Runs the SysID optimization process by parsing command-line arguments, validating data paths, and evaluating optimized parameters.

This function sets up the environment for system identification by accepting command-line arguments for robot name, and paths to simulation and real-world data. It validates the existence of the specified data directories, initializes the robot, and creates a results directory with a timestamp. The function then loads the datasets and evaluates the optimized parameters.

Raises:

ValueError – If the specified simulation or real experiment folder paths do not exist.

toddlerbot.tools.teleoperate module

Teleoperation interface for robot control.

toddlerbot.tools.teleoperate.main(ip: str)

Initializes and runs a teleoperation control loop, sending joystick inputs over a ZMQ connection.

Parameters:

ip (str) – The IP address for the ZMQ connection.

The function sets up a ZMQ sender node and a joystick interface, then enters a loop to continuously read joystick inputs. It toggles logging based on a specific button press and sends control inputs as messages over the ZMQ connection. The loop runs at a fixed control rate, updating a progress bar to indicate activity. The loop can be interrupted with a keyboard interrupt, which gracefully closes the progress bar.

toddlerbot.tools.zmq_jpeg_receiver module

ZMQ JPEG image receiver for real-time video streaming.

This module receives JPEG-compressed images from a ZMQ connection and displays them in real-time with latency measurements. It’s typically used on a remote controller to view the robot’s camera feed.

toddlerbot.tools.zmq_jpeg_receiver.main()

Continuously receives and processes image data from a ZMQNode receiver.

This function initializes a ZMQNode as a receiver and enters an infinite loop to receive messages containing image data. The image data is decoded and converted to BGR format for display. The function also calculates and prints the latency of the received message.

Note

The function runs indefinitely and requires a proper setup of a ZMQNode to function correctly. It also requires OpenCV and NumPy for image processing and display.

Module contents

Tools and utilities for ToddlerBot development and operation.

This package contains various development and operational tools for working with the ToddlerBot system, including:

  • System identification and motor calibration tools

  • Zero-point calibration utilities

  • Keyframe animation editor for motion design

  • Teleoperation interfaces and controllers

  • Audio processing and communication tools

  • Simulation-to-real transfer evaluation tools

  • ZMQ-based communication utilities

  • Keyboard and joystick input handlers

These tools support the entire development workflow from initial setup and calibration through policy development, testing, and deployment on real hardware.