Microsoft Robotics Developer Studio

Robotics Tutorial 1 (C#) - Accessing a Service

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 as a bumper) and displays a message in the Console window.

Figure 1 - Simple bumper service

The service you create in this tutorial "listens" for the bumper to be pressed and then displays the information on the console. This tutorial teaches you 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 C# language. You can find the project files for this tutorial at the following location under the Microsoft Robotics Developer Studio installation folder:

Sample location

 Samples\RoboticsTutorials\Tutorial1\CSharp

This tutorial teaches you how to:

Add References
Create a Partner Relationship
Initialize and Start Your Service
Write the Subscription
Create the Bumper Handler

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 following the Service Tutorials Overview included in Robotics Developer Studio). 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 C#. You can use:

Microsoft Visual C# Express Edition.
Microsoft Visual Studio Standard, Professional, or Team Edition.

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

Getting Started

To get started with this tutorial, create a service. The DssNewService tool creates a basic service that supports the Decentralized Software Services Protocol (DSSP) actions.

To Create a New Service

Open a DSS Command Prompt:
- From the Start menu, select All Programs, Microsoft Robotics Developer Studio, then DSS Command Prompt.
Navigate to the Samples directory.
```
cd samples
```
Run the DssNewService tool with the parameter /service:MyTutorial1 which names the new service MyTutorial1 and creates it in a directory called MyTutorial1:
```
dssnewservice /service:MyTutorial1
```
Navigate to the MyTutorial1 directory.
Load the MyTutorial1 solution using your C# editor.

In general, to use a service you must follow this process:

Add a project reference to the proxy DLL of the service with which you wish to communicate.
Add a using directive to make it easy to refer to the service.
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.

Step 1: Add References

When you used the DssNewService tool to create the MyTutorial service, references to several robotics DLL files are added to the service project by default. These DLLs are in the Global Assembly Cache (GAC), and include Microsoft.Ccr.Core, Microsoft.Dss.Base and Microsoft.Dss.Runtime. Consequently they can be added from the .NET tab on the Add Reference dialog if necessary.

This tutorial also requires functionality from the RoboticsCommon library in order to use a contact sensor. A reference to the Robotics Common Library should be made through its proxy DLL, RoboticsCommon.Proxy.dll, which is in the bin folder under the Robotics Developer Studio installation. DssNewService should have added a Reference Path to this folder, which you can check by looking on the Reference tab in the Project Properties.

To Add a Reference to the RoboticsCommon.Proxy.dll File

From Visual Studio, right-click on References in the Solution Explorer and choose Add Reference.
The Add Reference dialog box opens.
In the .NET tab, choose RoboticsCommon.Proxy.

RoboticsCommon defines a generic contract for a Contact Sensor. By using a generic contract, our service does not need to know in advance which hardware will be connected.

At the top of MyTutorial1.cs, add a using directive and alias for the generic ContactSensor contract which is the basis for the bumper service. The following code snippet uses the alias, bumper.

 using bumper = Microsoft.Robotics.Services.ContactSensor.Proxy;

Step 2: Create a Partner Relationship

Now create a partnership between the MyTutorial1 service and the bumper service. Service partners identify other services on which a service depends. To communicate with the bumper service, we set up a port of ContactSensorArrayOperations and identify this as a partner by using the Partner attribute. Add the following code to your service after the line that defines _mainPort:

 [Partner("bumper", Contract = bumper.Contract.Identifier,
    CreationPolicy = PartnerCreationPolicy.UseExisting)]
private bumper.ContactSensorArrayOperations _bumperPort = new bumper.ContactSensorArrayOperations();

Review the project files listed in Solution Explorer. When the MyTutorial1 service was created, a manifest file, MyTutorial1.manifest.xml, was also generated. Manifests specify the service or services that are started when your application runs.

The simplest way to bind the service partner to your hardware is to start an additional manifest which contains the service contract(s) for your hardware. The following lines show you how to modify the command line arguments to include an additional manifest for the LEGO NXT bumper to the debug settings supplied by DssNewService. To find the contracts for hardware supported for this tutorial, check the \Samples\Config\ directory in your RDS installation directory and look for the manifests which end with .MotorTouchSensor.manifest.xml and then find the one which corresponds with your supported robot. Modify your project settings under the Debug tab and change the Command Line Arguments setting to reference the proper manifest for your hardware.

      /p:50000 /t:50001 /m:"samples/MyTutorial1/MyTutorial1.manifest.xml"

