MotorVelocityController API Guide

Introduction

link= will be used throughout this guide.

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.

30V 50A DC Motor Phidget (DCC1020_0)

The 30V 50A DC Motor Phidget (DCC1020_0) is fully compatible with this guide.

30V 50A Brushless DC Motor Phidget (DCC1120_0)

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.

1. Phidget Info
2. Change/Update Events
3. Target Velocity
4. PID Settings
5. Additional Motor Settings
6. 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.

Other Considerations

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 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.

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.

Converting to Degrees

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

Converting to Rotations

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

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.

Example

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

Other Considerations

You can use the Rescale Factor to modify the base units of this property.

Tunings Constants (Kp, Ki, Kd)

Phidget Velocity Controllers run a sophisticated 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 run a sophisticated proportional-integral-derivative (PID) controller on board. 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

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

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.

Determining Your Current Limit

The datasheet of your DC 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.

Exceeding Your 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 DC Motor Phidget does not have the Surge Current Limit feature, you may consider dynamically adjusting the Current Limit yourself by monitoring the CurrentInput channel.

Current Limiting on Small Motors

Small motors may have a stall current that is less than the minimum Current Limit of your DC Motor Phidget. 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.

Torque Limiting

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.

Other Considerations

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

Reaching the Target Velocity with a 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, 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.