Webots Reference Manual - chapter 3 - section 41

Webots Reference Manual


3.41 Robot

Derived from Solid.

Robot {
  SFString   controller        "void"
  SFString   controllerArgs    ""
  SFBool     synchronization   TRUE
  MFFloat    battery           []
  SFFloat    cpuConsumption    0   # [0,inf)
  SFBool     selfCollision     FALSE
  SFBool     showRobotWindow   FALSE
  SFString   robotWindow       ""
  SFString   remoteControl     ""
}

Direct derived nodes: DifferentialWheels, Supervisor.

3.41.1 Description

The Robot node can be used as basis for building a robot, e.g., an articulated robot, a humanoid robot, a wheeled robot... If you want to build a two-wheels robot with differential-drive you should also consider the DifferentialWheels node. If you would like to build a robot with supervisor capabilities use the Supervisor node instead (Webots PRO license required).

3.41.2 Field Summary

3.41.3 Synchronous versus Asynchronous controllers

The synchronization field specifies if a robot controller must be synchronized with the simulator or not.

If synchronization is TRUE (the default), the simulator will wait for the controller's wb_robot_step() whenever necessary to keep the simulation and the controller synchronized. So for example if the simulation step (WorldInfo.basicTimeStep) is 16 ms and the control step (wb_robot_step()) is 64 ms, then Webots will always execute precisely 4 simulation steps during one control step. After the 4th simulation step, Webots will wait for the controller's next control step (call to wb_robot_step(64)).

If synchronization is FALSE, the simulator will run as fast a possible without waiting for the control step. So for example, with the same simulation step (16 ms) and control step (64 ms) as before, if the simulator has finished the 4th simulation step but the controller has not yet reached the call to wb_robot_step(64), then Webots will not wait; instead it will continue the simulation using the latest actuation commands. Hence, if synchronization is FALSE, the number of simulation steps that are executed during a control step may vary; this will depend on the current simulator and controller speeds and on the current CPU load, and hence the outcome of the simulation may also vary. Note that if the number of simulation steps per control step varies, this will appear as a variations of the "speed of the physics" in the controller's point of view, and this will appear as a variation of the robot's reaction speed in the user's point of view.

So generally the synchronization field should be set to TRUE when robust control is required. For example if a motion (or .motion file) was designed in asynchronous mode then it may appear completely different in asynchronous mode. The asynchronous mode is currently used only for the robot competitions, because in this case it is necessary to limit the CPU time allocated to each participating controller. Note that it is also possible to combine synchronous and asynchronous controllers, e.g., for the robot competitions generally the Supervisor controller is synchronous while the contestants controllers are asynchronous. Asynchronous controllers may also be recommended for networked simulations involving several robots distributed over a computer network with an unpredictable delay (like the Internet).

3.41.4 Self-collision

When selfCollision is FALSE (the default), Webots does not attempt to detect any internal collisions in a robot. In this case, nothing but the controller code can prevent the various body parts of a robot from crossing each other.

When selfCollision is TRUE, Webots detects inter-robot collisions and applies the corresponding contact forces. In this case robot limbs cannot cross each other (provided that they have Physics nodes). Note that Webots does automatically exclude directly joined bodies from the self-collision detection. The reason is that this type of collision is usually not wanted by the user, because otherwise a very accurate design of the boundingObjects would be required. When two body parts are not directly joined, i.e. joined through an intermediate body, then the collision detection takes place normally. Here is an example for a robot leg:

Thigh (body)
  |
Knee (joint)
  |
Leg (body)
  |
Ankle (joint)
  |
Foot (body)

In this example, no collision is detected between the "Thigh" and the "Leg" bodies because they are directly joined by the "Knee". In the same way no collision detection takes place between the "Leg" and the "Foot" bodies because the are also directly joined ("Ankle"). However, collisions may be detected between the "Thigh" and the "Foot" bodies, because they are not joined directly, but through and intermediate body ("Leg").

3.41.5 Robot Functions



NAME

   wb_robot_step, wb_robot_init, wb_robot_cleanup - controller step, initialization and cleanup functions

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  int wb_robot_step(int ms);
  void wb_robot_init();
  void wb_robot_cleanup();

DESCRIPTION

The wb_robot_step() function is crucial and must be used in every controller. This function synchronizes the sensor and actuator data between Webots and the controllers. If the wb_robot_step() function is not called then there will be no actuation in Webots and no update of the sensors in the controller.

The ms parameter specifies the number of milliseconds that must be simulated until the wb_robot_step() function returns. Note that this is not real time but virtual (simulation) time, so this is not like calling the system's sleep(). In fact the function may return immediately, however the important point is that when it returns ms milliseconds of simulation will have elapsed. In other words the physics will have run for ms milliseconds and hence the Servo may have moved, the sensor values may have changed, etc. Note that ms parameter must be a multiple of the WorldInfo.basicTimeStep.

