SAMI ROS-Based Simulator Overview

The simulator is implemented within a ROS 2 environment and uses RViz as the physics-based simulation platform for validating SAMI’s JSON-defined behavior files. Its primary purpose is to provide a controlled and safe testing environment where behaviors can be evaluated before deployment on the physical robot, reducing the risk of hardware damage. The simulator parses the JSON behavior descriptions and executes the corresponding actions through the ROS 2 simulation stack in RViz. In addition, the system includes a graphical user interface (GUI) that enables users to interact with and manipulate SAMI within the simulated environment. While the GUI supports user interaction and debugging, the core function of the simulator is the verification and testing of JSON-specified robot behaviors.

SAMI ROS 2 Simulation Workspace (sami_ws)

The sami_ws workspace provides a ROS 2-based environment for simulating the SAMI robot in RViz and executing joint animations from pre-recorded JSON behavior files. The following section outlines the step-by-step setup process for the environment. These setup instructions are also available in the sami_ws GitHub repository here.

0. Initial Setup

If you’re using a clean VM with ROS 2 Jazzy, start by installing dependencies and cloning the workspace:

git clone https://github.com/shareresearchteam/sami_ws.git
sudo apt install ros-jazzy-joint-state-publisher-gui
sudo apt install ros-jazzy-xacro

Then:

cd ~/sami_ws

1. Build the Workspace

In your terminal:

colcon build

Then, source the workspace:

source install/setup.bash

2. Launch the SAMI Robot in RViz

To visualize the robot:

ros2 launch sami_sim display.launch.py

You should see SAMI loaded in RViz with a joint control panel on the left.

3. Run the Behavior Playback

Important: Before running the script, close the Joint State Publisher GUI to avoid conflicts.

Open a new terminal, then:

cd ~/sami_ws
source install/setup.bash
ros2 run sami_sim json_joint_publisher.py

This will play the behavior file specified by the behavior variable inside the script (default: TEST.json).

4. Using Custom Behavior Files

To change which behavior file is played:

1. Place your .json file in the sami_sim/behaviors/ directory.
2. Open json_joint_publisher.py.
3. Modify this line near the top:

behavior = 'TEST.json'

1. Rebuild your workspace and re-run the script:

colcon build
source install/setup.bash
ros2 run sami_sim json_joint_publisher.py

Summary

Robot Joint Configuration

Joint Table

Note: Angles are in degrees. Empty fields indicates information still needs to be tested. Please be careful when applying these limits errors/typos are possible. If any errors are found please let us know,