Developing Motion Systems in Measurement Studio for Visual Basic

With the Motion Control Module for Measurement Studio, you can develop motion control applications using your NI 7334 or NI 7344 Series controller and Microsoft Visual Basic. Use the interactive property pages of the NIMotion ActiveX control to quickly and easily configure many types of moves and create sequences of moves for your motion control applications. Because the NIMotion control is an ActiveX control, you can use it in many ActiveX control containers.

This application note describes how to create a sequence of moves with different move types, display the status of your motion moves, and blend these moves into a smooth, continuous operation. You need the following tools to complete the examples in this application note:

• Microsoft Visual Basic 5 or later.

• Motion Control Module for Measurement Studio—if you have not purchased a licensed version of the Motion Control Module, visit ni.com/mstudio and follow the links to download evaluation software.

• National Instruments 733x or 734x series controller and FlexMotion 5.0 or later driver software—to order National Instruments products online, visit ni.com/store.

What Are Moves?

A move consists of the trajectory parameters that describe how a set of axes go from a starting position to a destination. In Measurement Studio, the NIMotionMove object contains all of the characteristics of a move. The NIMotionMove object consists of a move type and all of the properties associated with the move type. With the NIMotion control, you can configure many different types of moves. The type of move you choose determines the properties you must set for that move. For example, you can define the move type as point to point and then set the position, acceleration, deceleration, and maximum velocity for the move. See Table 1 for more information about move types and associated properties.

Table 1.

Move Type	Number of Axes	Description	Properties
Point-to-Point Move	1,2, or 3	Move from a starting position to a target position.	Position, PositionMode, PositionModulus, Velocity, Acceleration, Deceleration, and Scurve
Circular Arc	2	Move using circular interpolation in the xy plane.	Radius, StartAngle, TravelAngle, Velocity, Acceleration, Deceleration, and Scurve
Helical Arc	3	Move that defines a circular arc in the xy plane with synchronized linear travel along the z axis.	Radius, StartAngle, TravelAngle, LinearTravel, Velocity, Acceleration, Deceleration, and Scurve
Spherical Arc	3	Move that defines a circular arc rotated through an angle about the x and y axes.	Radius, StartAngle, TravelAngle, Velocity, PlanePitch, PlaneYaw, Acceleration, Deceleration, and Scurve
Velocity Move	1	Move at a constant velocity.	Velocity, Acceleration, Deceleration, and Scurve
Contour Move	1,2, or 3	Move of arbitrary position data that is splined to create a single move.	ContourData, ContourInterval, ContourMode,TotalPoints, Velocity, Acceleration, Deceleration, and Scurve

What Are Tasks and Sequences?

The NIMotionTask object consists of a collection of one or more axes and a collection of one or more moves. The number of axes you specify determines the types of moves you can use. A sequence contains two or more moves within a task. Depending on the type of task you select, you can create sequences that contain different types of moves.

To illustrate tasks and sequences, imagine an assembly line machine that cuts out a part with specific dimensions. Each finished piece must be the exact same size and shape, and the machine must quickly repeat the operation continuously. With the NIMotion control, you can create a task that contains the precise sequence of moves necessary to cut out the part and configure the task to repeat a specific number of times.

Using Task Types

Motion tasks can be of three types — complete moves, blended moves, and velocity move. Use a complete move if the task contains a single move or a sequence in which the next move in the sequence is sent to the motion controller and starts when the previous move is completed. Use a blended move if the task contains a sequence and you want the motion controller to blend the deceleration portion of the previous move with the acceleration portion of the next move to create the trajectory profile. Use a velocity move to move along a single axis at a constant velocity. During a velocity move, you can change the Velocity, Acceleration, or Deceleration properties and call the Start method to update the move.

Opening a New Project and Loading ActiveX Controls

1. Launch Visual Basic.

2. Open a new Standard EXE project.

3. Right click on the Visual Basic Toolbox and select Components.

4. Select National Instruments Motion Control Module and National Instruments CW UI. You will use the Graph and Button controls from the UI group in a later example.

5. Click OK.

Note: If you do not have Measurement Studio for Visual Basic installed on your machine, the Motion Control Module installs evaluation versions of the Measurement Studio User Interface, 3D Graph, and Analysis ActiveX controls. You can use these evaluation version controls to complete the examples in this application note. To purchase Measurement Studio for Visual Basic, visit ni.com.

