Prev

Prev-tail

Tail

Up

Chapter 23
Gostai 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 us directly, should you be working on a component not described or closely related to one described here:

standard@gostai.com

Any implementation of an Urbi server must comply with the latest version of this standard to get the “Urbi Ready” certification from Gostai S.A.S.

Gostai S.A.S. is currently the only authority which has the ability to deliver an “Urbi Ready” certification.

“Urbi Ready” and the associated logo are trademarks of Gostai S.A.S. and should not be used or displayed in any way without an explicit written agreement from Gostai.

 23.1 The Structure Tree
 23.2 Frame of Reference
 23.3 Component naming
 23.4 Localization
 23.5 Interface
  23.5.1 Identity
  23.5.2 Network
  23.5.3 Motor
  23.5.4 LinearMotor (subclass of Motor)
  23.5.5 LinearSpeedMotor (subclass of Motor)
  23.5.6 RotationalMotor (subclass of Motor)
  23.5.7 RotationalSpeedMotor (subclass of Motor)
  23.5.8 Sensor
  23.5.9 DistanceSensor (subclass of Sensor)
  23.5.10 TouchSensor (subclass of Sensor)
  23.5.11 AccelerationSensor (subclass of Sensor)
  23.5.12 GyroSensor (subclass of Sensor)
  23.5.13 TemperatureSensor (subclass of Sensor)
  23.5.14 Laser (subclass of Sensor)
  23.5.15 Mobile
  23.5.16 Tracker
  23.5.17 VideoIn
  23.5.18 AudioOut
  23.5.19 AudioIn
  23.5.20 BlobDetector
  23.5.21 TextToSpeech
  23.5.22 SpeechRecognizer
  23.5.23 Led
  23.5.24 RGBLed (subclass of Led)
  23.5.25 Battery
 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 robot 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:

PIC

And here is another example for an humanoid robot:

PIC

The leaves of the tree are called devices, and they usually match physical devices in the robot: 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):

 
body.leg[right].hip.tilt; 
body.arm.grip; 
body.laser; 
// ...  

The structure tree should not be mistaken for a representation of the kinematics chain of the robot. 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 of the robot.

23.2 Frame of Reference

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

PIC

Origin
the center of mass of the robot
X axis
oriented towards the front of the robot. 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 of the robot, 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 symmetrical plane, the Z axis can be chosen arbitrarily but a clear mark should be made visible on the robot 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 robot configuration. However, this document includes a table covering many different possible cases. We recommend that robot 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 robot, and up/pown matches the Z-axis, as depicted in the figure below:

PIC

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: 
robot.body.wheel[front][left]; 
// Front laser of a robot equipped with multiple sonars: 
robot.body.laser[front]; 
// Left camera from a robot with a stereo camera at the end of an arm: 
robot.body.arm.camera[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: 
robot.body.leg[front][left].foot.touch;  

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

PIC

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 “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: they are grayed and put around square brackets in the following table.

23.5.1 Identity

Contains information about the robot identity.

23.5.2 Network

Contains information about the network identification of the robot.

23.5.3 Motor

This interface is used to describe a generic motor controller.

23.5.4 LinearMotor (subclass of 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.

23.5.5 LinearSpeedMotor (subclass of Motor)

Motor similar to LinearMotor, but controlled by its translation speed.

23.5.6 RotationalMotor (subclass of Motor)

This interface is used to describe a position-controlled rotational motor controller.

23.5.7 RotationalSpeedMotor (subclass of Motor)

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

23.5.8 Sensor

This interface is used to describe a generic sensor.

23.5.9 DistanceSensor (subclass of Sensor)

This interface is used to describe a distance sensor (infrared, laser, ultrasonic...).

23.5.10 TouchSensor (subclass of Sensor)

This interface is used to describe a touch pressure sensor (contact, induction,...).

23.5.11 AccelerationSensor (subclass of Sensor)

This interface is used to describe an accelerometer.

23.5.12 GyroSensor (subclass of Sensor)

This interface is used to describe an gyrometer.

23.5.13 TemperatureSensor (subclass of Sensor)

This interface is used to describe a temperature sensor.

23.5.14 Laser (subclass of 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.

23.5.15 Mobile

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

23.5.16 Tracker

Camera-equipped robots 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.17 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 (!robot.body.head.camera.hasSlot("jpeg")) 
{ 
  var robot.body.head.camera.jpeg = 
    ImageConversion.new(robot.body.head.camera.getSlot("val")); 
  robot.body.head.camera.jpeg.format = 3; 
}  

23.5.18 AudioOut

The AudioOut interface groups every information relative to speakers.

23.5.19 AudioIn

The AudioIn interface groups every information relative to microphones.

23.5.20 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.21 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.22 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.23 Led

Simple uni-color Led.

23.5.24 RGBLed (subclass of Led)

Tri-color led.

23.5.25 Battery

Power source of any kind.

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:

yaw
rotational articulation around the Z axis in the robot.
pitch
rotational articulation around the Y axis in the robot.
roll
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 This is 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 This is 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 Fingers are a series of articulated motors at the extremity of the arm, and connected to the hand. They 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 the 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 tail is 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 AudioIn






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 AudioOut






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.

Example 1 (robot.body.armL.hand.fingerR)  

  1. Move all localization at the end: robot.body.arm.hand.fingerLR
  2. The full name remaining is: robot.body.arm.hand.finger
  3. finger should be kept, hand, arm, body and robot are not necessary since every finger component will always be attached only to a hand, itself attached to an arm and a body and a robot.
  4. The result is fingerLR

Example 2 (robot.body.head.yaw)  

  1. No localization to move
  2. yaw must be kept because head also have a pitch sub-component and
  3. head must also be kept to avoid ambiguity with other components having a yaw sub-component.
  4. The result is headYaw

Example 3 (robot.body.legL.knee.pitch)  

  1. Move all localization at the end: robot.body.leg.knee.pitchL
  2. pitch is not necessary because knee has only a pitch, so knee will be kept only
  3. The result is kneeL

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 = myCamera.new(); 
// Make it inherit from VideoIn. 
cam.addProto(Interface.VideoIn);  

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

23.8.2 Component

The Component 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 mechanisms 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(loc, value) function.

The following example illustrates a typical instantiation sequence:

 
// Create the top-level node. 
var Global.robot = Component.new("robot"); 
robot.addComponent("head"); 
var cam = MyCamera.new; 
cam.addProto(Interface.VideoIn); 
robot.head.addDevice("camera", cam); 
// Add two wheels 
robot.addComponent(Localizer.new("wheel")); 
robot.wheel[left] = MyWheel.new(0).addProto(Interface.RotationalMotor); 
robot.wheel[right] = MyWheel.new(1).addProto(Interface.RotationalMotor); 
// Implement the Mobile facet in urbiscript: 
var robot.go = function(d) 
{ 
  robot.wheel.val = robot.wheel.val + d / wheelRadius adaptive:1 
}; 
var robot.turn = function(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 
}; 
robot.addProto(Interface.Mobile); 
robot.makeCompactNames; 
// Let us see the result: 
robot.flatDump; 
[00010130] *** Mobile: robot 
[00010130] *** RotationalMotor: wheelL wheelR 
[00010130] *** VideoIn: camera