Driver Software
Simple control of a brushed DC motor

The Motor Control Wildcard driver software provides a simple interface for controlling a brushed DC motor. See Quick Start for a walkthrough on using the demo program for the Motor Control Wildcard, and refer to this page for detailed information on the driver functions, macros and constants.

Only two functions are implemented, which provide the most generalized interface to the driver. Most users will not need to call To_Motor() directly, and can instead use the simpler macros below. Depending on the application it may be useful to call Read_Motor_Status() directly to check for an over-temperature fault or over-current fault.

Macros are defined that simplify most use cases of the Motor Control Wildcard for C programmers; most applications will only need to use these macros. Each macro returns the result of Read_Motor_Status, which will be a non-zero value except in the event of an over-temperature fault or over-current fault.

The following constant values are used as arguments for To_Motor(). MOTOR_PWM_MAX may be used in your application for calculating a PWM duty cycle value to use with the To_Motor() function or the macros below. For Forth programmers, identically-named constants are provided in the Forth driver.

#define MOTOR_COAST( N ) To_Motor( MOTOR_DIR_COAST, 0, 0, (N) )

Turns off both outputs on the Motor Control Wildcard at module address N, allowing the motor to coast. See To_Motor() for more information.

#define MOTOR_DECAY_FAST   0x05

This constant is used for the decay argument to ToMotor() to select "fast" decay mode, in which the output polarity is reversed when the H-bridge controller IC suspends normal operation due to current limiting, and motor current flows in reverse through the power supply. This reduces average torque and dissipates more power on the H-bridge controller IC than slow decay mode.

#define MOTOR_DECAY_SLOW   0x04

This constant is used for the decay argument to ToMotor() to select "slow" decay mode, in which both low-side MOSFETS conduct current when the H-bridge controller IC suspends normal operation due to current limiting, and motor current flows in a short loop through the H-bridge chip. This dissipates less power on the H-bridge chip than fast decay mode, and matches the circuit behavior during the inactive portion of each PWM cycle during normal operation.

#define MOTOR_DIR_BRAKE_L  0x00

This constant is used for the state argument to ToMotor() to connect both motor outputs to the negative side of the power supply, allowing motor current to flow in a loop through the two low-side MOSFETs and producing a braking effect. Using this constant causes the PWM duty cycle argument to be overridden with zero.

#define MOTOR_DIR_BRAKE_H  0x03

This constant is used for the state argument to ToMotor() to connect both motor outputs to the positive side of the power supply, allowing motor current to flow in a loop through the two high-side MOSFETs and producing a braking effect. Using this constant causes the PWM duty cycle argument to be overridden with MOTOR_PWM_MAX.

#define MOTOR_DIR_CCW      0x01

This constant is used for the state argument to ToMotor() to connect output 1 to the high side of the power supply and output 2 to the low side of the power supply, and produce "counter-clockwise" torque, though the actual direction of rotation is determined by the motor wiring polarity and physical orientation.

#define MOTOR_DIR_COAST    0x04

This constant is used for the state argument to ToMotor() to disable all output MOSFETs. Any current in the motor will decay through flyback diodes in the H-bridge controller IC.

#define MOTOR_DIR_CW       0x02

This constant is used for the state argument to ToMotor() to connect output 1 to the low side of the power supply and output 2 to the high side of the power supply, and produce "clockwise" torque, though the actual direction of rotation is determined by the motor wiring polarity and physical orientation.

#define MOTOR_ON_CCW( P, N ) To_Motor( MOTOR_DIR_CCW, MOTOR_DECAY_SLOW, (P), (N) )

Connects output 1 to the high side of the power supply and output 2 to the low side of the power supply on the Motor Control Wildcard at module address N. The fraction of full-scale speed P is an unsigned integer up to MOTOR_PWM_MAX, i.e. 0 to 31. This produces "counter-clockwise" torque, though the actual direction of rotation is determined by the motor wiring polarity and physical orientation. See To_Motor() for more information.

