# Supervisor¶

Contents

## Introduction¶

Each simulation run is observed and possibly influenced by a Supervisor. It has complete access of all the Robot’s and environment’s properties and can exclusively execute certain actions (such as start, stop or record the simulation). To implement such a supervisor, one needs to set up a script and link it to the webots world (see Webots ecosystem). Within the script, the module controller can be imported (at runtime only), specifically its class controller.Supervisor. It provides the basic Webots interface.

The mixin WebotsSupervisorMixin extends the base functionality of controller.Supervisor by a WebotsSupervisorMixin.run() method. Within this method, the infinite control loop is executed. It only returns shortly before the simulation is terminated. In the loop, a number of user-defined checks is executed periodically. These checks are the main tool to customize the supervisor, since they are also allowed to invoke supervisor actions. The checks are executed one after another with no guaranteed order. They can be interpreted as a list of Strategies. A check should evaluate its condition (generally speaking, execute its code) and return if no action has to be taken. When reverting or restarting, it is advised to go through the predefined structures to ensure consistency.

For the typical use cases, checks have been predefined. They all are successors of SupervisorCheck and further divide into RevertCheck and RespawnCheck, based on their effect. However, note that checks are defined in a way that also allows them to be functions instead of classes, thus this hierarchy is optional.

## Example¶

The supervisor facility is intended to be used from within the webots simulator [Webots]. The simulator automatically appends the controller module to Python’s search path, such that the Supervisor class can be imported. Of course, the PuPy module is also made available:

>>> from controller import Supervisor
>>> import PuPy


The supervisor is capable of executing some checks from time to time and react correspondingly. Two checks are added, one that limits the time of the experiment and another one to catch a tumbled robot. Both checks revert the simulation if the respective condition is met:

>>> checks = []
>>> checks.append(PuPy.RevertTumbled(grace_time_ms=2000))
>>> checks.append(PuPy.RevertMaxIter(max_duration_ms=20*50*2*20))


With these checks, the supervisor can be created. For this, one has to go through the respective builder. This is because the webots module is not available within PuPy. In the case of the supervisor, supervisorBuilder() needs to be called with Supervisor as its first argument and the WebotsSupervisorMixin‘s arguments following.

>>> s = PuPy.supervisorBuilder(Supervisor, 20, checks)


With this, there’s a supervisor instance s which now can be started. The call to WebotsSupervisorMixin.run() will only exit when the simulation is somehow aborted.

>>> s.run()


## Reference¶

class PuPy.WebotsSupervisorMixin(sampling_period_ms, checks=None)

Webots supervisor ‘controller’. It actively probes the simulation, performs checks and reverts the simulation if necessary.

sampling_period_ms
The period in milliseconds which the supervisor uses to observe the robot and possibly executes actions.
checks
A list of callables, which are executed in order in every sampling step. A check’s interface must be compliant with the one of SupervisorCheck.
run()

Supervisor’s main loop. Call this function upon script initialization, such that the supervisor becomes active.

The routine runs its checks and reverts the simulation if indicated. The iterations counter is made available to the checks through WebotsSupervisorMixin.num_iter.

Note, that reverting the simulation restarts the whole simulation which also reloads the supervisor.

class PuPy.SupervisorCheck

A template for supervisor’s checks.

__call__(supervisor)

Evalute the check and implement the consequences.

supervisor
The supervisor instance. For communication back to the robot, an emitter is available through supervisor.emitter.
__weakref__

list of weak references to the object (if defined)

class PuPy.RevertCheck

Bases: PuPy.webots.SupervisorCheck

A template for supervisor’s revert checks.

revert(supervisor)

Revert the simulation.

class PuPy.RevertMaxIter(max_duration_ms)

Bases: PuPy.webots.RevertCheck

Revert the simulation if a maximum duration is exceeded.

max_duration_ms
Maximum time a simulation may run, in milliseconds. After this limit, the simulation is reverted.
class PuPy.RevertTumbled(grace_time_ms=2000)

Bases: PuPy.webots.RevertCheck

Revert the simulation if the robot has tumbled.

grace_time_ms
Let the robot run after tumbling for some time before the simulation is reverted. In milliseconds.
class PuPy.RespawnCheck(reset_policy=0, arena_size=(0, 0, 0, 0))

Bases: PuPy.webots.SupervisorCheck

A template for supervisor’s respawn checks.

reset_policy
Where to respawn the robot (0=center [0,0], 1=current position, 2=random position). Instead of literals, use RespawnCheck._reset_center, RespawnCheck._reset_current and RespawnCheck._reset_random. In case of random respawn the arena_size needs to be provided.
arena_size
Size of the arena as list [min_x, max_x, min_z, max_z].
respawn(supervisor)

Reset the robots position.

class PuPy.RespawnTumbled(grace_time_ms=2000, *args, **kwargs)

Bases: PuPy.webots.RespawnCheck

Respawn the robot if it has tumbled.

grace_time_ms
Let the robot run for some time after tumbling before it is respawned. In milliseconds
class PuPy.RespawnOutOfArena(distance=2000, arena_size=(0, 0, 0, 0), *args, **kwargs)

Bases: PuPy.webots.RespawnCheck

Respawn the robot if it comoes too close to the arena boundary.

distance
The robot’s distance to the arena boundary.
arena_size
Size of the arena as list [min_x, max_x, min_z, max_z].
class PuPy.QuitMaxIter(max_duration_ms)

Bases: PuPy.webots.SupervisorCheck

Quit webots if a time limit is exceeded. (in milliseconds!)

max_duration_ms
Maximum running time, in milliseconds.