Stellaris/Tiva Drivers
Miscellaneous drivers for Stellaris/Tiva microcontrollers
|
This is a servo driver for TI Stellaris microcontrollers. More...
Macros | |
#define | SERVO_TIMER_A |
Specifies the A "half" of the timer to use for the servo. | |
#define | SERVO_TIMER_B |
Specifies the B "half" of the timer to use for the servo. | |
Functions | |
int | Servo_Init (uint32_t sysClock, uint32_t timerPeriodUsecs) |
Initialize the servo driver. More... | |
ServoHandle_t | Servo_Config (uint32_t timerIdx, uint32_t timerHalf) |
Configure a servo instance. More... | |
int | Servo_Enable (ServoHandle_t hServo) |
Enable servo operation. More... | |
int | Servo_Disable (ServoHandle_t hServo) |
Disable servo operation. More... | |
int | Servo_Calibrate (ServoHandle_t hServo, int32_t usecsPer90, int32_t usecsAtZero, bool reverseAngle) |
Set the calibration parameters for the servo. More... | |
int | Servo_SetLimits (ServoHandle_t hServo, int32_t usecsMin, int32_t usecsMax) |
Set the limits for the servo. More... | |
int | Servo_SetMotionParameters (ServoHandle_t hServo, int32_t rateDegPerSec) |
Set servo motion parameters. More... | |
int | Servo_SetPositionUsecs (ServoHandle_t hServo, int32_t usecs) |
Set the servo position using the pulse width in microseconds. More... | |
int | Servo_SetPosition (ServoHandle_t hServo, int32_t centiDegrees) |
Set the servo position using the pulse width in centi-degrees. More... | |
int32_t | Servo_GetPositionUsecs (ServoHandle_t hServo) |
Get the position of the servo in microseconds of pulse width. More... | |
int32_t | Servo_GetPosition (ServoHandle_t hServo) |
Get the position of the servo in centi-degrees. More... | |
int | Servo_MoveUsecs (ServoHandle_t hServo, int32_t usecs, void(*pfnMotionObserver)(void *pObserverData), void *pObserverData) |
Move to position in microseconds pulse width, with motion control. More... | |
int | Servo_Move (ServoHandle_t hServo, int32_t centiDegrees, void(*pfnMotionObserver)(void *pObserverData), void *pObserverData) |
Move to position in centi-degrees, with motion control. More... | |
int | Servo_SetTickObserver (ServoHandle_t hServo, void(*pfnServoTickObserver)(void *pObserverData), void *pObserverData) |
Set a callback function on the PWM timer tick. More... | |
uint32_t | Servo_ReadBatteryRaw (void) |
Read the battery level in raw ADC counts. More... | |
uint32_t | Servo_ReadBatteryMv (void) |
Read the battery level in millivolts. More... | |
void | Servo_BatteryInit (uint32_t gain, uint32_t offset) |
Initialize the servo battery monitor. More... | |
This is a servo driver for TI Stellaris microcontrollers.
Specifically it is for the LM4F parts (such as LM4F120 or LM4F232) because this driver depends on the wide timers. The wide timers are not available on older LM3S devices.
Although it is not required, this driver was written to be used with a Servo BoosterPack. See https://github.com/kroesche/lp-servo12 and http://tronics.kroesche.org/servo-boosterpack.html
This driver provides a set of functions for configuring and using timers for servo motion control. It uses the PWM mode of the timers to generate the appropriate pulse-width control for typical hobby servos.
Two unit systems are provided for dealing with servo position: microseconds and centi-degrees. Because the servo position is controlled by the pulse width of the timer output signal, the position can be represented as a pulse width. Therefore microseconds is used as the units to represent the pulse width and thus the servo position. The other option for units is centi-degrees, which is degrees * 10. This allows resolution of 0.1 degrees which should be sufficient for hobby applications. Using centi-degrees allows fractional degree resolution without requiring floating point.
Servos can be moved two ways: direct position and motion control. When direct position is used, the servo is just immediately commanded to the new position and the rate of motion is whatever the servo provides. When motion control is used, the rate of motion is controlled. This allows for smoother and less jerky control.
The servo enable/disable can be used to apply/remove the pulse signal to the servos. It may be useful to disable a servo once it has reached the desired position so that the servo stops hunting around or jittering at the target position.
Two forms of callback are provided: tick and motion. The tick callback allows a client function to be called at each pulse period (timer tick). This allows for varying the pulse width at the pulse frequency. This could be used for some advanced control method where the position is varied over time according to some algorithm. The motion control makes use of this, so if you install a tick callback and then use a Move() function, your tick callback will be deleted. The motion callback is used with the Move() functions. Since Move() is asynchronous and returns before the motion is done, this allows a client to be notified when the motion is finished.
add acceleration feature to motion control
extend driver to work without wide timer
EXAMPLE: Here is code showing how you might use this driver in an example:
// init the driver err = Servo_Init(SysControlClockGet(), 20000); // 50 Hz // get a servo instance using wide timer 4A handle = Servo_Config(4, SERVO_TIMER_A) // enable the servo (this establishes a known position) err = Servo_Enable(handle); // set motion rate for 90 deg per sec err = Servo_SetMotionParameters(handle, 90); // command the servo to move to +45 deg err = Servo_Move(handle, 450, NULL, NULL);
int Servo_Init | ( | uint32_t | sysClock, |
uint32_t | timerPeriodUsecs | ||
) |
Initialize the servo driver.
[in] | sysClock | is the system clock rate used to run the timers. |
[in] | timerPeriodUsecs | is the timer period in microseconds, to used for servo pulse width generation. |
This function must be called to initialize the servo driver and before any of the other servo functions are called. The parameter timerPeriodUsecs is used to set the timer that is used for teh servo pulse period. The same value will be used for all the servos managed by this driver. The parameter sysClock is the value of the system clock or time base used for the timers. Internally this value is used to compute the number of timer ticks per microsecond so it shoud always be a whole MHz value. If fractional MHz is used for the system clock, then pulse width calculations will not be correct.
ServoHandle_t Servo_Config | ( | uint32_t | timerIdx, |
uint32_t | timerHalf | ||
) |
Configure a servo instance.
[in] | timerIdx | is the wide timer number to use for the servo |
[in] | timerHalf | is the half of the timer for this servo, A (0) or B(1). Macros SERVO_TIMER_A and SERVO_TIMER_B can be used. |
This function allocates and configures a servo instance. The caller specifies which wide timer is to be used for the servo. That timer will then be initialized to be used for servo PWM generation and the servo instance data will be populated. Default values will be used for all the calibration data.
int Servo_Enable | ( | ServoHandle_t | hServo | ) |
Enable servo operation.
[in] | hServo | is the servo handle |
This function will begin generating the PWM pulse to the servo at the present position. If the servo is not already at that position it will move there (without rate control).
int Servo_Disable | ( | ServoHandle_t | hServo | ) |
Disable servo operation.
[in] | hServo | is the servo handle |
This function will disable the servo. All callbacks will be deleted and interrupts disabled, and the PWM output will be turned off.
int Servo_Calibrate | ( | ServoHandle_t | hServo, |
int32_t | usecsPer90, | ||
int32_t | usecsAtZero, | ||
bool | reverseAngle | ||
) |
Set the calibration parameters for the servo.
[in] | hServo | is the servo handle |
[in] | usecsPer90 | is the number of microseconds of pulse witdth change that represents 90 degrees of motion |
[in] | usecsAtZero | is the pulse width in microseconds when the servo is at the position designated as zero |
[in] | reverseAngle | is a flag that means that angle calculations should be reversed (reverses the sign of motion) |
This function sets the parameters that are used for calibration of the servo movement. The values are dependent on the specific servos and the physical arrangement.
int Servo_SetLimits | ( | ServoHandle_t | hServo, |
int32_t | usecsMin, | ||
int32_t | usecsMax | ||
) |
Set the limits for the servo.
[in] | hServo | is the servo handle |
[in] | usecsMin | is the minimum pulse width in microseconds |
[in] | usecsMax | is the maximum pulse width in microseconds |
This function sets the limits that are used for determining the lower and upper bound for the pulse width that can be applied to the servo and represents the limits of range of motion. The values are dependent on the specific servos and the physical arrangement.
int Servo_SetMotionParameters | ( | ServoHandle_t | hServo, |
int32_t | rateDegPerSec | ||
) |
Set servo motion parameters.
[in] | hServo | is the servo handle |
[in] | rateDegPerSec | is the motion rate in degrees per second |
This function will set the motion rate as specified in degrees per second. Internally this will be silently constrained to a minimum of 9 degrees per second. This is the rate that the servo will move when commanded using a Move() function.
int Servo_SetPositionUsecs | ( | ServoHandle_t | hServo, |
int32_t | usecs | ||
) |
Set the servo position using the pulse width in microseconds.
[in] | hServo | is the servo handle |
[in] | usecs | is the pulse width in microseconds |
This function will set the servo PWM pulse width which represents a position. If the usecs value is outside the min and max defined for the servo, then the value will be constrained to the min or max with no error indicated.
int Servo_SetPosition | ( | ServoHandle_t | hServo, |
int32_t | centiDegrees | ||
) |
Set the servo position using the pulse width in centi-degrees.
[in] | hServo | is the servo handle |
[in] | centiDegrees | is the angle in centi-degrees |
This function will set the servo position as specified in centi-degrees. The position will be constrained per the default or prior set limits.
int32_t Servo_GetPositionUsecs | ( | ServoHandle_t | hServo | ) |
Get the position of the servo in microseconds of pulse width.
[in] | hServo | is the servo handle |
This function returns the current, absolute position of the servo in units of microseconds of pulse width.
int32_t Servo_GetPosition | ( | ServoHandle_t | hServo | ) |
Get the position of the servo in centi-degrees.
[in] | hServo | is the servo handle |
This function returns the current, absolute position of the servo in units of centi-degrees.
int Servo_MoveUsecs | ( | ServoHandle_t | hServo, |
int32_t | usecs, | ||
void(*)(void *pObserverData) | pfnMotionObserver, | ||
void * | pObserverData | ||
) |
Move to position in microseconds pulse width, with motion control.
[in] | hServo | is the servo handle |
[in] | usecs | is the position in microseconds of pulse width |
[in] | pfnMotionObserver | is a callback function, called when motion is complete |
[in] | pObserverData | is caller supplied data pointer to be passed to the callback function |
This function will move the servo to a new position. The position is specified as pulse width in microseconds. The servo is moved with motion control, which means that the servo is not immediately commanded to the new position but is moved gradually according to the motion parameters. This allows for smoother, more controlled motion. This starts the motion and returns right away, before the motion is complete. If the called supplied a callback function, then it will be called when the motion is complete.
int Servo_Move | ( | ServoHandle_t | hServo, |
int32_t | centiDegrees, | ||
void(*)(void *pObserverData) | pfnMotionObserver, | ||
void * | pObserverData | ||
) |
Move to position in centi-degrees, with motion control.
[in] | hServo | is the servo handle |
[in] | centiDegrees | is the position in centi-degrees |
[in] | pfnMotionObserver | is a callback function, called when motion is complete |
[in] | pObserverData | is caller supplied data pointer to be passed to the callback function |
This function will move the servo to a new position. The position is specified as centi-degrees. The servo is moved with motion control, which means that the servo is not immediately commanded to the new position but is moved gradually according to the motion parameters. This allows for smoother, more controlled motion. This starts the motion and returns right away, before the motion is complete. If the called supplied a callback function, then it will be called when the motion is complete.
int Servo_SetTickObserver | ( | ServoHandle_t | hServo, |
void(*)(void *pObserverData) | pfnServoTickObserver, | ||
void * | pObserverData | ||
) |
Set a callback function on the PWM timer tick.
[in] | hServo | is the servo handle |
[in] | pfnServoTickObserver | is the callback function for timer ticks |
[in] | pObserverData | is the data to pass to the callback |
This function will install a callback function that will be called once for each timer PWM period. Then the timer interrupts will be enabled so the callback should start getting called immediately. If NULL is passed as the callback function, then the callback is removed and interrupts disabled.
uint32_t Servo_ReadBatteryRaw | ( | void | ) |
Read the battery level in raw ADC counts.
This function returns the battery voltage as raw ADC counts (0-4095). It uses a moving average to smooth the voltage reading so the reading should be fairly smooth but will not respond to quick changes in battery voltage. This function should be called periodically in order to keep the moving average accurate. It should be used for the purpose of monitoring the battery state of charge and not for reading instantaneous voltage.
uint32_t Servo_ReadBatteryMv | ( | void | ) |
Read the battery level in millivolts.
This function returns the battery voltage in millivolts. It uses Servo_ReadBatteryRaw to get the smoothed ADC counts and then applies a conversion to obtain millivolts.
void Servo_BatteryInit | ( | uint32_t | gain, |
uint32_t | offset | ||
) |
Initialize the servo battery monitor.
[in] | gain | is the range of measurement, in millivolts |
[in] | offset | is the lowest measured voltage, in millivolts |
This function will initialize the ADC peripheral to prepare for measuring the battery voltage using Servo_BatteryReadMv. The parameters gain and offset can be used to calibrate the measurement. If these values are zero, then nominal calibration values are used so they can be left at 0 if calibration data is not available. The calibration values are not arbitrary - they must match the tuning of the battery measuring circuit.