RoboRealm Server API

• Download Examples of RoboRealm API
• Starting the API Server
• Testing the API communication
• API parameters
• XML messages
• COM functions
• API Tips

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.

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 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

<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

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.

Please refer to Command Line Parameters for more options.

API Tips

• 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 is running.
• If you bring up the API tab in the Options button you can watch the request/response replies as they happen.