URBI Doc for URBI-engine-bioloid

First, make sure your bioloid CM-5 module is operational.

You may have to flash the URBI firmware in the module. This operation is needed because the format of the URBI-engine send data is different from the Robotis protocol.

You can find the hex file here: in bin/firmware/ folder of your bioloid installation folder or latest version on http://www.gostai.com/bioloid

If procedure fails, try again! In case of 'Rewriting:0x0002' message: you already have the good firmware flashed.

Once you have a working robot you can install the bioloid engine. The installation procedure may vary depending on your system, but it should not be unfamiliar to you. Once it is completed, you will be provided with a bin directory in which you will find the urbi-server-bioloid binary and a script file urbi.sh or urbi.bat depending of your Operating System: this is the script you need tu run to launch the engine.

Other important files are located in the Bioloid.data directory.

Before launching the engine, you may need to change the connection port value in Bioloid.data/URBI.INI file with a simple text editor as notepad, gedit,vi, etc... At the same time you can check that URBI.INI contains a line like load("");.

Files between the brackets of load() command can be bioloid_scan.u file (default file) if you are just starting with urbi. This file scan your bioloid network and create all necessary objects.

You can obviously create your own .u files with custom behaviours. To be successfully loaded at engine startup, these files will need to be :

Check this file to see how to do this yourself if result is not appropriated to your bioloid network. (in particular, order of AX-12 motors, depending of your assemby).

Bioloid.connect(port, speed);

Connect to bioloid on port port at speed speed. COM1 or /dev/ttyS0" and 57600 are good usual values. This function return 0 for a successful port open. Warning: This does not mean a bioloid is really well connected.

Under Windows example:

Bioloid.connect("COM1", 57600);

For Windows users, basic launch of the engine can be achieved by the quicklaunch program menu, under the Gostai category.

Go to your bioloid install directory, change to the bin/ directory and launch urbi-server-bioloid --help.

The following help message should appear :

usage: ./urbi-server-bioloid [OPTIONS] [PATHS...]

  PATHS   absolute or relative path elements searched
          in order for files when 'load' is called.

Options:
  -p PORT   specify the tcp port URBI will listen to.
  -b ADDR   bind to a specific ip address.
  -w FILE   write port number to specified file.
  -n        disable networking.
  -r        report the time taken by URBI loop to execute
  -i        treat stdin as an urbi connection
  -P PERIOD base URBI interval in milliseconds
  -s PERIOD shell-mode (no network) with given period
  -t        use high priority scheduling
  -f        fast mode: the server will run as fast
            as possible and emulate the period specified
  -v, --version   print version information and exit

You can use script file can have a different extension, depending of your system:

to quickly launch the bioloid engine, run the urbi.bat file (resp. .sh) in the bin/ directory of the installation.

Just edit this file if you want to customize the way you start your engine. Here is some examples :

./urbi-server-bioloid -P 40

in urbi.sh for unix systems, or

cmd.exe /C urbi-server-bioloid -P 40 ../gostai/Bioloid.data

in a urbi.bat file for Windows users.

The engine will display a Gostai header. Next, there can be messages from the different scripts which are launched in the URBI.INI. If everything's all right, nothing more should happen.

