Before You Start

READ THIS PAGE FIRST

Before you install RDS, make sure that you have Visual C# installed. All Editions of Visual Studio 2010 that include C# are supported. If you do not do this, the Wizard/Template for creating new services will not be installed.

If you plan to use a Kinect sensor, either a simulated one or a real one, then you must install the Kinect for Windows SDK before installing RDS.

Once you have installed RDS, the next step is to run "Build All Samples" from the Start Menu. This will compile all of the samples and tutorials. If you do not do this, you might encounter problems when you try to follow the tutorials. (All of the items in the Start Menu will work without this step, but it is still best to build the samples first).

NOTE: Some samples will not compile without the Kinect for Windows SDK. Other samples require the Silverlight 4 SDK. (The Silverlight 5 SDK does not include Silverlight 4. However, both of them can be installed side-by-side.)

You should complete the steps listed below before you try to write your own code or run any of the samples. If you cannot successfully start a DSS Node then you are wasting your time trying anything else.

NOTE: There is also a Getting Started with RDS document in the Documentation folder under your RDS installation.

First Steps

The exact process for getting started with RDS depends on several things: your operating system, how you have configured your security, whether you are an Administrator, whether it has been installed previously and so on. It is not possible to provide a definitive list of steps, but this section gives some pointers and will work in most cases.

Firstly, you have the relevant documentation on your hard drive. Just go to the Start Menu, find RDS, and click on Documentation. The information in the online MSDN Library is identical to the Help file. Be sure to use the Help file, and in particular the Search tab, when you need information.

Secondly, become familiar with the contents of the Start Menu. This is particularly important for RDS because there are a lot of samples for Simulation.

RDS relies on a DSS (Decentralized Software Services) Node to run and manage services. A node can be started using either the DssHost.exe or DssHost32.exe programs. You must be able to run one of these programs in order to use RDS.

NOTE: DssHost and DssHost32 perform the same function. DssHost32 is specifically for use on 64-bit Windows and must be used if you want to run the Simulator or any other service that uses 32-bit components. In this Help file DssHost and DssHost32 are used interchangeably.

There are two parts to getting DSS working:

1. Run a DSS Node to verify that DSS can connect to the network.

2. Run a web browser to confirm that you can view services running in the DSS node.

NOTE: Even if you intend to use VPL, you should still go through these steps. VPL runs its own DSS Node using programs called VPLHost.exe or VPLHost32.exe. So if you do not first check that DssHost works you might be unable to get VPL to work either.

Steps to Start a DSS Node

Once you have installed RDS, follow the steps below.

1. From the RDS Start Menu, select Run DSS Node.
This should display a DSS Command Prompt window (a black and white text window) as well as a web browser window. There should be no error messages in the Command Prompt window.
(a) If this works, then DSS works on your computer and you are ready to go to the next section.
(b) If this does not work, you will most likely see the window flash up quickly and disappear. You need to diagnose the issue further.

2. The Run DSS Node shortcut contains a command line similar to:

"C:\Users\xxxx\Microsoft Robotics Dev Studio 4\bin\DssHost32.exe" /p:50000 /t:50001 /m:"samples\config\UriLauncher.manifest.xml"

This command uses port 50000 for HTTP (XML) communication and port 50001 for direct TCP (binary) communication. On some computers one or both of these ports are already in use by other services. Notice that this command line uses DssHost32 so that it will run on both 32-bit and 64-bit Windows.

You can manually start a DSS node to verify that it works. Open a DSS Command Prompt window from the RDS Start Menu. When the window appears, enter the following command to start a DSS Node manually:

dsshost32 /p:50000 /t:50001

If you make a mistake in the command-line parameters, DssHost32 will display a message showing the command syntax. (For more information see DSS Host Tool).

If you omit the parameters altogether, you will see an error message:

*** Initialization failure: A valid transport port was not specified

NOTE: You can edit the DssHost32.exe.config file (or DssHost.exe.config) in the bin folder to set the default port numbers so that you do not need to type them on the command-line. However, these instructions assume that you have not done this.

DssHost32 requires that you specify at least the /p qualifier with a port number so that it can communicate with services and you can use a web browser to connect to the DSS node. The /t qualifier is optional, but it is recommended that you include it because it results in more efficient communications. There is no particular significance in the numbers 50000 and 50001, but these are used consistently in the documentation and the samples.

