Robotics Tutorial 1 (C#) - Accessing a Service

Artigo
03/01/2012

Glossary Item Box

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:

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.

If you do not have an appropriate robot, you can use the RDS Simulator instead. Instructions on how to use the simulated LEGO NXT Tribot are included below.

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.
The core RDS DLLs are installed into the Global Assembly Cache (GAC), and you can find them in the .NET tab. However, RoboticsCommon is not in the GAC so you must click on the Browse tab, then browse to the bin folder to find the DLL. The screenshot below shows the Add Reference dialog. Choose RoboticsCommon.Proxy.dll.

Figure 2 - Adding a Reference to the Robotics Common 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;

You also need to add a using statement so that you can easily use LogGroups.Console later in the code. The statement should look like:

using Microsoft.Dss.Core;

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 or the simulator. The sample manifest in this case will be RoboticsTutorial1.manifest.xml. For example, for the LEGO NXT the command line arguments are:

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

If you want to use the simulated LEGO NXT, then you should use the following:

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

Notice that the Simple Dashboard is included. This is necessary because you will need to drive the robot over to a wall and bump into the wall to trigger the touch sensor.

IMPORTANT NOTE: If you are using 64-bit Windows, you must use DssHost32.exe and not DssHost.exe whenever you want to run a simulation. Check the setting in the Start external program box on the Debug tab of the Project properties.

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

NOTE: If you created a new service, there will be a Warning error when you compile. The message is generated by DssProxy and will be similar to the following:
The contract identifier contains the string 'tempuri.org'. You should consider changing it to a more specific value.
To correct this, change the Contract Identifier in the MyTutorial1Types.cs file to use a different URL. The URL does not need to refer to an actual web site - you can make one up. URLs are used in Contract Identifiers simply to make them unique and because they are human-readable.

If you are using a real robot, press the bumper (touch sensor) on your robot. This will cause a log message to be generated.

Alternatively, if you are using the Simulator, you will have to drive the robot over to a wall and then carefully drive into the wall to trigger the touch sensor. Use the Simple Dashboard to do this. The screenshot below shows the simulated LEGO NXT Tribot approaching a wall.

Figure 3 - Simulated LEGO NXT Tribot Approaching a Wall

NOTE: Do not drive too fast because it is easy to tip the robot over if you hit the wall too hard.

To see the log message, you need to do the following:

Start a web browser and browse to https://localhost:50000
Click on Debug and Trace Messages in the menu at the left
Check the q1:Info checkbox. A list of messages is shown at the bottom of the window.
Click on the small arrow beside the "Ouch" message and you should see the full details as shown below.

Figure 4 - Log Message when the bumper is pressed

Each time the bumper is pressed, a new message is logged. You will have to refresh the browser window to see the new messages.

You will find this completed tutorial in the samples\RoboticsTutorials\Tutorial1\CSharp\ subdirectory. As noted above, you will need to modify the Project properties if you want to use the simulator instead of a real robot.

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

Partilhar via

Robotics Tutorial 1 (C#) - Accessing a Service

Robotics Tutorial 1 (C#) - Accessing a Service

This tutorial teaches you how to:

See Also:

Prerequisites

Hardware

Software

Getting Started

To Create a New Service

Step 1: Add References

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

Step 2: Create a Partner Relationship

Step 3: Service Startup Initialization

Step 4: Write the Subscription

Step 5: Create the Bumper Handler

Try It Out

Summary

Recursos adicionais