Architecture:Specification of BABEL Interfaces
| Previous: Overview | Next: Modules |
Contents
Interfaces
Overview
In this page we present a number of standardized interfaces (IFs) for each layer of modules in our architecture. One given module may implement only one or several such interfaces simultaneously, a specially common case in the HAD layer.
Each interface is implemented in one and only one BABEL service groups, whose services are specified here. Data types are given in the standard BABEL description language (BDL), with some small additions declared under the namespace BABEL::COMMON, as shown in this Appendix.
The input parameter "devIndex" deserves more discussion, since it solves the problem of multiple copies of hardware devices with just one software module. This parameter is a zero-based index which specifies which device is being referenced for each access. The number of different devices is stored in the RPD (see section 4). Only modules in layers 2 and 3 are supposed to know about this parameter, so high-level modules never need to worry about how many hardware devices are present on the robot.
Developers of HAD modules are strongly encouraged to do implement real support for "devIndex". For example, at module start-up, the RPD may be checked to discover how many devices are present on the robot and what are they parameters (configuration ".ini"-like text block). An internal list of objects can be hold within the BABEL module, one for each physical device, so each request is directed to the appropriate device. If however, "devIndex" is ignored in either the calling or called part, please set it to "0" for compatibility with future versions that will really do use this index.
Hardware Abstraction Driver (HAD) interfaces
The next section ( Modules) contains a list of existing modules and the corresponding implemented IFs.
DRV_ALIASES
This interface is implemented in all hardware-related Modules that support multiple internal working copies ("aliases"). It is mainly used to retrieve the number of physical devices represented by this module, such as the parameter deviceIndex in all other interfaces can be in the range [0,nAliases-1].
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
out short nAliases </cpp> |
Retrieves the number of physical devices represented by this module, such as the parameter deviceIndex in all other interfaces can be in the range [0,nAliases-1]. |
DRV_IOBOARD
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, out unsigned short count ) </cpp> |
Returns the number of Analog-to-Digital converters (ADC) available as inputs on this device. |
|
<cpp>
in short devIndex, out COMMON::SeqOfFloats readings, out boolean error ) </cpp> |
Return the latest ADC readings from the device. They are given in volts and are supposed to be acquired in last few milliseconds (Max. 1 sec.). Error is true on any error. | |
|
<cpp>
in short devIndex, out unsigned short count ) </cpp> |
Returns the number of Digital-to-Analog converters (DAC) available as outputs on this device. |
|
|
<cpp>
in short devIndex, in unsigned short channel, in float value, out boolean error ) </cpp> |
Sets an analog output. Desired value is given in volts, first channel is 0; error is true on failure. |
|
|
<cpp>
in short devIndex, out unsigned short count ) </cpp> |
Returns the number of sonars-range-finders attached to this device. |
|
|
<cpp>
in short devIndex, out COMMON::SeqOfFloats readings, out boolean error ) </cpp> |
Return the latest sonars readings from the device. They are given in meters and are supposed to be acquired in last few milliseconds (Max. 1 sec.). Error is true on any error. |
|
|
<cpp>
in short devIndex, out unsigned short count ) </cpp> |
Returns the number of PWM generators available as outputs on this device. They can be used to control servos. |
|
|
<cpp>
in short devIndex, in unsigned short channel, in float value, out boolean error ) </cpp> |
Sets the PWM “on” period, given in seconds. Typical values are 0.0002-0.004 secs; first channel is 0; error is true on failure. |
|
DRV_MOBILE_BASE
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, in boolean reset, out double x, out double y, out double phi, out double v, out double w, out boolean error ) </cpp> |
Reads the current odometric increment: x,y in meters and phi in radians, positive values are anticlockwise. phi=0 means heading towards positive x axis. If reset is true, odometry is set to (0,0,0) thus each request acquires the motion difference. Linear (v) and angular (w) velocities are also estimated, in m/s (positive/negative for forward/backward) and rad/s (positive is anticlockwise), respectively; error is true on failure. |
|
<cpp>
in short devIndex, in double x, in double y, in double phi, out boolean error ) </cpp> |
Changes the odometry estimation of the device. ; error is true on failure. |
|
|
<cpp>
in short devIndex, in double v, in double w, out boolean error ) </cpp> |
Changes the desired base linear (v) and angular (w) velocities, in m/s and rad/s, respectively. The conventions are the same than in service “getOdometry”; error is true on failure. |
|
|
<cpp>
in short devIndex, out double x, out double y, out double phi, out double v, out double w, out boolean error ) </cpp> |
Only for simulated robots: It returns the true pose, and velocities, of the robot in the simulated world coordinate reference. In non-simulated modules this method may return the current robot odometry. |
|
|
<cpp>
in short devIndex, in double maxPeriod, out boolean error ) </cpp> |
Enables the watchdog timer, which completely stops the robot if "setVelocities" is not called in a period of "maxPeriod" seconds. An error=true will be obtained only for invalid values of devIndex. |
|
|
<cpp>
in short devIndex, out boolean error ) </cpp> |
Disables the watchdog timer. An error=true will be obtained only for invalid values of devIndex. |
|
DRV_2D_RANGE_SCANNER
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, out COMMON::SeqOfFloats scan, out COMMON::SeqOfBools valid, out COMMON::TTimeStamp time, out boolean error ) </cpp> |
Reads the last received scan, as distances in meters. Valid indicates non-reflected rays or any other error in individual measurements; error is true on failure. |
|
<cpp>
in short devIndex, out COMMON::SeqOfBytes obs, out boolean error ) </cpp> |
Return the last scan as a serialized MRPT object of the class mrpt::slam::CObservation2DRangeScan. |
|
DRV_INERTIAL_SENSOR
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, out COMMON::SeqOfBytes obs, out boolean error ) </cpp> |
Return the last reading as a serialized MRPT object of the class mrpt::slam::CObservationIMU. |
DRV_GAS_SENSOR
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, out COMMON::SeqOfBytes obs, out boolean error ) </cpp> |
Return the last reading as a serialized MRPT object of the class mrpt::slam::CObservationGasSensors. |
DRV_CAMERA_SENSOR
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, out COMMON::SeqOfBytes obs, out boolean error ) </cpp> |
Return the last reading as a serialized MRPT object of class either: NOTE: At the choice of each image-server module, images can be stored in MRPT "delayed-load" format, which allows ultra-fast passing of image objects through the BABEL interface by a file-based cache system which is transparent to the final user. However, even this mechanism being transparent, images may be cached for a small period of time only, thus make a copy of the image if it will be needed a few seconds (~10 secs?) after grabbing. |
DRV_BATTERY_LEVEL
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, out boolean charging, out float level, out float estLife, out boolean error ) </cpp> |
Reads the level of the battery (0:empty, 1:full), and an estimation of the remaining running time to full discharge (estLife) in seconds; if charging is true, the robot is connected to a power supply and previous values should not be applicable. error is true on any error. |
DRV_SPEECH
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, in boolean enable, out boolean error ) </cpp> |
Enables (true) or disables (false) sending events on speech detection. error is true on any error. Default is disabled. Event code is 5000. |
|
<cpp>
in short devIndex, out COMMMON::SeqOfStrings phrases out boolean error ) </cpp> |
Returns the queue of last recognised phrases in a strings list. If none the list will be empty. This can be polled or read after an event is received. error is true on any error. |
|
|
<cpp>
in short devIndex, in string text, out boolean error ) </cpp> |
Synthesizes the given text. error is true on any error. This should returns immediately, and do not wait until execution completion. |
|
DRV_PTU
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, in float yaw, in float pitch out boolean error ) </cpp> |
Changes the orientation of the PTU. Angles are in radians, and error will be true on any error. |
DRV_MOBILE_JOINT
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, out COMMMON::TMatrix44 pose, out boolean error ) </cpp> |
Returns the current pose of the termination point (to be defined in each specific device) relative to the base of the element. error will be true if the measure is unavailable. (See section 4) |
DRV_GPS
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in short devIndex, out double lat, out double lon, out double height, out short fixQuality, out COMMON::TTimeStamp time, out boolean error ) </cpp> |
Returns the current estimation from the device (fixQuality: 1=GPS, 2=DGPS, 4=RTK fixed, 5=RTK Float). error will be true if the device is unavailable. |
|
<cpp>
in short devIndex, out COMMON::SeqOfBytes obs, out boolean error ) </cpp> |
Return the last reading as a serialized MRPT object of the class mrpt::slam::CObservationGPS. |
|
Common Sensory Interface
Next we expose the Common Sensory IF, applicable to Basic Sensory (BS) and Sensory Detectors (SD) modules. All services should take ~ 100ms to execute tops. Thus, buffers must be used where appropriate if accessing sensors takes a longer time.
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
out COMMON::SeqOfBytes SF, out boolean error ) </cpp> |
SF is a MRPT mrpt::slam::CSensoryFrame object. The lastest available observations from each sensor are returned. If no valid observation can be acquired, error is true. All observations in the SF can be of the same class, which must be specified in modules documentation. Max. execution time should be <100ms |
|
<cpp>
in boolean onNewObservation, in boolean onFailure ) </cpp> |
Enables (true) or disables (false) sending events on arrival of new measurements or a sensors failure. Default values are all events disabled. The events numeric codes must be unique for each module (see appendix II). |
|
Common Actions Interface
The Common Actions IF is detailed next. It is used by Basic Actuators (BA) and Function Executors (FE) modules, and was inspired by the equivalent interface in ACHRIN.
All services should take 100ms or less to execute.
| BABEL service group | BABEL services to implement | |
|
|
<cpp>
in string action, in string params, out unsigned long actionId, out string errorReason ) </cpp> |
This starts the execution of action with parameters given in params, a multi-line string with "key=value" lines. The specific values to use depend on the module implementation, thus refer to each module documentation. Modules must clearly describe the possible values and their meaning. On error, actionId will be 0 and errorReason must provide some clarification. Otherwise, actionId can be kept as an identifier to the requested action for subsequent request about the execution progress. |
|
<cpp>
in unsigned long actionId, out short status, out float age, out float terminationAge, out string terminationMsg ) </cpp> |
Returns the execution status of a given action, given by its actionId. Valid values for status are:
|
|
|
<cpp>
in unsigned long actionId, out boolean error ) </cpp> |
Suspend the execution of an action. Error will be true on invalid actionId values or on already finished actions. Suspending an already suspended action is not an error and takes no effect. | |
|
<cpp>
in unsigned long actionId, out boolean error ) </cpp> |
Resumes the execution of a previously suspended action. If action was already in execution this takes no action and results in no error. error is true on return if an invalid actionId is supplied or if action has already finished. | |
|
<cpp>
in unsigned long actionId, out boolean error ) </cpp> |
Cancels the execution of an action. If the action has already finished or an invalid actionId is supplied, error will be true on return. |
|
|
<cpp>
in boolean onTerminationEvent ) </cpp> |
Enables (true) or disables (false) the launching of events on action termination (does not matter the termination reason). Unique event codes are defined for each specific module, as listed in Appendix II. Default is events disabled. |
|
Remarks about calling services (VERY IMPORTANT)
The following sections are taken from the Babel Definition Language (BDL) help file. They define some basic rules to avoid memory leaks in the current CORBA-based BABEL implementations.
Strings as output parameters in a service (point of view of the CLIENT)
Use a char* variable as parameter (the parameter is a class that behaves as a char*&). The variable value will be overwritten without freeing its content, so, make sure to free its contents before using it as an output parameter. The returned value can be "" but never NULL. When you do not need the returned string anymore, you must delete it using BABEL::string_free() as described earlier (do not use delete/delete[] to free it).
Also, you can pass as output parameter a string which is part of a composed type. In that case the current string will be automatically freed. For example, if you have a service "MyOp" with an output parameter "string s", you can pass as that parameter the following: "MyStruct.stringfield", provided that MyStruct is a variable of some struct type that contains a field ("stringfield") of type string.
Strings as output parameters in a service (point of view of the SERVER)
The parameter will be a class that behaves as a char*&. The callee must do the assignment to a string output parameter once and only once. If you do it more than once, the previous string will not be freed. If you do not assign any string to it, the parameter value will be undefined and that is an error. However, the following is valid:
<cpp> void foo::MyOperation(/*out string parameter data type*/ str) { str = BABEL::string_dup("Unknown"); if(/*...*/) { BABEL::string_free(str); // free the previous string str = BABEL::string_dup("Ok"); } } </cpp>
This is NOT valid:
<cpp> void foo::MyOperation(/*out string parameter data type*/ str) { str = "My answer"; // ERROR, don't do this.
std::string myStr = "Hi man"; str = myStr.c_str(); // ERROR, don't do this. Should be str = BABEL::string_dup(...); } </cpp>
