Robot Control Meta Language (RCML)

1.1 Quick Start

RCML Quick Start for Windows


RCML Quick Start for Linux


Go to SourceForge project page at:

From the folder of your OS, download the archive with files of compiler and the archive with files of modules, where X is compiler version. Versions for these two archives must be the same.

Extract both of the downloaded archives to the same folder.

Go to the folder with the files extracted and create config.ini file there with the following contents:

module = test

In the current folder, create another file called hello.rcml with the following contents:

function main() {
	robot_test->print("Hello world!\n", 0);

This will be your first program in RCML, consisting of a single operator – a function calling output of the line “Hello world!\n” of the test virtual robot robot_test with a delay of 0 sec.

To compile a program, run the command line editor in the current folder and execute the following command:

rcml_compiler.exe hello.rcml hello.rcml.pc

A file of compiled program hello.pc will appear in the current folder, as shown in the figure 1.

Figure 1 Result of program compilation

To run the compiled program, execute the following command:

rcml_intepreter.exe hello.rcml

Please note that in this case you do not specify pc extension of the compiled program file. The example of successful execution of the file is shown in the figure 2.

Figure 2 Result of successful program execution

1.2 Description of RCML Program Generation Process

You can write a program in RCML in any text editor, saving it in a plain text file with rcml extension.

Rcml extension is advisory in nature, in fact, a file can have any name supported by the file system of your OS.

Subsequently, this file is compiled by RCML language compiler, while executing a number of procedures to prepare the program for execution, namely:

  • Validation of the program syntax;
  • Validation of function calls, robots and transfer of parameters;
  • Conversion of the program text into the byte code;
  • Execution of various modifications to the byte code to speed up its execution and memory utilization optimization.

Upon successful program compilation, RCML language compiler generates a file with program byte code, with the recommended double extension rcml.pc (PC – pseudo code). A file with the byte code includes binary content with a structure close to machine codes of the processor, executed by its own virtual machine due to certain features of RCML language.

The immediate program execution is performed by RCML language interpreter, as the name implies, interpreting byte code instructions through an internal virtual machine into real processor commands.

1.3 Installation and Configuration of RCML Compiler and Interpreter

The compiler and interpreter are available for downloading from the SourceForge project page:

The compiler and interpreter are two executable files that are to be put into the same folder. Additionally, in the folder you will have to create a text file config.ini, which is the RCML environment configuration file. The configuration is the same for the compiler and the interpreter.

This file may contain the following sections:

  • [robot_modules] – the section for connecting robots' modules;
  • [function_modules] - the section for connecting functional modules;
  • [control_modules] - the section for connecting control modules; 
  • [choice_modules] – the section for connecting the robot's choosing modules.

The name of the connected module is specified in the module property in the section of the same type as the module. If there are several connected modules of the same type, a separate line is allocated for each of them. Modules of a particular type are loaded in the order, in which they were listed in their section.

An example of setting connected modules in config.ini:

module = test
module = tarakan
module = uarm
module = lego_ev3
module = math
module = test
module = keyboard
module = gamepad
module = myo
module = avg

For modules of all types, folders named after the section are to be created in the folder with the compiler and interpreter (robot_modules, function_modules, control_modules or choice_modules). For each module, in the folder corresponding to its type, a directory with the same name as the one of the module should be created; this directory will be further referred to as the module directory. The module itself is represented by a dynamic-link library file which should have the same name as the module, but with suffix _module added. The module file should be in the module folder. The module folder may contain other files required for module operation, e.g., configuration files.

Additionally, the config.ini file may contain following sections:

  • [statistics] – this section may have only one property - db_path - the path to the database file where the robots will write statistics about the performed functions. If the database file does not exist, it will be created. If the database already exists, it will be amended. If this property is null or empty, no stats will be recorded.
  • [lib_search_paths] – search paths for the compiled RCML libraries. In this section, the path property may specify the default path to the RCML library. There may be several paths, in case each path is set via a separate path property. The required library is searched by the specified paths in the same order in which the path in this section have been specified.
  • [locale_settings] is the section of the current locale settings; it may contain only one property – locale, where the parameters of the current locale for RCML are specified as a string according to the rules adopted in the Linux environment. By default, the current locale is English; it is set by value en_US.UTF-8.

For example, to switch the current locale to Russian, set it to ru_RU.UTF-8.

Important! The locale_settings option is supported only in Windows OS.

The files of all supported locales may be downloaded from the respective directory at the official download page of the SourceForge project:

You can read how to add your own locale to your RCML project in the locales repository webpage for RCML:

1.4 Details of Robot Modules

Robot modules hold one of the key positions in RCML language, because communication and transfer of commands to the physical robot is performed via them, see. the figure 3.

Figure 3 The role of robot modules in communication with the physical robots

Robot module is responsible for sending commands from RCML language interpreter to one or more robots of a single class (or type) incorporated by this module. It is recommended to use a separate module for each robot class or type. RCML interpreter communicates with the robot module through the declared API, and that in turn communicates with each robot assigned to it. Thus, communication and control of a robot by the interpreter is implemented through the robot module, allowing to connect a wide range of robots to it. Read more on how to write your own robot module and connect it to the interpreter in Section "Creating Own Modules for RCML".

Depending on their functionality, robot modules can additionally provide manual robot control by the control device represented by an appropriate module in RCML environment.

1.5 Details of Function Modules

You can add new features to RCML language through function modules that are not appropriate or can not be implemented in this language, for example, any complex calculations. Thus, function modules may allow RCML communication with other software through a separate API.

1.6 Details of Control Modules

Modules of this type are used for making decisions about choosing the next robot for performing a particular function. Alternatively, the choice may be based on previously accumulated statistical data about this function, robot, or the program. Using the choosing modules, it is possible to choose the robot by various different algorithms used in the modules. Usually, a separate module is a separate algorithm for choosing the robot.

Without these modules, the robots are chosen at the discretion of robots modules. Read more about the mechanism of choosing the robot in section "Using the robot choosing module".

1.7 Compiling and Running RCML Program

As noted earlier, a program written in the RCML language should first be compiled into the byte-code, after which it can be invoked by the interpreter.

For compiling the program, start the RCML compiler; by default, the name of its executable (without extension, since it may vary depending on the OS) is rcml_compiler. The compiler is to be started with 2 parameters passed to it:

rcml_compiler <rcml_text_file> <rcml_pc_file>

The first parameter, rcml_text_file, is the path to the file with the RCML program, and the second parameter, rcml_pc_file, is the path to the file into which the byte-code of the program is to be written.

If compilation is successful, the file with the byte-code will be created, or overwritten if it already exists. And now it can be invoked using the RCML interpreter, by default, the name of the executable file is rcml_interpreter. At startup, the compiler expects a single parameter – the file with the byte-code. The syntax of the command for starting the interpreter:

rcml_interpreter <rcml_pc_file>

Important! The interpreter automatically appends the .pc extension to the rcml_pc_file path.

1.8 RCML command-line options

The command line of the RCML compiler has the following pattern:

rcml_compiler [--version] [--logfile log_file_path] <rcml_text_file> <rcml_pc_file>
  • --version - shows the current version of the RCML compiler, the list of versions supported by the API modules, and the build date. If this flag is specified, the compiler shows the information and immediately exits;
  • --logfile log_file_path - writes the output of the RCML compiler to a file in the log_file_path part;
  • rcml_text_file is the path to the file with textual representation of the RCML program; 
  • rcml_pc_file is the path to the file that the compiled program is written to.

The command line of the RCML interpreter has the following pattern:

rcml_interpreter [--version] [--logfile log_file_path] <rcml_pc_file> [rcml_params]
  • --version - shows the current version of the RCML interpreter, the list of versions supported by the API modules, and the build date. If this flag is specified, the interpreter shows the information and immediately exits;
  • --logfile log_file_path - writes the output of the RCML interpreter to a file in the log_file_path part;
  • rcml_pc_file is the path to the file with compiled RCML program; and
  • rcml_params is the startup options of the RCML program. Read more about interpreter options in section "Passing parameters to the RCML program".

Important! The interpreter automatically appends the .pc extension to rcml_pc_file.


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


+7 (342) 214 01 84