VPL Lab 1 - Joystick a Robot in Simulation and in Hardware

Glossary Item Box

VPL Hands On Labs: VPL Lab 2 - Advanced Motion

VPL User Guide: Getting Started

Microsoft Robotics Developer Studio

Send feedback on this topic

VPL Lab 1 - Joystick a Robot in Simulation and in Hardware

For your first task, you will write a simple program in Microsoft Visual Programming Language (VPL) to control a robot using a joystick.

This lab is meant to be your first experience with Robotics Developer Studio (RDS). It shows you how to use Microsoft Visual Programming Language (VPL) to connect predefined generic services, associate them with a particular robot, and use the robot in a simulated environment. You will also learn how you can substitute your real robot hardware for the simulated robot without having to change your program.

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

Samples\VplHandsOnLabs\Lab1

Contents

• Step 1: Add a Desktop Joystick Service
• Step 2: Add a Generic Differential Drive
• Step 3: Connect the Components
• Step 4: Try It Out

See Also:

• A Quick Introduction to VPL

Prerequisites

Hardware

No special hardware is required to complete the simulation portion of this lab. To complete the hardware portion a robot with a differential drive is required. (A Differential Drive is a system where the robot's wheels can be driven independently. See Getting Started below.) Note that instructions for setting up your robot are not included in this Tutorial. Please refer to "Setting Up Your Hardware" in the RDS documentation.

If you have a real joystick or game controller that works with DirectInput (such as a wired Xbox controller), then it can be used in this lab. Where changes are required to use a physical joystick they will be indicated in the lab.

Software

This lab is designed for use with Microsoft Visual Programming Language (VPL). You will also need Microsoft Internet Explorer or another conventional web browser.

Getting Started

Many robots use what is called a "Differential Drive" which has two wheels that can be driven independently. Although most Differential Drives have two driven wheels, there is often a third passive wheel, called a castor or jockey wheel, which is just for balance. The reason this configuration is popular is that it allows the robot to rotate on the spot. It can therefore drive in any direction after making a tight turn that takes a space no larger than the robot.

RDS defines a generic contract for a Differential Drive that specifies the programming interface for controlling a drive regardless of the type of robot that you are using (which is why it is called generic).

In this lab you will only use the SetDrivePower operation which simply sets the power to each of the drive's wheels. However, as you will see, this gives you complete control over where the robot goes.

To get started, open the Visual Programming Language application.

Step 1: Add a Desktop Joystick Service

Add the service

From the Services toolbox at the bottom-left of the VPL window, drag the Desktop Joystick service onto your workspace, which is called a diagram. An activity block will appear in the diagram to represent the service. This is shown in Figure 1.

Figure 1 - Desktop Joystick Activity

The Desktop Joystick service displays a window that exposes the basic capabilities of a joystick which can be driven with a mouse or keyboard. As with most activities, it has an input connection pin (or port) on the left (a red arrow pointing into the block), an output connection pin on the right (a red arrow pointing out of the block) and a notification pin also on the right (a red circle). You send requests to the service via the input pin. These are also called actions or operations. The result or response is sent on the output pin. Notifications can be sent at any time by a service - you do not have to send a request. These are important for a service like the Desktop Joystick because it sends messages constantly when you are moving the joystick. Your VPL program can process these messages and use them to control a robot.

Try it out

From the menu, select Run -> Start, or press the F5 key. The first time that you run a new diagram you will be prompted to save it. If you opened the diagram what was installed as part of RDS (rather than creating a new one) it is a good idea to save it to a different location using File -> Save As. This way you will keep the original diagram intact so that you can refer back to it if you accidentally mess up the diagram.

VPL will start a DSS Node and run the diagram. (All services in RDS run under Decentralized Software Services, or DSS for short). When the diagram starts running you will see a window entitled Desktop Joystick. Figure 2 shows what it looks like while it is in use. Spend a little time seeing how this window responds to the mouse and keyboard.

Figure 2 - Desktop Joystick in action

Click on the "trackball" with the left mouse button and hold the button down. As you drag, it will simulate moving a joystick. With the keyboard, the keys W, A, S, and D can also be used. If you play computer games you might be familiar with these keys from first-person shooter games. If not, look carefully at the layout of these keys on the keyboard because they correspond to the four directions: forward; left; back; and right. With a little practise you should be able to control the joystick quite easily.

Step 2: Add a Generic Differential Drive

In the same way as you added the Desktop Joystick service in Step 1, now add a Generic Differential Drive (GDD) service. It is called generic because it supports common operations available on most differential drives, but it is not by default associated with a specific drive system. A generic drive can be associated with a real drive at runtime using a file called a manifest. One of the benefits of RDS is that you can write general programs that will run on a variety of robots simply by changing the manifest.

To associate the generic drive with a specific robot drive system, so that you can interact with the robot's hardware, first click on the Generic Differential Drive block on the main diagram to make sure that it is selected. (The activity block will be highlighted with a blue border). Then, in the Properties toolbox on the bottom-right, under Configuration, select the Use a Manifest entry from the drop-down list. Now, under Manifest, click the Import button. Select the entry for IRobot.Create.Simulation.Manifest.xml. The Properties toolbox should now look like Figure 3.

Figure 3 - Associate the Generic Differential Drive with a specific robot's manifest

The manifest specifies, among other things, which service will be implementing the generic drive when you run the program. By selecting a manifest, the generic drive in the diagram has been associated with a particular robot drive service (in this case a simulated iRobot Create). If you wanted to use a real Create, or some other robot, you would just select a different manifest.

Step 3: Connect the Components

Connect a notification to a request

Robotics Developer Studio supports a Publish-Subscribe model. A service, or in this case your diagram, can subscribe to the notifications that another service publishes. In this example, when the position of the joystick changes the Desktop Joystick service will issue a notification. The diagram can receive that notification by connecting to the notification pin on the Desktop Joystick service, which is the small red circle on the right side of the activity block. The small red arrow on the right is a result output. These outputs are discussed in more detail in the Quick Introduction to VPL at the end of this lab. In this example the output pin is not used.

Connect the notification pin of the Desktop Joystick (the small red circle) to the input pin of the GDD (the small red arrow on the left side) as shown in Figure 4. To do this, click the left mouse button on the notification pin and hold it down, then drag the mouse over the GDD block. You do not have to place the mouse exactly over the input pin. A connection link will follow the mouse as you move the cursor. (Wave the mouse around. It's fun to watch VPL drawing bezier curves.) The GDD block will be highlighted when you have the mouse positioned correctly. Release the mouse button and the connection link will snap into place between the two blocks. Figure 4 shows what the completed connection looks like, but you have not finished yet.

Figure 4 - Connect the Desktop Joystick to the Generic Differential Drive

The Connections dialog box will pop up. This shows the available notifications that the Desktop Joystick service supports in the From column on the left, and the available request types that the GDD service supports in the To column on the right. The purpose of this VPL diagram is to drive a robot using the joystick, so select UpdateAxes from the left column and SetDrivePower in the right column, then click OK.

Figure 5 - Available connections between Desktop Joystick and Generic Differential Drive

Now the Data Connections dialog box pops up. This dialog allows you to specify how the notification produced by the Desktop Joystick is consumed by the GDD service.

Figure 6 - Data Connections dialog box

As shown in Figure 6, you can select which data member from the notification message is sent to the each of the target fields in the request to the GDD service.

Configure the Data Connection

The Desktop Joystick service sends notifications when the joystick axes change (in this case the X and Y values change), as you may have noticed when trying out the diagram earlier. (While the joystick is not moving, notifications are not sent). These values vary between -1000 and 1000.

The GDD service expects LeftWheelPower and RightWheelPower values between -1.0 and 1.0, where these values indicate the amount of power to be fed to the Left and Right wheels respectively. If both are positive then the robot will move forward; if both are negative then the robot will move backwards; if the left and right values are different then the side of the robot with the higher value will move forward move than the side with the lower value, causing the robot to turn in an arc. If you exactly match the power settings, but they have opposite signs, then the robot will rotate on the spot.

You now need to create a data transformation that will convert the X and Y values from the Desktop Joystick into LeftWheelPower and RightWheelPower settings. Select the Edit values directly check box at the bottom of the DataConnections dialog. Then enter the following expressions into the Value boxes for the LeftWheelPower and RightWheelPower targets.

• (-Y + X) / 1000.0
• (-Y - X) / 1000.0

The DataConnections dialog will now look like Figure 7. Take a moment to understand how these expressions convert the X and Y values from the joystick into left and right values for a differential drive system. Notice that there is a scale factor of 1000. You could use more complicated formulas, but these ones work reasonably well.

Figure 7 - Data Connections dialog for SetDrivePower

Once a connection has been established, you can change the details later. If you right-click on the connection link, the pop-up context menu contains options to delete the link or open the Connections or Data Connections dialogs. If you select a link by clicking on it with the left mouse button, the Data Connections are shown in the Properties toolbox and you can change them there. This is similar to the Data Connections dialog. When a link is selected, small boxes appear over the pins at each end. Look carefully because it might not be obvious to you if you are a beginner.

Step 4: Try It Out

Running in simulation

Select Run -> Start from the menu, or press F5. Have fun driving your simulated robot around, immersed in the realism of the simulation engine's physics model. If you click on the Simulation window so it has focus, and you can use the the mouse and also the keys W, A, S, D, Q, and E to change the camera location in the simulated environment.

Figure 8 - Simulated iRobot Create in simulated environment

Note that the Desktop Joystick automatically displays on top of other windows so it appears in Figure 8 over the top of the simulation. It is not part of the simulation window.

Changing the Manifest to Use a Physical Robot

Now change the manifest for the Generic Differential Drive to iRobot.Drive.manifest.xml, assuming you are using an iRobot Create. If you have a different supported robot, just choose its manifest instead. That's all you need to change to run your program on a physical robot! Run your program again. If you are using an iRobot Create, this time a web page should pop up asking you to connect to the robot. (Note that you will need to set up your Bluetooth connection to the robot and "pair" with the robot first. This is not covered here.)

Figure 8 - Connecting to an iRobot Create

The web page allows you to enter some configuration information. You should set the Serial Port to the port you are using to connect to your robot. The Baud Rate shown in the diagram is the correct rate for the iRobot Create. The values on the web page are initialized by the values in the manifest file, so the default Baud Rate displayed is most likely correct. (If you are using a different robot then it might use a different baud rate). The polling interval is set by default to 201 milliseconds. This is how often your robot's sensors will be polled (interrogated). You will need to select the correct connection type, and you should set the robot model as appropriate and select Maintain Status to be Full. You will learn about what this means in a future Tutorial.

Once the settings are correct, make sure your robot is turned on and hit the Connect in the web browser window. You should hear a beep indicating that you have successfully connected to the robot.

Using a Real Joystick

In order to use a physical Joystick with this diagram, drag a Game Controller service from the Services toolbox to the diagram. Then drag from the notification pin (the small red circle) on the right of the Game Controller service to the middle of the wire connecting the Desktop Joystick and Generic Differential Drive services, as in Figure 10.

Figure 10 - Adding a Game Controller service

When you release the end of the new connection onto the middle of the existing connection a Data Connection dialog will pop up. (If you miss the connection when you release the button a menu will pop up that allows you to add an activity instead). On the left side in From, choose UpdateAxes as before, on the right side in To choose MergeConnections. A Merge activity will be added at that point. Now your diagram will work with both the Desktop Joystick and a physical Joystick at the same time. This is possible because both of the services support the same interface (or contract in DSS terminology).

A Quick Introduction to VPL

VPL is based on a dataflow programming model. This makes it particularly suitable for programming robotics applications where distribution and concurrency are inherent.

As you have seen in this lab, a program in VPL consists of blocks, which are generally called Activities. A dataflow consists of a sequence of connected activities. Activity blocks in VPL can represent a number of different things. In this lab you used a Desktop Joystick, which is a pre-compiled service that VPL makes available to you. An activity block can also be an element that controls the flow of data, a function (code that performs a task), a user-created piece of code, etc. You will write your programs in VPL by connecting up activities.

In VPL, connected activities pass data down the connections. Take a look at the following figure.

Example dataflow - Data is passed along the connections

In this figure, the Data activity passes the value 10 along the connection to the Calculate activity. Notice that there is a label at the bottom of the Data block that says int. This indicates that the value is a whole number, i.e. it does not have decimal places. The value passed on a line is usually called value. The Calculate activity receives the value, which is 10, adds 50 to it, and passes the result as the value down the line to the Variable activity. The Variable activity takes the incoming value, and uses it to set the variable (a storage location that is part of the service's state) with the name Total which is indicated in the textbox.

Note that in this diagram the Data activity has no input connection. This means that it will execute immediately when you run the diagram. In other words, it kicks off the process and from then on the messages follow the connections.

You should know by now that activities are connected up to arrows or circles on the activity blocks. These are referred to as connection pins. The pins on the left of a block are for input, and the pins on the right are for output. These pins represent connections to the activity's internal actions/handlers. When you connect to the input pin of an activity you select the action/handler that you want to call. For example, in this lab when you connected to the Generic Differential Drive activity, you selected the action SetDrivePower.

When an activity receives a valid input message, it is activated and processes the message data by runnung the handler associated with the requested action. In the case of a SetDrivePower request, a valid input message consists of a double (which is a number with decimal places) for the Left Drive Power and another one for the Right Drive Power. However, there are some activities that do not need any data in the request and in this case the message is simply for control flow, i.e. to control the flow of the program by causing the activity to run when a message arrives.

You will notice that in VPL many activities, e.g. If blocks and Merge blocks, forward the data they receive as input. If you make your own activity however (you will learn how to do this in later labs), you will see that this is not the default behavior for activities. If you want to forward data, you have to explicitly put it on the output connection.

Activities have two types of output pins. The arrow-shaped pins are for result/response outputs. A response output is given as the result of a particular input (similar to calling a function and getting a result, or sending a message and getting a response). The round pins are for notification outputs. A notification is typically sent in response to some internal state change or event. However, an activity can also send a notification in response to an incoming message.

It is a good idea to lay out your diagrams carefully so that they are easy to read. To line up your activity blocks, you can select several of them. Hold down the mouse button and drag across them to create the selection - a "rubber band" rectangle shows you the selected area and blocks are highlighted as they are added to the selection. Then select one of the alignment options from the Align list in the View menu. You can also flip the connections on an activity so that the input and output are reversed. Select a block, then in the pop-up context menu select "Flip Connections". This is handy sometimes to avoid connections crossing over.

It is important to note that unlike a result output, which will only send an output in response to an input message, a notification output can fire repeatedly. For example, in the code you just wrote, you got a notification from the Desktop Joystick every time that you moved the joystick.

To get started writing code in VPL you should experiment with the activities in the Basic Activities toolbox. You can take a look at the Reference section in the Microsoft Visual Programming Language documentation to read about each of the Basic Activities. In the course of the following labs, you will learn more about these activities, and see how to combine them with your own activities to write complex robotic applications.

Summary

In this lab, you learned how to:

• Step 1: Add a Desktop Joystick Service
• Step 2: Add a Generic Differential Drive
• Step 3: Connect the Components
• Step 4: Try It Out

VPL Hands On Labs: VPL Lab 2 - Advanced Motion

VPL User Guide: Getting Started

© 2012 Microsoft Corporation. All Rights Reserved.