Robotics Tutorial 1 (VB.NET) - Accessing a Service

  • Article

Writing an application using RDS is a simple matter of orchestrating input and output between a set of services. Services represent the interface to software or hardware and allow you to communicate between processes that perform specific functions.

This tutorial teaches you how to use a basic service that reads the output of a contact sensor (referred in this tutorial to as a bumper) and displays a message in the Console window.

Figure 1

Figure 1 - Simple bumper service

The service that you create in this tutorial "listens" for the bumper to be pressed and then displays the information on the console. This tutorial describes how to connect to the bumper sensor and how to register to receive notification messages. While this tutorial focuses on obtaining information from a bumper, the service created in this tutorial can be adapted for other sensor devices.

This tutorial is provided in the Visual Basic .NET language. You can find the project files for this tutorial at the following location under the Microsoft Robotics Developer Studio installation folder:

 Samples\RoboticsTutorials\Tutorial1\VB.Net

This tutorial teaches you how to:

  • Add References.
  • Start the DSS Environment and Services.
  • Subscribe to the Bumper Service.
  • Create the Bumper Handler.

See Also:

  • Getting Started
  • Try It Out

Prerequisites

Hardware

You need a robot with microcontroller and a contact sensor. Contact sensors are typically simple mechanical switches that send a signal when physical contact is made. The sensor can also be distance detection devices (like sonar or infrared sensors) that provide a simple binary signal when a particular threshold is detected. Connect the sensor to your robot's microcontroller following the normal conventions for the hardware you are using.

To determine if support is included in RDS for your robot and to setup your hardware, see Setting Up Your Hardware. You may be able to apply this tutorial for other robots that provide similar services (or create your own services by performing the Service Tutorials included in RDS). Setting up Your Hardware may also provide you with any recommended guidelines for setting up your PC to communicate with your robot.

Software

This tutorial is designed for use with Microsoft Visual Basic.NET. You can use:

  • Microsoft Visual Basic Express Edition.
  • Microsoft Visual Studio Standard, Professional, or Team Edition.

You will also need Microsoft Internet Explorer or another conventional web browser.

This tutorial is not designed to work with Microsoft Visual Basic 6.0 or earlier.

Getting Started

Start the VB.NET editor, select New Project from the File Menu and use the Console Application template to create a new VB Console Application project. (You can also adapt this tutorial to other VB projects.) This creates a project that includes a module with a Sub Main subroutine for you.

In general, to use a service you have to:

  1. Add a project reference to the proxy DLL of the service with which you wish to communicate.
  2. Start the DSS runtime (DSSEnvironment) and the service you wish to use.
  3. Set up a port to facilitate communication with the service. A port is defined by the service we are consuming and provides a strongly typed interface for interacting with the service.

The following steps describe this process.

Step 1: Add References

To access the services for robot, add the following references to your project. Choose the Project menu, and then Properties. Click on the References tab and then click on the Reference Paths button. If the RDS bin directory is not present, then click on the ... button and browse to the bin folder then click on Add Folder. Back in the main dialog click on the Add button. In the .NET tab, select and add the following DLLs to your project:

      Microsoft.Ccr.Core.dll
      Microsoft.Dss.Base.dll
      Microsoft.Dss.Environment.dll
      Microsoft.Dss.Runtime.dll
      Microsoft.Dss.Runtime.Proxy.dll

These DLLs are in the Global Assembly Cache (GAC), not the bin folder. You also need to add the reference for the proxy dll for the generic drive types which is bin\RoboticsCommon.proxy.dll, and this is in the bin folder. However, now that you have set a reference path it should show up on the .NET tab in the Add Reference dialog.

At the beginning of your module (the declarations section) use the Imports statement to access these references in your code:

 Imports Microsoft.Ccr.Core
Imports Microsoft.Dss.Core
Imports Microsoft.Dss.Hosting
Imports Microsoft.Dss.ServiceModel.Dssp

Step 2: Start the DSS Environment and Services

Use the Initialize method to start the DSS runtime (DssEnvironment). The Initialize method for DssEnvironment takes the port numbers for communicating with the service. These can be any valid port number, but it is generally best to use numbers above 32000 to avoid conflicts with your system's use of the Internet or other functions. You must also supply the location of a manifest file that will have the configuration information of the services that you want to start. To find the manifests for hardware supported for this tutorial, check the Samples\Config\ directory in your Robotics Developer Studio installation directory and look for the manifests which end with .MotorTouchSensor.manifest.xml and then find the one which corresponds with your supported robot.

In the code snippet that follows you can see that the manifest for the LEGO NXT has been specified.

 ' Determine path of manifest we want to start
Dim manifestLocation As String = LayoutPaths.RootDir + LayoutPaths.SampleDir + "config\LEGO.NXT.MotorTouchSensor.manifest.xml"

