IndexNextUpPreviousUrbi SDK 3.0.0

Chapter 23
Urbi Standard Robotics API

This section aims at clarifying the naming conventions in Urbi Engines for standard hardware/software devices and components implemented as UObject and the corresponding methods/attributes/events to access them. The list of available hardware types and software component is increasing and this document will be updated accordingly. Please contact the maintainers, should you be working on a component not described or closely related to one described here.

 23.1 The Structure Tree
 23.2 Frame of Reference
 23.3 Component naming
 23.4 Localization
 23.5 Interface
  23.5.1 AudioIn
  23.5.2 AudioOut
  23.5.3 Battery
  23.5.4 BlobDetector
  23.5.5 Identity
  23.5.6 Led
  23.5.7 Mobile
  23.5.8 Motor
  23.5.9 Network
  23.5.10 Sensor
  23.5.11 SpeechRecognizer
  23.5.12 TextToSpeech
  23.5.13 Tracker
  23.5.14 VideoIn
 23.6 Standard Components
  23.6.1 Yaw/Pitch/Roll orientation
  23.6.2 Standard Component List
 23.7 Compact notation
 23.8 Support classes
  23.8.1 Interface
  23.8.2 Component
  23.8.3 Localizer

23.1 The Structure Tree

The hardware will be described as a set of components organized in a hierarchical structure called the structure tree. The relationship between a component and a sub-component in the tree is a ‘part-of’ inclusion relationship. From the point of view of Urbi, each component in the tree is an object, and it contains attributes pointing to its sub-components. Here is an example illustrating a part of a hierarchy that could be found with a wheeled robot with a gripper:


And here is another example for an humanoid robot:


The leaves of the tree are called devices, and they usually match physical devices in the hardware: motors, sensors, lights, camera, etc. Inside Urbi, the various objects corresponding to the tree components are accessed by following the path of objects inclusions, like in the example below (shortcuts will be described later):

// ...  

The structure tree should not be mistaken for a representation of the kinematics chain. The kinematics chain is built from a subset of the devices corresponding to motor devices, and it represents spatial connections between them. Except for these motor devices, the structure tree components do not have a direct counterpart in the kinematics chain, or, if they do, it is as a subset of the kinematics chain (for example, leg[right] is a subset of the whole kinematics chain).

The goal of this standard is to provide guidelines on how to define the components and the structure tree, knowing the kinematics chain.

23.2 Frame of Reference

In many cases, it will be necessary to refer to an absolute frame of reference attached to the hardware. To avoid ambiguities, the standard frame of reference will have the following definition:


the center of mass
X axis
oriented towards the front of the machine. If there is a camera, the front is defined by the default direction of the camera, otherwise the front will be seen as the natural frontal orientation for a mobile robot (the direction of “forward” movement). If the robot is not naturally oriented, the X axis will be chosen to match the main axis of symmetry of the robot body and it will be oriented towards the smallest side, typically the top of a cone for example. In case of a perfectly symmetrical body, the X axis can be chosen arbitrarily but a clear mark should be made visible on the robot body to indicate it.
Z axis
oriented in the opposite direction from the gravity. If there is no gravity or natural up/down orientation in the environment or normal operation mode, the Z axis should be chosen in the direction of the main axis of symmetry in the orthogonal plane defined by the X axis, oriented towards the smallest side. In case of a perfectly symetrical plane, the Z axis can be chosen arbitrarily but a clear mark should be made visible on the machine’s body to indicate it.
Y axis
oriented to make a right-handed coordinate system.

The axes are oriented in a counter-clockwise direction, as depicted in the illustration above.

23.3 Component naming

Each component A, which is a sub-component of component B has a name, distinct from the name of all the other components at the same level. This name is a generic designation of what A represents, such as “leg” ,“head”, or “finger”.

Using the correct name for each component is a critical part of this standard. No formal rule can be given to find this name for any possible hardware configuration. However, this document includes a table covering many different possible cases. We recommend that manufacturers pick from this table the name that fits the most the description of their component.

23.4 Localization

