Skip to main content

Getting Started

Playarea is a minimal, lightweight planar robot simulator — a few megabytes, no ROS or heavyweight simulator to install. A simulated differential-drive robot lives on a metric occupancy-grid map, and you control it over TCP/UDP with a Python client library. The goal: get started teaching mobile robot navigation fast. A browser Map Editor ships alongside it.

Install​

The quickest way to get the simulator and its Python client is the pip package:

pip install playarea

This installs a platform wheel that bundles the native simulator binary and its assets, plus the playarea Python client library.

Run the simulator​

Launch the simulator window:

playarea

By default it opens control on TCP port 9000 and streams sensor feedback over UDP to any client that subscribes. See the Developer documentation for the full flag list and the wire protocol.

Drive it from Python​

The playarea package wraps the network protocol in a small Robot class:

from playarea import Robot

with Robot() as robot:              # connects to localhost:9000
    robot.set_speed(v=0.2, w=0.5)   # linear m/s, angular rad/s

    robot.subscribe_odom()
    print(robot.odom)               # latest pose estimate

Ready-to-run demos live in the examples/00-simple/ directory — driving in a circle, plotting the laser scan RViz-style, and viewing the head-camera stream live:

cd examples/00-simple
uv run main.py     # or: uv run scan.py / uv run camera.py

Design a map​

Use the browser-based Map Editor to draw brick walls on a metric grid, place the robot's spawn pose, and export a ROS-style map.png + map.yaml pair the simulator loads directly:

playarea --map_yaml /path/to/map.yaml

Next steps​

  • Developer documentation — build from source, the full network interface, wire formats, and coordinate conventions.
  • Map Editor — design and export occupancy maps in the browser.