What is RobotDSL?

RobotDSL is a language and a compiler for mobile robots. You describe the robot, the world it drives in, the task it must do and, if you want, how a run is judged. The compiler checks the four descriptions against each other and writes one directory your robot stack runs: the robot description, the world, the controller and navigation settings, the task and a launch file.

Without it, one robot is spread over many hand-written files, each in its own format: the robot description, the simulated world, the controller settings, the navigation settings. The same fact, such as a wheel radius, the footprint or a sensor's topic, appears in several of them, and nothing notices when the copies drift apart. RobotDSL states each fact once and derives every file from it, so a new target adds files to derive, not facts to repeat.

Four files

A program is four small files. The file's extension says which one it is.

File	Describes
.core	The robot: a chassis, and the wheels, sensors and attachments placed on it
.world	Where it drives: gravity, the spawn pose, obstacles, and named goals
.task	What it must do: navigate to a goal, spin, wait, retry, as a behavior tree
.eval	Optional. How a run is judged: speed, clearance, contact and time limits

Robot drone_mecanum {
    Mecanum_four_wheel chassis(ref = "tslot_1515_drone")
    Mecanum wheel_lf(ref = "mecanum_black", glue = (0.1275, 0.1494, -0.0216, 0, 1, 0))
    // wheel_lb, wheel_rf and wheel_rb are placed the same way
    Lidar top_lidar(ref = "lidar_ld06", glue = (0, 0.0001, 0.0344, 0, 0, -1))
}

Every ref names a part in a component library, a directory of real parts with their meshes, masses and mating points. You pick parts; you do not type in their dimensions.

What the compiler checks

Before it writes anything, the compiler:

• resolves every name against the vocabulary and your libraries, and suggests a near miss when one does not exist;
• mates each part onto the connector its glue names, of the chassis or of a part already placed, and derives the wheel contacts, the mass and centre of mass, the footprint and the drive kinematics;
• runs its validation rules on those facts: every wheel mount filled, axles horizontal, wheels on one plane, the centre of mass inside the ground contacts, a base that can spin when the task spins;
• checks that the chosen target can realize everything, and refuses what it cannot rather than emitting it silently wrong.

A problem is reported at the line that caused it, in the program or in the part file, with what to change. See Reading diagnostics.

What it does not do

• It does not launch anything. You run the output in your own environment: ROS 2 for the two ROS targets, MuJoCo alone for mjcf.
• It does not invent a missing physical value. A part that states no collision box or no mass basis is reported, not guessed at.
• It does not install anything. Libraries are plain directories named on the command line, and the output needs nothing built.

Targets

A target is the robot stack the output is for. There are three. The two ROS targets share the robot description, controllers, navigation and task runtime; mjcf writes the robot alone, to drive by hand:

Target	Runs on
ros-gz-nav2	ROS 2 Jazzy, Gazebo Harmonic, ros2_control, Nav2
ros-mujoco-nav2	ROS 2 Jazzy, MuJoCo 3.11 or later, ros2_control, Nav2
mjcf	MuJoCo alone, its viewer or MuJoCo in a browser page: the robot on its floor and how to drive it

Gazebo or MuJoCo explains the difference.

Next

• Installation sets up the compiler.
• Getting started checks, compiles and runs a first program.