When two identical components A1 and A2, such as the two legs of an humanoid robots, are present in the same sub-component B, an extra node is inserted in the hierarchy to differentiate them. This node is of the Localizer type, and provides a [] operator, taking a Localization argument, used to access each of the identical sub-components. The Urbi SDK provides an implementation for the Localizer and Localization classes. When possible, localization should be simple geometrical qualifier like right/center/left, front/middle/back or up/in-between/down. Note that “right” or “front” are understood here from the point of view of a man standing and looking in the direction of the X-axis of the machine, and up/pown matches the Z-axis, as depicted in the figure below:


Several geometric qualifiers can be used at the same time to further refine the position. In this case, multiple Localizer nodes are used. As a convention, height information (U/I/D) comes first, followed by depth information (F/M/H), and then side information (R/C/L).

// Front-left wheel of a four-wheeled robot: 
// Front laser of a robot equipped with multiple sonars: 
// Left camera from a robot with a stereo camera at the end of an arm:[left]; 
// Top-left LED of the left eye. 
robot.body.head.eye[left].led[up][left].val = 1; 
// Touch sensor at the end of the front-left leg of a four-legged robot: 

You can further qualify a side+depth localization with an additional F/B side information. This can be used in the typical layout below:


This dual positioning using side+depth can also be used to combine side+height or height+depth information.

Layouts with a sequence of three or more identical components can use numbers as their Localization, starting from 0. The smaller the number, the closer to the front, up, or left. For instance, an insectoid robot with 3 legs on each side will use robot.body.leg[left][0] to address the frontleft leg.

Layouts with identical components arranged in a circle can also use numeric localization. The component with index 0 should be the uppermost, or front-most if non applicable. Index should increase counterclockwise.

Some components like spines or tails are highly articulated with a set of identical sub-components. When talking about these sub-components, the above localization should be replaced by an array with a numbering starting at 0. The smaller the number, the closer the sub-component is to the robot main body. For surface-like sub-components, like skin touch sensors, the array can be two dimensional.

Other possible localization for sensors are the X, Y and Z axis themselves, like for example for an accelerometer or a gyro sensor, available in each of the three directions.

robot.body.accel[x]; // accelerometer in the x direction  

Examples of component names including localization:

leg[right], leg[left]; 
finger[right], finger[center], finger[left];  // three-finger hand 
joint[0], joint[1] ... joint[5]               // from tail 
touch[478][124]                               // from skin 
accel[x], accel[y], accel[z];                 // typical accelerometer 
gyro[x], gyro[y], gyro[z];                    // typical gyro sensor  

23.5 Interface

An interface describes some aspects of a type of device, by specifying the slots and methods that implementations must provide. Each child node of the component hierarchy should implement at least one interface.

For example, for a joint, we can have a “Swivel” interface, used to define patella joints. For the robot body itself, we have a Interface.Mobile interface describing mobile robots, which includes some standard way of requesting a move forward, a turn, etc.

In short, interfaces are standard Urbi objects that components can inherit from to declare that they have some functionalities.

The following pages describe a few of the most standard interfaces. Each device in the component hierarchy which falls within the category of an interface should implement it.

Each interface defines slots, which can be functions, events or plain data. Some of those slots are optional.

23.5.1 AudioIn

The AudioIn interface groups every information relative to microphones.

23.5.2 AudioOut

The AudioOut interface groups every information relative to speakers.

23.5.3 Battery

Power source of any kind.

23.5.4 BlobDetector

Ball detectors, marker detectors and various feature-based detectors should all share a similar interface. They extract a part of the image that fits some criteria and define a blob accordingly. Here are the typical slots expected:

23.5.5 Identity

Information about the hardware.

23.5.6 Led

Simple uni-color Led. RGBLed

Subclass of Interface.Led. Tri-color led.

23.5.7 Mobile

Mobile robots all share this generic interface to provide high order level motion control capabilities. Blocking API

The following set of functions will block until associated movement is finished. If a function of this set is called while an other is already running, the first call will be canceled: the movement will be interrupted and the call will return.

Many of the functions below take a position argument. This position is expressed as a subset of the six values x, y, z, rho, theta, phi. Speed-control API

In addition to the previous functions, one can directly set the target movement speed in all linear/angular directions using the 6 scalar variables xSpeed, ySpeed, zSpeed, yawSpeed, pitchSpeed, rollSpeed, or the variable speed which contains a list. Writing to one of those slots will abort any function in the blocking API.

