RoboRealm Server API
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.
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.
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
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
For another example try pasting in the following which, assuming you have installed RoboRealm in the default location,
it will load in an image.
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.
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.
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.
- Think of RoboRealm like a server. Slower to start and stop the application but very fast to
service requests. It is best to start RoboRealm at the beginning of your application, leave
it running and then close when your application exits. This is what is done in the
C# SampleApp and other continious loops. RoboRealm is really meat to quickly
process successive images so the speed is favored towards that and NOT to startup or
stopping of the application.
- Load in one robofile at the start and use conditionals or tab calls to get
different functionality. Loading in a robofile takes a bit and is not optimized.
Again, RoboRealm does not expect the robofile to change from image to image so
it is biased again to setup a new pipeline for successive image processing rather
than quick loading.
- Keep in mind that CTRL-ALT-R when focused on the desktop will bring a faceless
RoboRealm into view. Normally when doing development using the API it is helpful
to just open up the RoboRealm GUI and switch on the API to keep watch of what is
going on via the GUI. This is helpful for debugging purposes and to catch mistakes.
- If your application starts RoboRealm but doesn't close it down correctly
(i.e. you press stop on your application) it is possible for a second instance
of RoboRealm to start which can cause conflicts. If you suspect communications
issues, check your Task manager to ensure that only one instance of RoboRealm.exe
- If you bring up the API tab in the Options button you can watch
the request/response replies as they happen.