3. Assuming that you entered the command correctly, it might still fail. Under the Windows 7 operating system, you might see a User Account Control (UAC) dialog and you must click on Continue. You might also be prompted by the Windows Firewall to allow the program to set up a TCP/IP port. You must select Unblock. If you accidentally block DssHost, you can go to Control Panel and Windows Firewall to change the settings.

*** Initialization failure: Could not create TCP Listener.
 The two most common causes for this are:
 1) You already have another program listening on the specified port
 2) You dont have permissions to listen to TCP requests.
 Exception message: Only one usage of each socket
    address (protocol/network address/port) is normally permitted

(This error message can also appear if you already have DssHost or VPL running on your computer. In this case, shutdown the other program and try again).

It is possible that the port number(s) are already in use by other background programs that run on your computer. To find out if this is the case, enter the following command:

netstat -a -p tcp

Look carefully through the list of port numbers currently in use. Look in the Local Address column and see if any of the addresses end in ":50000" or ":50001". Try to find some other numbers that are not in use. For example, 40000 and 40001 work for many people, as do 51000 and 51001.

Now try again with these new port numbers.
(a) If you succeed, then continue to the next section.
(b) If not, there is still another possibility in the next step.

4. On Windows 7 you might see an error message indicating that you do not have permission to use the port(s):

*** Initialization failure: Could not start HTTP Listener.
 The two most common causes for this are:
 1) You already have another program listening on the
    specified port
 2) You dont have permissions to listen to http requests.
    Use the httpreserve command line utility to run using a non-administrator
    account.
 Exception message: Access is denied

Notice that the last line of this message says "Access is denied". This is likely to happen if you are not an Administrator (and you started the DSS Command Prompt window as an Administrator). You will have to get an Administrator to reserve the appropriate ports for you. This can be done using the HTTP Namespace Reservation tool. This section does not explain how to use HttpReserve in detail, but the following example should help. Also see DSS Node Security Model for more information.

HttpReserve /p:50000 /u:yourdomain\yourusername

Once the ports are reserved for you, DssHost should run without further problems. (The reservations are permanent, unless removed, so you do not have to do them every time you want to use RDS). Continue on to the next section.

Using a Web Browser to View the DSS Node

DSS has been designed so that you can use a web browser to examine the services running in a DSS Node. The last stage of setup is to verify that you can browse to a DSS node on your computer.

1. Assuming that you started the node using port 50000, then you should start up your web browser and enter the following URL in the address bar:

http://localhost:50000

If you started the DSS Node successfully from the Start Menu, then a web browser should already be displayed.

You should see a web page similar to the one below.

(a) If you see a page similar to the one above, congratulations you have RDS working. Spend some time investigating the various menu options on the left-hand side of the page.
(b) If you do not see this page, then continue troubleshooting.

2. If you are not using Internet Explorer, you might be prompted for your login credentials. Even if this happens with Internet Explorer, the procedure is the same.

If you know your login username and password, then you can enter those details and you should see the page. If you use a computer where you do not have to log in, you can find out the your username by typing the set command at a command prompt. This will display a list of environment variables and you should look for two of them:

USERDOMAIN=xxx
USERNAME=xxx

Enter the username in the format domain\user and then the password that you normally use to log into the computer, or leave it blank if you do not use a password. If your computer is not in a domain, you should use the name of the computer instead of a domain name.

(a) If this works, you are finished. You can change the settings for the future by selecting Security Manager from the menu at the left-hand side of the page.
(b) If you still cannot log in, then you might have to configure the security settings manually.

3. You can change the security settings for DSS through an XML configuration file called SecuritySettings.xml which should be placed in the store folder. DSS Node Configuration explains how to configure your system to allow access.

WARNING: The following instructions disable the DSS security on your computer.

Use Notepad (or another text editor, but not a word processor like Word) to create a text file containing the following XML code:

<?xml version="1.0"?>
<SecuritySettings
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://schemas.microsoft.com/robotics/2008/02/security.html">
    <AuthenticationRequired>false</AuthenticationRequired>
    <OnlySignedAssemblies>false</OnlySignedAssemblies>
    <Users />
</SecuritySettings>

Save this as store\SecuritySettings.xml and then start the DSS Node again. This time you should be able to connect using a web browser. Once you have a connection working in the browser, you can use the Security Manager menu to view and change the settings, which is easier and less error-prone than editing an XML file.

In addition, with RDS 4 it is necessary to enable remote access from other computers on the network. This requires Administrator access. Please see the DSS Node Security Model for more information.

See also the Getting Started with RDS document in the Documentation folder under your RDS installation.