Implementations should provide default reasonable values for speed in the slots defaultXSpeed, defaultYSpeed, defaultZSpeed, defaultYawSpeed, defaultPitchSpeed and defaultRollSpeed. Safety State

23.5.8 Motor

This interface is used to describe a generic motor controller. LinearMotor

Subclass of Interface.Motor. This interface is used to describe a linear motor controller.

A wheel can fall in this category, if the reported position is the distance traveled by a point at the surface of the wheel. LinearSpeedMotor

Subclass of Interface.Motor. Motor similar to Interface.LinearMotor, but controlled by its translation speed. RotationalMotor

Subclass of Interface.Motor. This interface is used to describe a position-controlled rotational motor controller. RotationalSpeedMotor

Subclass of Interface.Motor. Interface describing a motor similar to RotationalMotor controlled by its rotation speed.

23.5.9 Network

Contains information about the network identification of the hardware.

23.5.10 Sensor

This interface is used to describe a generic sensor. AccelerationSensor

Subclass of Interface.Sensor. This interface is used to describe an accelerometer. DistanceSensor

Subclass of Interface.Sensor. This interface is used to describe a distance sensor (infrared, laser, ultrasonic…). GyroSensor

Subclass of Interface.Sensor. This interface is used to describe an gyrometer. Laser

Subclass of Interface.Sensor. Interface for a scanning laser rangefinder, or other similar technologies.

Depending on the implementation, some of the parameters can be read-only, or can only accept a few possible values. In that case it is up to the implementer to select the closest possible value to what the user entered. It is the responsibility of the user to read the parameter after setting it to check what value will actually be used by the implementation. TemperatureSensor

Subclass of Interface.Sensor. This interface is used to describe a temperature sensor. TouchSensor

Subclass of Interface.Sensor. This interface is used to describe a touch pressure sensor (contact, induction, etc.).

23.5.11 SpeechRecognizer

Speech recognition allows to transform a stream of sound into a text using various speech recognition algorithms. Implementations should use the micro component as their default sound input.

23.5.12 TextToSpeech

Text to speech allows to read text using a speech synthesizer. Default implementations should use the speaker component (or alias) as their default sound output.

23.5.13 Tracker

Camera-equipped machines can sometimes move the orientation of the field of view horizontally and vertically, which is a very important feature for many applications. In that case, this interface abstracts how such motion can be achieved, whether it is done with a pan/tilt camera or with whole body motion or a combination of both.

23.5.14 VideoIn

The VideoIn interface groups every information relative to cameras or any image sensor.

The image sensor is expected to use the cheapest way in term of CPU and/or energy consumption to produce images of the requested format. Implementations linked to a physical image sensor do not have to implement all the possible formats. In this case, the format closest to what was requested must be used. A generic image conversion object will be provided. In order to avoid duplicate image conversions when multiple unrelated behaviors need the same format, it is recommended that this object be instantiated in a slot of the VideoIn object named after the format it converts to:

if (!"jpeg")) 

  var ="val")); = 3; 

23.6 Standard Components

Standard components correspond to components typically found in wheeled robots, humanoid or animaloid robots, or in industrial arms. This section provides a list of such components. Whenever possible, robots compatible with the Gostai Standard Robotics API should name all the components in the hierarchy using this list.

23.6.1 Yaw/Pitch/Roll orientation

Note that Gostai Standard Robotics API considers the orientation to be a component name, and not a localizer. So one would write head.yaw and not head.joint[yaw] to refer to a rotational articulation of the head around the Z axis.

It is not always clear which rotational direction corresponds to the yaw, pitch or roll components (listed in the table below). This is a quick guideline to help determine the proper association.

Let us consider the robot in its resting, most prototypical position, like “standing” on two or four legs for a humanoid or animaloid, and let all members “naturally” fall under gravity. When gravity has no effect on a certain joint (because it is in the orthogonal plan to Z, for example), the medium position between rangemin and rangemax should be used. The body position achieved will be considered as a reference. Then for each component that is described in terms of yaw/pitch/roll sub-decomposition, the association will be as follow:

