Screenshots     Download     Pricing     Documentation     Tutorials     Resources     Contact     Forum     Search  

RoboRealm Server API

Introduction

The RoboRealm Server API specifies a socket based communication protocol that can be used to remote control the RoboRealm Application. This API allows you to use your own program to command RoboRealm to load/save image, load/save programs, get/put images and perform any image analysis processing as you would using the RoboRealm application.

The RoboRealm API is different than the RoboRealm Plugins as the plugins are used to add new image processing modules into RoboRealm for use in any application/project. They also guarantee that each frame is processed by the plugin before execution is passed back to the image processing pipeline. The API is used for external applications to query the data within RoboRealm and/or manage the RoboRealm application remotely.

The RoboRealm API is used for situations where you have a main control program that is the central processor for all functions and you need to interface vision processing into parts of your program when needed. You can use the API commands to execute a sequence of image processing instructions which then return the results to your program. Your program would then continue based on those results.

There are API routines to manipulate variables and parameters. Variables are containers of information that are global within RoboRealm and can be accessed by scripting functions like the VBScript module using GetVariable function calls. You can see all current variables in RoboRealm using the Watch module. Parameters, are similar to variables but they specify a specific value within one of the GUI interfaces and are localized to that module. Thus if you want to set a value that you use in an IF statement or in the VBScript module use variables, whereas if you want to change the static number or text within the GUI interface of a module use parameters.

Note that some GUI modules allow for the [expression] format to be used in place of a number/text. In that case setting a variable will modify a GUI parameter too. This is the recommended usage when possible as variable modification is quicker than parameter changes as parameter changes need to interact with the GUI interface.

To determine what parameters to do what within a GUI dialog, insert that module within the RoboRealm GUI, save that pipeline using the save button to something.robo. Then load that something.robo into a text editor and you will see the XML tags that are the parameters to the module and what values they have. These XML names are the parameter names that can be used in the API to change those values.

Download Examples of RoboRealm API

The examples currently within the above zip download include C/C++, CSharp, Java, Python, Visual Basic (VB and .Net), Labview, Lisp, Matlab, Processing and WScript examples. While many of the examples include code in the languages native format to create a connection directly to the API server, it is recommended to use the COM object in all languages as the C/C++ and COM examples are the ONLY examples kept up to date. As new functions are added only the C/C++ and COM examples are updated to reflect these changes. Should you chose to use a native connection, you may have to refer to the XML messages to create messaging function that provides the needed functionality.

To use the COM examples you must first register the COM object using 'regsvr32 \path\API\RR_COM_API.dll' where path is the path you unzipped the API.zip file. This can be done by typing in the above line into the Windows Start Button->Run or by first opening a command prompt (aka cmd in the Start->Run program). Either CD to that folder or type the full path.

Regsrv32 example

Special attention is needed for the Execute message as it is one of the most powerful but most generic function that accepts an XML image processing sequence string. The string will contain data that can be modified prior to sending the command sequence to be executed (using sprintf in C/C++). For example, you may want to change the filename in the example above as needed. The main difficulty of this routine is in creating the appropriate RoboRealm based XML string needed to accomplish a specific task. The easiest way to create these command strings is to run RoboRealm, configure the image processing pipeline using the provided GUI controls, save the program into a .robo file and then cut and paste the contents of the .robo file into the execute parameter. I.e. the execute function uses the same XML format as the .robo file. To determine the appropriate values for each of the modules you can use the same procedure and check what parameter values have changed.

Starting the API Server

The RoboRealm Server enabled/disabled from the Options dialog (click on the Options button from the main RoboRealm dialog window). For security reasons the RoboRealm Server is OFF by default. Clicking on the checkbox will active the socket listener and set RoboRealm ready to accept remote commands.

RoboRealm Server Activation

The API communicates to RoboRealm over network sockets. This means that RoboRealm can be remote controlled from a different machine located on your network. Note that this assumes that RoboRealm is already running as the API has no way of starting RoboRealm on a different machine than where the API commands are being executed. In this case you will want to place a link to RoboRealm in your windows "startup" folder.

Once you have started the RoboRealm Server (by clicking on the checkbox in the Options Button->API Server tab->Activate RoboRealm API Server checkbox) you can command RoboRealm from any socket based program given the specific commands.

Testing the API communication

For a quick test to see if your RoboRealm API Server is functioning correctly you can execute the following command from the windows command console to request the IMAGE_COUNT variable (the number of images that have been processed so far).

First open up a command console using Windows Start Button->Run->Type cmd and press OK. You should then see something like the following:


Within this window type:

telnet localhost 6060
and press enter. This should clear the screen and show nothing. Next copy the following text into your clipboard

<request>
  <get_variable>IMAGE_COUNT</get_variable>
</request>

and move back to the command console, right click and select paste. This will immediately send this text to the RoboRealm Server and return back an XML string with a single value of the image count (look for the value inbetween the <IMAGE_COUNT>X</IMAGE_COUNT> reply). You can then paste again to get another updated value.