At this time, your engine should be running. To test the connection, use either a tool specialy provided by Gostai (like URBI_console, see http://www.urbiforge.com/), or a simple telnet client (please note that all URBI engine ports default to 54000).

telnet localhost 54000

If no error occurs, your telnet client should receive the same kind of header you saw in the engine window. The last line should give your connection Id and be of the following form :

[65000000:ident] *** ID: U135766920

If this is not the case, please make sure you correctly installed the engine and followed the previous steps. Please refer to Troubleshooting and FAQ if you still have problems launching the server afterwards.

You are now ready to send commands to your robot through the bioloid URBI engine. For exemple try :

vars;
...
[00004004] *** Bioloid = OBJ
...

The first line asks for all variables known by the server and the following, which you don't have to take care of, list symbols and their respective values.

There is some special files like URBI.INI which is read at start of the engine, if this file exist. There is a URBI.INI file in the Bioloid standard package, you can run your engine with this file by entering this:

./urbi-server-bioloid -P 40 ../gostai/Bioloid.data 

The folder ../gostai/Bioloid.data/ contain a URBI.INI file and some files.u.

Note: before entering previous command, make sure you have edited bioloid_scan.u and uncommented the line Bioloid.connect adapted to your system.

This chapter will introduce basic concepts for the use of the bioloid URBI engine. It may be skipped if you are already familiar with URBI engines.

For further instructions and informations on URBI commands, please read the first chapters of the URBI tutorial.

Before anything else, make sure the steps presented in the Quickstart chapter succeeded.

Here is a quick list of the devices available on the bioloid which you can control through the engine. This are the default devices created with no .u file or .ini file

This devices are parent devices, it is needed to create devices from them to use with your bioloid robot: this is explained next.

Try this first command in your telnet session :

sensor = new Sensor(100);
[00000124] 0.000000

If not already done, this line create the UObject linked to your real AX-S1 dynamixel with ID 100, change this value to fit your configuration.

sensor.irC;
[00000476] 0.000000

The first line asks for the value of the center IR emitter. The second is the answer from the bioloid engine. The first integer value is a timestamp for the answer (in miliseconds from the engine startup). It is followed by a tag. Please refer to the URBI tutorial for more details. What is important here is the floating point value ending the line. It is the value stored in the front IR emitter. Here 0.000000 indicates nothing is in front of the robot. With your hand right in front of the robot, you should get a value close to 255.000000.

Please note that the next commands will be enclosed in +end:{...};. This is to make the engine warn you when the command comes to an end.

Try the following :

+end:{motor__1.speed = 100; sleep (2s) | motor__1.speed = 0;};
[00002622] *** end

Your robot should have the 1st motor rotating for 2 second, and then stop. Now try to make it come back to its initial position with a similar command.

Next try :

+end:{motor__1.speed = -100; sleep (2s) | motor__1.speed = 0;};
[00005095] *** end

Your motor should come back to its original position.

The last simple command will be :

sensor on;
irCDetect:at (sensor.irC > 100) echo "Front obstacle : " + sensor.irC;

Now try to put your hand close to the front of your bioloid AX-S1 module. You should get a message like :

[00008215] *** Front obstacle : 230

The at keyword allows you to detect events and make your bioloid act accordingly.

The bioloid interface is close to the one specified in the manual of the AX-12 and of the AX-S1. Type "myMotor; mySensor;" in a connection (where myMotor is an instanciated Motor, and mySensor a Sensor) to get the full list of their attributes.

You should now be able to play with the bioloid URBI engine. The next chapters will give you complete details about the engine, but what we saw here is enough to get used with the bioloid and URBI.

This object is the master of all other objects for Bioloid. It has only three methods available for user.

connect("device",int speed) Connect to RS232 Bioloid network. This method need to be call first of all other commands. it returns 0 on connection success.

under Unix system:

	Bioloid.connect("/dev/ttyS0", 57600);
	[00000066] 0
 

under Windows system:

	Bioloid.connect("COM1", 57600);
	[00000076] 0
 

Please, note that the firmware flashed in Bioloid CM-5 is programmed for working at 57600 bauds for the moment; Giving 57600 as parameter in all cases for the second parameter is a good practise.

	Bioloid.ping(12);
	[00004993] 12
	Bioloid.ping(29);
	[00012900] 255
 

	Bioloid.scan();
	scanning network, may take some time...
	[00099415] [12, 18, 100]
	Bioloid;
	[00109621] OBJ [listAXS1:[100],load:1,listAX12:[12, 18]]
 

Note: How scan() works: it does a ping on all IDs and wait for reply.

After calling this functions, two lists are available in Bioloid object: Bioloid.listAXS1 and Bioloid.listAX12. The lists contain IDs (sorted) of respectivly AX-S1 and AX-12 dynamixels. You can use these lists to create all your motors and sensors objects. (see <bioloid-dir>/Bioloid.data/bioloid_scan.u in your installation directory for more details and examples).

The bioloid motors are accessed through the Motor objects and have the following carateristics :

If your engine doesn't load any filename.u at start (declared in CLIENT.INI or in URBI.INI), by default no motors are created because of the structure of the bioloid, we don't know how many motors are in your robot. You must declare them before sending any command to them

motor[i] = new Motor(j);

This method can be used to create an array for all your motors. Remember the array begins at index 0. Moreover, the parameter you give to Motor is the ID of the motor you want to instanciate.

var i = 0;
for j in [10,12,16,18] {
 motor[i] = new Motor(j);
 i = i + 1;
};

or for a full automated creation of all available motors:

var i = 0;
for j in Bioloid.listAX12 {
 motor[i] = new Motor(j);
 i = i + 1;
};

this sample create the 4 motors of the bioloid car:

Motors are available by the motor__X, with X between 0 and your max_numbered_motor. You can (need to) adapt the #ID of motors in your scripts to the configuration of your robot (it's easier to rename each motor)!

Naming Standard: Depending the form of your bioloid robot (humanoid, car, quaduped, etc ...) *.u files exists for creating aliases and groups for this motors, to have a common naming standard for all robot. see Bioloid.data folder.

Not all config are already defined, don't hesitate to create and share your own .u files on www.urbiforge.org

A motor has the following attributes:

all this attributes are accessibled by calling myMotor.attribute like:

You can drive your motor in two modes, depending of the close-loop control you want:

To use this feature you need to set .cwAngleLimit and .ccwAngleLimit to adapted values:

Note that every descriptions beginning with a 0xNN address number is directly associated to AX-12 memory address, see dynamixel AX-12 manual for more informations on these functions : AX-12 Dynamixel or here

When the bioloid engine is ready, you can create Sensor objects ( same way as Motor objects ). Then you can access to their different members which return all values of an AX-S1 module. To create a new sensor uobject (AX-S1 #ID is 100 in this example):

sensor = new Sensor (100);

The AX-S1 dynamixel sensor module is accessed through the Sensor object and have the following attributes :

Here you can find the AX-S1 Specifications for more information.

This chapter will introduce a few simple scripts. To use them type in the console :

load ("filename.u");

Depending on the version of the bioloid URBI engine you got, some scripts may be available in the data, profiles or scripts folders of your installation directory.

Before anything else, make sure you are familiar with the previous parts of this document.

For further instructions and informations on URBI commands, please read the first chapters of the URBI tutorial.

All these simple scripts assumes URBI.INI is empty, so comment lines with # or // at start of each lines of URBI.INI to avoid unpredicable behaviour.

/* ----------------- Basic for bioloid  --------------------------------- */
/// assume there is nothing in the URBI.INI
/// Connect to bioloid (do not do if already connected!)
Bioloid.connect("COM1", 57600);

/// Create motors
var i = 0;
//declare ID of your connected motors there
for j in [10,12,16,18] {
 motor[i] = new Motor(j);
 i = i + 1;
};

var NumberOfMotor = i;

t: {
  for (j=0; j<3;j++) {
    for (i=0; i<NumberOfMotor;i++) motor[i].speed = 100 smooth:1s;
    sleep(1.5s);
    for (i=0; i<NumberOfMotor;i++) motor[i].speed = 0 smooth:1s;
    sleep(1.5s);
  };
};
/* ----------------- Basic for bioloid  --------------------------------- */

This should make your bioloid test all motors by a little move, 3 times.

/* -------------------- Music for bioloid  --------------------------------- */
/// assume there is nothing in the URBI.INI
/// Connect to bioloid (do not do if already connected!)
Bioloid.connect("COM1", 57600);

/// Create sensor
sensor = new Sensor(100);
music:{
 for (i=0; i<27;i++){
  sensor.buzzerTime=255;
  sensor.buzzerIndex=i;
  sleep(1.5s);
 };
};
/* -------------------- Music for bioloid  --------------------------------- */

This should make your bioloid AX-S1 module play its 26 pre-recorded melodies one by one with a wait of 1.5 seconds between each.

/* ----------------- Bumper for bioloid car --------------------------------- */
bumper:at (irC > 100)         // at obstacle detection
{
  wheels = 0 | sleep (500ms);  // stop and wait a bit
  wheels = -50 | sleep (1s);   // go backward
  wheels = 0 time:1s |        // stop smoothly
  wheels = 100;               // go forward
};

wheels = 100;                 // initial start
/* ----------------- Bumper for bioloid car --------------------------------- */

This should make your bioloid car go forward, stop before the first obstacle, go back for a bit and go again. You will have to figure how to make it stop. You must load bioloid_car.u before executing this script to have good result. (it's better to have a robot with 4 wheels to have a good look of the behaviour, see description of motors in bioloid_car.u).

/* ----------------- Navigator for bioloid car --------------------------------- */
var WHEEL_SLOW = 30;              // moving speed
var WHEEL_FAST = 80;              // turning speed
var NAV.side = 1;                 // way to turn

navigator:at (irC > 150)                      // at obstacle detection
{
  wheels = 0 | sleep (500ms);                  // wait a bit
  wheels = -40 | sleep (500ms);                // go back
  NAV.side = NAV.side * -1;                   // change way
  wheelL = NAV.side * WHEEL_FAST &            // turn
    wheelR = - NAV.side * WHEEL_FAST;
  waituntil (irC < 50) | wheels = WHEEL_SLOW; // wait for clear way
                                              // and go forward
};

wheels = WHEEL_SLOW;          // initial start
/* ----------------- Navigator for bioloid car --------------------------------- */

You must load bioloid_car.u before executing this script to have good result.

This script should make your robot turn either left or right upon obstacle detection until it finds a clear way. It then will go forward again until the next obstacle.

In this section you will learn how to create your own Bioloid engine with the modules you need for your Bioloid robot.

Binary executable file urbi-server-bioloid contain only UObjects to manage CM-5, AX-12 and AX-S1 bricks. If you want your robot to have other features, like a camera, micro, etc ... you need to add UObjects to your engine (and hardware, too): they can be plugged or remote.

Create your own UObjects : generally these are .cc files, see tutorial: UObject documentation for more details.

How to compile:

Template exists for Visual C++, Dev-CPP, see Gostai Website for downloads

Manual method: create a Makefile file with this in it:

#name of the final binary
PRG=myBioloidEngine

#where is the folder named "urbiengine-bioloid"
URBIENGINE_BIOLOID_DIR=/

LIBURBIENGINE_BIOLOID=\
$(URBIENGINE_BIOLOID_DIR)/usr/local/gostai/core/i686-pc-linux-gnu/\
engine/liburbiengine-bioloid.a

BIN_BIOLOID=$(URBIENGINE_BIOLOID_DIR)/usr/local/bin


all:
	$(BIN_BIOLOID)/umake-engine --prefix=../usr/local \
	-o $(PRG)   $(LIBURBIENGINE_BIOLOID) *.cc

clean:
	rm -rf _ubuild-$(PRG)  $(PRG)

$PRG is the name of the final binary you generate.

$URBIENGINE_BIOLOID_DIR is the install directory where can be found .../gostai/core/.../liburbiengine-bioloid.a.

To compile your engine, just enter make in a shell in your directory.

You can find UObjects here for example: Urbiforge .

None known at this time. Make us feedback if any.