rotational articulation around the Z axis in the robot.
rotational articulation around the Y axis in the robot.
rotational articulation around the X axis in the robot.

When there is no exact match with the X/Y/Z axis, the closest match, or the default remaining available axis, should be selected to determine the yaw/pitch/roll meaning.

23.6.2 Standard Component List

The following table summarizes the currently referenced standard components, with a description of potential components that they could be sub-component of, a description of potential components they may contain, and a list of relevant interfaces. This table should be seen as a quick reference guide to identify available components in a given robot.

Name Description Sub. of Contains Facets

robot The main component that represents an abstraction of the robot, and the root node of the whole component hierarchy. body Identity Network Mobile Tracker

body The main component that contains every piece of hardware in the robot. This includes all primary kinematics sub-chains (arms, legs, neck, head, etc) and non-localized sensor arrays, typically body skin or heat detectors. Localized sensors, like fingertips touch sensors, will typically be found attached to the finger component they belong and not directly to the body. robot wheel arm leg neck head wheel tail skin torso …

wheel Wheel attached to its parent component. body RotationalMotor

leg Legs are found in humanoid or animaloid robots and correspond to part of the kinematics chain that are attached to the main body by one extremity only and which do touch the ground in normal operation mode (unlike arms). A typical configuration for humanoids contains a hip, a knee and an ankle. If the leg is more segmented, the leg can be described with a simple array of joints. body hip knee ankle foot joint

arm Unlike legs, an arm’s extremity does not always touch the ground in normal operating mode. This applies to humanoid robots or single-arm industrial robots. Arms supersede legs in the nomenclature: if a body part behaves alternatively like an arm and like a leg, it will be considered as an arm. body shoulder elbow wrist hand grip joint

shoulder The shoulder is the upper part of the arm. It can have one, two or three degrees of freedom and is the closest part of the arm relative to the body. arm yaw pitch roll

elbow Separates the upper arm and the lower arm, this is usually a single rotational axis. arm pitch

wrist Connects the hand and the lower part of the arm. Usually three degrees of freedom axis. arm yaw pitch roll

hand The hand is an extension of the arm that usually holds fingers. It’s not the wrist, which is articulated and between the arm and the hand. arm finger

finger A series of articulated motors at the extremity of the arm, and connected to the hand. Fingers are usually localized with arrays and/or lateral localization respective to the hand. hand touch Motor

grip Simple two-fingers system. arm hand touch Motor

hip The hip is the upper part of the leg and connects it to the main body. It can have one, two or three degrees of freedom. leg yaw pitch roll

knee Separates the upper leg and the lower leg, this is usually a single rotational axis. leg pitch

ankle Connects the foot and the lower part of the leg. Usually three degrees of freedom axis. leg yaw pitch roll

foot The foot is an extension of the leg that usually holds toes. It’s not the ankle, which is articulated and between the leg and the foot. The foot can also contain touch sensors in simple configurations. leg touch

toe Like fingers, but attached to a foot. foot touch Motor

neck The neck corresponds to a degree of freedom not part of the head, but relative to the rigid connection between the head and the main body. body yaw pitch roll

tail A series of articulated motors at the back of the robot. body joint

head The head main pivotal axis. body neck camera mouth ear lip eye eyebrow

mouth The robot mouth (open/close). head lip Motor

ear Ears may have degrees of freedom in certain robots. head Motor

joint Generic articulation in the robot. tail arm leg lip Motor

yaw Rotational articulation around the Z axis in the robot. See Section 23.6.1. body neck knee ankle shoulder elbow wrist torso RotationalMotor RotationalSpeedMotor

pitch Rotational articulation around the Y axis in the robot. See Section 23.6.1. body neck knee ankle shoulder elbow wrist torso RotationalMotor RotationalSpeedMotor

roll Rotational articulation around the X axis in the robot. See Section 23.6.1. body neck knee ankle shoulder elbow wrist torso RotationalMotor RotationalSpeedMotor

x Translational movement along the X axis. body arm LinearMotor LinearSpeedMotor

y Translational movement along the Y axis. body arm LinearMotor LinearSpeedMotor

z Translational movement along the Z axis. body arm LinearMotor LinearSpeedMotor