Example – Configuring a Task

In this example, you will configure a motion task containing one axis and one move. By default, the NIMotion control contains a task with one move and one axis.

Note: You must initialize your controller on power up before executing any motion operations. If the controller is not initialized, a PowerUpReset error is returned. Initialize your controller in National Instruments Measurement & Automation Explorer (MAX). Launch MAX by clicking the MAX icon on the Tasks property page. Refer to the MAX help for more information about initializing your controller.

1. Place the NIMotion control on the Visual Basic form. Right click the control and select Properties to configure the move type, destination, and velocity of the move.

2. Right click the NIMotion control and select Properties. On the Tasks property page, choose your controller from the pulldown menu.

3. Set Number to an axis number that is valid for your motion controller. If you do not specify a valid axis, the example will not run. Refer to your hardware documentation for more information.

4. Set Type to Complete moves. Accept the Units default value of counts/s.

5. Use the default values of all other properties on the page, as shown in Figure 1.

In this example, you will create a point-to-point move.

Configuring Move Properties

1. On the Moves property page, select Move1, click the Edit button, and rename the move PointToPoint1. You can use this new name to access the move in the property pages or programmatically.

2. On the Trajectory subtab, set Type to Point-to-point, Mode to Relative position, and XAxis pos to 4000 counts. As shown in Figure 2, your move is now configured to move to encoder position 4000.

Tip: As you enter the destination value, the NIMotion preview window interactively changes to reflect the velocity and position of the move.

3. Switch to the Velocity subtab. Set the Velocity property to 1000 counts/s. Accept the default values for acceleration, deceleration, and s-curve.

4. Click OK to close the property pages.

5.Place a Visual Basic CommandButton on the project form. Change Name to cmdStart and Caption to Start.

6. Add Visual Basic code to configure and start the motion move. Double click the Start button and add the following code:

Private Sub cmdStart_Click()
NIMotion1.Configure
NIMotion1.Start
End Sub

7. Place another CommandButton on the project form. Change Name to cmdStop and Caption to Stop.

8. Add Visual Basic code to stop the motion move. Double click the Stop button and add the following code:

Private Sub cmdStop_Click()
NIMotion1.Stop
End Sub

9. Select Run»Start to run your program. Click the Start button to configure and start the move. Stop and end your program when you finish testing.

Example – Using the MoveCompleted and TaskCompleted Events

When a single move is completed, the MoveCompleted event is generated. The MoveCompleted event returns the move and task objects. As a result, you can add code to the MoveCompleted event procedure that prints the name of the completed move on the form. When a motion task is completed, the TaskCompleted event is generated. You also can add code to the TaskCompleted event procedure to notify you when the task is finished.

1. Place a Visual Basic TextBox on the project form. Change Name to txtStatus and delete the text from Text. Place a Visual Basic Label on the form and change Caption to Status.

2. In the code window, select NIMotion1 from the object listbox and MoveCompleted from the procedure listbox to create the MoveCompleted event procedure.

3.Add the following bold code to the MoveCompleted event procedure:

Private Sub NIMotion1_MoveCompleted(ByVal Move As NIMotionControlLib.NIMotionMove, ByVal Task As NIMotionControlLib.NIMotionTask)
txtStatus.Text = Move.Name & " completed."
End Sub

4. Run your program. As shown in Figure 3, "PointToPoint1 completed" is printed in the Status textbox after the move completes. Stop and end your program when you finish testing.

TaskCompleted Event

Use the TaskCompleted event to turn off an LED indicator when the task is complete:

1. Place a CWButton control on the project form. By default, Visual Basic names the control CWButton1. Place a Label on the form and change Caption to Task in Progress.

2. Right click the CWButton control and select Properties to configure the control:

a. On the Style property page, select the 3D Round LED style.

b. Click OK.

3. Add the following bold line of code to the cmdStart_Click event procedure to turn on the LED when the task begins:

Private Sub cmdStart_Click()
NIMotion1.Configure
NIMotion1.Start
CWButton1.Value = True
End Sub

4. Add the TaskCompleted event to your program. In the code window, select NIMotion1 from the object listbox and TaskCompleted from the procedure listbox to create the TaskCompleted event procedure.