becomes:

      /p:50000 /t:50001
      /m:"samples/MyTutorial1/MyTutorial1.manifest.xml"
      /m:"samples/config/LEGO.NXT.MotorTouchSensor.manifest.xml"

If you use the completed tutorial, samples\RoboticsTutorials\Tutorial1\CSharp\RoboticsTutorial1.csproj, be sure to modify your project settings under the Debug tab and change the Command Line Arguments setting to reference the proper manifest for your hardware. However, the sample manifest in this case will be RoboticsTutorial1.manifest.xml.

/p:50000 /t:50001 /m:"samples/config/RoboticsTutorial1.manifest.xml" /m:"samples/config/LEGO.NXT.MotorTouchSensor.manifest.xml"

Step 3: Service Startup Initialization

Every service must declare a Start() method. The Start() method is automatically called after a service is initialized. Modify the Start() method to subscribe to the bumper service and begin listening for contact sensor notifications.

At the end of the Start() method, add a call to the SubscribeToBumpers method to subscribe to the bumper service. We will define SubscribeToBumpers in the next step.

 // Start listening for bumpers.
SubscribeToBumpers();

The call to base.Start() that you see in the Start() is part of the template that was created by the DssNewService tool. This method causes the base service to activate the service handlers for messages sent to the main port. It also publishes the service to the local service directory so that other services can find it. To learn more about the Start() method or the DssNewService tool, refer to the Service tutorials.

Step 4: Write the Subscription

After the Start() method, add the following definition of the SubscribeToBumpers() method.

 /// <summary>
/// Subscribe to the Bumpers service
/// </summary>
void SubscribeToBumpers()
{
    // Create the bumper notification port.
    bumper.ContactSensorArrayOperations bumperNotificationPort = new bumper.ContactSensorArrayOperations();

    // Subscribe to the bumper service, receive notifications on the bumperNotificationPort.
    _bumperPort.Subscribe(bumperNotificationPort);

    // Start listening for updates from the bumper service.
    Activate(
        Arbiter.Receive<bumper.Update>
            (true, bumperNotificationPort, BumperHandler));
}

The first task of the SubscribeToBumpers() method is to create a notification port on which to receive notifications from the bumper service. Create a notification port by creating an instance of ContactSensorArrayOperations.

     bumper.ContactSensorArrayOperations bumperNotificationPort = new bumper.ContactSensorArrayOperations();

Subscribe to the _bumperPort port, and specify that notifications be sent to the bumperNotificationPort.

     _bumperPort.Subscribe(bumperNotificationPort);

Use the Activate() method to set up the handler to receive notifications from the bumper. Activate() is a generic method that registers relationships between ports and arbiters. The Receive arbiter that is used in the following code snippet facilitates the forwarding of notification messages from the bumper to the bumper handler.

     Activate(
        Arbiter.Receive<bumper.Update>
            (true, bumperNotificationPort, BumperHandler));

With these changes, the BumperHandler method is called each time your service receives a bumper notification from the bumper service.

Step 5: Create the Bumper Handler

Add the BumperHandler() method near the end of the MyTutorial1.cs file. When your service is notified that the bumper has been pressed, the BumperHandler() method sends a message to the console screen.

 /// <summary>
/// Handle Bumper Notifications
/// </summary>
/// <param name="notification">Update notification</param>
private void BumperHandler(bumper.Update notification)
{
    if (notification.Body.Pressed)
        LogInfo(LogGroups.Console, "Ouch - the bumper was pressed.");
}

Try It Out

To build and run the MyTutorial1 service, choose the Debug menu and click Start Debugging (or press F5).

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

Figure 2 - Console output when the bumper is pressed

Each time the bumper is pressed, a message appears on the console.

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

Summary

In this tutorial, you learned how to:

Add References
Create a Partner Relationship
Initialize and Start Your Service
Write the Subscription
Create the Bumper Handler