Robot Control Meta Language (RCML)

17.1 An example of connecting robot modules

17.1.1 Quick connection of robot test module to RCML

The test robot module is intended for imitating a physical robot and testing connected components and programs.

To enable the test module robot, add the "module" property to section [robot_modules] of the RCML configuration file, and set it equal to the "test" value in accordance with section "Installation and Configuration of RCML Compiler and Interpreter". The test module does not require additional configuration.

The following is the text of a program in the RCML language. The program invokes the test robot, and sends the command to run the do_something() function. The following describes in more details what this function means

function main() {
	@lr = robot_test; 
	@lr->do_something(1000);
}

During the execution of this program, the test robot imitates physical execution of an action that would take 1 second.

After connecting the module, the following options are available for the programmer:

Name

Number of parameters

Returns a value

Throws an exception

Description

none

0

No

No

A function doing nothing.

do_something

1

No

No

As the parameter, the function takes the number of milliseconds that the execution of the program will be stopped for.

get_some_value

1

Yes

No

Returns the value passed as the input parameter.

throw_exception

0

No

Yes

When invoked, throws an exception.

print

2

No

No

Accepts the first string parameter and prints it in the console after the delay specified in milliseconds by the second parameter.

In addition, the test robot also has axes:

Name

The upper limit

The lower limit

Note

X

100

-100

 

Y

1

0

Binary

Z

100

0

 

17.1.2 Quick connection of the lego_ev3 module to RCML

Lego Mindstorms Ev3 is the third generation of the Lego kit.

More information is available from the official website of the kit:

