MotorPositionController API Guide

Introduction

The 30V 50A DC Motor Phidget (DCC1020_0) will be used throughout this guide.

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.

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.

DC Motor Phidget (DCC1000_0)

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)

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)

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)

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.

1. Phidget Info
2. Motor Status
3. Target Position
4. PID Settings
5. Motor Configuration
6. 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.

Other Considerations

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.

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

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

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

Example

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

Other Considerations

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.

Determining Your Current Limit

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.

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 controller does not have the Surge Current Limit feature, you may consider dynamically adjusting the Current Limit yourself by monitoring the Current Sensor channel.

Current Limiting on Small Motors

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.

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