lip Corresponds to animated lips. mouth joint Motor

eye Corresponds to the eyeball pivotal axis. head camera

eyebrow Some robots will have eyebrows with generally one or several degrees of freedom. head joint Motor

torso This corresponds to a pivotal or rotational axis in the middle of the main body. body yaw pitch roll

spine This is a more elaborated version of “torso”, with a series of articulations to give several degrees of freedom in the back of the robot. torso joint

clavicle This is not to be mixed up with the “top of the arm” body part. It is an independent degree of freedom that can be used to bring the two arms closer in a sort of “shoulder raising” movement. body Motor

touch Touch sensor. finger grip foot toe TouchSensor

gyro Gyrometer sensor. body GyroSensor

accel Accelerometer sensor. body AccelerationSensor

camera Camera sensor. If several cameras are available, localization shall apply; however there must always be an alias from camera to one of the effective cameras (like cameraR or cameraL). head body VideoIn

speaker Speaker device. If several speakers are available, localization shall apply; however there must always be an alias from speaker to one of the effective speakers (like speakerR or speakerL). head body AudioOut

micro Microphone devices. If several microphones are available, localization shall apply; however there must always be an alias from micro to one of the effective microphones (like microR or microL). head body AudioIn

speech Speech recognition component. robot SpeechRecognizer

voice Voice synthesis component. robot TextToSpeech

23.7 Compact notation

Components are usually identified with their full-length name, which is the path to access them inside the structure tree. For convenience and backward compatibility with pre-2.0 versions of Urbi, there is also a compact notation available. We will describe here how to construct the compact notation starting from the full name and the structure tree.

Full name Compact name

robot.body.armR.elbow elbowR
robot.body.head.yaw headYaw
robot.body.legL.knee.pitch kneeL
robot.body.armR.hand.finger[3][2] fingerR[3][2]
robot.body.armL.hand.fingerR fingerLR

The rule is to move every localization qualifier at the end of the compact notation, in the order where they appear in the full-length name. The remaining component names should then be considered one by one to see if they are needed to remove ambiguities. If they are not, like typically the robot or body components which are shared with almost every other full-length name, they can be ignored. If finally several component names have to be kept, they should be separated by using upper case letters for the first character instead of a dot, like in Java-style notation.

Some detailed examples:

23.8 Support classes

The Urbi SDK provides a few support urbiscript classes to help you build the component hierarchy. You can access to those classes by including the files ‘urbi/naming-standard.u’ and ‘urbi/component.h’.

23.8.1 Interface

The Interface class contains urbiscript objects for all the interfaces defined in this document. Implementations must inherit from the correct interface.

// Instantiate a camera. 
var cam =; 
// Make it inherit from VideoIn. 

The Interface.interfaces method can be called to get a list of all the interfaces an object implements.

23.8.2 Component

This class can be used to create intermediate nodes of the hierarchy. It provides the following methods:

23.8.3 Localizer

The Localizer class is a special type of Component that stores other components based on their localization. It provides a ’[]’ operator that takes a Localization, such as top,left,front, and that can be used to set and get the Component or device associated with that Localization.

Note that the ’[]’ function is using a mechanism to automatically look for its argument as a slot of Localizer. As a consequence, you cannot pass a variable to this function, but only one of the constant Localization. To pass a variable, use the get(loc) or the set(locvalue) function.

The following example illustrates a typical instantiation sequence.

// Create the top-level node. 
var Global.robot ="robot"); 
var cam =; 
robot.head.addDevice("camera", cam); 
// Add two wheels. 
robot.wheel[left] =; 
robot.wheel[right] =; 
// Implement the Mobile facet in urbiscript. 
function robot.go (d) 

  robot.wheel.val = robot.wheel.val + d / wheelRadius adaptive:1 
function robot.turn(r) 

  var v = r * wheelDistance / wheelRadius; 
  robot.wheel[left].val = robot.wheel[left].val + v adaptive:1 & 
  robot.wheel[right].val = robot.wheel[right].val - v adaptive:1 
// Let us see the result. 
[00010130] *** Mobile: robot 
[00010130] *** RotationalMotor: wheelL wheelR 
[00010130] *** VideoIn: camera