Live Distributed Objects

Installation and Basic Configuration

Prerequisites
Hardware Requirements
Software Requirements
Development Environment
Accessing the Live Objects Website
General Information
Accessing the SSL-secured Portion of the Website
Registration
Downloading and Installing the Software
Download and the First Installation Using a Standalone Installer



Prerequisites

Hardware Requirements

In terms of hardware requirements, the most important limitation is that imposed by the XNA framework. If you machine does not support DirectX 9.0c and Shader Model 1.1, you will not be able to execute graphical components that rely on those features. You may or may not be able to install the system and use other components (we have not tested our system on legacy platforms). For more detail on the hardware requirements, refer to the information on the Microsoft's DirectX and XNA web pages.

Note: The above requirement may prevent you from being able to run the system in a virtual machine under VMWare, Microsoft Virtual PC, or Microsoft Virtual Server. We don't keep track of the current status of the problem and have not tested our system on these platforms, and the last time we checked, the hardware still lacked adequate support. If you do manage to run the graphical components or even the minimal subset of the platform on a virtual machine, please do let us know.


Software Requirements

Currently, our system is only supported on Windows XP/2003/Vista/2008. The system will work on 32-bit and 64-bit versions of the OS (although in the latter case it will do so using WOW64; currently, Microsoft's XNA libraries are not supported for true 64-bit applications). True 64-bit and Linux versions of the runtime with limited functionality will be available in the near future.

In order to simply run the platform (but not develop components for it), you will need to install the following minimum runtime components, in the order in which they are listed below (note you may also need to install the latest service packs).
  1. Microsoft .NET Framework 3.5 Service Pack 1
  2. Microsoft Visual C++ 2008 SP1 Redistributable Package (x86)
  3. DirectX End-User Runtimes (February 2010)
  4. Microsoft XNA Framework Redistributable 3.1

Development Environment

In order to develop components for the platform, you should equip yourself with a recent version of Visual Studio and the relevant SDKs (Windows, DirectX). We recommend setting up the following environment.
  1. Microsoft Visual Studio 2008 Express Edition (or any higher edition; we recommend Professional since it supports multithreaded debugging)
  2. Microsoft Visual Studio 2008 Service Pack 1
  3. Microsoft Windows SDK for Windows Server 2008 and .NET Framework 3.5
  4. Microsoft DirectX SDK March 2009
  5. Microsoft XNA Game Studio 3.0
  6. Microsoft Visual Studio 2008 SDK
Components that are distributed as ISO can be installed by mounting ISO as a virtual drive, for example using (freeware) SlySoft's Virtual CloneDrive or the popular Daemon Tools.

Your Visual Studio 2008 SP1 install will also need the Visual Studio Team System 2008 Service Pack 1 Forward Compatibility Update for Team Foundation Server 2010 to communicate with the Codeplex servers.

Once you have installed this software, you can proceed.
  1. Open Visual Studio and connect to the appropriate Codeplex TFS server (see Source Code tab)
  2. Create a new workspace for the Live Objects source (this path CANNOT contain spaces)
  3. Right click on the liveobjects solution in the Source Control Explorer and select 'Get Latest Version'

Now its time to setup some external paths:
  1. Open the Visual Studio solution 'BaseClasses.sln' located at: 'C:\Program Files\Microsoft SDKs\Windows\v6.1\Samples\Multimedia\DirectShow\BaseClasses'. Note that your version of windows may differ from 6.1, but it should not matter as long as the rest of the BaseClasses solution exists.
  2. Ensure the Solution Configuration at the top is set to 'Debug' and not 'Debug_MBCS' or other option.
  3. Now build the solution. Build -> Build Solution.
  4. Assuming there are no errors, you can close out of this solution now.
  5. Go back to the original Visual Stuidio window with the liveobjects project.
  6. Select Tools -> Options...
  7. Projects and Solutions -> VC++ Directories
  8. At the top right, select Include Files from the dropdown.
  9. Add the following entries to the list, AT THE TOP and IN THIS ORDER FROM TOP TO BOTTOM (Note: your version of windows or SDK may be different)
    1. C:\Program Files\Microsoft SDKs\Windows\v6.1\Samples\Multimedia\DirectShow\BaseClasses
    2. C:\Program Files\Microsoft DirectX SDK (August 2008)\Include
    3. C:\Program Files\Microsoft SDKs\Windows\v6.1\Include
  10. Now select Library Files from the dropdown and add the following entries to the list, AT THE TOP and IN THIS ORDER FROM TOP TO BOTTOM. (Note: your version of windows or SDK may be different)
    1. C:\Program Files\Microsoft SDKs\Windows\v6.1\Samples\Multimedia\DirectShow\BaseClasses\Debug
    2. C:\Program Files\Microsoft SDKs\Windows\v6.1\Lib
    3. C:\Program Files\Microsoft DirectX SDK (August 2008)\Lib\x86
  11. You are done with this. Click 'Ok' and return to the Source Control Explorer.

The final task for build configuration is to install Cygwin (under the default C:\Cygwin) with the program "patch.exe" explicitly selected. This allows the liveobjects_7 project to build, as it depends on patching (with patch.exe) some .NET include files.

You should now be able to build the liveobjects solution under the Debug Configuration with Platform set as Win32. Be sure that all these paths are set up for this configuration and platform.


Although not necessary, the following are also extremely useful for this type of development:
  1. Debugging Tools for Windows
  2. (set the system environment variable "_NT_SYMBOL_PATH" to value "SRV*c:\symbols*http://msdl.microsoft.com/download/symbols")
  3. SysInternals Suite (in particular the extremely useful "Process Explorer")
  4. Some scripting tools, ideally PowerShell and IronPython because they they natively support .NET
  5. Some network monitoring software, for example Ethereal
For some advanced configuration, you may also need to locate on your machine or download various additional administrative tools, such as "makecert.exe" or "httpcfg.exe".

For comfortable development, you will sometimes need to control the local firewall settings, and be able to run as a local "Administrator" on the machine on which you are developing your application. On Windows Vista and Windows 2008, you may need to launch Visual Studio and Command Prompt in the "elevated" mode.
Debugging a Custom Live Objects Component
If you are working on a liveobjects component in your own, local solution, you can do the following to utilize Visual Studio debugging:

Right click on the c# project in the solution explorer and select "Properties". Click on the "Debug" tab on the left hand side of the window that pops up. Under the "Start Action" section choose "start external program" and enter the path to the liveobjects.exe executable. If you installed liveobjects normally, the path will probably be something like "C:\liveobjects\bin\liveobjects.exe". Then, in the "Start Options" section, under "command line arguments" enter the path to the liveobject file that uses your code. Now you should be able to click "start debugging" and the Visual Studio debugger will start running the liveobject, stopping and any breakpoints specified.

One thing to note is that if you are getting different behaviors when running code in the debugger and executing it outside of visual studio, make sure the libraries being generated are being properly updated in the correct places. Visual Studio does not always update DLLs after a build. If this is happening, make sure that liveobjects.exe is not running and execute a "rebuild all".



Accessing the Live Objects Website

Before you read the tutorial, you may watch this short video that illustrates the sequence of actions we will walk you through.



General Information

The distribution, documentation, and all related content resides at http://liveobjects.cs.cornell.edu. Some of the content is only available through a secure SSL connection, and some is only available to registered users. Anyone can register for free. We require registration because we would like to have a rough idea of who is using our system. We will not collect any personal information without explicitly requesting your permission to do so, and we will not share the registration data with anyone.

Accessing SSL-secured Portion of the Website

To access the secured portion of the website, you need to have a browser that supports 128-bit encryption, and you should install our server certificate in your trusted certificate storage, in the "Trusted Root Certification Authorities" folder and optionally also in the "Trusted People" folder. If the browser does not prompt you to do install the certificate automatically, you should follow the process outlined below.

Note: For the purpose of browsing the content on this server, it is enough to install the certificate in the folders associated with the "Current User". If your browser automatically prompts you to install the certificate, this is where the certificate will go. However, if you plan to use our optional update mechanism to automatically keep our machine in sync with our update server, you should place the certificate in the folders associated with the "Local Machine", so that it can be used also by the update service. The process outlined here achieves the latter.
  1. Download the certificate from http://liveobjects.cs.cornell.edu/getcertificate.aspx, or by clicking the "certificate" button on the main page.
  2. Open the Microsoft Management Console by typing "mmc" either in the input field under the "Run..." option in "Start Menu", or in a new console window launched by "Command Prompt" from the "Accessories" menu.
  3. Select "File", followed by "Add/Remove Snap-In", and add the "Certificates" snap-in to the console. You will need to edit the certificates stored on the local machine, so choose the "Computer Account" in the following dialog.
  4. In the tree view, navigate to "Console Root", then "Certificates (Local Computer)", then "Trusted Root Certification Authorities", right-click on the node and choose the "Import..." command from the "All Tasks" menu. Navigate to the ".cer" file downloaded from the unsecure portion of the liveobjects website and import the certificate.
  5. Optionally, copy the certificate to the "Trusted People" folder by using copy and paste commands from the context menu.
The installed certificate should appears in the management console window as follows:
screenshot_001.gif

Registration

To register, simply click "register" navigate on the main page, or go directly to the registration form at https://liveobjects.cs.cornell.edu/registration.aspx. After you provide the credentials, we will send you an email with an activation code, which you need to type into the form at the activation page at https://liveobjects.cs.cornell.edu/activation.aspx to activate the account and gain access to the secured area at https://liveobjects.cs.cornell.edu/s/, from which you will be able to download the system and eventually also control various personal settings, such as notification or access to other services. Your email address will serve as the account name. Your credentials are stored in the cookies.

Downloading and Installing the Software

Download and the First Installation Using a Standalone Installer

Before you read the tutorial, you may watch this short video that illustrates the sequence of actions we will walk you through.




To perform the initial installation, you need to download a standalone "liveobjects.msi" file containing the installer from the Downloads tab on Codeplex. After downloading, execute the file from an account with Administrative permissions (the installation involves registering two system services and writing a handful of registry entries). As long as you have satisfied all prerequisites, the installation should not go smoothly. If any errors occur, double-check whether you have the necessary runtime components, and whether older, beta versions of these components are still on the system, thus causing problems with loading libraries and resolving dependencies. If the installation fails for unknown reason, please do contact us.

After installation, your machine is modified in the following manner:
  1. All binaries, configuration, content, and other files are gathered in one place, by default at "C:\liveobjects".
  2. A system service is installed that run under the SYSTEM account, by default are stopped, and is configured to start manually:
    1. "Live Distributed Objects". This service is mapped to file "\bin\liveobjects.exe" relative to the root installation folder, and it is simply a special instance of the live objects runtime that runs with the SYSTEM credentials and hosts service components shared by all processes on the current machine. The components to run in the system scope are collected in the "\services" folder, and include a simple local multicast server that you can use for running a demo or for debugging purposes.
  3. We register a number of COM components and modify the file associations, so that files with the ".liveobject" extension are executed by the liveobjects runtime when doubleclicked or launched from the console window.

To quickly test the system, start the "Live Distributed Objects" service, either by using the "Services" tool in "Administrative Tools", or by executing "net start LiveDistributedObjects" in the console window. Check that the service process has not terminated unexpectedly, and that it has a TCP port open at the default address 60000. You may do the latter by typing in "netstat -a -b -n" in the console window. In the output of the command, you should be looking for an entry that looks more or less like the following:
TCP 172.23.16.35:60000 0.0.0.0:0 LISTENING
[liveobjects.exe]
If you installed the SysInternals suite, you can achieve the same more easily by launching Process Explorer, double-clicking on the "liveobjects.exe" process, and selecting the "TCP/IP" tab in the information dialog that pops up.

If the service is running, you should be able to launch some of the pre-configured components we provided to get you started. Double-click on the shared_text_1.liveobject file in the "\examples" folder, or type "C:\liveobjects\bin\liveobjects.exe C:\liveobjects\examples\shared_text_1.liveobject" from the console window (modify the path accordingly). Do it at least twice. You should see two (or more) windows popping up. Any text typed in one of the windows should be automatically propagated to the others, in either direction. It should look more or less as follows.

screenshot_002.gif


You can also test whether XNA framework is supported on your machine by executing file "window_x.liveobject", again either by double-click, or by passing it as an argument to "liveobjects.exe". The component you are starting is a generic container for rendering live objects with 3-dimensional interface. If you see a window with a black background (picture on the left), the graphics components are working. In all likelihood, you will also hear a distinct noise of the fan on your graphics adapter spinning up. Now, try to drag file "shared_folder_1.liveobject" (don't confuse it with "shared_folder_1_view.liveobject") into the black window. The file you are dragging is a shared folder, and by connecting it to the 3-dimensional window, you instruct the runtime to start rendering all objects that reside in the shared folder and have a 3-dimensional interface. By default, the shared folder is empty, hence you should only see a patch of blue sky. The caption should also confirm that you are connected to the shared folder (as in a picture on the right).

screenshot_003.gif

When you are done testing, you can shutdown the service by executing "net stop LiveDistributedObjects". Because the multicast component we have installed by default for debugging purposes does not require secure connections, it is best to leave the service as starting manually and shut it down when not needed. Later in the tutorial, we will discuss the ways to configure secure communication.

Last edited Oct 25, 2010 at 10:39 PM by mikeryan, version 46

Comments

No comments yet.