For another example try pasting in the following which, assuming you have installed RoboRealm in the default location, it will load in an image.

<request>
  <load_image>
    <filename>c:\program files\RoboRealm\remo.gif</filename>
  </load_image>
</request>

Once this is done check the RoboRealm interface to see if it loaded in the specified image.

Note the usage of the "telnet" program which is a generic network connection program. The first line sets up the telnet program with the correct hostname and port number (RoboRealm Server runs on port 6060). The text you are pasting into that application is the XML command string that is interpreted by RoboRealm and executed accordingly. Note that the filename specification is relative to the machine that RoboRealm is running on and may be different that specified above. You can execute this sequence from any machine in your network AND from any operating system (including Linux) that has the telnet program installed.

The above text is a quick example of how the API can be used directly. We provide a complete source code examples written in C++, Java, C# (CSharp), VB.Net, Visual Basic, Matlab, LabView, Python, Lisp and WScript that implements the API socket communication. You can include this source into your own robot control program to add in the full vision processing capabilities of RoboRealm.

Testing Problems

If you have problems with the above example, the most likely scenario is that either the RoboRealm API is not running or you have a network restriction enabled. To check that RoboRealm is running ensure that you see the application running in your task bar AND that you have enabled the API Server (which is disabled by default) by checking the checkbox in Options Button->API Server Tab. Also be sure that the port specified in that interface is the SAME as what you are using in the example above.

If things still do not work (i.e. you see something like 'Connecting To localhost...Could not open connection to the host') then you probably have a firewall restriction that is preventing RoboRealm in opening and listening on port 6060. This is a non-known port so most likely your firewall does not like it. What you can try instead is to change the port to 80 and likewise in the API Server tab under the Port value. Changing it to 80 which is the port that browsers use may allow the firewall to agree to let information pass. Please note that if you are already running a webserver or have activated the RoboRealm Web Server this change will not be accepted. You may try port 8080 instead which may or may not work. If this fails you will have to check with your IT staff to determine how to allow your firewall to allow RoboRealm to run on a port.

API Parameters

When invoking RoboRealm.exe from your own application you have several command line options that you can use to force RoboRealm's behavior when it runs.

c:\RoboRealm\bin\RoboRealm.exe -api_port 1234 -new_instance -instance_2 -ini_file c:\temp\RoboRealm.ini -faceless

api_port - If you wish to run multiple copies of RoboRealm and use the API in each separate instance you will have to run RoboRealm with different API port numbers. Using -api_port 1234 will run a copy of RoboRealm using the API port 1234 instead of whatever is saved as the last configuration or the default 6060. Specifying the -api_port will also force the API server to execute regardless of the settings saved within RoboRealm's configuration. To force a new instance of RoboRealm each time you can use. This option can also be found in Options Button->API Tab in the GUI.

new_instance - Forces another RoboRealm instance to appear as apposed to defaulting to the already running instance. This option can also be found in Options Button->Startup Tab in the GUI.

instance_2 - Forces RoboRealm to run using the configuration of the second instance of RoboRealm. Whenever RoboRealm is run with more than one instance of the application the settings for that instance are separate from the first. This allows successive instances to run using the same settings as they did the last time they ran. Using the -instance_X command will allow you to pick which instance to run regardless of how many actual instances of RoboRealm you currently have running. Note that -instance_1, -instance_2, ... -instance_16 are valid parameters but only one is valid at a time.

ini_file - The ini_file parameter forces RoboRealm to read all configuration that is normally stored in the Registry from an ini file. This can be useful if you want to copy the configuration of RoboRealm and move it to another machine without having to reconfigure the application. Note that the instance_X parameter still applies in this case as each instance is also stored in the single ini file.

faceless - Forces RoboRealm to operate in faceless (without GUI) mode.


API Related Forum PostsLast postPostsViews
installable versions
Hello I'm using Roborealm in 2 identical robotic cells in two very different locations, the second ...
3 days 2 50
Failing to pause pipeline after waiting 10 seconds...
Hi, I have written a c# application that is based on the c# sample app that uses sockets to communi...
1 month 7 309
GetVariable("BLOB_COUNT") returns null
Hi, I am trying to use BLOB_COUNT with filters to check that there is nothing of a certain colour, ...
2 months 2 259
2D code read
Hello I have a problem with reading 2D code. I have a few 2d codes as in the picture. ...
1 year 4 272
Registering API COM object
I am going through your tutorial on RoboRealm Server API and to the point where I need to register the com object (I am running ...
1 year 2 157
Connection from Android phones
STeven, trying to look for next steps in my Sudoku application, I am looking for ways of transmitti...
1 year 1 264
Bug in Python 2.x Module
STeven, if you run the above script, open the Python module and try to pull down the slider on the ...
1 year 7 264


© 2005 - 2015 RoboRealm. All Rights Reserved. | Contact | Glossary | Privacy | Disclaimer | Link to Us | Resources