Create your first simulation builder socket

This tutorial will guide you through the creation of a simple simulation where you can control a mobile robot and read data from its sensors.

It makes use of MORSE Builder API: a set of Python functions that allow to define:

  • The robots to use
  • The components attached to them
  • The middleware bindings used for communication
  • The environment of the simulation

During the tutorial, we will write such a Python script that can be executed by MORSE to create your simulation and start it.


If you want, you can get the script resulting from this tutorial here: $MORSE_ROOT/share/morse/examples/tutorials/, where $MORSE_ROOT is your installation prefix (typically /usr/local/).

Create the script

Create a new script in your favorite Python editor, and give it an appropriate name. For instance:

In order to use the API, you must first import the morse.builder module:

from morse.builder import *

Then you will make calls to predefined functions to create and configure the components necessary in your scene.

MORSE knows three main components: the robots, the sensors and the actuators (the robots are mostly supports for sensors or actuators).

All these components live in an environment, which may be any physics-enabled 3D model.

The behaviour of these components can be altered by modifiers and their interactions with softwares running outside the simulator rely on middlewares.

Add a robot to the scene

The robot is the base where we will install other sensors and actuators.

atrv = ATRV()

Here, we simply import a standard ATRV 4-wheeled outdoor robot.

The atrv is known by MORSE, as you can see in the component library.

Append an actuator

Then, let’s add a v, omega actuator. This one controls the robot by changing the linear and angular velocity of the movement.

motion = MotionVW()

The append method parents the actuator to the robot.

Append a sensor

We can now add a Pose sensor, which provides us with the location and rotation of the robot.

The data it sends back is the (x, y, z) coordinates, and the (yaw, pitch, roll) orientation. For any component, you can know what in exported from the documentation page of the component: Pose

pose = Pose()

Configuring the middlewares

The simplest way to test MORSE is to use the basic socket to access the data-streams and services provided by the components. This method has no software requirements other than the base MORSE installation.

You need to tell MORSE how each of the components attached to a robot will communicate with the outside world. This is done with these instructions:


Each of the components can use a different middleware, enabling the use of MORSE in an heterogeneous environment. You can check the full list of supported middlewares for reference.

Finalising the scene

Every builder script must finish with an environment description.

The parameter for the Environment method is the name of a Blender .blend file you provide (with its full path) or a pre-defined one.

The Environment object also provides additional options to place and aim the default camera, by using the methods set_camera_rotation and set_camera_location.

env = Environment('indoors-1/indoor-1')
env.set_camera_location([5, -5, 6])
env.set_camera_rotation([1.0470, 0, 0.7854])

Now save your script file.

Running the simulation

Starting the simulation

Simply run:

$ morse run

Alternatively, you can choose to open first your simulation in Blender, and start it from there:

  1. Launch MORSE in edit mode, passing your script in argument:

    $ morse edit
  2. Place your mouse inside the 3D view of the scenario

  3. Press p to start the Game Engine

Control the simulation with services

Using sockets to connect to robot services is the simplest way to interact with the simulation. You can talk with MORSE through a simple telnet connection. On a separate terminal, type:

$ telnet localhost 4000

Port 4000 is the default port used by MORSE to expose the services.

The motion controller we have added to the robot export one service, set_speed: to make the robot move in a circle, with linear speed 2 m/s and angular speed -1 rad/s, type this instruction:

id1 atrv.motion set_speed [2, -1]


the first part of the request, id1 is any identifier you want. It is useful when running asynchronous services (ie, non-blocking) to get notified of the service termination.


the internal name of the component is (here, atrv.motion) is displayed in the MORSE log at the end of the simulation initialisation.

In the same way, you can query the atrv.pose sensor for the data it contains:

id2 atrv.pose get_local_data

The format of these commands is simple, they are composed of four parts:

Try giving the motion controller different speeds, and querying the pose sensor at different locations.

Accessing the sensors data streams

The Pose sensor actually permanently export its data as a stream.

We can use telnet as well to monitor it.

Since many sensors may output their data-stream on the socket interface, each of them is assigned a port at runtime. You can retrieve this port either by looking at MORSE console output, or with the simulation services list_streams and get_stream_port:

id3 simulation list_streams
> id3 SUCCESS ["atrv.pose"]
id4 simulation get_stream_port ["atrv.pose"]
> id4 SUCCESS 60000

So we know that the pose sensor exports its datastream on the port 60000.

Open another telnet session:

$ telnet localhost 60000

Your screen should be filled pretty quickly with the sensor output.

Many actuators also accept a datastream as input to control their behaviour.

To exit the simulation, press esc in the Blender window.

What’s next?

  • You can try to add different components to the robot, by experimenting with the various objects available in the MORSE component library. This is the main reference of robots, actuators, sensors that are available out of the box in MORSE.


The names you pass to the Builder functions link to the names of the Blender .blend files that contain the components’ meshes. They are provided for each component in the component library.