View source for MotorPositionController API Guide

{{#seo:|description=Get started with your Position Controller}}
[[Category:IntroGuide]]

<div class="nonumtoc">
<div class="toclimit-4">
=Introduction=
[[Image:DCC1020.png|thumb|<center>The [https://cdn.phidgets.com/docs/images/7/7f/DCC1020.png 30V 50A DC Motor Phidget (DCC1020_0)] will be used throughout this guide.</center>]]
This guide will provide information about the MotorPositionController 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}} 30V 50A Brushless DC Motor Phidget (DCC1120_0)]]]
The [{{SERVER}}/?prodid=1333 30V 50A Brushless DC Motor Phidget (DCC1120_0)] is fully compatible with this guide.
|-|
DCC1000=
[[Image:DCC1000_0.jpg|link=https://cdn.phidgets.com/docs/images/c/cf/DCC1000_0.jpg|thumb|200px|[{{SERVER}}/?prodid=965 DC Motor Phidget (DCC1000_0)]]]
[{{SERVER}}/?prodid=965 DC Motor Phidget (DCC1000_0)] considerations:
* When reviewing the [[#Current Limit|Current Limit]], please note that [[#Surge Current Limit|Surge Current Limit.]] functionality is not available for this device.
* '''Current Regulator Gain''' is not listed in this guide. Information on this topic is available in the device API.
* '''Encoder IO Mode''' is not listed in this guide. Information on this topic is available in the device API.
* '''Fan Mode''' is not listed in this guide. Information on this topic is available in the device API.
* '''Normalize PID''' is not listed in this guide, though it is recommended to enable this functionality. Information on this topic is available in the device API. 
|-|
DCC1001=
[[Image:DCC1001_0.jpg|link=https://cdn.phidgets.com/docs/images/3/3c/DCC1001_0.jpg|thumb|200px|[https://www.phidgets.com/?prodid=1012 2A DC Motor Phidget (DCC1001_0)]]]
[https://www.phidgets.com/?prodid=1012 2A DC Motor Phidget (DCC1001_0)] considerations:
* '''Normalize PID''' is not listed in this guide, though it is recommended to enable this functionality. Information on this topic is available in the device API.
|-|
DCC1002=
[[Image:DCC1002_0.jpg|link=https://cdn.phidgets.com/docs/images/7/7d/DCC1002_0.jpg|thumb|200px|[{{SERVER}}/?prodid=1117 4A DC Motor Phidget (DCC1002_0)]]]
[{{SERVER}}/?prodid=1117 4A DC Motor Phidget (DCC1002_0)] considerations:
* When reviewing the [[#Current Limit|Current Limit]], please note that [[#Surge Current Limit|Surge Current Limit.]] functionality is not available for this device.
* '''Normalize PID''' is not listed in this guide, though it is recommended to enable this functionality. Information on this topic is available in the device API.
|-|
DCC1100=
[[Image:DCC1100_0.jpg|link=https://cdn.phidgets.com/docs/images/8/87/DCC1100_0.jpg|thumb|200px|[https://www.phidgets.com/?prodid=1013 Brushless DC Motor Phidget (DCC1100_0)]]]
[https://www.phidgets.com/?prodid=1013 Brushless DC Motor Phidget (DCC1100_0)] considerations:
* '''Stall Velocity''' is not listed in this guide. Information on this topic is available in the device API. 
* '''Normalize PID''' is not listed in this guide, though it is recommended to enable this functionality. Information on this topic is available in the device API. 
|-|
</tabber>

=MotorPositionController 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_PositionController.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 Position Controller entry to view the program.


[[Image:DCC1020_0_PositionController.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
#Motor Status
#Target Position
#PID Settings
#Motor Configuration
#Sandbox/Tuning

In this guide, we will focus on the areas that contain important information about the Position 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 Position Controller.

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

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

===Duty Cycle===
{{DCMotor_DutyCycle|position}}

==Target Position==
===Target Position===
The large text box in this area stores the Target Position value. You must press enter to send the new target position to the controller (you'll see the green TargetPosition graph change when you do). When the controller is engaged, it will attempt to reach the Target Position.

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

If you're using a BLDC motor without an encoder, the default units are in commutations. 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}}

====Other Considerations====
If there is a non-zero [[#Deadband|Deadband]], the final position of the motor may not match the Target Position.

===Engage Motor===
{{DCMotor_Engage|position}}

===Zero Position===
This button will zero your Position. It uses the {{Code|addPositionOffset}} method in the API.

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

===Rescale Factor===
{{DCMotor_RescaleFactor|position}}

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

=====Brushless DC Motor without Encoder=====
If you're using a brushless DC motor without an encoder, view the [[Brushless_DC_Motor_API_Guide#Example_Calculations|Brushless DC Motor API Guide]] for examples of how to calculate the rescale factor for the Hall Effect sensors.

===Use Encoder for Position===
[[Image:Positioncontroller_BLDC_Encoder.png|thumb|link=https://cdn.phidgets.com/docs/images/5/57/Positioncontroller_BLDC_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 position sensor.

===Velocity Limit===
Your controller allows you to configure a Velocity Limit for your motor. When tracking position, it will attempt to follow this limit. 

====Other Considerations====
* Your controller may exceed the Velocity Limit to track the Target Position more accurately.
* {{Template:DCMotor_RescaleFactorNote}}

===Acceleration===
{{DCMotor_Acceleration}}

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

===Deadband===
{{DCMotor_Deadband|position}}

====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
* Velocity
* 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
* Velocity
* 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:Positioncontroller_sandbox_tempimage.PNG|thumb|link=https://cdn.phidgets.com/docs/images/a/a8/Positioncontroller_sandbox_tempimage.PNG|Reaching the Target Position 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 Position, Position, Expected Position
*Error
*Duty Cycle


[[#Target Position|Target Position]], [[#Position|Position]], and [[#Duty Cycle|Duty Cycle]] have been previously described in this document. Error is calculated by taking the difference of Position and Expected Position.

===Tuning===
Information about the Tuning tab can be found in the [[Position Controller Tuning Guide]].

==Failsafe==
{{DCMotor_Failsafe}}

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

==Errors==
{{DCMotor_Errors}}