If this function returns -1, this indicates that Webots wishes to terminate the controller. This happens when the user hits the Revert button or quits Webots. So if your code needs to do some cleanup, e.g., flushing or closing data files, etc., it is necessary to test this return value and take proper action. The controller termination cannot be vetoed: one second later the controller is killed by Webots. So only one second is available to do the cleanup.

If the synchronization field is TRUE, this function always returns 0 (or -1 to indicate termination). If the synchronization field is FALSE, the return value can be different from 0: Let controller_time be the current time of the controller and let dt be the return value. Then dt may be interpreted as follows:

The C API has two additional functions wb_robot_init() and wb_robot_cleanup(). There is not equivalent of the wb_robot_init() and wb_robot_cleanup() functions in the Java, Python, C++ and MATLAB APIs. In these languages the necessary initialization and cleanup of the controller library is done automatically.

The wb_robot_init() function is used to initialize the Webots controller library and enable the communication with the Webots simulator. Note that the wb_robot_init() function must be called before any other Webots API function.

Calling the wb_robot_cleanup() function is the clean way to terminate a C controller. This function frees the various resources allocated by Webots on the controller side. In addition wb_robot_cleanup() signals the termination of the controller to the simulator. As a consequence, Webots removes the controller from the simulation which can continue normally with the execution of the other controllers (if any). If a C controller exits without calling wb_robot_cleanup(), then its termination will not be signalled to Webots. In this case the simulation will remain blocked (sleeping) on the current step (but only if this Robot's synchronization field is TRUE). Note that the call to the wb_robot_cleanup() function must be the last API function call in a C controller. Any subsequent Webots API function call will give unpredictable results.

SIMPLE C CONTROLLER EXAMPLE

language: C

#include <webots/robot.h>

#define TIME_STEP 32

static WbDeviceTag my_sensor, my_led;

int main() {
  /* initialize the webots controller library */
  wb_robot_init();

  // get device tags
  my_sensor = wb_robot_get_device("my_distance_sensor");
  my_led = wb_robot_get_device("my_led");

  /* enable sensors to read data from them */
  wb_distance_sensor_enable(my_sensor, TIME_STEP);

  /* main control loop: perform simulation steps of 32 milliseconds */
  /* and leave the loop when the simulation is over */
  while (wb_robot_step(TIME_STEP) != -1) {

    /* Read and process sensor data */
    double val = wb_distance_sensor_get_value(my_sensor);

    /* Send actuator commands */
    wb_led_set(my_led, 1);
  }

  /* Add here your own exit cleanup code */

  wb_robot_cleanup();

  return 0;
}



NAME

   wb_robot_get_device - get a unique identifier to a device

SYNOPSIS [Matlab]

  #include <webots/robot.h>

  WbDeviceTag wb_robot_get_device(const char *name);

DESCRIPTION

This function returns a unique identifier for a device corresponding to a specified name. For example, if a robot contains a DistanceSensor node whose name field is "ds1", the function will return the unique identifier of that device. This WbDeviceTag identifier will be used subsequently for enabling, sending commands to, or reading data from this device. If the specified device is not found, the function returns 0.

SEE ALSO

wb_robot_step.



NAME

   Robot::getAccelerometer, Robot::getCamera, Robot::getCompass, Robot::getConnector, Robot::getDistanceSensor, Robot::getDisplay, Robot::getEmitter, Robot::getGPS, Robot::getGyro, Robot::getInertialUnit, Robot::getLED, Robot::getLightSensor, Robot::getPen, Robot::getReceiver, Robot::getServo, Robot::getTouchSensor - get the instance of a robot's device

SYNOPSIS [C++] [Java] [Python]

  #include <webots/Robot.hpp>

  Accelerometer *Robot::getAccelerometer(const std::string &name);
  Camera *Robot::getCamera(const std::string &name);
  Compass *Robot::getCompass(const std::string &name);
  Connector *Robot::getConnector(const std::string &name);
  Display *Robot::getDisplay(const std::string &name);
  DistanceSensor *Robot::getDistanceSensor(const std::string &name);
  Emitter *Robot::getEmitter(const std::string &name);
  GPS *Robot::getGPS(const std::string &name);
  Gyro *Robot::getGyro(const std::string &name);
  InertialUnit *Robot::getInertialUnit(const std::string &name);
  LightSensor *Robot::getLightSensor(const std::string &name);
  Pen *Robot::getPen(const std::string &name);
  Receiver *Robot::getReceiver(const std::string &name);
  Servo *Robot::getServo(const std::string &name);
  TouchSensor *Robot::getTouchSensor(const std::string &name);

DESCRIPTION

These functions return a reference to an object corresponding to a specified name. Depending on the called function, this object can be an instance of a Device subclass. For example, if a robot contains a DistanceSensor node whose name field is "ds1", the function getDistanceSensor will return a reference to a DistanceSensor object. If the specified device is not found, the function returns NULL in C++, null in Java or the none in Python.

SEE ALSO

wb_robot_step.



NAME

   wb_robot_battery_sensor_enable, wb_robot_battery_sensor_disable, wb_robot_get_battery_sampling_period, wb_robot_battery_sensor_get_value - battery sensor function

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  void wb_robot_battery_sensor_enable(int ms);
  void wb_robot_battery_sensor_disable();
  double wb_robot_battery_sensor_get_value();
  int wb_robot_get_battery_sampling_period(WbDeviceTag tag);

DESCRIPTION

These functions allow you to measure the present energy level of the robot battery. First, it is necessary to enable battery sensor measurements by calling the wb_robot_battery_sensor_enable() function. The ms parameter is expressed in milliseconds and defines how frequently measurements are performed. After the battery sensor is enabled a value can be read from it by calling the wb_robot_battery_sensor_get_value() function. The returned value corresponds to the present energy level of the battery expressed in Joules (J).

The wb_robot_battery_sensor_disable() function should be used to stop battery sensor measurements.

The wb_robot_get_battery_sampling_period() function returns the period given into the wb_robot_battery_sensor_enable() function, or 0 if the device is disabled.



NAME

   wb_robot_get_basic_time_step - returns the value of the basicTimeStep field of the WorldInfo node

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  double wb_robot_get_basic_time_step();

DESCRIPTION

This function returns the value of the basicTimeStep field of the WorldInfo node.



NAME

   wb_robot_get_mode - get operating mode, simulation vs. real robot

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  int wb_robot_get_mode();
  void wb_robot_set_mode(int mode, void *arg);

DESCRIPTION

The wb_robot_get_mode function returns an integer value indicating the current operating mode for the controller.

The wb_robot_set_mode function allows to switch between the simulation and the remote control mode. When switching to the remote-control mode, the wbr_start function of the remote control plugin is called. The argument arg is passed directly to the wbr_start function (more information in the user guide).

The integers can be compared to the following enumeration items:

ModePurpose
WB_MODE_SIMULATIONsimulation mode
WB_MODE_CROSS_COMPILATIONcross compilation mode
WB_MODE_REMOTE_CONTROLremote control mode

Table 3.4: Helper enumeration to interpret the integer argument and return value of the wb_robot_[gs]et_mode() functions



NAME

   wb_robot_get_name - return the name defined in the robot node

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  const char *wb_robot_get_name();

DESCRIPTION

This function returns the name as it is defined in the name field of the robot node (Robot, DifferentialWheels, Supervisor, etc.) in the current world file. The string returned should not be deallocated, as it was allocated by the libController shared library and will be deallocated when the controller terminates. This function is very useful to pass some arbitrary parameter from a world file to a controller program. For example, you can have the same controller code behave differently depending on the name of the robot. This is illustrated in the soccer.wbt sample demo, where the goal keeper robot runs the same control code as the other soccer players, but its behavior is different because its name was tested to determine its behavior (in this sample world, names are "b3" for the blue goal keeper and "y3" for the yellow goal keeper, whereas the other players are named "b1", "b2", "y1" and "y2"). This sample world is located in the projects/samples/demos/worlds directory of Webots.



NAME

   wb_robot_get_model - return the model defined in the robot node

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  const char *wb_robot_get_model();

DESCRIPTION

This function returns the model string as it is defined in the model field of the robot node (Robot, DifferentialWheels, Supervisor, etc.) in the current world file. The string returned should not be deallocated, as it was allocated by the libController shared library and will be deallocated when the controller terminates.



NAME

   wb_robot_get_project_path - return the full path of the current project

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  const char *wb_robot_get_project_path();

DESCRIPTION

This function returns the full path of the current project, that is the directory which contains the worlds and controllers subdirectories (among others) of the current simulation world. It doesn't include the final directory separator char (slash or anti-slash). The returned pointer is a UTF-8 encoded char string. It should not be deallocated.



NAME

   wb_robot_get_synchronization - return the value of the synchronization field of the Robot node

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  bool wb_robot_get_synchronization();

DESCRIPTION

This function returns the boolean value corresponding to the synchronization field of the Robot node.



NAME

   wb_robot_get_time - return the current simulation time in seconds

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  double wb_robot_get_time();

DESCRIPTION

This function returns the current simulation time in seconds. This correspond to the simulation time displayed in the bottom right corner of Webots window. It does not matter whether the controller is synchronized or not.



NAME

   wb_robot_keyboard_enable, wb_robot_keyboard_disable, wb_robot_keyboard_get_key - keyboard reading function

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/robot.h>

  void wb_robot_keyboard_enable(int ms);
  void wb_robot_keyboard_disable();
  int wb_robot_keyboard_get_key();

DESCRIPTION

These functions allow you to read a key pressed on the computer keyboard from a controller program while the main window of Webots is selected and the simulation is running. First, it is necessary to enable keyboard input by calling the wb_robot_keyboard_enable() function. The ms parameter is expressed in milliseconds, and defines how frequently readings are updated. After the enable function is called, values can be read by calling the wb_robot_keyboard_get_key() function repeatedly until this function returns 0. The returned value, if non-null, is a key code corresponding to a key currently pressed. If no modifier (shift, control or alt) key is pressed, the key code is the ASCII code of the corresponding key or a special value (e.g., for the arrow keys). However, if a modifier key was pressed, the ASCII code (or special value) can be obtained by applying a binary AND between to the WB_ROBOT_KEYBOARD_KEY mask and the returned value. In this case, the returned value is the result of a binary OR between one of WB_ROBOT_KEYBOARD_SHIFT, WB_ROBOT_KEYBOARD_CONTROL or WB_ROBOT_KEYBOARD_ALT and the ASCII code (or the special value) of the pressed key according to which modifier key was pressed simultaneously. If no key is currently pressed, the function will return 0. Calling the wb_robot_keyboard_get_key() function a second time will return either 0 or the key code of another key which is currently simultaneously pressed. The function can be called up to 7 times to detect up to 7 simultaneous keys pressed. The wb_robot_keyboard_disable() function should be used to stop the keyboard readings.

language: C++
The keyboard predefined values are located into a (static) enumeration of the Robot class. For example, Robot.KEYBOARD_CONTROL corresponds to the Control key stroke.
language: Java
The keyboard predefined values are final integers located in the Robot class. For example, Ctrl+B can be tested like this:

int key=robot.keyboardGetKey()
if (key==Robot.KEYBOARD_CONTROL+'B')
  System.out.Println("Ctrl+B is pressed");

language: Python
The keyboard predefined values are integers located into the Robot class. For example, Ctrl+B can be tested like this:

key=robot.keyboardGetKey()
if (key==Robot.KEYBOARD_CONTROL+ord('B')):
  print 'Ctrl+B is pressed'



NAME

   wb_robot_task_new - start a new thread of execution

SYNOPSIS

  #include <webots/robot.h>

  void wb_robot_task_new(void (*task)(void *), void *param);

DESCRIPTION

This function creates and starts a new thread of execution for the robot controller. The task function is immediately called using the param parameter. It will end only when the task function returns. The Webots controller API is thread safe, however, some API functions use or return pointers to data structures which are not protected outside the function against asynchronous access from a different thread. Hence you should use mutexes (see below) to ensure that such data is not accessed by a different thread.

SEE ALSO

wb_robot_mutex_new.



NAME

   wb_robot_mutex_new, wb_robot_mutex_delete, wb_robot_mutex_lock, wb_robot_mutex_unlock - mutex functions

SYNOPSIS

  #include <webots/robot.h>

  WbMutexRef wb_robot_mutex_new();
  void wb_robot_mutex_delete(WbMutexRef mutex);
  void wb_robot_mutex_lock(WbMutexRef mutex);
  void wb_robot_mutex_unlock(WBMutexRef mutex);

DESCRIPTION

The wb_robot_mutex_new() function creates a new mutex and returns a reference to that mutex to be used with other mutex functions. A newly created mutex is always initially unlocked. Mutexes (mutual excluders) are useful with multi-threaded controllers to protect some resources (typically variables or memory chunks) from being used simultaneously by different threads.

The wb_robot_mutex_delete() function deletes the specified mutex. This function should be used when a mutex is no longer in use.

The wb_robot_mutex_lock() function attempts to lock the specified mutex. If the mutex is already locked by another thread, this function waits until the other thread unlocks the mutex, and then locks it. This function returns only after it has locked the specified mutex.

The wb_robot_mutex_unlock() function unlocks the specified mutex, allowing other threads to lock it.

SEE ALSO

wb_robot_task_new.

Users unfamiliar with the mutex concept may wish to consult a reference on multi-threaded programming techniques for further information.

release 7.0.2
Copyright © 2012 Cyberbotics Ltd. All right reserved.