View source for MotorVelocityController API Guide

{{#seo:|description=Get started with your Velocity Controller}}
[[Category:IntroGuide]]
<div class="nonumtoc">
<div class="toclimit-4">
=Introduction=
[[Image:DCC1020.png|thumb|<center>The [{{SERVER}}/?prodid=1333 30V 50A DC Motor Phidget (DCC1020_0)] will be used throughout this guide.</center>]]
This guide will provide information about the MotorVelocityController API to get you up and running with your new Phidget motor controller.


Before starting this guide, visit the Quick Start Guide on your motor controller's product page for information about wiring and power.

==Guide Compatibility==
<tabber>
Info=
''Select your controller for compatibility information relating to this guide.''
|-|
DCC1020=
[[Image:DCC1020.png|link=https://cdn.phidgets.com/docs/images/7/7f/DCC1020.png|thumb|200px|[{{SERVER}}/?prodid=1333 30V 50A DC Motor Phidget (DCC1020_0)]]]
The [{{SERVER}}/?prodid=1333 30V 50A DC Motor Phidget (DCC1020_0)] is fully compatible with this guide.
|-|
DCC1120=
[[Image:DCC1120_0.png|link=https://cdn.phidgets.com/docs/images/3/38/DCC1120_0.png|thumb|200px|[{{SERVER}}/?prodid=1334 30V 50A Brushless DC Motor Phidget (DCC1120_0)]]]
The [{{SERVER}}/?prodid=1334 30V 50A Brushless DC Motor Phidget (DCC1120_0)] is fully compatible with this guide.
|-|
</tabber>

=MotorVelocityController API Overview=
==Phidget Control Panel==
After wiring your Phidget, we recommend opening the [https://www.phidgets.com/docs/Phidget_Control_Panel Phidget Control Panel] on a Windows computer to experiment with key features.


[[Image:DCC1020_0_Panel_VelocityController.png|center|link=]]


When your Phidget is powered, it will appear up on the Phidget Control Panel device list as shown above. Double-click on the Velocity Controller entry to view the program.


[[Image:DCC1020_0_VelocityController.png|800px|center|link=]]


After opening the program, you will see the screen shown above. The program is split into multiple sections to help you get familiar with your motor controller.
#Phidget Info
#Change/Update Events
#Target Velocity
#PID Settings
#Additional Motor Settings
#Sandbox/Tuning

In this guide, we will focus on the areas that contain important information about the Velocity Controller API. For information about the Phidget Info section, and the Phidget Control Panel in general, visit our [https://www.phidgets.com/docs/Phidget_Control_Panel Phidget Control Panel] Page.

==Motor Status==
This area of the program shows information that has been sent back from your Velocity Controller.

===Velocity===
The most recent Velocity value reported by the Velocity Controller. This value is related to [[#Target Velocity|Target Velocity]].

====Other Considerations====
{{Template:DCMotor_RescaleFactorNote}}

===Duty Cycle===
{{DCMotor_DutyCycle|velocity}}

==Target Velocity==
===Target Velocity===
The large text box in this area stores the Target Velocity value. You must press enter to send the new target velocity to the controller (you'll see the green TargetVelocity graph change when you do). While the Velocity Controller is engaged, it will attempt to maintain the Target Velocity.

====Units====
By default, the units of Target Velocity and Velocity will relate to encoder pulses per second. For example, if your encoder reports 1000 quadrature cycles per revolution (1000 CPR) of your motor shaft, setting your Target Velocity to 4000 will rotate your motor shaft one full revolution per second (assuming no gearbox).  

If you're using a BLDC motor without an encoder, the default units are in commutations per second. You can calculate how many commutations are in one revolution by multiplying the number of poles by the number of phases. You can find this information in your motor's specifications or data sheet.  

{{Template:DCMotor_RescaleFactorNote}}

===Engage Motor===
{{DCMotor_Engage|velocity}}

==PID Settings==
These settings allow you to easily tune your Velocity Controller to meet the needs of your application

===Rescale Factor===
{{DCMotor_RescaleFactor|velocity}}

====Example Calculations====
{{DCMotor_RescaleExamples}}

===Use Encoder for Position===
[[Image:DCC1120_0_VelocityController_Encoder.PNG|thumb|link=https://cdn.phidgets.com/docs/images/f/fa/DCC1120_0_VelocityController_Encoder.PNG|This checkbox is only visible for Brushless DC Motor Phidgets]]
When using a Brushless DC Motor Phidget, check the ''Use Encoder for Position'' box if you are using an encoder to track the position of your brushless motor. If this is left unchecked, the controller will use the Hall Effect sensors.


This checkbox uses the PositionType API to configure the sensor.

===Acceleration===
Acceleration controls how quickly your controller can change the motor’s velocity.

{{hiddenh4|Example}}

{| class="wikitable" style="margin:auto;width:75%;text-align: center;"
! style="text-align: center;" | Acceleration<br>(rotations/s²)
! style="text-align: center;" | Initial Velocity<br>(rotations/s)
! style="text-align: center;" | Target Velocity<br>(rotations/s)
! style="text-align: center;" | Time to Reach Target Velocity
|-
| style="text-align: center;" | 0.1 || 0.0 || 1.0 || 10 seconds
|-
| style="text-align: center;" | 1.0 || 0.0 || 1.0 || 1 second
|-
| style="text-align: center;" | 5.0 || 0.0 || 1.0 || 0.2 seconds
|}

{{hiddenh4|Other Considerations}}
{{Template:DCMotor_RescaleFactorNote}}

===Tunings Constants (Kp, Ki, Kd)===
{{DCMotor_TuningConstants|velocity}}

===Deadband===
{{DCMotor_Deadband|velocity}}
====Example====
{| class="wikitable" style="margin:auto;width:75%;text-align: center;"
! style="text-align: center;" | Target Velocity<br>(rotations/s)
! style="text-align: center;" | Deadband<br>(rotations/s)
! style="text-align: center;" | Velocity<br>(rotations/s)
! style="text-align: center;" | Result
|-
| style="text-align: center;" | 0.0 || 0.0 || 0.0 || Deadband is not active. Motor holds stop position and will move back to original stop position if pushed around by external forces.
|-
| style="text-align: center;" | 0.0 || 1.0 || 0.9 || Control of the motor is relaxed. The motor moves freely.
|-
| style="text-align: center;" | 0.0 || 1.0 || -0.9 || Control of the motor is relaxed. The motor moves freely.
|-
| style="text-align: center;" | 0.0 || 1.0 || 1.1 || The controller attempts to reach the Target Velocity.
|-
| style="text-align: center;" | 0.1 || 1.0 || 0.9 || Deadband is not active (Target Velocity is not 0). The controller attempts to reach the Target Velocity.
|}

====Other Considerations====
{{Template:DCMotor_RescaleFactorNote}}

===Save, Load, Restore Defaults===
Please note that these buttons are not connected to any Position Controller APIs. They are provided as a convenience in the Phidget Control Panel program to assist in tuning your Position Controller.

====Save====
Save the following properties to a local JSON file:
* Rescale Factor
* Tuning Constants (Kp, Ki, Kd)
* Deadband
* Acceleration
* Current Limit

====Load====
Load a previously saved configuration.

====Restore Defaults====
Apply default parameters to the following properties:
* Rescale Factor
* Tuning Constants (Kp, Ki, Kd)
* Deadband
* Acceleration
* Current Limit

==Motor Configuration==
This area of the Phidget Control Panel program allows you to configure advanced motor properties.

===Current Limit===
{{DCMotor_CurrentLimit|dc}}

===Surge Current Limit===
{{DCBLDCMotor_SurgeCurrentLimit}}

===Motor Inductance===
{{DCMotor_MotorInductance}}

===Failsafe Settings===
Failsafe configuration is detailed [[#Failsafe|here]].

==Sandbox/Tuning==
===Sandbox===
[[Image:Velocitycontroller_sandbox.PNG|thumb|link=https://cdn.phidgets.com/docs/images/3/33/Velocitycontroller_sandbox.PNG|Reaching the Target Velocity with a [{{SERVER}}/?prodid=1333 30V 50A DC Motor Phidget (DCC1020_0)]]]
This section of the Phidget Control Panel program provides visual information about the following parameters:
*Target Velocity, Velocity, Expected Velocity
*Error
*Duty Cycle


[[#Target Velocity|Target Velocity]], [[#Velocity|Velocity]], and [[#Duty Cycle|Duty Cycle]] have been previously described in this document. Error is calculated by taking the difference of Velocity and Expected Velocity.
<br><br>
===Tuning===
Information about the Tuning tab can be found in the [[Velocity Controller Tuning Guide]].

==Failsafe==
{{DCMotor_Failsafe}}

==E-Stop==
{{DCMotor_ESTOP}}

==Errors==
{{DCMotor_Errors}}