5. To turn off the LED when the task completes, add the following bold line of code to the TaskCompleted event procedure:

Private Sub NIMotion1_TaskCompleted(ByVal Task As NIMotionControlLib.NIMotionTask)
CWButton1.Value = False
End Sub

6. Run your program. Notice that after the move is completed, the MoveCompleted event is generated and a message appears in the Status textbox. The LED turns off when the TaskCompleted event is generated. Stop and end your program when you finish testing.

Tip: Remember to save your program throughout the examples.

Example – Creating a Sequence

To create a sequence, you must add additional moves. This sequence will contain two point-to-point moves and a circular arc.

1. On the Tasks property page, click the Axis button to add a second axis to the task. (Remember that circular arcs require two axes.) Set Number to value that is valid for your motion controller. When you add an additional axis to a task, that axis becomes part of all moves.

2.Change the PointToPoint1 move to reflect the added axis. On the Moves property page select PointToPoint1 and ensure that Mode is set to Relative position. Set XAxis pos to 3845 and YAxis pos to 5000. The first move now moves 3845 encoder positions along the XAxis and 5000 encoder positions along the YAxis.

3. Switch to the Velocity subtab. Set the Velocity property to 4000 counts/s. Set Acceleration to 20000 counts/s2 and Deceleration to 5000 counts/s2.

4. On the Moves property page, click the Add button to add a second move. Rename this move PointToPoint2 and set Mode to Relative position. Set XAxis pos to 3845 and YAxis pos to -5000.

5. Switch to the Velocity subtab. Set the Velocity property to 4000 counts/s. Set Acceleration to 20000 counts/s2 and Deceleration to 5000 counts/s2.

6. On the Moves property page, click the Add button to add a third move. Rename the move CircularArc.

7. On the Trajectory subtab, set Type to Circular arc. Set Radius to 5000, Start angle to 40 degrees, and Travel angle to -260 degrees.

8. Switch to the Velocity subtab. Set the Velocity property to 4000 counts/s. Set Acceleration to 10000 counts/s2 and Deceleration to 10000 counts/s2.

After you configure the sequence, your preview window displays the completed sequence, as shown in Figure 4.

9. Run your program. As each move is completed, the MoveCompleted event is generated and the name of the completed move is printed in the Status textbox. The LED turns off after the task is completed. Stop and end your program when you finish testing.

Example – Reading and Displaying Status

You can track the velocity and position of your motion task with the GetCurrentVelocity and GetCurrentPosition methods. The GetCurrentVelocity method returns the velocity of the entire task. The GetCurrentPosition method returns an array containing the current position on each axis. In this example, you will use a textbox to display the velocity and the Measurement Studio Graph (CWGraph) control to chart the current position.

1. Place a TextBox on the project form. Change Name to txtVelocity and delete the text from Text. Place a Label on the form and change Caption to Current Velocity.

2. Place a CWGraph control on the form. By default, Visual Basic names the control CWGraph1. Right click the control and select Properties to configure the control:

1. On the Ticks property page, set Axis caption to XAxis for the XAxis.
2. In the listbox, select YAxis-1 and set Axis caption to YAxis. Both axes display captions labeling each axis.
3. On the Graph property page, set Chart history to Fixed and set the Fixed value to 2000. When you run the program, the graph stores 2000 points before deleting old data.
4. Click OK.

3. To ensure the plot is cleared each time you click the Start button, add the following bold line of code to the cmdStart_Click event procedure:

Private Sub cmdStart_Click()
NIMotion1.Configure
CWGraph1.ClearData
NIMotion1.Start
CWButton1.Value = True
End Sub

4. Because there are several sections of code that must call the GetCurrentVelocity and GetCurrentPosition methods, create a new Visual Basic procedure:

1. From the Visual Basic menu, select Tools»Add Procedure.
2. Name the procedure DisplayPositionVelocity, set Type to Sub, and set Scope to Public.
3. Click OK.

5. In the DisplayPositionVelocity procedure, add code to display the current velocity in the Current Velocity textbox:

Public Sub DisplayPositionVelocity()
Dim velocity As Variant
NIMotion1.Tasks("Task-1").GetCurrentVelocity velocity
'Display the velocity returned from the method.
txtVelocity.Text = velocity
End Sub

