MotorPositionController API Guide
Introduction
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
Select your controller for compatibility information relating to this guide.
The 30V 50A DC Motor Phidget (DCC1020_0) is fully compatible with this guide.
The 30V 50A Brushless DC Motor Phidget (DCC1120_0) is fully compatible with this guide.
DC Motor Phidget (DCC1000_0) considerations:
- When reviewing the Current Limit, please note that 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.
2A DC Motor Phidget (DCC1001_0) considerations:
- When reviewing the Current Limit, please note that 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.
4A DC Motor Phidget (DCC1002_0) considerations:
- When reviewing the Current Limit, please note that 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.
Brushless DC Motor Phidget (DCC1100_0) considerations:
- This device does not offer current limiting or surge current limiting.
- 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.
MotorPositionController API Overview
Phidget Control Panel
After wiring your Phidget, we recommend opening the Phidget Control Panel on a Windows computer to experiment with key features.
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.
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 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.
Other Considerations
You can use the Rescale Factor to modify the base units of this property.
Duty Cycle
The most recent Duty Cycle value reported by the controller. Phidget motor controllers uses a pulse-width modulated (PWM) signal to modify the average voltage across your motor.
The table below shows the result of different Duty Cycle values when using a 24-volt power supply.
| Duty Cycle | Result |
|---|---|
| 0.0 | The motor is not being powered. The average voltage across your motor is 0V. |
| 1.0 | The motor is fully powered. The average voltage across your motor is 24V. |
| -1.0 | The motor is fully powered (in reverse). The average voltage across your motor is -24V. |
| 0.5 | The average voltage across your motor is 12V. |
| -0.5 | The average volage across your motor is -12V. |
This value indicates how hard the motor is working to achieve the target.
The Duty Cycle provides useful information when tuning your system. For more information, view our guide on tuning your Position Controller here.
Target Position
Target Position
The large text box in this area stores the Target Position value. You must press the Enter button to send the value to the controller. 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.
You can use the Rescale Factor to modify the base units of this property.
Other Considerations
If there is a non-zero Deadband, the final position of the motor may not match the Target Position.
Engage Motor
Your Position Controller will not attempt to control the position of your motor until it is engaged.
When disengaged, the controller will stop powering to your motor, it will instead be in a freewheel state.
Zero Position
This button will zero your Position. It uses the 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
The Rescale Factor allows you to change the units of the following properties:
- Target Position, Position, Expected Position, Deadband
- VelocityLimit, Acceleration
By default, the units will be in encoder pulses which is dictated by your encoder and are often non-intuitive. We recommend utilizing the Rescale Factor so your software is easier to understand.
Example Calculations
Generally, most users will prefer units of degrees or rotations. To determine an appropriate Rescale Factor, you will need to know the following values:
- Encoder pulses per revolution, equivalent to 4x the counts per revolution (CPR)
- Gearbox ratio (if applicable)
These values will be available from manufacturer data sheets, or directly on the motors/encoders.
Specifications of system:
- Motor gear ratio: 76:1
- Encoder quadrature cycles per revolution (CPR): 300
- Encoder pulses per revolution = 300*4 = 1200
- Preferred Units: Degrees
Rescale Factor = 360 / (76*1200) = 0.003947368421
Specifications of system:
- Motor gear ratio: 76:1
- Encoder quadrature cycles per revolution (CPR): 300
- Encoder pulses per revolution = 300*4 = 1200
- Preferred Units: Rotations
Rescale Factor = 1 / (76*1200) = 0.00001096491228
Brushless DC Motor without Encoder
If you're using a brushless DC motor without an encoder, view the Brushless DC Motor API Guide for examples of how to calculate the rescale factor for the Hall Effect sensors.
Use Encoder for Position
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 property 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.
- You can use the Rescale Factor to modify the base units of this property.
Acceleration
Acceleration controls how quickly your controller can change the motor’s velocity.
| Acceleration (rotations/s²) |
Initial Velocity (rotations/s) |
Velocity Limit (rotations/s) |
Time to Reach Velocity Limit |
|---|---|---|---|
| 0.1 | 0.0 | 1.0 | 10 seconds |
| 1.0 | 0.0 | 1.0 | 1 second |
| 5.0 | 0.0 | 1.0 | 0.2 seconds |
You can use the Rescale Factor to modify the base units of this property.
Tunings Constants (Kp, Ki, Kd)
Phidget Position Controllers use trapezoidal motion profiling combined with a proportional-integral-derivative (PID) controller on board. Kp, Ki, and Kd are tuning constants that must be derived for each application.
For more information, view our guide on tuning your Position Controller here.
DeadBand
Phidget Position Controllers use trapezoidal motion profiling combined with a proportional-integral-derivative (PID) controller. The DeadBand refers to an area around your Target Position (Target Position ± DeadBand) where control of the motor is relaxed.
A small error can lead to the motor continually hunting for a target causing unwanted effects. A non-zero DeadBand can prevent this behavior.
The motor will be disengaged when it enters the DeadBand. If your application needs to hold position against an external force (e.g. gravity), a DeadBand is likely to cause oscillations and should be avoided.
For more information, view our guide on tuning your Position Controller here.
Other Considerations
You can use the Rescale Factor to modify the base units of this property.
Save, Load, Restore Defaults
Please note that these buttons are not connected to any MotorPositionController API methods. They are provided as a convenience in the Phidget Control Panel program to assist in tuning your application.
Save
Save the following properties to a local JSON file:
- Rescale Factor
- Tuning Constants (Kp, Ki, Kd)
- DeadBand
- Velocity Limit
- Acceleration
- Current Limit
- Surge 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 Limit
- Acceleration
- Current Limit
- Surge Current Limit
Motor Configuration
This area of the Phidget Control Panel program allows you to configure advanced motor properties.
Current Limit
Current limiting is an advanced, yet easy-to-use feature that intelligently monitors and controls the current through your motor. This will help to keep your system safe in a variety of situations.
The datasheet of your motor will specify the following parameters:
- Rated Current
- Stall Current
We recommend setting your Current Limit to 1.1x the rated current of your motor. For increased performance from your motor, review Surge Current Limit.
You may choose to increase the Current Limit significantly above the rated current of your motor. In these situations, it is important to understand how heat will impact your motor.
The heating of your motor increases with the square of the current through your motor. Below is a table showing the approximate time to failure of a 24VDC motor with a 20A rated current and 100A stall current.
| Operating Voltage (VDC) | Operating Current (A) | Heating Rate | Approximate Time to Failure |
|---|---|---|---|
| 24 | 20 | Normal | N/A |
| 24 | 40 | 4x faster than normal | minutes |
| 24 | 100 | 25x faster than normal | seconds |
Many applications rely on a motor operating at higher-than-rated power levels. This is typically done at a low frequency which allows for adequate heat dissipation. Implementing a Surge Current Limit is one way to easily achieve this.
If your controller does not have the Surge Current Limit feature, you may consider dynamically adjusting the Current Limit yourself by monitoring the Current Sensor channel.
Small motors may have a stall current that is less than the minimum Current Limit of your controller. In these situations, your controller will not be able to provide current limiting protection. Consider using a more suitable motor controller or monitor the current yourself via the Current Sensor channel.
Current is directly proportional to torque. If you have an oversized motor that may cause damage to your system downstream, a purposefully reduced Current Limit can provide an extra layer of protection.
Over Temperature conditions may reduce your Current Limit.
Surge Current Limit
Surge Current Limit is an advanced feature on new Phidget motor controllers. It allows you to safely exceed your Current Limit for a limited time (approximately one second, intelligently determined by your controller), allowing for faster acceleration from your motor than would otherwise be possible.
For applications where faster acceleration is desirable, we recommend setting your Surge Current Limit equal to the stall current of your motor. For all other applications, the Surge Current Limit can be set equal to the Current Limit, which will disable the feature.
Enabling Functionality
| Surge Current Limit vs Current Limit | Surge Current Limit Functionality |
|---|---|
| Surge Current Limit > Current Limit | Enabled |
| Surge Current Limit = Current Limit | Disabled |
| Surge Current Limit < Current Limit | Disabled* |
* The controller ensures that the Surge Current Limit is never set lower than the Current Limit. If an attempt is made to set the Surge Current Limit below the Current Limit, the controller will automatically adjust the Current Limit to match. Similarly, if the Current Limit is set higher than the Surge Current Limit, the controller will increase the Surge Current Limit to match.
Other Considerations
Over Temperature conditions may reduce your Surge Current Limit.
Motor Inductance
The inductance of a motor is a critical parameter that can significantly improve motor control when understood. The latest generation of Phidget motor controllers automatically measure the inductance of your motor.
You will hear an ascending pair of beeps after the controller has booted indicating the measurement was successful. You will hear no beep, or a descending pair of beeps if the measurement fails.
Other Considerations
- To properly characterize the inductance of your motor, it must be stopped, or turning very slowly when the controller is opened by your application. If this is not possible for your application, consider manually setting the Motor Inductance in the Attach Event. You can use a previously measured value, or a value from your motor's datasheet.
- Inductance measurements will have variations from measurement to measurement, which may cause slight variability in your motor's behavior. If you would like to limit this variability (or you would like to avoid the audible beeps), you can manually set the Motor Inductance in the Attach Event. You can use a previously measured value, or a value from your motor’s datasheet.
- The API for your controller will specify a minimum and maximum Motor Inductance. If your motor falls outside this range, please contact us for more information.
Failsafe Settings
Failsafe configuration is detailed here.
Sandbox/Tuning
Sandbox
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, Position, and 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
Your controller will enter a Failsafe state in the following circumstances:
- The Failsafe timer has elapsed. For more information, view our Failsafe Guide
- The E-Stop circuit has been opened
When your controller enters a Failsafe state it will apply the Failsafe Settings listed below and reject all communication until the software channel has been closed and reopened.
Failsafe Settings
There are two Failsafe settings that can be customized for your application:
- Failsafe Braking Enabled
- Failsafe Current Limit
Failsafe Braking Enabled
Disabled (Default Behavior)
When disabled (default behavior), your controller will not attempt to slow down your motor upon entering a Failsafe state, it will allow it to coast (freewheel) instead.
Enabled
When enabled, your controller will forcefully slow down your motor upon entering a Failsafe state, which will often cause power to flow back to your supply (i.e. regenerative braking).
Failsafe Current Limit
This will supersede the Current Limit and Surge Current Limit when the controller has entered a Failsafe state.
Other Considerations
The Failsafe timer mentioned above can be enabled or disabled through an API. The E-Stop circuit is always enabled and cannot be disabled. If you do not intend to use it, you must leave the inputs shorted.
E-Stop
New Phidget motor controllers include an E-Stop circuit that can be used to trigger a Failsafe state.
| E-Stop Input Terminals | Result |
|---|---|
| Shorted | Normal operation |
| Open | Failsafe state activated |
The E-Stop input is shorted with a jumper wire by default. If you would like to implement an E-Stop system, we recommend connecting a normally-closed (NC) switch to the E-Stop input.
Other Considerations
The E-Stop circuit does not physically interact with the supply voltage or the motor connection. You should not wire your motor, or your supply voltage to this circuit.
Errors
If the error you are looking for is not mentioned below, please visit the API for your controller.
Energy Dump
New Phidget motor controllers include onboard voltage sensing that will attempt to mitigate damage caused by irregular voltage events.
| Input Voltage During Operation (VDC) | Result |
|---|---|
| 8-30 | Normal operation |
| >= 42 | Energy Dump error condition. The Phidget will attempt to regulate the voltage. The Phidget will stop controlling the motor, entering a freewheel state until a full power cycle occurs. |
Please note that the voltage regulation mentioned in the table above is not intended to protect against continuous over-voltage conditions and may shorten the life of your controller. To ensure your system is properly protected against these events, a Power Guard Phidget is required.
Over Temperature
New Phidget motor controllers include onboard temperature sensing that provides thermal protection for your system. View the table below for more information.
| Temperature | Result |
|---|---|
| < 75°C | Normal operation |
| 75°C to 90°C | Current Limit and Surge Current Limit scaling begins. Your current limits will scale down linearly from your set value as temperature increases, to a maximum of 40A at 90°C. |
| 90°C to 100°C | Current Limit and Surge Current Limit are limited to 40A. |
| >= 100°C | Over Temperature condition. The Phidget will stop attempting to control the motor. It will enter a freewheel state until the Phidget is closed and reopened via software. |
