MotorVelocityController API Guide
Introduction
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
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.
MotorVelocityController 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 Velocity 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
- 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 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.
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 Velocity Controller here.
Target Velocity
Target Velocity
The large text box in this area stores the Target Velocity value. You must press the Enter button to send the value to the controller. 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.
You can use the Rescale Factor to modify the base units of this property.
Engage Motor
Your Velocity Controller will not attempt to control the velocity 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.
PID Settings
These settings allow you to easily tune your Velocity Controller to meet the needs of your application
Rescale Factor
The Rescale Factor allows you to change the units of the following properties:
- Target Velocity, Velocity, Expected Velocity, Deadband
- 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
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 sensor.
Acceleration
Acceleration controls how quickly your controller can change the motor’s velocity.
| Acceleration (rotations/s²) |
Initial Velocity (rotations/s) |
Target Velocity (rotations/s) |
Time to Reach Target Velocity |
|---|---|---|---|
| 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 Velocity 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 Velocity Controller here.
DeadBand
Phidget Velocity Controllers use trapezoidal motion profiling combined with a proportional-integral-derivative (PID) controller. The DeadBand only applies when the Target Velocity is set to 0. It allows your motor to move freely, up to a minimum Velocity, to prevent unwanted jitter around 0. It's also useful for applications where you want the motor to coast at zero velocity, since the motor will hold position at zero velocity without DeadBand.
For more information, view our guide on tuning your Velocity Controller here.
Example
| Target Velocity (rotations/s) |
Deadband (rotations/s) |
Velocity (rotations/s) |
Result |
|---|---|---|---|
| 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. |
| 0.0 | 1.0 | 0.9 | Control of the motor is relaxed. The motor moves freely. |
| 0.0 | 1.0 | -0.9 | Control of the motor is relaxed. The motor moves freely. |
| 0.0 | 1.0 | 1.1 | The controller attempts to reach the Target Velocity. |
| 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
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 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
- 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
- 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 Velocity, Velocity, Expected Velocity
- Error
- Duty Cycle
Target Velocity, Velocity, and Duty Cycle have been previously described in this document. Error is calculated by taking the difference of Velocity and Expected Velocity.
Tuning
Information about the Tuning tab can be found in the Velocity 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. |
