Derived from Solid.

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

Direct derived nodes: DifferentialWheels, Supervisor

3.35.1 Description

Robot is the root node for building a virtual robot. This node can be derived into either a Supervisor node or either a DifferentialWheels node.

3.35.2 Field Summary

• controller: name of the controller program that the simulator must use to control the robot. This program is located in a directory which name is equal to the field's value, which is itself located in the controllers subdirectory of the current project directory. For example, if the field value is "my_controller" then the controller program should be located there my_project/controllers/my_controller/my_controller[.exe]. The .exe extension is added on the Windows platforms only.

• controllerArgs: string containing the arguments (separated by space characters) to be passed to the main() function of the C/C++ controller program or the main() method of the Java controller program.

• synchronization: if the value is TRUE (default value), the simulator is synchronized with the controller; if the value is FALSE, the simulator runs as fast as possible, without synchronization. The wb_robot_get_synchronization() function can be used to read the value of this field from a controller program.

• battery: this field should contain three values: the first one corresponds to the present energy level of the robot in Joules (J), the second is the maximum energy the robot can hold in Joules, and the third is the energy recharge speed in Watts ([W]=[J]/[s]). The simulator updates the first value, while the other two remain constant. Important: when the current energy value reaches zero, the corresponding controller process terminates and the simulated robot stops all motion.

  Note: [J]=[V].[A].[s] and [J]=[V].[A.h]/3600

• cpuConsumption: power consumption of the CPU (central processing unit) of the robot in Watts.

• selfCollision: setting this field to TRUE will enable the detection of collisions within the robot. This is useful for complex articulated robots for which the controller doesn't prevent inner collisions. Enabling self collision is, however, likely to decrease the simulation speed, as more collisions will be generated during the simulation.

3.35.3 Robot Functions

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

DESCRIPTION

The wb_robot_step() function requests that the simulator perform a simulation step of ms milliseconds; that is, to advance the simulation by this amount of time. In synchronous simulation mode, the request is always fulfilled and the function always returns 0. In asynchronous mode, the request may not be fulfilled. In this case, the return value (which we'll call dt), representing the delay, may not be 0.

Let controller_date be the current time of the controller. The return value may be interpreted as follows:

• if dt = 0, then the behavior is equivalent to synchronous mode.

• if 0 <= dt <= ms, then the actuator values were set at controller_date + dt, and the sensor values were measured at controller_date + ms, as requested. It means that the step actually lasted the requested number of milliseconds, but the actuator commands could not be executed on time.

• if dt > ms, then the actuators values were set at controller_date + dt, and the sensor values were also measured at controller_date + dt. It means that the requested step duration could not be respected.

• if dt = -1, then a message for destructing the current controller has been raised. This must be treated in order to leave cleanly and safely the controller.

For the C API, two supplementary functions are needed for running a controller. The wb_robot_init function must be called before any other controller API function call in order to initialize the robot controller library. While it is recommended to call the wb_robot_cleanup function after any other controller API function call.

For the oriented-object API (Java, Python and C++), the void controller can be programmed by using only the wb_robot_step function..

MINIMAL C CONTROLLER EXAMPLE

#include <webots/robot.h> static WbDeviceTag my_sensor, my_actuator; int main() {     wb_robot_init(); /* initialize the webots controller library */      my_sensor = wb_robot_get_device("my_sensor");   my_actuator = wb_robot_get_device("my_actuator");      /* You should enable the sensors you want to read data from    */   /* using the corresponding wb_*_enable(my_sensor,32) functions */   /* main loop */   while (wb_robot_step(32) != -1) {     /* Perform a simulation step of 32 milliseconds   */     /* and leave the loop when the simulation is over */          /* Read and process sensor data */     /* Send actuator commands */   }   /* Add here your own exit cleanup code */   wb_robot_cleanup();   return 0; }

MINIMAL C++ CONTROLLER EXAMPLE

#include <webots/Robot.hpp> //#include <webots/LED.hpp> //#include <webots/DistanceSensor.hpp> using namespace webots; class MyRobot : public Robot {   //LED* led;   //DistanceSensor* distanceSensor;      public:     MyRobot(): Robot() {       //led = getLED("ledName");       //distanceSensor = getDistanceSensor("distanceSensorName");     }     virtual ~MyRobot() {       // Enter here exit cleanup code     }          void run(){       while (step(32) != -1) {         // Read the sensors, like:         //  double val = distanceSensor->getValue();                  // Process sensor data here                  // Enter here functions to send actuator commands, like:         //  led->set(1);         // Perform a simulation step       }     } }; int main(int argc, char **argv) {   MyRobot* controller = new MyRobot();   controller->run();   delete controller;   return 0; }

MINIMAL JAVA CONTROLLER EXAMPLE

import com.cyberbotics.webots.controller.*; public class MyRobot extends Robot {   //private LED led;   //private DistanceSensor distanceSensor;      public MyRobot() {     super();       // led = getLED("ledName");       // distanceSensor = getDistanceSensor("distanceSensorName");   }      public void run() {     while (step(32) != -1) {       // Read the sensors, like:       //  double val = distanceSensor.getValue();              // Process sensor data here              // Enter here functions to send actuator commands, like:       //  led.set(1);       // Perform a simulation step     }     // Enter here exit cleanup code   }      public static void main(String[] args) {     MyRobot controller = new MyRobot();     controller.run();   } }

MINIMAL PYTHON CONTROLLER EXAMPLE

from controller import * class template (Robot):   def run(self):     # led = self.getLed('ledName')     # distanceSensor = self.getDistanceSensor('distanceSensorName')          while (self.step(32) != -1):       # Read the sensors, like:       #  val = distanceSensor.getValue()       # Process sensor data here              # Enter here functions to send actuator commands, like:       #  led.set(1)                # Enter here exit cleanup code controller = template() controller.run()

NAME

C SYNOPSIS

DESCRIPTION

This function returns a unique identifier to 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

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

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 subclasse. 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

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

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.

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

DESCRIPTION

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

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

DESCRIPTION

This function returns an integer value indicating the current operating mode for the controller:

• 0: simulation in Webots.

• 1: cross-compiled version running natively on real robot.

• 2: robot remote controlled from Webots.

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

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

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

DESCRIPTION

This function returns 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

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

DESCRIPTION

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

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

DESCRIPTION

This function returns the current simulation time as a double precision floating point value. This time should correspond to the one displayed in the bottom right corner of the main Webots window. It is expressed in seconds.

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

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 logical AND with the WB_ROBOT_KEYBOARD_KEY mask to the key code. WB_ROBOT_KEYBOARD_SHIFT, WB_ROBOT_KEYBOARD_CONTROL and WB_ROBOT_KEYBOARD_ALT are OR-ed with the key code if the corresponding modifier key is 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.

Note: In C++, the keyboard predefined values are located into a (static) enumeration of the Robot class. For example, Robot.KEYBOARD_CONTROL corespond to the Control key stroke.

Note: In Java, the keyboard predefined values are located into a subclass (called KeyboardKey) of 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"); ...

Note: In Python, the keyboard predefined values are located into a enumeration of the Robot class. For example, Ctrl+B can be tested like this:

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

NAME

C SYNOPSIS

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

C SYNOPSIS

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 it 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.

^ page top ^