The module of the lego_ev3 robot is used for connecting Lego Ev3 units to RCML. 

  1. To activate a lego_ev3 module, add entry "property module" to section [robot_modules] to the RCML configuration file, and set it equal to lego_ev3 in accordance with Section "Installation and Configuration of RCML Compiler and Interpreter".
  2. The Bluetooth adapter should be paired with the Lego Ev3 module.
  3. After pairing, go to the properties of the added device. You should know the address of the COM port with which interaction occurs.
  • Next, you should configure the module. Namely, you should specify, which COM port should communicate with the Ev3 module. Go to the directory with therobot modules (robot_modules), and then to the directory of the Ev3 module (lego_ev3).
  • In the directory of the lego_ev3 module, create file config.ini with the following content:
  • [connections]
    connection = COM6
    [options]
    dynamic_connection = 0

    Configuration file config.ini contains the following properties divided into two sections [connections] and [options]:

    The [connections] section contains the numbers of ports of the connected robots; for each robot, a record is made as follows: 

    connection = COMX, where X is the number of the port that is used in the properties of the connection.

    Section [options] contains property dynamic_connection.

    dynamic_connection is used to dynamically connect robots, i.e., it allows to change the number of the used robots immediately at the time of program execution. However, each activated robot takes time to connect to it. If the dynamic_connection value is set to 1, then the Bluetooth connection with the robot will be established at the time of the robot invocation, and disconnected after it is released, which may cause significant delays in using the robot in the RCML program.

    If the value of dynamic_connection is set to 0, the Bluetooth connection with the robot will be established at the moment the program starts, and disconnected after completion.

    By default, the value will be set to 0.

    The following is an example text of a program in the RCML language. A program invokes the Lego robot and interacts with the motor connected to the Ev3 unit. The text of the program is the following:

    function main() {
    	@lr = robot_lego_ev3;
    	@lr->motorMoveTo("B",10,200,0);
    }

    The first line creates a variable the Lego robot will be associated with.

    The second line will move the motor B to position 200 at speed 10 without using the brake.

    Besides, the Lego robot may be presented to RCML as "Track Vehicle", which will allow to address two motors of the Lego robot as a whole, and provides additional control functions. The setTrackVehicle function has been specially created for robots of special configurations, with two drive wheels and one swivel wheel/prop, or for configurations of tracks-type robots, 1 motor per each wheel or caterpillar. This mode automates motors control for maneuvering the robot. To initialize the robot in the "Track Vehicle" mode, use the setTrackVehicle function in the program.

    The following is an example of program text in the RCML language, where "Track Vehicle" is created and controlled.

    function main() {
    	@lr = robot_lego_ev3; 
    	@lr->setTrackVehicle("B","C",1,1);
    	@lr->trackVehicleForward(10);
    	system.sleep(1000);
    	@lr->trackVehicleOff();
    }

    As a result of executing the program, the robot will symmetrically rotate both motors connected to B and C ports at speed 10. A more detailed list of commands is provided below.

    If the program code does not invoke the "Track Vehicle" setTrackVehicle function, then an exception will be thrown when functions related to the use of "Track Vehicle" are executed; this exception may be handled with the try/catch construct. More information about it is available in Section "Exceptions".

    There are peculiarities associated with the input values for the functions of the module.

    To invoke motors A,B,C,D, characters "A","B","C" and "D" are used, respectively;

    To invoke sensors numbered 1,2,3,4, corresponding numbers are used;

    Parameters of speed and percent functions have the following limitations:
    •    speed takes values [-100;100];
    •    percent takes values [0;100].

    When these limits are exceeded, the called function throws an exception that can be processed using a construct in the RCML language. More detail about exception handling is available in Section "Exceptions.

    The available functions of the robot are shown in the Table:

    Definition

    Description

    Example

    motorSetSpeed(
          motor,
          speed
      )

    Sets speed "speed" for motor "motor"

    @lr->motorSetSpeed ("B",20); Sets speed 20 for motor B.

    motorOff(
    motor
      )

    Disables the motor without using the brake, i.e., the motor stops immediately.

    @lr->motorOff("C"); Will stop motor C.

    motorBrake(
    motor
      )

    Stops the motor using the brake. Immediate stop.

    @lr->motorBrake("D"); Will stop motor D.

    motorSetDirection(
          motor,
          direction
      )

    Sets motor direction. direction=0 sets motor direction "backward". direction != 0 sets motor direction to "forward".

    @lr->motorSetDirection("A",0); Will set motor A direction to "backward".

    motorGetDirection(
          motor
      )

    Returns 1 if motor direction is set to "forward"; returns 0 if motor direction is set to "backward". The motor will not stop immediately.

    RecievedDirection = @lr->motorGetDirection("C");

    motorMoveTo(
          motor,
          speed,
          position,
          brake
      )

    Moves the motor to position "position" at speed "speed". brake = 0 - brake not to be used, brake != 0 - brake to be used.

    @lr->motorMoveTo("B",10,200,0); Will move motor B to position 200 at speed 10 without using the brake.

    motorGetTacho(
          motor
      )

    Returns motor position.

    RecievedTacho = @lr->motorGetTacho("C");

    motorResetTacho(
          motor
      )

    Sets current motor position to zero.

    @lr->motorResetTacho("C");

    waitMotorToStop(
          motor
      )

    Waits until the motor stops.

    @lr->waitMotorToStop("C");

    waitMultiMotorsToStop(
          motorA,
          motorB,
          motorC,
          motorD
      )

    Waits until several motors stop. If motor != 0, waits for the stop, if motor = 0, does not wait.

    @lr->waitMultiMotorsToStop(1,0,0,1); Waits until the motors A and D stop.

    setTrackVehicle(
          motorLeft,
          motorRight,
          LeftReverse,
          RightReverse
      )

    Logically connects 2 motors - motorLeft and motorRight in Track Vehicle (tracked vehicles). Allows to invoke these motors as a whole, and provides additional Track Vehicle control functions with prefix "trackVehicle". If the value is != 0, Left and Right Reverse sets motors' reverse direction.

    @lr->setTrackVehicle("B","C",1,0); Logically connects the motors B and C in Track; motor B changes its direction to the opposite.

    trackVehicleBackward(
          speed
      )

    Track Vehicle moves backward at speed "speed".

    @lr->trackVehicleBackward(20);

    trackVehicleForward(
          speed
      )

    Track Vehicle moves forward at speed "speed".

    @lr->trackVehicleForward(40);

    trackVehicleOff()

    Disables Track Vehicle motors. The motors will not stop immediately.

    @lr->trackVehicleOff();

    trackVehicleBrake()

    Stops the Track Vehicle motors using a brake.

    @lr->trackVehicleBrake();

    trackVehicleSpinLeft(
          speed
      )

    Track Vehicle turns left around its vertical axis.

    @lr->trackVehicleSpinLeft(10);

    trackVehicleSpinRight(
          speed
      )

    Track Vehicle turns right around its vertical axis.

    @lr->trackVehicleSpinRight(90);

    trackVehicleTurnLeftForward(
          speed,
          percent
      )

    Track Vehicle turns left, moving forward. The right motor will be set to speed "speed", and the left one to (speed - speed*percent/100). Therefore, if percent=0, the motors will have the same speed, and if percent=100, the left engine will have zero speed.

    @lr->trackVehicleTurnLeftForward(20, 50);

    trackVehicleTurnRightForward(
          speed,
          percent
      )

    Track Vehicle turns left, moving forward. The left motor will be set to speed "speed", and the right one to (speed - speed*percent/100). Therefore, if percent=0, the motors will have the same speed, and if percent=100, the tight engine will have zero speed.

    @lr->trackVehicleTurnRightForward(10, 90);

    trackVehicleTurnLeftReverse(
          speed,
          percent
      )

    Track Vehicle turns left, moving backward. The right motor speed is set to "speed", and the left motor one to (speed - speed*percent/100).

    @lr->trackVehicleTurnLeftReverse(10,20);

    trackVehicleTurnRightReverse(
          speed,
          percent
      )

    Track Vehicle turns right, moving backward. The left motor speed is set to "speed", and the right motor one to (speed - speed*percent/100).

    @lr->trackVehicleTurnRightReverse(50,50);

    readSensor(
          sensor,
          mode
      )

    Reads sensor No. "sensor" indications in the mode "mode". For different sensors, there are different numbers of modes.

    @lr->readSensor(2,1); Reads indications of the sensor connected to port 2 in mode 1.

    isMotorRunning(
          motor,
          sleep
      )

    Returns 1 if motor "motor" is enabled, and 0 if it is not. If sleep is not 0, the motor will be polled with a 200 microseconds delay.

    @lr->isMotorRunning("B",1);

    getMotorSpeed(
          motor,
          sleep
      )

    Returns the speed value of motor "motor". If sleep is not 0, the motor will be polled with a 200 microseconds delay.

    @lr->getMotorSpeed("B",1);

    For the lego_ev3 module, connection of 8 types of sensors is available. Their indices are used in commands of the RCML language. Types of sensors and their indices are shown in the table:

    Sensor

    Mode

    Ultrasonic

    1 - the mode of measuring the distance in centimeters

    2 - the mode of measuring the distance in inches

    3 - listening mode

    Infrared

    1 - the mode of measuring the distance

    2 - the mode of locating the infrared remote control

    3 - the mode of detecting button actions on the infrared remote control

    Color

    1 - the mode of defining light intensity

    2 - the mode of defining color (see the color table)

    3 - mode of defining raw value of the reflected light

    4 - the mode of defining reflected light

    Gyroscopic

    1 - mode of defining the angle in degrees

    2 - the mode of defining angular velocity in degrees per second

    Pressing sensor

    1 - pressing detection mode

    2 - the mode of displaying the number of pressings

    Temperature sensor

    1 - the mode of measuring temperature in degrees Celsius

    2 - the mode of measuring temperature in degrees Fahrenheit

    Sound sensor

    1 - the mode of measuring sound volume in dB

    2 - the mode of measuring sound volume in dBA

    Light sensor

    1 - mode of measuring intensity

    2 - the mode of measuring reflected light

    The color sensor can return the color code. The returned color codes are shown in the Table:

    Color

    Return value

    Black

    1

    Blue

    2

    Green

    3

    Yellow

    4

    Red

    5

    White

    6

    Brown

    7

    The following axes are always available for controlling the Ev3 unit:

    Axis

    The upper limit

    The lower limit

    Description

    locked

    1

    0

    Binary axis. If its value is 1, the robot is considered blocked and ignores changes in the values in any other axes.

    speedMotorA

    100

    -100

    The value of the axis sets the speed of the motor connected to port A.

    speedMotorB

    100

    -100

    The value of the axis sets the speed of the motor connected to port B.

    speedMotorC

    100

    -100

    The value of the axis sets the speed of the motor connected to port C.

    speedMotorD

    100

    -100

    The value of the axis sets the speed of the motor connected to port D.

    moveMotorA

    1,000

    -1,000

    The axis value specifies the position that motor A will turn at speed 50.

    moveMotorB

    1,000

    -1,000

    The axis value specifies the position that motor B will turn at speed 50.

    moveMotorC

    1,000

    -1,000

    The axis value specifies the position that motor C will turn at speed 50.

    moveMotorD

    1,000

    -1,000

    The axis value specifies the position that motor D will turn at speed 50.

    If the Lego robot is used in the "Track Vehicle" mode, the robot has the following axes, to which it can connect for control:

    straight

    100

    -100

    The axis value specifies the speed at which "Track Vehicle" moves straightforward

    rotation

    100

    -100

    The axis value specifies the speed at which "Track Vehicle" rotates around its vertical axis.

    The Lego robot has to be initialized in the "Track Vehicle" mode before straight axis or rotation is activated, i.e., before activating manual control!

    17.1.3 Quick connection of the lego_nxt module to RCML

    Lego Mindstorms NXT is the second generation of the Lego kit.

    More information is available from the official website of the kit: 

    The module of the lego_nxt robot is used for connecting Lego NXT units to RCML. 

      1. To activate the lego_nxt module, add entry "property module" to section [robot_modules] in the RCML configuration file, and set it equal to lego_nxt in accordance with Section "Installation and Configuration of RCML Compiler and Interpreter".
      2. The Bluetooth adapter should be paired with the Lego NXT module.
      3. After pairing, go to the properties of the added device. You should know the address of the COM port with which interaction is established.
    1. Next, configure the module. Namely, specify which COM port should communicate with the NXT module. Go into the directory with the robotmodules (robot_modules), and then to the directory of the NXT module (lego_nxt).
    2. In the directory of the lego_nxt module, create the config.ini file with the following content:
    [connections]
    connection = COM6
    [options]
    dynamic_connection = 0

    The config.ini configuration file contains the following properties divided into two sections [connections] and [options]:

    The [connections] section contains the numbers of ports of connected robots; for each robot, a record is made as follows: 

    connection = COMX, where X is the number of the port that is used in the properties of the connection.

    Section [options] contains property dynamic_connection.

    dynamic_connection is used to dynamically connect robots, i.e., it allows to change the number of the used robots immediately at the time of program execution. However, each activated robot takes time to connect to. If the dynamic_connection value is set to 1, then the Bluetooth connection with the robot will be established at the time of the robot invocation, and disconnected after it is released, which may cause significant delays in using the robot in the RCML program.

    If the value of dynamic_connection is set to 0, the Bluetooth connection with the robot will be established at the moment of program start, and disconnected after completion.

    By default, the value will be set to 0.

    The following is an example text of a program in the RCML language. A program invokes the Lego robot, and interacts with the motor connected to the NXT unit. The text of the program is the following:

    function main() {
    	@lr = robot_lego_nxt;
    	@lr->motorMoveTo("B",10,200,0);
    }

    The first line creates a variable the Lego robot will be associated with.

    The second line will move the motor B to position 200 at speed 10 without using the brake.

    Besides, the Lego robot may be presented to RCML as "Track Vehicle", which will allow addressing two motors of the Lego robot as a whole, and provides additional control functions. The setTrackVehicle function has been specially created for robots with special configurations, with two drive wheels and one swivel wheel/prop, or for configurations of tracks-type robots, 1 motor per each wheel or caterpillar. This mode automates motors control for maneuvering the robot. To initialize the robot in the "Track Vehicle" mode, use the setTrackVehicle function in the program. The following is an example of program text in the RCML language, where "Track Vehicle" is created and controlled.

    function main() {
    	@lr = robot_lego_nxt; 
    	@lr->setTrackVehicle("B","C",1,1);
    	@lr->trackVehicleForward(10);
    	system.sleep(1000);
    	@lr->trackVehicleOff();
    }

    As a result of executing the program, the robot will symmetrically rotate both motors connected to B and C ports at speed 10. A more detailed list of commands is provided below.

    If the program code does not invoke the "Track Vehicle" setTrackVehicle function, then an exception will be thrown when functions related to the use of "Track Vehicle" are executed; this exception may be handled with the try/catch construct. More information about it is available in Section "Exceptions".

    There are peculiarities associated with the input values for the functions of the module.

    To invoke motors A,B,C,D, characters "A","B","C" and "D" are used, respectively;

    To invoke sensors numbered 1,2,3,4, corresponding numbers are used;

    Parameters of speed and percent functions have the following limitations:
    •    speed takes values [-100;100];
    •    percent takes values [0;100].

    When these limits are exceeded, the called function throws an exception that can be processed using a construct in the RCML language. More detail about exception handling is available in Section "Exceptions"

    The available functions of the robot are shown in the Table below:

    Definition

    Description

    Example

    motorSetSpeed(
         motor,
         speed
      )

    Sets speed "speed" for motor "motor"

    @lr->motorSetSpeed ("B",20); Sets speed 20 for motor B.

    motorOff(
         motor
      )

    Disables the motor without using the brake, i.e., the motor stops immediately.

    @lr->motorOff("C"); Will stop motor C.

    motorBreak(
         motor
      )

    Stops the motor using the brake. Immediate stop.

    @lr->motorBrake("A"); Will stop motor A.

    motorSetDirection(
         motor,
         direction
      )

    Sets the direction of motor "motor". direction=0 sets motor direction "backward". direction != 0 sets motor direction to "forward".

    @lr->motorSetDirection("A",0); Will set motor A direction to "backward".

    motorGetDirection(
         motor
      )

    Returns 1 if motor direction is set to "forward", returns 0 if motor direction is set as "backward". The motor will not stop immediately.

    RecievedDirection = @lr->motorGetDirection("C");

    motorMoveTo(
         motor,
         speed,
         position,
         brake
      )

    Moves motor "motor" to position "position" at speed "speed". brake = 0 - brake not to be used, brake != 0 - brake to be used.

    @lr->motorMoveTo("B",10,200,0); Will move motor B to position 200 at speed 10 without using the brake.

    motorGetTacho(
         motor
      )

     

    Returns motor position.

    RecievedTacho = @lr->motorGetTacho("C");

    motorResetTacho(
         motor
      )

    Sets current motor "motor" position to zero.

    @lr->motorResetTacho("C");

    waitMotorToStop(
         motor
      )

    Waits until the motor stops.

    @lr->waitMotorToStop("C");

    waitMultiMotorsToStop(
         motorA,
         motorB,
         motorC
      )

    Waits until several motors stop. If motor != 0, waits for the stop, if motor = 0, does not wait.

    @lr->waitMultiMotorsToStop(1,0,1); Waits until the motors A and C stop.

    setTrackVehicle(
         motorLeft,
         motorRight,
         LeftReverse,
         RightReverse
      )

    Logically connects 2 motors - motorLeft and motorRight in Track Vehicle (tracked vehicles). Allows to invoke these motors as a whole, and provides additional Track Vehicle control functions with prefix "trackVehicle". If the value is != 0, Left and Right Reverse sets motors' reverse direction.

    @lr->setTrackVehicle("B","C",1,0); Logically connects the motors B and C in Track; motor B changes its direction to the opposite.

    trackVehicleBackward(
         speed
      )

    Track Vehicle moves backward at speed "speed".

    @lr->trackVehicleBackward(20);

    trackVehicleForward(
         speed
      )

    Track Vehicle moves forward at speed "speed".

    @lr->trackVehicleForward(40);

    trackVehicleOff()

    Disables Track Vehicle motors. The motors will not stop immediately.

    @lr->trackVehicleOff();

    trackVehicleBrake()

    Stops the Track Vehicle motors using a brake.

    @lr->trackVehicleBrake();

    trackVehicleSpinLeft(
         speed
      )

    Track Vehicle turns left around its vertical axis.

    @lr->trackVehicleSpinLeft(10);

    trackVehicleSpinRight(
         speed
      )

    Track Vehicle turns right around its vertical axis.

    @lr->trackVehicleSpinRight(90);

    trackVehicleTurnLeftForward(
         speed,
         percent
      )

    Track Vehicle turns left, moving forward. The right motor will be set to speed "speed", and the left one to (speed - speed*percent/100). Therefore, if percent=0, the motors will have the same speed, and if percent=100, the left engine will have zero speed.

    @lr->trackVehicleTurnLeftForward(20, 50);

    trackVehicleTurnRightForward(
         speed,
         percent
      )

    Track Vehicle turns left, moving forward. The left motor will be set to speed "speed", and the right one to (speed - speed*percent/100). Therefore, if percent=0, the motors will have the same speed, and if percent=100, the right engine will have zero speed.

    @lr->trackVehicleTurnRightForward(10, 90);

    trackVehicleTurnLeftReverse(
         speed,
         percent
      )

    Track Vehicle turns left, moving backward. The right motor speed is set to "speed", and the left motor one to (speed - speed*percent/100).

    @lr->trackVehicleTurnLeftReverse(10,20);

    trackVehicleTurnRightReverse(
         speed,
         percent
      )

    Track Vehicle turns right, moving backward. The left motor speed is set to "speed", and the right motor one to (speed - speed*percent/100).

    @lr->trackVehicleTurnRightReverse(50,50);

    isMotorRunning(
         motor,
         sleep
      )

    Returns 1 if motor "motor" is enabled, and 0, if it is not. If sleep is not 0, the motor will be polled with a 200 microseconds delay.

    @lr->isMotorRunning("B",1);

    The following options are available for the lego_nxt module:

    Definition

    Description

    Modes

    readHiTecColor (port, mode)

    Reads HiTecColor sensor indications at port "port" in mode "mode".

    1 - Returns the red color value [0;255]

    2 - Returns the green color value [0;255]

    3 - Returns the blue color value [0;255]

    readHiTecCompass (port)

    Reads indications of the HiTecCompass sensor at port "port".

    Returns the value in degrees

    readHiTecGyro (port)

    Reads indications of the HiTecGyro sensor at port "port".

    Returns angular acceleration in degrees per second

    readHiTecTilt (port, mode)

    Reads HiTecTilt sensor indications at port "port" in mode "mode".

    1 - Returns an integer position of the sensor along the x-axis

    2 - Returns an integer position of the sensor along the y-axis

    3 - Returns an integer position of the sensor along the z-axis

    readNXTColor (port, mode)

    Reads NXTColor sensor indications at port "port" in mode "mode".

    1 - Returns an integer value corresponding to the color table

    2 - Returns intensity of the red color in percent

    3 - Returns intensity of the green color in percent

    4 - Returns intensity of the blue color in percent

    5 - Returns light intensity in percent

     

    readNXTLight (port, mode)

    Reads NXTLight sensor indications at port "port" in mode "mode".

    1 - Returns light intensity as an integer value

    2 - Returns light intensity in percent

    readNXTSonar (port, mode)

    Reads NXTLight sensor indications at port "port" in mode "mode".

    1 - the mode of measuring the distance in centimeters

    2 - the mode of measuring the distance in inches

    readNXTSound (port,mode)

    Reads NXTSound sensor indications at port "port" in mode "mode".

    1 - the mode of measuring sound volume in dB

    2 - the mode of measuring sound volume in dBA

    readNXTTouch (port,mode)

    Reads NXTTouch sensor indications at port "port" in mode "mode".

    1 - the pressing detection mode

    2 - the mode of displaying the number of pressings

    readRCXLight (port, mode)

    Reads RCXLight sensor indications at port "port" in mode "mode".

    1 - the mode of measuring intensity

    2 - the mode of measuring reflected light

    readRCXRotation (port)

    Reads indications of the RCXRotation sensor at port "port".

    Returns rotation increment [-16;+16]

    readRCXTemperature (port, mode)

    Reads RCXTemperature sensor indications at port "port" in mode "mode".

    1 - the mode of measuring temperature in degrees Celsius

    2 - the mode of measuring temperature in degrees Fahrenheit

    The color sensor can return the color code. The returned color codes are shown in the Table:

    Color

    Return value

    Black

    1

    Blue

    2

    Green

    3

    Yellow

    4

    Red

    5

    White

    6

    The following axes are always available for controlling the NXT unit:

    Axis

    The upper limit

    The lower limit

    Description

    locked

    1

    0

    Binary axis. If its value is 1, the robot is considered blocked and ignores changes in the values in any other axes.

    speedMotorA

    100

    -100

    The value of the axis sets the speed of the motor connected to port A.

    speedMotorB

    100

    -100

    The value of the axis sets the speed of the motor connected to port B.

    speedMotorC

    100

    -100

    The value of the axis sets the speed of the motor connected to port C.

    moveMotorA

    1,000

    -1,000

    The axis value specifies the position that motor A will turn at speed 50.

    moveMotorB

    1,000

    -1,000

    The axis value specifies the position that motor B will turn at speed 50.

    moveMotorC

    1,000

    -1,000

    The axis value specifies the position that motor C will turn at speed 50.

    If the Lego robot is used in the "Track Vehicle" mode, the robot has the following axes, to which it can connect for control:

    Axis

    The upper limit

    The lower limit

    Description

    straight

    100

    -100

    The axis value specifies the speed at which Track Vehicle moves straightforward

    rotation

    100

    -100

    The axis value specifies the speed at which "Track Vehicle" rotates around its vertical axis.

    The Lego robot has to be initialized in the "Track Vehicle" mode before straight axis or rotation is activated, i.e., before activating manual control!

    17.1.4 Quick connection of uarm module to RCML

    uArm is a 4-axis manipulator, a miniature version of the industrial ABB PalletPack IRB460 robot. 

    More information is available from the official website of the robot:

    The module of uarm is used for connecting the uArm robot to RCML.

    1. The uArm robot should be connected to the computer. First, visit the Download Center section at the manufacturer's website, then go to Instructions, and go to Getting Started, after which follow the instruction for the suitable uArm model.
    2. Next, you have to change the robot software to work with SDK C#. Quick start instruction for working with SDK C#.
    3. To activate a uarm module, add entry "property module" to section [robot_modules] to the RCML configuration file, and set it equal to uarm in accordance with Section "Installation and Configuration of RCML Compiler and Interpreter".
    4. Next, you should configure the module. Namely, you should specify which COM port should communicate with the robot. To do so, go into the directory with the robot modules (robot_modules), and then to the directory of the uarm module.
    5. In the directory of the uarm module, create file config.ini with the following content:
    [main]
    count_robots = 1
    is_debug = 0
    robot_port_0 = com3

    The module configuration file consists of section [main], which includes the following properties:

    • count_robots is the property that takes as the parameter the number of uArm robots (number) to which it should connect.
    • is_debug displays additional information about functions executable by the uArm robot in the console. May take value 0 or 1.
    • robot_port_X contains the name of the COM port that robot X is connected to; the robots count is zero-based. The port address should be specified in the comY format, where Y is the serial port number that was previously used in par. 1 and 2.

    The following is the text of a program in the RCML. The program invokes the uArm robot and activates the vacuum pump for 5 seconds, then deactivates it:

    function main() {
    	@ur = robot_uarm;
    	@ur-> pump_on();
    	system.sleep(1000);
    	@ur-> pump_off();
    }

    Available functions of the robot are shown in the Table:

    Definition

    Description

    Example

    move_to(X, Y, Z)

    moves the robot grip to the point with coordinates X, Y, Z. The motion occurs at the maximum possible speed.

    @Robot->move_to (10, 10, 10); moves the robot grip to the point with coordinates X=10, Y=10, Z=10

    pump_on()

    activates the grip pump

    @Robot->pump_on(); activates the grip pump

    pump_off()

    deactivates the grip pump

    @Robot->pump_off(); deactivates the grip pump

    find_x()

    returns the X coordinate of the point the robot grip is located at

    X = @Robot->find_x(); gets the X coordinate of the point the robot grip is located at, and stores it to variable X

    find_y()

    returns the Y coordinate of the point the robot grip is located at

    Y = @Robot->find_y(); gets the Y coordinate of the point the robot grip is located at, and stores it to variable Y

    find_z()

    returns the Z coordinate of the point the robot grip is located at

    Z = @Robot->find_z(); gets the Z coordinate of the point the robot grip is located at, and stores it to variable Z

    move_to_at_once(x,Y, Z)

    moves the robot grip to the point with coordinates X, Y, Z. The motion occurs at the maximum possible speed.

    @Robot->move_to_at_once (10, 10, 10); moves the robot grip to the point with coordinates X=10, Y=10, Z=10

    move(x, Y, Z)

    moves the robot grip from the point with current coordinates X_current, Y_current, Z_current to the point with coordinates X_current + X, Y_current + Y, Z_current + Z. The movement occurs smoothly.

    @Robot->move(1, 1, 1); changes the coordinates of the point where the robot grip is located to the point with specified values (X_current + 1, Y_current + 1, Z_current + 1)

    move_to_1(x, Y, Z,T)

    moves the robot grip to the point with coordinates X, Y, Z with delays T between intermediate steps. Time is specified in milliseconds

    @Robot->move_to_1(1, 1, 1, 50); moves the robot grip to the point with coordinates X=1, Y=1, Z=1, with 50 millisecond delays between intermediate steps.

    move_to_2(x, Y, Z,T, R, Th4)

    moves the robot grip to the point with coordinates X, Y, Z with delays T between intermediate steps. Also rotates the robot grip around the axis by Th4 degrees

    @Robot->move_to_2(1, 1, 1, 1, 1, 30); moves the robot grip to the point with coordinates X=1, Y=1, Z=1, with 50 millisecond delays between intermediate steps. Will also rotate the robot grip around the axis by 30 degrees

    write_angles(Th1,Th2, Th3, Th4)

    changes the angles of the servo-drives by values Тh1, Th2, Th3, and Th4

    @Robot->write_angles(10, 10, 10, 10); will change the angles of the servo-drives by 10 degrees

    rotate_servo4(Th4)

    will change the angle of robot grip servo-drive position by specified value Тh4

    @Robot->rotate_servo4(15); will change the angle of robot grip servo-drive position by 15 degrees

    The following axes for controlling uArm robot are available:

    Axis

    Upper
    limit

    Lower
    limit

    Description

    locked

    1

    0

    Binary axis. If its value is 1, the robot is considered blocked and ignores changes in the values in any other axes.

    pump

    1

    0

    Binary axis. If its value is 1, the robot pump will be enabled. If the value is 0, the pump will be disabled.

    servo1

    180

    0

    The axis of changing the angle of the first servo located in the base.

    servo2

    180

    0

     The axis of changing the angle of the second servo acting on the angle between the base and the lower shoulder of the robot.

    servo3

    180

    0

    The axis to changing the angle of the third servo - between the shoulders of the robot.

    servo4

    180

    0

    The axis of changing the angle of the fourth servo that changes the angle of grip rotation.

    17.1.5 Quick connection of smc module to RCML

    The module of the smc robot allows in RCML to control LEH series industrial electromechanical grips manufactured by SMC, using the LECP6 controller of the same manufacturer. Each grip is presented in RCML as a robot that may be used and released afterwards. The LECP6 controller is connected to a PC running RCML via the proprietary cable that comes with the SMC Controller setting kit LEC-W2 used to control gripping from the PC.

    Industrial LEH series electromechanical grips manufactured by SMC

    Standard LECP6 controller for controlling LEH series grips

    These grips allow programming the travel and force of the jaws. More information about the LEH series grips is available at the official website:

    To control an SMC LEH series grip via RCML, one has to:

    1. Install and connect the grip to the controller according to the manufacturer's instructions.
    2. Connect the controller to the PC.
    3. Add an entry into section [robot_modules] of the RCML configuration file: property module, and set it equal to smc in accordance with section "Installation and Configuration of RCML Compiler and Interpreter".
    4. Next, configure the module. Specify which COM port should communicate with the grip controller. To do so, go into the directory with the robot modules (robot_modules), and then to the directory of the SMC module.
    5. In the directory of the smc module, create file config.ini with the following content:
    [main]
    count_robots = 1
    is_debug = 0
    robot_port_0 = \\.\\COM3

    The module configuration file consists of section [main], which includes the following properties:

    • count_robots is the property that takes as the parameter the number of SMC controllers to which it should connect.
    • is_debug displays in the console the data packages sent to the LECP6 controller. It may take value 0 or 1.
    • robot_port_X – contains the name of the COMport to which robot X is connected. The port address is to be specified in format \\.\\COMY, where Y is the number of the port (0-based enumeration).

    The following is the text of a program in the RCML language. The program calls the SMC grip, sends a command to separate the jaws by 1 cm at the speed of 1 mm/sec, and then sends the command to return to the default position:

    function main() {
    @r = robot_smc;
    @r-> move_to(1000, 1);
    @ur->return_to_origin();
    }

    The available functions of the module are shown in the Table:

    Definition

    Description

    Example

    move_to(pos, spd)

    Sets the distance between the jaws of the grip to pos (in hundredths of a millimeter). The jaws of the grip move at the speed of spd (mm/sec)

    @Robot->move_to (200, 10); sets the distance between the jaws of the grip equal to 2 mm. The jaws of the grip move at the speed of 10 mm/sec

    return_to_origin()

    Returns the jaws of the grIp to the default position (1 mm distance between the jaws)

    @Robot->return_to_origin();

    get_cur_position()

    Restores the current distance between the jaws of the grip (hundredths of a millimeter)

    @Robot-\>get\_cur\_position();

    get_cur_speed()

    Returns the current speed of grip jaws movement in mm/sec

    X = @Robot->find_x(); gets the X coordinate of the point the robot grip is located at, and stores it to variable X;

    get_cur_thrust()

    Returns the current load value (%)

    thrust = @Robot->get_cur_thrust();

    move_to2( move_mode, spd, pos, accel, decel, pushing_force, trigger_level, pushing_speed, moving_force, area_output1, area_output2, in_position)

    Sets the distance between the jaws of the grip to pos (hundredths of a millimeter); move_mode - movement type (1 - absolute movement, 2 - relative movement); spd - speed (mm/s), accel – acceleration at the start of the movement (mm/s^2); decel – deceleration at stop (mm/s^2); pushing_force (0 - positioning, [1-100] - effect with specified torque (%); trigger_level – the value of the effect, at which INP flag will become 1; pushing_speed - speed of movement at effect (mm/s); moving_force – the maximum force during movement (%); area_output1, area_output2 - if the current position is between the specified values, flag AREA will become 1; in_position - if the current position coincides with the specified value, INP flag will take 1

     

    set_hand_control_params(spd, accel, decel)

    Sets spd speed in mm/sec, acceleration accel in mm/s^2 and deceleration decel in mm/s^2 for manual control of the grip

    @Robot->set_hand_control_params(20, 50, 50);

    Available axes for the manual control mode:

    Axis

    The upper limit

    The lower limit

    Description

    locked

    1

    0

    Binary axis. If its value is 1, the grip is considered blocked and ignores changes in the values in any other axes.

    servo1

    1000

    100

    The axis that sets the distance between grip jaws.

    17.1.6 Quick connection of FANUC module to RCML

    For operating FANUC industrial robots with RCML, there is a cognominal robot module, FANUC. This module is compatible with production controllers of the A-cabinet and the B-cabinet series with enabled Modbus TCP software option. Therefore, the FANUC module supports all robots that are compatible with these controllers.

    Read more about FANUC robots on the official website of the company:

    This module can control the robot from a PC via RCML, and set in runtime arbitrary trajectories of the robot, including support of controlling additional groups of axes (rotary table, etc.)

    The low-level functionality of the FANUC module is the ability to send various data types to the controller from RCML: bits, integers, real numbers, and program invocation using the PNS mechanism.

    The PC with RCML communicates with the FANUC controller via an FTP Ethernet cable. The robot, the controller and the PC with RCML should be appropriately configured beforehand. The information about the setup procedure and preparation is available on request. Send you free form request to info@robotct.ru

    To connect the FANUC module, perform the following steps:

    1. Perform the required initial configuration of the robot and the controller;
    2. Configure the PC with RCML for establishing communication with the controller;
    3. Connect the FANUC controller to the PC with RCML via an FTP Ethernet cable; if there are several robots, they may be connected into the same network using appropriate network equipment.
    4. Add an entry into section [robot_modules] of the RCML configuration file: property module, and set it equal to fanuc in accordance with section "Installation and Configuration of RCML Compiler and Interpreter".
    5. Next, configure the FANUC module itself; to do that, create a file named config.ini in the module directory, and fill it according to the rules below.

    The configuration file should always contain section "main" with property count_robots, which indicates the number of the controlled FANUC robots.

    For each controlled robot, a section is created with name like robot_X, where X is the serial number of the robot, countdown starts with 1. This section is called "robot section". The robot section should contain 4 properties:

    • robot_name - the unique display name of the robot, string;
    • ip – the IP address of the robot controller in the network, string;
    • port - the port of the robot, digit; and
    • slave_id - the number of the robot in the Modbus network.

    It is expected that all robots connected to RCML will have the same configuration of digital inputs and outputs, DI and DO, respectively. For configuring DI, a homonymous section is used, where the sent data cells and their types may be specified. Each cell has a display name used in the RCML program for reference to that cell.

    The following data types are supported:

    • Boolean. Specified as logic_%name% = X, where %name% is the cell name, and X is the input number. This type involves only 1 input.
    • Integer. Specified as integer_%name% = X, where %name% is the cell name, and X is the number of the input where the counting of positions starts for sending the number. This type has the size of 16 bits and, accordingly, it uses 16 inputs. With that, counting of positions may use only those inputs the numbers of which, when divided by 16, give 1 in residuo (1, 17, 33, 49, etc.). The integer type can transmit only non-negative integers.
    • Real. It is specified as real_%name% = A,B,C, where %name% is the cell name, and A is the number of the input used for sending the number sign, B is the number of the input from which counting of positions starts for sending the integer part of the real number, and C is the number of the input from which counting of positions starts for sending the fractional part of the real number. This type has the size of 1+16+16 = 33 positions, and uses the same number of inputs. With that, the rule for choosing the input for B and C part is the same as the one for the integer data type.
    • Big integer. Specified as big_integer_%name% = A,B, where %name% is the cell name, and A is the number of the input where counting of positions starts for sending the first part of the number, B is the number of the input where counting of positions starts for sending the second part of the number. This type has the size of 16+16 = 32 positions, and uses the same number of inputs. With that, the rule for choosing the input for A and B part is the same as the one for the integer data type. The main purpose of this type is sending big non-negative integers.

    To set the configuration for digital outputs of the robot - DO, the same data types are applied, the rules of their description being the same. The only difference is that digital outputs are configured in the section named DO.

    The FANUC Module supports invoking PNS programs in the robot, but this requires allocating additional inputs/outputs with the following names.

    For DI:

    • logic_cycle_stop
    • logic_fault_reset
    • logic_start
    • logic_enable
    • logic_input_PNS1
    • logic_input_PNS2 
    • logic_input_PNS3
    • logic_input_PNS4
    • logic_input_PNS5
    • logic_input_PNS6
    • logic_input_PNS7
    • logic_input_PNS8
    • logic_PNS_strobe
    • logic_prod_start

    For DO:

    • logic_cmdenabled
    • logic_prg_running
    • logic_prg_paused
    • logic_motion_held
    • logic_fault
    • logic_busy
    • logic_out_PNS1
    • logic_out_PNS2
    • logic_out_PNS3
    • logic_out_PNS4
    • logic_out_PNS5
    • logic_out_PNS6
    • logic_out_PNS7
    • logic_out_PNS8
    • logic_snack

    In setting all these inputs/outputs, the module will have access to functions run_program and run_program_soft that use the PNS mechanism.

    The available functions of the module are shown in the Table:

    Definition

    Description

    run_program(number)

    Invokes the PNS program at number num in the robot, and awaits its completion. After normal termination returns default value, 0.0, and in case of an error, an exception is thrown. This function is available only if you have made configuration of inputs / outputs that are required for operation of the PNS mechanism. If no configuring was made, the function throws an exception.

    run_program_soft(num)

    Invokes the PNS program at number num in the robot, and does not wait for its completion. The running program may only be terminated manually through operating corresponding inputs/outputs that are responsible for controlling the PNS mechanism. This function is available only if you have made configuration of inputs / outputs that are required for operation of the PNS mechanism. If no configuring was made, the function throws an exception.

    set_logic_di(name, value)

    Setting the value to value for a Boolean input named name. The function throws an exception if the input with the specified name has not been found. A positive signal is sent to the input, if the value of value is not zero, otherwise, a negative signal is sent.

    get_logic_di(name)

    Obtaining the value of the Boolean input named name. The function throws an exception if the input with the specified name has not been found. The function returns 1 if the signal at the input is positive, and 0 if it is negative.

    get_logic_do(name)

    Obtaining the value of the Boolean output named name. The function throws an exception if the input with the specified name has not been found. The function returns 1 if the signal at the input is positive, and 0 if it is negative.

    set_integer_di(name, value)

    Setting the value to value for an integer input named name. The function throws an exception if the input with the specified name has not been found. If you are setting the value of value as real, it is rounded according to the mathematical rules.

    get_integer_di(name)

    Obtaining the value of the integer input named name. The function throws an exception if the input with the specified name has not been found.

    get_integer_do(name)

    Obtaining the value of the integer output named name. The function throws an exception if the input with the specified name has not been found.

    set_real_di(name, value)

    Setting the value to value for an integer input named name. The function throws an exception if the input with the specified name has not been found. In the sent value value, the digits after the 3rd decimal position will be dropped.

    get_real_di(name)

    Obtaining the value of the real input named name. The function throws an exception if the input with the specified name has not been found.

    get_real_do(name)

    Obtaining the value of the real output named name. The function throws an exception if the input with the specified name has not been found.

    set_big_integer_di(name, value)

    Setting the value to value for a big digit input named name. The function throws an exception if the input with the specified name has not been found. If you set the value of value as real, it is rounded according to the mathematical rules.

    get_big_integer_di(name)

    Obtaining the value of the big integer input named name. The function throws an exception if the input with the specified name has not been found.

    get_big_integer_do(name)

    Obtaining the value of the big integer output named name. The function throws an exception if the input with the specified name has not been found.

    The module of the FANUC robot has no axes available for the manual control axis.

    17.2 An example of connecting function modules

    17.2.1 Quick connection of the math module to RCML

    The math functional module is used to access mathematical functions similar to those in the math.h library in C++.

      1. To include the math module, add an entry to section [function_modules] in the RCML configuration file in accordance with Section "Installation and Configuration of RCML Compiler and Interpreter". The module does not require additional configuration.
      2. Now, there are the following functions at your disposal:

    Definition

    Description

    An exception is thrown, if

    pow(a, b)

    Powering a to power b.

     

    sqrt(a)

    Returns square root of a; a cannot be less than 0.

    a < 0

    abs(a)

    Returns the absolute value of a.

     

    rand(a,b)

    Returns a random integer in the range [b; a+b]; a cannot be less than or equal to 0.

    a ≤ 0

    sin(a)

    Functions sin, cos, tan accept values in radians.

    Returns the sine of a.

     

    cos(a)

    Returns the cosine of a.

     

    tan(a)

    Returns the tangent of a.

     

    asin(a)

    Returns the arcsine of a. Because of the function properties, argument a must be within [-1; 1].

    Functions asin, acos, atan return values in radians.

    a ∉ [-1;1]

    acos(a)

    Returns the arc cosine of a. Because of the function properties, argument a must be within [-1; 1].

    a ∉ [-1;1]

    atan(a)

    Returns the arc tangent of a.

     

    exp(a)

    Returns e to power a.

     

    log(a)

    Returns the natural logarithm of a. Because of the function properties, argument a must be more than 0.

    a ≤ 0

    log10(a)

    Returns the decimal logarithm of a. Because of the function properties, argument a must be more than 0.

    a ≤ 0

      1. In accordance with Section "Calling Functions", the syntax of the program using the math module is as follows:
    function main() {
    	r = 9;
    	r = math.sqrt(r);
    	system.echo(r);
    }

    The result of running this program is number 3.0000

    1. The following example shows throwing an exception in case of incorrect input data.
    function main() {
    	try {
    		r=math.log(0);
    	} catch {
    		system.echo("Throw exception log(0) undefined");
    	}
    }

    More detail about using exceptions is available in section "Exceptions".

    17.3 An example of connecting control modules

    17.3.1 Quick connection of control test module to RCML

    The test control module is used to imitate obtaining axis values from the control devices.

    To enable the test module, you need to add the property module and set its value to "test" in section [control_modules] in the configuration RCML file according to Section "Installation and Configuration of RCML Compiler and Interpreter". The test control module does not require additional configuration.

    The following is an example of using a test control module in interaction with test robot:

    function main() {
    	@lr = robot_test; 
    	system.hand_control(@lr,"test","X","X");
    }

    In running this program for 10 seconds, a random value is sent along the X-axis once per second. For functioning of the program, the test robot module should be connected. More detail about connecting is available in section "Quick connection of robot test module to RCML".

    The test control module has the following axes available:

    Name

    The upper limit

    The lower limit

    Note

    X

    100

    -100

     

    Y

    1

    0

    Binary

    Z

    100

    0

     

    The values of axes that are transmitted every second:

    Name

    1

    2

    3

    4

    5

    6

    7

    8

    9

    10

    X

    100

    -30.1

    -2.58

    48.9

    99.01

    -100

    12.0

    -36.9

    0.25

    0

    Y

    0

    0

    0

    1

    1

    0.5

    0.25

    0.1

    0.75

    0.35

    Z

    4.56

    0

    78.9

    100

    50

    48.8

    66.7

    32.4

    40

    20

    17.3.2 Quick connection of the keyboard module to RCML

    The keyboard control module is used to manually control the robot with the use of a keyboard.

    1. To activate a keyboard module, add entry "property module" to section [control_modules] to the RCML configuration file, and set it equal to keyboard in accordance with section "Installation and Configuration of RCML Compiler and Interpreter".
    2. In the folder of the keyboard module in the control_modules directory, create the config.ini module configuration file. 
    3. The configuration file of the keyboard module describes which axes are available to the programmer for interaction with the robot in the manual mode. To add a new axis, adhere to the following rules of describing it:

    3.1. In case of adding a new axis, add axis name property to section [mapped_axis] and set it equal to the value of the keyboard key in HEX format; there may be several keyboard button values for one axis. In general, an entry in the [mapped_axis] section will look as follows:

    axis_name = keyboard_button_value_in_HEX_format

    3.2. You should set the maximum and the minimum values that the axis may take. To do so, add to the config.ini configuration file a section named as the name of the axis, and set the upper_value and lower_value properties for passing the values of the axis' maximum and minimum. In general, the section looks as follows:

    [axis_name]
    upper_value = the_max_axis_value
    lower_value = the_min_axis_value

    3.3. Next, you should determine what value the axis will have after a previously defined button on the keyboard is pressed. The values are defined by creating a section with the name consisting of the axis name and the value of keyboard button in Hex format, separated by underscores. To set the default (not pressed) and pressed state values, unpressed_value and pressed_value are used, where the values are passed. In general, the section in this case will look as follows: 

    [axis_name_keyboard_button_value_in_HEX_format]
    pressed_value = axis_value_with_pressed_button
    unpressed_value = axis_value_with_released_button
     

    For clarity, here is an example of configuration for the keyboard module with comments

    ;Section for Linux
    [options]
    input_path = /dev/input/event2; Path to the input stream file
    
    ;Mandatory section
    [mapped_axis]
    ;axis_name = key_code (in HEX format)
    go = 0x26; up_arrow
    go = 0x28;down_arrow
    
    ;Description of the go axis, should always have both keys
    [go]
    upper_value = 1 ;Upper limit of axis values
    lower_value = -1 ;Lower limit of axis values
    
    ;Description of the go axis behavior for the *up_arrow* key (0x26)
    [go_0x26]
    pressed_value = 1 ;If *up_arrow* is pressed, the axis value to be set to 1
    unpressed_value = 0 ;If *up_arrow* is released, the axis value to be set to 0
    
    ;Description of the go axis behavior for the *down_arrow* key (0x28)
    [go_0x28]
    pressed_value = -1 ;If *down_arrow* is pressed, the axis value to be set to 1
    unpressed_value = 0 ;If *down_arrow* is released, the axis value to be set to 0

    An example of a module configuration description includes one go axle, which will return the maximum value of 1 when up arrow is pressed, and 0 when it is released, or -1 when the down arrow is pressed, and 0 when it is released. More detailed information about the axes and manual control is available in section "General Information".

    As an example, an advanced configuration file of the keyboard module is provided, where the following axes are initialized:

    • [go] – up and down arrows are used as control buttons;
    • [rotate] – the axis is controlled by left and right arrows;
    • [locked] – used to lock the robot by pressing the "A" button on the keyboard.

    The following is a listing of the configuration file of the keyboard module with three axes:

    [mapped_axis]
    go = 0x26
    go = 0x28
    rotate = 0x25
    rotate = 0x27
    locked = 0x41
    
    [go]
    upper_value = 1
    lower_value = -1
    
    [rotate]
    upper_value = 1
    lower_value = -1
    
    [locked]
    upper_value = 1
    lower_value = 0
    
    [locked_0x41]
    pressed_value = 1
    unpressed_value = 0
    
    [go_0x26]
    pressed_value = 1
    unpressed_value = 0
    	
    [go_0x28]
    pressed_value = -1
    unpressed_value = 0
    
    [rotate_0x25]
    pressed_value = 1
    unpressed_value = 0
    
    [rotate_0x27]
    pressed_value = -1
    unpressed_value = 0

    The following is an example text of a program in the RCML. The program invokes the test robot, which had been connected according to section "Quick start" and looks as follows:

    function main() {
    	@tr = robot_test; 
    	system.hand_control(@tr,"keyboard","X","go");
    }

    The first line of code creates a variable that is attached to the test robot; information about what a test robot is, and how to connect to it is available in Section "Quick connection of robot test module to RCML".

    The second line switches the test robot to manual control mode. As previously described, the go axis takes its value depending on pressed up and down arrows, and has the maximum value 1 and the minimum value -1, which translates their X-axis of the robot. However, during the program execution, the value of the axis of the control device will not be equal to the value of the axis of the robot. The axis is automatically scaled, i.e., the maximum value of the key is converted into the maximum axis value of the robot. A similar situation is observed when the down arrow button is pressed. The keyboard control module gets the minimum value of the keypad axis, and converts it to the minimum value of the robot axis. Thus, when the up arrow is pressed, the test robot will announce that it will move to the maximum position 100, and when the down arrow is pressed, it will move to -100.

    The test robot has two extra axes - Y, Z. Using the configuration file of the keyboard module described in step 3, let us add one more robot control axis. Let there be the "rotate" axis value passed along the existing values to the Z-axis of the test robot. The program code in this case will be as follows:

    function main() {
    	@tr = robot_test; 
    	system.hand_control(@tr,"keyboard","X","go","Y","rotate");
    }

    During the program execution, pressing the up or down arrows will call a test message from the robot, stating that a command has been received to change the values on the X-axis and Y-axis, when the left or right buttons are pressed. With that, the values received by the robot will be the maximum for these axes.

    More information about manual control is available in Section "Hand Control Mode".

    17.3.3 Quick connection of gamepad module to RCML

    The gamepad control module ensures manual robot control with the use of a gamepad.

    The number of the used axes depends on the contents of the config.ini module configuration file. The maximum number of axes that can be defined in the configuration file is 18, including:

    • 11 binary axes corresponding to buttons;
    • 4 axes for the sticks;
    • 2 axes for the D-pad;
    • 1 axis named "Exit" assigns the manual completion function to a button.
    1. To activate a gamepad module, add entry "property module" to section [control_modules] to the RCML configuration file, and set it equal to «gamepad» in accordance with Section "Installation and Configuration of RCML Compiler and Interpreter".
    2. Next, go into the RCML modules folder where control modules (control_modules) are located, then go to the «gamepad» folder.
    3. Create an empty config.ini file in the «gamepad» folder. Later, this file will be used for joystick configuration.
    4. Next, configure the config.ini configuration file of the module. It is proposed to use one of the two ready module configurations that are suitable for most gamepads:

    4.1. The universal module configuration file for interaction with gamepad No. 1

    [axis]
    Exit = 9
    B1 = 1
    B2 = 2
    B3 = 3
    B4 = 4
    L1 = 7
    L2 = 5
    R1 = 8
    R2 = 6
    start = 10
    T1 = 11
    T2 = 12
    RTUD = 13
    RTLR = 16
    LTUD = 15
    LTLR = 14
    arrowsUD = 17
    arrowsLR = 18
    
    [B1]
    upper_value = 1
    lower_value = 0
    	
    [B2]
    upper_value = 1
    lower_value = 0
    	
    [B3]
    upper_value = 1
    lower_value = 0
    	
    [B4]
    upper_value = 1
    lower_value = 0
    	
    [L1]
    upper_value = 1
    lower_value = 0
    	
    [L2]
    upper_value = 1
    lower_value = 0
    	
    [R1]
    upper_value = 1
    lower_value = 0
    	
    [R2]
    upper_value = 1
    lower_value = 0
    	
    [start]
    upper_value = 1
    lower_value = 0
    	
    [T1]
    upper_value = 1
    lower_value = 0
    	
    [T2]
    upper_value = 1
    lower_value = 0
    	
    [RTUD]
    upper_value = 0
    lower_value = 65535
    	
    [RTLR]
    upper_value = 0
    lower_value = 65535
    	
    [LTUD]
    upper_value = 0
    lower_value = 65535
    
    [LTLR]
    upper_value = 0
    lower_value = 65535
    	
    [arrowsUD]
    upper_value = 1
    lower_value = -1
    	
    [arrowsLR]
    upper_value = 1
    lower_value = -1
    4.2. The universal module configuration file for interaction with gamepad No. 2:
    [axis]
    Exit = 9
    B1 = 4
    B2 = 2
    B3 = 1
    B4 = 3
    L1 = 5
    L2 = 7
    R1 = 6
    R2 = 8
    start = 10
    T1 = 11
    T2 = 12
    RTUD = 16
    RTLR = 13
    LTUD = 15
    LTLR = 14
    arrowsUD = 17
    arrowsLR = 18
    	
    [B1]
    upper_value = 1
    lower_value = 0
    	
    [B2]
    upper_value = 1
    lower_value = 0
    	
    [B3]
    upper_value = 1
    lower_value = 0
    	
    [B4]
    upper_value = 1
    lower_value = 0
    
    [L1]
    upper_value = 1
    lower_value = 0
    
    [L2]
    upper_value = 1
    lower_value = 0
    
    [R1]
    upper_value = 1
    lower_value = 0
    	
    [R2]
    upper_value = 1
    lower_value = 0
    	
    [start]
    upper_value = 1
    lower_value = 0
    
    [T1]
    upper_value = 1
    lower_value = 0
    
    [T2]
    upper_value = 1
    lower_value = 0
    
    [RTUD]
    upper_value = 0
    lower_value = 65535
    
    [RTLR]
    upper_value = 0
    lower_value = 65535
    	
    [LTUD]
    upper_value = 0
    lower_value = 65535
    
    [LTLR]
    upper_value = 0
    lower_value = 65535
    
    [arrowsUD]
    upper_value = 1
    lower_value = -1
    	
    [stick_zero_positions]
    axis_1 = 31487
    axis_2 = 31487
    axis_3 = 31487
    axis_4 = 31487
    arrows = 4294967295
    
    [options]
    input_path = /dev/input/js1
    
    [arrowsLR]
    upper_value = 1
    lower_value = -1

    If ready module configuration files are used, steps 5 through 8 should be skipped. If the configuration files do not provide the desired level of control, it is necessary to additionally perform the skipped steps.

    Before proceeding to controlling a real physical robot, it is recommended to validate the configuration of «gamepad» on a test robot, the methods of connecting the test robot to RCML is available in Section "Quick connection of robot test module to RCML".

    5. Make sure the gamepad is connected to the computer. Otherwise, when the 'calibrator.exe' is executed further, a ‘cant CreateDevice’ error will be generated.

    6. To fill the configuration file, run the 'calibrator.exe' file.
    This console application will start the calibration wizard. The instructions of this wizard are to be followed to fill the config.ini file.
    To skip assigning a button, it is enough to wait for the time specified as the parameter. (5 seconds by default)

    7. If pressing a button was skipped, or a wrong button has been pressed, close the window, restart 'calibrator.exe', and follow the instructions more carefully.

    8. Thus, the gamepad module configuration will be created. If this file is opened, it will contain the names of the axes and their threshold values.

    9. The following is the table with transcript of each available axis of the gamepad:

    Name

    The upper limit

    The lower limit

    Note

    B1

    1

    0

    Binary axis. Corresponds to any button from the ABXY group of buttons of the x-box gamepad.

    B2

    1

    0

    Binary axis. Corresponds to any button from the ABXY group of buttons of the x-box gamepad.

    B3

    1

    0

    Binary axis. Corresponds to any button from the ABXY group of buttons of the x-box gamepad.

    B4

    1

    0

    Binary axis. Corresponds to any button from the ABXY group of buttons of the x-box gamepad.

    L1

    1

    0

    Binary axis. Corresponds to the button with the same name of the x-box gamepad

    L2

    1

    0

    Binary axis. Corresponds to the button with the same name of the x-box gamepad

    R1

    1

    0

    Binary axis. Corresponds to the button with the same name of the x-box gamepad

    R2

    1

    0

    Binary axis. Corresponds to the button with the same name of the x-box gamepad

    start

    1

    0

    Binary axis. Corresponds to the button with the same name of the x-box gamepad

    T1

    1

    0

    Binary axis. Corresponds to the button with the same name of the x-box gamepad

    T2

    1

    0

    Binary axis. Corresponds to the button with the same name of the x-box gamepad

    RTUD

    Assigned

    Assigned

    Discrete axis. Corresponding to the right stick.

    RTLR

    Assigned

    Assigned

    Discrete axis. Corresponding to the right stick.

    LTUD

    Assigned

    Assigned

    Discrete axis. Corresponds to the left stick.

    LTLR

    Assigned

    Assigned

    Discrete axis. Corresponds to the left stick.

    arrowsUD

    1

    -1

    Discrete axis. Corresponds to the D-pad of the gamepad.

    arrowsLR

    1

    -1

    Discrete axis. Corresponds to the D-pad of the gamepad.

    The following is an example text of a program in the RCML language. The program invokes the test robot, which had been connected according to Section "Quick start" and looks as follows:

    function main() {
    	@tr = robot_test; 
    	system.hand_control(@tr,"gamepad","X","RTUD");
    }

    The first line of code creates a variable that the test robot is assigned to.

    The second line switches the test robot to manual control mode from the gamepad.

    During the program execution, using the right stick in the up-down direction will pass value of the X-axis to the test robot. Each time the position of the stick changes, the window will display a message stating that the test robot has received a change of the value along the X-axis.

    More information about manual control is available in Section "Hand Control Mode".

    17.3.4 Quick connection of Myo to RCML

    Myo is an armband that allows using various gestures to control a PC, a smartphone or a tablet.

    More information is available from the official website of the device:

    The myo control module is used for manual control of the robot using the Myo device, which detects gestures and position of the hand in space.

    1. First, you have to run "install and configure Myo" on your computer, as shown in Setting up the Myo armband with your Windows PC.
    2. Next, configure the following settings for Myo Connect.

    2.1. Configure General settings in accordance with the Figure.

    2.2. Configure Presentation Mode as shown in the Figure.

    2.3. Moreover, it is necessary to disconnect Connector and Presentation Mode in accordance with Figure.

    2.4. You should also configure Myo Keyboard Mapper as shown in the Figure.

    • To activate a myo module, add entry "property module" to section [control_modules] to the RCML configuration file, and set it equal to myo in accordance with Section "Installation and Configuration of RCML Compiler and Interpreter".
      The module does not require additional configuration, and will by default connect to the first armband in the system.
    function main() {
    	@r = robot_test;
    	system.hand_control(@r,"myo","X","fist");
    }

    The first line of the program creates a variable that is attached to the test robot; information about how to connect the test robot is available in Section "Quick connection of robot test module to RCML".

    The second line of the program specifies that the robots will be operated in manual mode. That is, the value of the fist axis of the Myo control device will be passed to the X-axis of the @r test robot. More information about what manual control function means is available in Section "Hand Control Mode".

    During the program execution, make the "fist" gesture (double your fist), the gesture will be recognized by Myo and via the myo control module, and the new value of the X-axis will be passed to the test robot. Since 1 is the maximum value of the "fist" axis for Myo, and for the test robot the maximum value of the X-axis is 100, the upper limit of the fist axis value will be converted to the upper limit of the X-axis. Thus, the robot will change the value of the X-axis to the maximum possible value – 100.

    The Myo armband can recognize the following gestures:

    • fist;
    • fingers spread;
    • double tap;
    • wave out;
    • wave in;
    • rest (no gesture, relaxed hand).

    All these gestures are available to the programmer by default.

    In addition, the following axes in the module are available for the programmer:

    Name

    The upper limit

    The lower limit

    Note

    locked

    1

    0

    Binary axis. Shows the status of the Myo bracelet: blocked - 1, unblocked - 0.

    fist

    1

    0

    Binary axis. If the fist gesture is observed, 1, otherwise - 0.

    left_or_right

    1

    -1

    Discrete axis. Convenient for specifying the direction of movement or rotation. It is based on the wave out and wave in gestures. Automatically determines rightward or leftward hand direction in these gestures (no matter which arm the armband is worn on) and takes the following values: -1 for leftward, 0 - no gesture, and 1 for rightward.

    fingers_spread

    1

    0

    Binary axis. 1 if the "fingers spread" gesture is detected, otherwise - 0.

    double_tap

    1

    0

    Binary axis. 1 if the "double tap" gesture is detected, otherwise - 0.

    fist_pitch_angle

    18

    0

    Continuous axis. Detects the pitch of the armband relative to the earth, in case of the "fist" gesture.

    fist_roll_angle

    18

    0

    Continuous axis. Detects the roll of the armband relative to the earth, in case of the "fist" gesture.

    fist_yaw_angle

    18

    0

    Continuous axis. Detects the yaw of the armband relative to the earth, in case of the "fist" gesture.

    fingers_spread_pitch_angle

    18

    0

    Continuous axis. Detects the pitch of the armband relative to the earth, in case of the "fingers spread" gesture.

    fingers_spread_roll_angle

    18

    0

    Continuous axis. Detects the roll of the armband relative to the earth, in case of the "fingers spread" gesture.

    fingers_spread_yaw_angle

    18

    0

    Continuous axis. Detects the yaw of the armband relative to the earth, in case of the "fingers spread" gesture.

    Notes to the table:

    1. The values of all axes are transmitted 20 times per second.
    2. The values of the axes with suffix "angle" are changed and transmitted only after detecting the corresponding gesture.
    3. If the armband is blocked, the values of all gestures axes, except for the axis "locked" and the axes with suffix "angle", will be equal to 0.
    4. The armband is blocked automatically if for some short time (1-2 seconds) the sensors detect an unknown gesture, or the "rest" gesture is detected, as well as in case shift of the armband on the arm is detected, or if the armband is taken off the arm.
    5. The armband in unblocked by the "double tap" gesture, same as in many Myo-compatible applications.
    6. It is recommended to use caution when using simultaneously the "fist" or "fingers_spread" axes, and the axes with names containing the same "fist" or "fingers_spread" prefixes, respectively, for controlling the robot. The reason is that the axes of gestures take value 1 when there is an attempt to change the values of axes that are active after the corresponding gesture, since it requires detection of this gesture.

    Beside the test robot, another RCML-compatible robot may be connected to the RCML system.

    17.4 An example of connecting choice robot modules

    17.4.1 Quick connection of choosing avg module

    The robot selection module avg implements the simplest logics for choosing the fastest robot based on the RCML statistical data.

    First, the module starts populating the statistical data into the database so that each robot from the set of available robots performs the required function at least once.

    After that, it will always choose the robot with the shortest average time of performing the required function by its (robot's) number of attempts to perform this function.

    Enabling the avg module is standard: add the module property to section [choice_modules] of the RCML configuration file, and set it equal to avg in accordance with section "Installation and Configuration of RCML Compiler and Interpreter" of the RCML Manual.

    No additional configuration of the avg module is required. However, RCML should be in the mode of writing statistical information, otherwise the module will prohibit invocation.

    Address:

    12, Monastyrskaya St., lit. A,
    Office 600, Perm, Russia

    Phone:

    +7 (342) 214 01 84

    E-mail:

    info@robotct.ru