6. Add the code to chart the current position of the moves. To chart the data, use the CWGraph ChartXvsY method. This method charts an array of Y data against an array of X data. In this case, the position on XAxis is charted against the position on YAxis. The GetCurrentPosition method returns an array. Each element in the array corresponds to the current position for an axis in the task. Add the following bold lines of code:

Public Sub DisplayPositionVelocity()
Dim velocity As Variant
Dim position As Variant
NIMotion1.Tasks("Task-1").GetCurrentVelocity velocity
'Display the velocity returned from the method.
txtVelocity.Text = velocity
NIMotion1.Tasks("Task-1").GetCurrentPosition position
'Chart the position on XAxis versus the position on YAxis.
CWGraph1.ChartXvsY position(0), position(1)
End Sub

Now you must determine when the DisplayPositionVelocity procedure is called. When you run your application, the program should begin returning the velocity and position when you click the Start button. The program should return these values at a specific interval, which means you must add a Visual Basic Timer control to the project form and specify the interval at which values are returned.

7. Add the following bold line of code to the cmdStart_Click event procedure to call DisplayPositionVelocity immediately before the task begins:

Private Sub cmdStart_Click()
NIMotion1.Configure
CWGraph1.ClearData
DisplayPositionVelocity
NIMotion1.Start
CWButton1.Value = True
End Sub

8. Place a Visual Basic Timer control on the project form. By default, Visual Basic names the control Timer1.

9. In the Properties window, set Enabled to False. The timer is enabled when the Start button is clicked.

Note: You can call the GetCurrentPosition and GetCurrentVelocity methods only on a configured task. Because the timer calls GetCurrentPosition and GetCurrentVelocity, you must call Configure on the task before enabling the timer.

10. Add code to enable the timer when you click the Start button and to set the Timer to go off every 200 ms. Add the following bold lines of code:

Private Sub cmdStart_Click()NIMotion1.Configure
DisplayPositionVelocity
NIMotion1.Start
CWButton1.Value = True
Timer1.Interval = 200
Timer1.Enabled = True
End Sub

11. When the timer goes off, the DisplayPositionVelocity procedure is called. Double click the Timer control to create a new procedure and add the following line of code:

Private Sub Timer1_Timer()
DisplayPositionVelocity
End Sub

12. To stop the timer and cease acquiring position and velocity, add the following bold line of code to cmdStop_Click event procedure:

Private Sub cmdStop_Click()
Timer1.Enabled = False
NIMotion1.Stop
End Sub

13. Run your program and click the Start button. As shown in Figure 5, the graph plots the task while the Current Velocity textbox displays the velocity of the moves. Stop and end your program when you finish testing.

While running your program, you might notice that the transitions between moves are not smooth. Remember that with the task type set to complete moves, the next move is not sent to the motion controller until the MoveCompleted event is generated for the previous move. As a result, there is a short pause between moves. For smoother transitions between moves, you can set the task type to blended moves and configure when moves are blended in the task. You can specify if blending begins before or after deceleration or after a delay specified by the blend factor. The blend factor, or dwell time, determines how long the transition between moves takes.

Example-Blending Moves

In this example, use the NIMotion control property pages to change the previously configured task so that it uses blended moves.

1. On the Tasks property page, set Type to Blended moves.

2. Switch to the Moves property page and select the first move. In this task, the moves should begin blending before the previous move starts decelerating. On the Velocity subtab, set Blend to before decelerating.

3. Because you specified that you want to start blending before decelerating, the blend factor is automatically set to -1. This value causes the pending move to start when the previous move finishes its constant velocity segment and starts to decelerate.

4. Configure each move in the task with the same three settings.

5. Run your program. Notice that the moves transition more smoothly. Stop the program when you finish testing.

The BlendCompleted Event

If you set the task type to blended moves, the control generates the BlendCompleted event. The BlendCompleted event is generated after each move finishes blending. While blending, the control does not generate the MoveCompleted event. You can add code to your applications to notify you when each pending move has completed blending into the previous move:

1. In the code window, select NIMotion1 from the object listbox and BlendCompleted from the procedure listbox to create the BlendCompleted event procedure.

2. Add the following bold line of code to the BlendCompleted event procedure:

