Skip to content

Quickstart

Get a simulated robot patrolling in under 5 minutes.

1. Install the CLI

uv tool install defined-cli --from git+https://github.com/Defined-Robotics/defined-cli.git

2. Clone the starter repo

git clone https://github.com/Defined-Robotics/botcrate.git
cd botcrate

3. Start the simulation

Make sure Docker is running, then:

defined --manifest defined.yaml

This starts Docker containers (Gazebo + ROS2 + Nav2), compiles the example patrol task, and opens the interactive TUI.

4. Run a mission

In the TUI command bar, type:

/run patrol

The robot navigates to each POI defined in the world file, reports at each location, and returns to dock.

5. Edit the task

Open tasks/patrol.task.yaml in your editor. The format:

name: MyPatrol
steps:
  - verb: go_to
    params:
      target: $world.pois.kitchen
  - verb: report
    params:
      message: "kitchen_checked"

Change the POI names, add steps, or swap verbs. Recompile with /run patrol in the TUI.

6. Visualize with Foxglove

The simulation exposes a Foxglove WebSocket bridge at ws://localhost:8765. Open Foxglove and connect to see the robot, map, laser scan, and navigation path in real time.

  1. Download Foxglove Studio (free, cross-platform)
  2. Open a new connection → Foxglove WebSocket → ws://localhost:8765
  3. Add panels: 3D, Map, Raw Messages (/mission_status)

Tip

Foxglove works on macOS, Linux, and Windows — no ROS2 installation needed on your host. The WebSocket bridge runs inside the Docker container.

7. Add a POI

In the TUI:

/world add breakroom 2.5 1.0

Now you can reference $world.pois.breakroom in your task.

Next steps