#define MOTOR_ON_CW( P, N ) To_Motor( MOTOR_DIR_CW, MOTOR_DECAY_SLOW, (P), (N) )

Connects output 1 to the low side of the power supply and output 2 to the high side of the power supply on the Motor Control Wildcard at module address N. The fraction of full-scale speed P is an unsigned integer up to MOTOR_PWM_MAX, i.e. 0 to 31. This produces "clockwise" torque, though the actual direction of rotation is determined by the motor wiring polarity and physical orientation. See To_Motor() for more information.

#define MOTOR_PWM_MAX      0x1F

This constant represents the maximum value for the pwm argument to To_Motor(), at which the output PWM duty cycle is 100% and the motor runs at full speed. This may be used in your application code to help calculate the appropriate value to achieve a given fraction of the full-scale speed.

#define MOTOR_STOP(  N ) To_Motor( MOTOR_DIR_BRAKE_L, MOTOR_DECAY_SLOW, 0, (N) )

Connects both outputs to the low side of the power supply on the Motor Control Wildcard at module address N, allowing motor current to flow in a loop through the two low-side MOSFETs and producing a braking effect.

C function

int Read_Motor_Status ( int modulenum );

Forth word

: Read_Motor_Status ( modulenum -- [true] or [false] )

Reads the state of the nFAULT pin on the H-bridge controller IC, and returns zero in the event of an over-temperature fault or over-current fault, or returns a non-zero value if there is no fault. Any call to To_Motor() or any of the wrapper macros will reset the H-bridge controller IC and clear the fault; an over-temperature fault can only be cleared after the temperature of the Motor Control Wildcard has decreased to a safe level.

C function

int To_Motor ( int state, int decay, int pwm, int modulenum );

Forth word

: To_Motor ( state\decay\pwm\modulenum -- [true] or [false] )

To_Motor is the most general interface to the Motor Control Wildcard.

state accepts the values MOTOR_DIR_CW, MOTOR_DIR_CCW, MOTOR_DIR_BRAKE_L, MOTOR_DIR_BRAKE_H, or MOTOR_DIR_COAST to indicate "clockwise" rotation, "counter-clockwise" rotation, braking with outputs low, braking with outputs high, or coasting respectively. Note that "clockwise" and "counter-clockwise" are used as notation for the two directions of rotation, but actual direction of rotation is determined by the motor wiring polarity and physical orientation. Note that changing the direction of rotation without first stopping the motor is likely to cause an over-current fault.

decay accepts the values MOTOR_DECAY_SLOW or MOTOR_DECAY_FAST to select the decay mode used when the H-bridge controller IC suspends normal operation to limit motor current. In "slow" decay mode, motor current passes in a loop through the H-bridge controller IC when the outputs are disabled by current limiting, and in "fast" decay mode motor current passes in reverse through the power supply, actively opposing the motor rotation when the H-bridge outputs are inactive due to current limiting. In general the "slow" decay mode should be selected to match the behavior of the H-bridge outputs during the inactive portion of PWM cycles under normal operation.

pwm accepts an integer with value 0 to 31, used to select the duty cycle for the speed regulation PWM circuit without feedback from an optical encoder ("open-loop" control), or the fraction of full speed if an optical encoder is used for closed-loop feedback and the PI control jumper J3 is installed.

modulenum is the Wildcard module address, assigned based on placing the Motor Control Wildcard on either module port 0 (or stacked on top of QCard) for addresses 0-3 or on module port 1 of the PDQ Board or Docking Panel for addresses 4-7. The address within that range is selected by installing jumpers J1 and/or J2. See User's Guide for detailed information on selecting the Wildcard module address.

The return value is the result of calling Read_Motor_Status(). Note that the return value from To_Motor() will only be zero (false) in the event of an over-temperature fault; a previous over-current fault will be reset by a call to To_Motor, and an over-current fault caused by a call to To_Motor(), for example by attempting to abruptly change direction of rotation, will occur after the function call has returned.