Adding a New Robot

In order to guarantee a homogeneous overall quality, several steps have to be fulfilled when adding a new robot to the Webots main repository. This page lists these steps.

In order to illustrate this documentation, let say that the fictional robot to be added is called iCobra 22 and is developed by the Snake Logistics company.

Target Branch

The branch containing the new robot can target the develop branch.

General Considerations

• The new robot should be defined as a PROTO node if feasible.
• A pertinent .*.wbproj perspective file should be released for each *.wbt world file. This hidden file is automatically generated when saving the world in Webots.

Files, Directories and Name Convention

• File and directory names should be written in Snake case.
• PROTO names should be written in Camel case. Dashes can be added if they help to understand better the robot name.
• The new directory should be added in the projects/robots/COMPANY/ROBOT_NAME directory and fulfill the standard file hierarchy.

For example:

$WEBOTS_HOME/projects/robots/snake_logistics/i_cobra_22/controllers/i_cobra_22/
$WEBOTS_HOME/projects/robots/snake_logistics/i_cobra_22/protos/ICobra22.proto
$WEBOTS_HOME/projects/robots/snake_logistics/i_cobra_22/protos/icons/ICobra22.png
$WEBOTS_HOME/projects/robots/snake_logistics/i_cobra_22/worlds/i_cobra_22.wbt

Expected PROTO Header

• The PROTO header should contain a description of the robot, it's license and license URL.
• The PROTO header should contain a keywords: line containing one of the following value: robot/arm, robot/legged, robot/wheeled, robot/flying, robot/tracked or robot/other. This will be used to classify the robot on https://webots.cloud/proto.
• If feasible, the robot PROTO fields should contain the following fields (as shown in the example above): translation, rotation, name, controller, controllerArgs, customData, supervisor, synchronization and extensionSlot.

For example:

#VRML_SIM R2019a utf8
# license: Copyright Cyberbotics Ltd. Licensed for use only with Webots.
# license url: https://cyberbotics.com/webots_assets_license
# keywords: robot/arm
# documentation url: https://www.cyberbotics.com/doc/guide/i-cobra-22
# The "iCobra-22" is a robot developed by "Snake Logistics": https://snake-logistics.com/icobra

PROTO ICobra22 [
  field SFVec3f    translation     0 0 0        # Is `Transform.translation`.
  field SFRotation rotation        0 1 0 1.5708 # Is `Transform.rotation`.
  field SFString   name            "iCobra 22"  # Is `Solid.name`.
  field SFString   controller      "i_cobra_22" # Is `Robot.controller`.
  field SFString   controllerArgs  ""           # Is `Robot.controllerArgs`.
  field SFString   customData      ""           # Is `Robot.customData`.
  field SFBool     supervisor      FALSE        # Is `Robot.supervisor`.
  field SFBool     synchronization TRUE         # Is `Robot.synchronization`.
  field MFNode     extensionSlot   []           # Extends the robot with new nodes located in the body center.
]
{
  Robot {
    translation IS translation
    rotation IS rotation
    controller IS controller
    controllerArgs IS controllerArgs
    customData IS customData
    supervisor IS supervisor
    synchronization IS synchronization
    name IS name
    model "Snake Logistics' iCobra 22"
    # ...
    children [
      Group {
        children IS extensionSlot
      }
      # ...
    ]
  }
}

Main Build System

The C / C++ and Java controllers should have a Makefile. This Makefile should be called by the parent Makefile(s). For example, to build

1. https://github.com/cyberbotics/webots/blob/master/projects/robots/gctronic/e-puck/controllers/e-puck/Makefile
2. https://github.com/cyberbotics/webots/blob/master/projects/robots/gctronic/e-puck/controllers/Makefile
3. https://github.com/cyberbotics/webots/blob/master/projects/robots/Makefile

Documentation

It's required to write a documentation page for the robot.

Please refer to this documentation to know more about the Webots documentation system: https://github.com/cyberbotics/webots/tree/master/docs

Files to be created/updated:

$WEBOTS_HOME/docs/guide/i_cobra_22.md
$WEBOTS_HOME/docs/guide/menu.md [to be updated]
$WEBOTS_HOME/docs/guide/robots.md [to be updated]
$WEBOTS_HOME/docs/guide/images/robots/i_cobra_22/model.png
$WEBOTS_HOME/docs/guide/images/robots/i_cobra_22/icon.png
$WEBOTS_HOME/docs/guide/images/robots/i_cobra_22/*.wbt.png

Add a Change Log Item

An item should be added to the change log file: $WEBOTS_HOME/docs/reference/changelog-r2022.md.

Helper Scripts

Icon Studio

Icon studio may help to create the required icon and documentation screenshots. Please refer to the related documentation: https://github.com/cyberbotics/webots/tree/master/scripts/icon_studio

Web Component Studio

Web Component Studio is required to create the required 3D component of documentation: Please refer to the related documentation: https://github.com/cyberbotics/webots/tree/develop/scripts/web_component_studio