Private Sub NIMotion1_BlendCompleted(ByVal Move As NIMotionControlLib.NIMotionMove, ByVal Task As NIMotionControlLib.NIMotionTask)
txtStatus.Text = Move.Name & " blend completed."
End Sub

3. Run your program. After each move finishes blending, the Status textbox displays the statement you added to the BlendCompleted event. Stop and end your program when you finish testing.

Handling Errors and Exceptions with the Motion Control

Error Handling

The NIMotion control provides numerous properties, methods, and events for handling errors and exceptions in your applications.

Every method on the NIMotion control has a return value that indicates the success or failure of the operation. If a method fails, the NIMotion control returns either a FlexMotion driver error or an NIMotion-specific error. You can check the return value from each method and handle any errors immediately following the method call. For example, in the following section of code, any errors returned by the Configure method are printed in a textbox on the form:

Private Sub cmdStart_Click()
Dim motionErr as Long
motionErr = NIMotion1.Configure()
If (motionErr = 0) Then
motionErr = NIMotion1.Start()
Else
txtError = "The Configure method returned error code " + Str(motionErr) + ". Please correct the error and restart the operation."
End If
End Sub

With the GetErrorDescription method, you also can retrieve the error string corresponding to the error code:

txtError = NIMotion1.GetErrorDescription(motionErr)

Exception Handling

Instead of checking the return value from each method call, you can specify that execution moves to a label in the procedure and perform all error handling in that section of the procedure. The ExceptionOnError property specifies if NIMotion methods raise an exception on an error condition. You must set ExceptionOnError to True to raise exceptions. In the following code sample, textboxes display messages if the Configure and Start methods succeed. If either method fails, the program goes to the ErrHandler label, which prints the returned error code in another textbox:

Private Sub cmdStart_Click()
NIMotion1.ExceptionOnError = True
On Error GoTo ErrHandler
NIMotion1.Configure
txtError = "Configure Succeeded"
NIMotion1.Start
txtError = "Start Succeeded"
'If no error occurs, the procedure is finished.
Exit Sub
ErrHandler:
txtError = "The Motion Control generated run time error " + Str(Err.Number)
End Sub

Note: Error information is stored in Err, a global Visual Basic object.

MotionError Event

While return values and exceptions are useful for responding to synchronous errors, the MotionError event is the primary mechanism for notifying you of asynchronous errors and other run-time errors that occur during the execution of the control. For example, suppose you create a sequence containing a point-to-point move followed by a circular arc. You call the Start method, which begins the first move and returns without error. If you use an invalid travel angle value for the circular arc, the MotionError event is generated when the circular arc move is sent to the controller. To manage such errors, you can write the following code in the event handler for the MotionError event:

Private Sub NIMotion1_MotionError(ByVal ErrorCode As Long, ByVal ErrorDescription As String, ByVal ErrorContextID As Long, ByVal ErrorContextDescription As String)
MsgBox "Motion Error Event: " + ErrorContextDescription + vbCrLf + ErrorDescription
End Sub

The MotionError event returns all the relevant information on the error. In addition to returning the error code and error description, the event also returns error contexts and error context descriptions. Error contexts provide more information about the circumstances leading to an error. You set error contexts with the ErrorEventMask property. This property stores all possible contexts in which you want the MotionError event generated. For example, if you want the MotionError event generated if an error occurs during the Configure method, while the sequence is executing, or during the GetCurrentPosition and GetCurrentVelocity methods, add the following line of code:

NIMotion1.ErrorEventMask = nimotionConfiguring + nimotionRunning + nimotionReadingCurrentStatus

If you do not specify any values for ErrorEventMask, the MotionError event is not generated. Alternatively, you can set ErrorEventMask to -1, and all errors generate the MotionError event. The MotionError event then becomes the primary mechanism for responding to all motion errors.

Conclusion

The Measurement Studio Motion concepts presented in this application note—moves, tasks, sequences, position and velocity status, and error handling—provide you with a foundation for building custom motion control applications in Visual Basic. For more information about these concepts, refer to the Measurement Studio Reference (Start»Programs»National Instruments»Measurement Studio»Help»Measurement Studio Reference). For information about and tutorials on advanced motion concepts, search the National Instruments Developer Zone at zone.ni.com.

Reader Comments | Submit a comment »