Simulation
Simulation test
CI drives DiffBot and Remo in this simulation on every pull request, without a display. Simulation Test shows how Gazebo, gazebo_ros_control and the controllers work together.
Simulators
DiffBot and Remo use Gazebo Classic 11 with ROS Noetic. Simulators explains its end of life, the new Gazebo for ROS 2, and other simulators and when to use them.
Tuning the simulated robot
How a simulated robot drives depends on more than its kinematics: on its collision shapes, masses, contact settings and the gains of its simulated motors. Wheel Dynamics in Simulation explains what each of them does. This section lists DiffBot's and Remo's settings, why they have these values, and how to tune them.
The current settings
The tables show the settings of the diffbot repository at 5631e7b and of remo_description 2.0.0; the source links below are pinned to these revisions. The experiments on the theory page used earlier revisions, which its box About the experiments names. The Basis column says where a value comes from: measured on the robot, derived from other values, Gazebo's default, selected and tested in the simulation, configured (set in the model, but not varied in these experiments), a placeholder, or not modeled. The Reason / limitation column says what the value is for and what it doesn't cover.
Geometry and mass
| Setting | DiffBot | Remo | Basis | Reason / limitation |
|---|---|---|---|---|
| Wheel radius | 0.0333 m | 0.0330 m | measured | Half the mean of the two wheels' diameters. The loaded rolling radius isn't measured. |
| Wheel separation | 0.138 m | 0.144 m | measured | Center to center, as the kinematic model and odometry use it. |
| Wheel width | 0.025 m | 0.025 m | measured | Used for the inertia; the collision is a sphere. |
| Wheel collision | sphere with the wheel radius | sphere with the wheel radius | selected, tested on flat ground | Puts an upright wheel's ideal contact in its center plane, where the kinematic model assumes it. It doesn't reproduce a tire's footprint, or contacts on slopes and edges. |
| Wheel mass | 0.032 kg | 0.032 kg | measured | The same wheels on both robots. |
| Wheel inertia about the axle | \(1.77 \cdot 10^{-5}\) kg m² | \(1.74 \cdot 10^{-5}\) kg m² | derived: \(\frac{1}{2} m r^2\) of a solid cylinder | Follows the mass and radius, independent of the collision shape. A real wheel with a heavy tire has somewhat more. |
| Caster mass | 38 g | 22 g | measured; DiffBot's split between its parts estimated | DiffBot's caster was weighed as one part (38 g); the model gives its base, hub and wheel 10, 10 and 18 g. Remo's parts were weighed one by one; its whole caster weighs 23 g. |
| Robot mass, model / weighed | 1145 g / about 1145 g, estimated | 1154 g / 1303 g | model: sum of the links; weighed | DiffBot: 705 g weighed with its AA battery pack, plus its lidar (190 g, RPLidar A2M8 datasheet) and its power bank (250 g, the value of Remo's model for the same power bank). Its base, a thin box, carries everything not modeled separately, so its center of mass and inertia are approximations. Remo's model lacks about 149 g, for example cables and screws. |
Sources: DiffBot's config/diffbot (front_wheel.yaml, caster_wheel.yaml, base.yaml, motor.yaml, sensors.yaml), Remo's config/remo, geometry.yaml, the wheel collision and cylinder_inertia in DiffBot's and Remo's common_macros.urdf.xacro.
Contacts
| Setting | DiffBot | Remo | Basis | Reason / limitation |
|---|---|---|---|---|
Friction mu1, mu2 |
1, 1 | 1, 1 | selected | A usual order of magnitude for rubber on a hard floor, not measured for these tires and floors. Gazebo uses the smaller coefficient of the wheel and the ground. Friction 200 changed nothing measurable in Remo's wheel tracking (experiment E3). |
fdir1 |
not set | not set | selected | Left unset to avoid a direction that turns with the sphere's frame and leaves the contact plane, as 0 0 1 would; a direction along the axle would stay in the contact plane, but Gazebo Classic uses only one of the two surfaces' fdir1 in each contact. |
Contact kp, kd |
\(10^{7}\) N/m, 1 N s/m | \(10^{7}\) N/m, 1 N s/m | selected | With Gazebo's stiff default (\(10^{12}\) N/m), both robots' light wheels missed their speed commands; DiffBot then turned only 0.33 to 0.87 of what its odometry said (diffbot#137). Damping 0 alone made no difference (experiment E3). |
minDepth |
0 | 0 | selected | With Remo's compliant contacts, a positive value let the wheels creep into the ground. Zero is the tested choice for these wheels, not a universal rule. |
maxVel |
0.01 m/s | 0.01 m/s | default | Limits how fast a penetration is corrected. |
| Caster wheel contact | friction 1, \(10^{7}\) N/m, 1 N s/m | friction 0.01, \(10^{12}\) N/m, 0 N s/m, minDepth 0.01 |
DiffBot: selected; Remo: configured | DiffBot: with the stiff default, its 18 g caster wheel made the drive wheels' speeds jitter in right turns. Remo's low friction lets its caster slide; it wasn't varied in these experiments. |
Sources: DiffBot's drive-wheel contacts in common_macros.urdf.xacro and its caster's in diffbot_caster_macro.urdf.xacro; Remo's drive-wheel and caster contacts, with the friction argument of remo.urdf.xacro.
Control and world
| Setting | DiffBot | Remo | Basis | Reason / limitation |
|---|---|---|---|---|
Wheel velocity PID p, i, d |
0.02, 0.6, 0 | 0.03, 0.6, 0 | selected, tested at a 1 ms step | Both P are below the free-wheel limit of about 0.035 for their 32 g wheels. For DiffBot, P 0.01, 0.02 and 0.03 tracked equally well; 0.02 keeps more distance to the limit. Neither is shown to be optimal. |
i_clamp, antiwindup |
0.05 N m, true | 0.05 N m, true | selected | The I term can supply up to 0.05 N m; without i_clamp, an I gain does nothing. |
| Wheel torque limit | none | none | not modeled | A real motor has a stall torque. |
| Physics | ODE, quick solver with 150 iterations, 1 ms step | the same | inherited from the world | The simulation test's diffbot_empty.world. Other worlds differ, for example playground.world with a 10 ms step, and the gains depend on the step. |
Sources: pid.yaml of DiffBot and Remo, the test world.
How these values were found: diffbot#119 (geometry), diffbot#120 and remo_description#2 (collisions and contacts), diffbot#121 (gains), diffbot#137 (DiffBot's masses, contacts and gain).
How to tune
Tune the model in this order, so that a later step doesn't hide an error of an earlier one. One error can hide another: for example, wheels that sink into the ground can change where they touch it. So after each fix, go through the later steps again.
- Geometry and inertia first. Measure the wheel diameters and their separation, center to center, and enter them in the URDF's
front_wheel.yamland the controller'sgeometry.yaml; the geometry test checks that both agree. Check the expanded URDF withxacro: the wheel joints' distance, the collision radius, and an inertia whose \(\frac{1}{2} m r^2\) is about the joint axis. - Record a baseline. Note the world, its time step and solver (the gains depend on the time step), and run the simulation test: the odometry and the true pose, driving straight and turning on the spot.
- Check the spawn and the settling. The robot has to stay at its spawn pose without NaN velocities, and its wheels have to stay on the ground: a wheel link's height above the ground should stay at its radius over a minute (
/gazebo/link_states). Example: with compliant contacts and a positiveminDepth, Remo's wheels crept about 8 mm into the ground within a minute, and the turn test still passed. Only the height showed it. - Wheel speed tracking. Turn on the spot in both directions and drive straight, and compare the wheel joints' speeds in
/diffbot/joint_stateswith the commanded ones: their mean and their standard deviation. A lasting error can come from the controller, a torque limit or the contact load; jitter can come from contact solving or an unstable loop. Keep P below the free-wheel limit \(2J/h\). Example: with a P gain alone, Remo's wheels reached only about 80 % of the command when turning on the spot, because turning needs torque; an I term withi_clampremoved the error. - Agreement with the true motion. Compare the odometry with the true pose. Example: wheel speeds within 1 % of the command, but a true turn of only about 0.85 of the odometry's. Then test the effective contact separation, for example with a different collision shape, and keep the controller as it is.
- One change at a time. After each change, repeat straight driving and turns in both directions, for both robots, and run each case more than once to see how much the results vary.
Don't compensate one error with another setting: a wrong geometry with gains, or an unstable velocity loop with heavier wheels than the real ones. The simulation test catches regressions, but passing it doesn't make the simulation accurate at other speeds, on other floors or slopes.
Simulate DiffBot in Gazebo
As described in the Creating your own Gazebo ROS Package, it is common in ROS to create a package that contains all the world files and launch files used with Gazebo. These files are located in a ROS package named /MYROBOT_gazebo. For DiffBot the package is named diffbot_gazebo. Another example that follows best pratices is rrbot which can be found in the gazebo_ros_demos repository.
1 2 3 4 5 | |
The diffbot_gazebo package contains a launch file to launch a world in Gazebo and spawn the robot model,
which is defined in the previously created diffbot_description package.
For the launch files the convention is to have a folder named launch and for Gazebo world files a folder named world inside a package.
1 | |
Inside the launch folder is the diffbot.launch.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
In the world folder of the diffbot_gazebo package is the diffbot.world file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | |
With these files build the catkin workspace and source it to make the new diffbot_gazebo package visible to roslaunch:
1 2 | |
Then its possible to launch the diffbot.launch with:
1 | |
This will lead to the following output:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | |
Also, the Gazebo simulator will open a new window with the objects defined in diffbot.world except for the Gas station because it is a model
that has to be downloaded first, which is happening in the background. TODO: gas station is not showing this way.
To get the Gas station or other available models it is possible to clone the gazebo models repository into your /home/your_username/.gazebo folder, e.g.:
1 | |
Using ROS launch to Spawn URDF Robots
According to the Gazebo roslaunch tutorial the recommended way
to spawn a robot into Gazebo is to use a launch file. Therefore, edit the diffbot.launch inside the diffbot_gazebo package by adding the following inside the <launch> </launch tag:
1 2 3 4 5 6 7 | |
See also the complete diffbot.launch file.
This will open Gazebo simulator and show the DiffBot model:
Moving the Robot
Note that the robot cannot be moved without having either a Gazebo plugin loaded or making use of ROS Control
and its Gazebo plugin gazebo_ros_control, see also the Gazebo ROS Control Tutorial. Using the ROS Control and its Gazebo plugin is done in case of DiffBot.
An alternative would be to use the existing differential_drive_controller Gazebo plugin without having to rely on ROS Control.
The next section explains the diffbot_control package in more detail and how to setup the
diff_drive_controller
from the ros_controllers package.
Adding Sensors
To add sensors to a robot model make use of link and joint tags to define the desired location and shape, possibly using meshes.
For the simulation of these sensor there exist common Gazebo plugins that can be used. See, the [Tutorial: Using Gazebo plugins with ROS]
for existing plugins and more details how to use them. For a full list of plugins see also gazebo_ros_pkgs which is a package or interface
for using ROS with the Gazebo simulator.
Camera
This section follows Gazebo tutorial Adding a Camera.
Laser (Lidar)
This section follows Gazebo tutorial Adding a Laser GPU.
Ultrasonic Ranger
See the source of the gazebo_ros_range plugin.
Inertial Measurement Unit (IMU)
Both robots' models have an IMU, so that the EKF runs in the simulation as on the robot. The xacro macro imu_sensor in common_sensors.xacro (DiffBot's, and Remo's in remo_description) adds the link imu_link on chassis_link, with a small box for the board, and Gazebo's IMU sensor with the plugin libdiffbot_gazebo_ros_imu_sensor.so. The plugin measures the link's angular velocity and acceleration in Gazebo at 50 Hz, adds Gaussian noise with a standard deviation of 0.005 (rad/s and m/s²) to every value, and publishes /diffbot/imu/gazebo.
The plugin comes from the package diffbot_gazebo_plugins. It's a copy of the IMU plugin libgazebo_ros_imu_sensor.so from gazebo_plugins, with the same parameters and the same message. The copy differs in two ways. It leaves out the call to ros::spinOnce(), and it keeps publishing after a reset of the simulation.
After publishing an IMU message, the original plugin calls ros::spinOnce() from Gazebo's physics thread, which advances the simulation. This call runs the waiting callbacks from ROS's global queue in the calling thread. A callback is a function that handles an incoming message or service request. This queue includes the controller manager's callbacks for loading and starting controllers.
If the physics thread runs one of those callbacks, the callback can wait for the controller manager's next update() to take the change. But update() needs the same physics thread, which is waiting inside the callback. The thread is waiting for work that only it can do. This is a deadlock, and the simulation's clock stops (#185).
The copy publishes the IMU message without calling ros::spinOnce(). The ROS spinner threads handle the queued callbacks, leaving the physics thread free to run update().
A reset of the simulation, for example rosservice call /gazebo/reset_simulation, sets the simulation's clock back to zero (Gazebo's simulation control services). The plugin limits its rate by comparing the sensor's time with the time of its last update. After a reset, the sensor's time is earlier than that. The copy then starts the comparison from the new time and publishes again one sample period later. The original plugin keeps the old time and publishes nothing until the clock has passed that time.
DiffBot's model names the copy's library. Remo's model (remo_description 2.5.0 and newer) takes the library as the xacro argument imu_plugin, which diffbot_view.launch sets.
The xacro arguments imu_xyz and imu_rpy set imu_joint's origin on chassis_link, for example xacro diffbot.urdf.xacro imu_xyz:="0 0 0.01". Remo's defaults describe the mounting on the robot's Raspberry Pi deck. imu_link lies about 7.6 cm behind the wheel axle and 2.34 cm left of the robot's center line, with the board's header pins seated in the breadboard. The frame is rotated by −90° about chassis_link's z axis, matching the orientation established by the tilt test. DiffBot uses the same BNO055 as Remo. Its mounting on DiffBot hasn't been measured, so DiffBot's model uses a placeholder position.
The plugin also estimates an orientation, which the robot's firmware doesn't provide. imu_raw_adapter.py, started by diffbot_view.launch, removes it and publishes the rest unchanged, with its stamp, as /diffbot/imu/data_raw: the same topic and contents as the firmware, so the EKF gets the same input in the simulation and on the robot.
The simulation test checks the simulated IMU in test_imu.py: its rate, its frame, the orientation marked as missing, gravity on the upward axis at rest, and a positive yaw rate in a left turn. test_imu_reset.py checks that the IMU publishes again right after a reset of the simulation.
Troubleshooting
A quick way to verify if the conversion from xacro to urdf to sdf is working is the following (source: Tutorial URDF in Gazebo):
First convert the xacro model to a urdf model with the xacro command:
1 | |
This will output the urdf into a file named diffbot.urdf in the current working directory. For Remo, use $(rospack find remo_description)/urdf/remo.urdf.xacro and remo.urdf.
Then use the gz command to create a sdf:
1 2 | |
Each link's collision/surface element in the output holds its contact settings. From URDF to SDF explains them, with Remo's wheel as an example.
In case the output looks like the following, there are most certainly missing <inertial> tags in the <link> tag.
For the Gazebo simulator the <inertial> must be present, in order to simulate the dynamics of the robot.
See also http://wiki.ros.org/urdf/XML/link and the Gazebo tutorials on URDF.
1 2 3 | |
Comments
Comments are GitHub Discussions, shown with giscus. Loading them connects to giscus.app (hosted by Vercel, USA) and GitHub (USA); you need a GitHub account to comment.