' Start the DSS node on specified ports and the needed services using a manifest
DssEnvironment.Initialize(50000, 50001, manifestLocation)

Every service has a Contract Identifier in the form of a Universal Resource Identifier (URI) that uniquely identifies it. So when you start (create) the service you are passed its URI, which can be specified in the manifest. You query the Directory service for the generic instance of the bumper service and specify the DirectoryQuerySuccess method to be called when the information for bumper service is retrieved. In case of failure, DirectoryQueryFailure will be called.

 ' Start looking for the generic contact sensor service
Arbiter.Activate(DssEnvironment.TaskQueue, _
    Arbiter.Choice(DssEnvironment.DirectoryQuery(bumper.Contract.Identifier), _
        AddressOf DirectoryQuerySuccess, AddressOf DirectoryQueryFailure))

Now add a little code to enable you to exit this application.

 ' Wait for user input
Console.WriteLine("Wait a few seconds for bumpers or press 'Enter' anytime to exit")
Console.ReadLine()

' Shutdown DSS node
DssEnvironment.Shutdown()

Define the DirectoryQueryFailure handler as below:

 ' Handler for directory query failure
Private Sub DirectoryQueryFailure(ByVal failure As W3C.Soap.Fault)

    DssEnvironment.LogError("Could not find service")

End Sub

Define the DirectoryQuerySuccess handler as below:

 ' Handler for directory query success
Private Sub DirectoryQuerySuccess(ByVal success As ServiceInfoType)

    Try
        ' You will add the code for handling directory query here...
    Catch
        DssEnvironment.LogError("Could not subscribe to bumper.")
    End Try

End Sub

Next, in the DirectoryQuerySuccess handler, inside Try/Catch, create a notification port by creating an instance of ContactSensorArrayOperations which will be used to receive events or notifications from the bumper service, via a forwarder. A forwarder creates the port representing a service so that you can receive or send messages to that service.

 ' Create URI from service instance string
Dim addr As System.Uri = New System.Uri(success.Service)

' Create a forwarder for operation ports for needed services
Dim _bumperPort As bumper.ContactSensorArrayOperations = _
    DssEnvironment.ServiceForwarder(Of bumper.ContactSensorArrayOperations)(addr)

Create the port using the URI you received in the success response, ServiceInfoType.

Step 3: Subscribe to the Bumper Service

The bumper service generates notification messages (events) when the bumper is pressed. To receive those messages add the following lines also into the DirectoryQuerySuccess subroutine to subscribe to the port you just created.

 ' Create bumper notification port
Dim bumperNotificationPort As bumper.ContactSensorArrayOperations = _
    New bumper.ContactSensorArrayOperations()

' Subscribe to bumpers
_bumperPort.Subscribe(bumperNotificationPort)

Activate a receive arbiter. Activate is a generic function registering relationships between ports and arbiters. An arbiter facilitates the communication of the message from the service through its port.

 ' Activate bumper notification port so that we receive notifications
Arbiter.Activate(DssEnvironment.TaskQueue, _
    Arbiter.Receive(Of bumper.Update)(True, bumperNotificationPort, AddressOf bumperUpdate) _
)

The Receive method calls the bumper handler that you will create in the next step.

Step 4: Create the Bumper Handler

Now write a bumper handler so that you will receive the notification and your Bumper Handler will display a message box when the bumper is pressed.

To do this, create a subroutine that will process the notification.

 ' Handler for bumper replace
Private Sub bumperUpdate(ByVal notification As bumper.Update)
    If notification.Body.Pressed Then Console.WriteLine("Ouch - the bumper was pressed.")
End Sub

Try It Out

Before you compile and run your application, add an Application Configuration file to your project. (Choose the Project menu, then Add New Item, and then choose Application Configuration File, and click OK). When the file is added, replace the default contents with the following:

 <?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <probing privatePath="bin;services"/>
    </assemblyBinding>
  </runtime>
</configuration>

Now save your project.

Compile your application but do not attempt to run it directly pressing F5. Instead, build your solution by choosing the Build menu, click Build Solution. Set the destination of your build to the file to the RDS bin directory.

Run your program by running your compiled executable from the bin\ directory.

Press the bumper to see the notification message on the console screen.

Figure 2

Figure 2 - Console output when the bumper is pressed

You will find this completed tutorial in the samples\RoboticsTutorials\Tutorial1\VB.Net subdirectory.

Summary

In this tutorial, you learned how to:

  • Add References.
  • Start the DSS Environment and Services.
  • Subscribe to the Bumper Service.
  • Create the Bumper Handler.
See Also 

DSS Hosting Tutorials: Hosting Tutorials Overview

 

 

© 2009 Microsoft Corporation. All Rights Reserved.