servo360 library  v0.9.2
Parallax Feedback 360 High Speed Servo functions for control, monitoring, and setting
Functions
servo360.h File Reference

Parallax Feedback 360 High Speed Servo control and monitoring functions. Uses one additional cog to control up to 4 Parallax Feedback 360 Continuous Rotation Servos. When the abdrive360 library is in use, the total drops to two, since two are already in use as the ActivityBot 360's differential drive servos.
More...

#include "simpletools.h"

Go to the source code of this file.

Functions

int servo360_connect (int pinControl, int pinFeedback)
 Initializes a connection to a Parallax Feedback 360 servo. The current position of the servo during the call will be used as the 0-degree position. More...
 
int servo360_angle (int pin, int position)
 Set an angle in degrees for servo to move to and hold. The default degree is 1/360th of a full circle, and the default angle limits are +/- 524,287 degrees. More...
 
int servo360_getAngle (int pin)
 Get measured angle of servo in degree units. More...
 
int servo360_speed (int pin, int speed)
 Set servo rotation speed in degrees per second. The default max values range from 720 degrees per second (full speed counterclockwise) to 0 (stop) to -720 degrees per second (full speed clockwise). More...
 
int servo360_getSpeed (int pin)
 Measure the current speed. For best results, take the average of multiple measurements. More...
 
int servo360_goto (int pin, int position)
 Go to a certain number of degrees from the current position. Positive values are counterclockwise, negative values are clockwise. This is a "set it and forget it" function that returns immediately after the maneuver has been initiated. The maneuver's progress can be monitored with servo360_getCsop and also with servo360_getAngle. More...
 
int servo360_getCsop (int pin)
 Csop is an abbreviation for control system operation, which could be speed, position, or goto control. During a servo360_goto maneuver, this function will return S360_GOTO. When the maneuver has completed, it will return S360_POSITION. More...
 
int servo360_stop (int pin)
 Stop servo motion if it is turning. It is equivalent to a call to servo360_speed(pin, 0). More...
 
Settings - Speed Control
int servo360_setAcceleration (int pin, int unitsPerSecSquared)
 Set acceleration in terms of degrees per second squared. The default is 3600 degrees per second squared, which allows the servo to accelerate as fast as it can, regardless of power supply. To exert control over acceleration, use values in the 180 to 1800 range. More...
 
int servo360_getAcceleration (int pin)
 Get current acceleration in terms of degrees per second squared. More...
 
int servo360_setMaxSpeed (int pin, int speed)
 Set the maximum servo speed in terms of degrees per second. More...
 
int servo360_getMaxSpeed (int pin)
 Get the max speed setting. More...
 
int servo360_setRampStep (int pin, int stepSize)
 Set acceleration in terms of degrees per second per 50th of a second.
For a more straightforward implementation, use servo360_setAcceleration. More...
 
int servo360_getRampStep (int pin)
 Get current acceleration setting in terms of degrees per second per 50th of a second. For a more straightforward implementation, use servo360_getAcceleration instead. More...
 
Settings - Angle Control
int servo360_setAngleLimits (int pin, int ccwMax, int cwMax)
 Set the angle limits the servo is allowed to turn to during position control. These limits only affect angle control, not speed or goto control. The default angle limits are +/- 524287 degrees. More...
 
int servo360_getAngleLimits (int pin, int *ccwMax, int *cwMax)
 Check the angle limits the servo is allowed to turn to during position control. These limits only affect angle control, not speed or goto control. The default angle limits are +/- 524287 degrees. More...
 
int servo360_setAngleCtrlSpeedMax (int pin, int speed)
 Set the maximum speed at which the servo is allowed to turn while adjusting to a new angle set point. More...
 
int servo360_getAngleCtrlSpeedMax (int pin)
 Check the maximum speed at which the servo is allowed to turn while adjusting to a new angle set point. More...
 
int servo360_setAngleOffset (int pin, int angle)
 Set the offset from the servo's mechanical 0 degree position. If this function is not called, the 0 degree position is the angle measured when servo_connect is called. More...
 
int servo360_getAngleOffset (int pin)
 Check the offset from the servo's mechanical 0-degree position. If servo360_setAngleOffset has not been called, the 0-degree position will be whatever angle was measured when servo_connect was called. More...
 
Settings - General
int servo360_setUnitsFullCircle (int pin, int units)
 Set the number of units in a full circle. By default, this value is 360.
This function does not actually change acceleration or other settings. IMPORTANT: This function DOES change the degrees value in any function called after the new degree value has been set. For example, the default max speed setting is 720 degrees per second = 2 revolutions per second. If you change the units to 64 degrees per full circle, the max speed will still be 2 revolutions per second, but for max speed, the speed supplied to servo360_speed will have to be 128 instead of 720. This applies to all other control, setting, and monitoring functions -they will be in terms of 64 (or whatever value you choose) instead of 360. More...
 
int servo360_getUnitsFullCircle (int pin)
 Get the number of units in a full circle. By default, this value is 360, but it can be changed with servo360_setUnitsFullCircle, and checked with this function. See servo360_setUnitsFullCircle for more info. More...
 
int servo360_setControlSys (int pin, int constant, int value)
 The servo360.h library is designed to use Proportional, Integral and Derivative (PID) control to maintain both speed and position. The default values are mainly for no load or a light load. This function can be used to change those settings to accommodate different loads or make the responses more peppy (at the expense of possible oscillations when the set point has been reached). An example of calling this function to restore the original proportional control setting would be servo360_setControlSys(pin, S360_SETTING_KPV, 500). More...
 
int servo360_getControlSys (int pin, int constant)
 Check control system constant. See the servo360_setControlSys function for more info. More...
 
int servo360_setTurns (int pin, int turns)
 Change the number of turns that have elapsed since the application has started. Use this function to reset to zero if the number of revolutions since the application started running approaches 524,000 under speed and/or goto control. For angular control, use it if the angle approaches +/- 524,287 degrees. When the application is restarted with either RESET or by turning power off and back on, the turns return to zero automatically. More...
 
int servo360_getTurns (int pin)
 Get the number of times the output shaft has turned in a full circle since the application started (either by power-on or press/release RESET). The turns value is positive for counterclockwise turns or negative for clockwise. More...
 
Settings - Differential Drive
int servo360_couple (int pinA, int pinB)
 This function is used by the abdrive360 library to reduce the drive on a servo whose position is further ahead in relation to the calculated target position during a given 50th of a second. More...
 
int servo360_setCoupleScale (int pinA, int pinB, int scale)
 Change the scale factor in a pair of servos that were coupled with the servo360_couple call. The scale factor is how much the control system subtracts from the faster servo's drive level in response to differences between two coupled servos distances from their respective distance set points during a given 50th of a second. The default scale value is 2000, which multiplies a distance error in 4096ths of a circle by 2 and adds/subtracts it to/from the requested drive speed to reduce the faster servos lead in its progress to the final angle. More...
 
Settings - Advanced
int servo360_enable (int pin, int state)
 Enable or disable the control system signal. More...
 
int servo360_feedback (int pin, int state)
 Enable or disable the feedback system. If the feedback system is disabled, the servo should only be controlled with servo360_set. More...
 
int servo360_set (int pinControl, int time)
 Use pulse width control to set servo speed without feedback. Make sure to call serov360_feedback(pin, 0) before making any calls to this function. More...
 
int servo360_setAngleCalc (int pin, int angle)
 During servo360_speed maneuvers, the target position gets recalculated every 50th of a second. The control system code compares this calculated position against the measured position from servo360_getAngle to make adjustments to maintain a given speed. This call is typically used in applications where there is some difference between the calculated and actual position due to external factors, such as a robot pushing against a wall. If the wall prevents the wheels from turning, this calculated angle can be changed to the result of the servo360_getAngle function to make the control system stop applying pressure to the wall, without making the application reverse the wheel direction for a certain amount of time. More...
 
int servo360_getAngleCalc (int pin)
 During servo360_speed maneuvers, the target position gets recalculated every 50th of a second. The control system code compares this calculated position against the measured position from servo360_getAngle to make adjustments to maintain a given speed. This call can be used to check the calculated angle, which can be compared to servo360_getAngle call results to gain insights into certain servo360 behaviors. More...
 

Detailed Description

Parallax Feedback 360 High Speed Servo control and monitoring functions. Uses one additional cog to control up to 4 Parallax Feedback 360 Continuous Rotation Servos. When the abdrive360 library is in use, the total drops to two, since two are already in use as the ActivityBot 360's differential drive servos.

Author
Parallax Inc
Version
0.9.2

Function Documentation

◆ servo360_angle()

int servo360_angle ( int  pin,
int  position 
)

Set an angle in degrees for servo to move to and hold. The default degree is 1/360th of a full circle, and the default angle limits are +/- 524,287 degrees.

These values can be adjusted with the servo360_setUnitsFullCircle and servo360_getAngleLimits functions.

Parameters
pinControl pin used in servo360_connect call.
positionAngle in degrees from zero degrees. The zero degree value is either the position when servo360_connect was called, or a custom position relative to mechanical zero that can be set with the servo360_setAngleOffset function.
Returns
0 or higher if success.

◆ servo360_connect()

int servo360_connect ( int  pinControl,
int  pinFeedback 
)

Initializes a connection to a Parallax Feedback 360 servo. The current position of the servo during the call will be used as the 0-degree position.

Error codes:
-4 control pin already allocated, -5 feedback pin already allocated, -6 control or feedback pin out of 0...27 range, -7 too many devices, -8 no feedback signal found on pinFeedback.

Parameters
pinControlI/O pin connected to the servo's white control signal line.
pinFeedbackI/O pin connected to the servo's yellow feedback line.
Returns
0 or higher if success.

◆ servo360_couple()

int servo360_couple ( int  pinA,
int  pinB 
)

This function is used by the abdrive360 library to reduce the drive on a servo whose position is further ahead in relation to the calculated target position during a given 50th of a second.

Parameters
pinAThe control pin of one of the two coupled servos.
pinBThe control pin of the other coupled servo.
Returns
0 or higher if success.

◆ servo360_enable()

int servo360_enable ( int  pin,
int  state 
)

Enable or disable the control system signal.

Parameters
pinControl pin used in servo360_connect call.
state1 enabled, 0 disabled
Returns
0 or higher if success.

◆ servo360_feedback()

int servo360_feedback ( int  pin,
int  state 
)

Enable or disable the feedback system. If the feedback system is disabled, the servo should only be controlled with servo360_set.

Parameters
pinControl pin used in servo360_connect call.
state1 enabled, 0 disabled.
Returns
0 or higher if success.

◆ servo360_getAcceleration()

int servo360_getAcceleration ( int  pin)

Get current acceleration in terms of degrees per second squared.

Parameters
pinControl pin used in servo360_connect call.
Returns
degrees per second squared acceleration setting for servo360_speed and servo360_goto.

◆ servo360_getAngle()

int servo360_getAngle ( int  pin)

Get measured angle of servo in degree units.

Parameters
pinControl pin used in servo360_connect call.
Returns
The current angle in degree units.

◆ servo360_getAngleCalc()

int servo360_getAngleCalc ( int  pin)

During servo360_speed maneuvers, the target position gets recalculated every 50th of a second. The control system code compares this calculated position against the measured position from servo360_getAngle to make adjustments to maintain a given speed. This call can be used to check the calculated angle, which can be compared to servo360_getAngle call results to gain insights into certain servo360 behaviors.

Parameters
pinControl pin used in servo360_connect call.
Returns
angle The target angle value in terms of servo360_setUnitsFullCircle units. The default is degrees -360ths of a full circle. If this function is called for an ActivityBot 360 servo after calling an abdrive360.h function, the angle for either of its drive servos will be 64ths of a full circle.

◆ servo360_getAngleCtrlSpeedMax()

int servo360_getAngleCtrlSpeedMax ( int  pin)

Check the maximum speed at which the servo is allowed to turn while adjusting to a new angle set point.

Parameters
pinControl pin used in servo360_connect call.
Returns
speed Maximum speed in degrees per second.

◆ servo360_getAngleLimits()

int servo360_getAngleLimits ( int  pin,
int *  ccwMax,
int *  cwMax 
)

Check the angle limits the servo is allowed to turn to during position control. These limits only affect angle control, not speed or goto control. The default angle limits are +/- 524287 degrees.

Parameters
pinControl pin used in servo360_connect call.
*ccwMaxMaximum counterclockwise degree angle limit.
*cwMaxMaximum clockwise degree angle limit.
Returns
Current angle limit.

◆ servo360_getAngleOffset()

int servo360_getAngleOffset ( int  pin)

Check the offset from the servo's mechanical 0-degree position. If servo360_setAngleOffset has not been called, the 0-degree position will be whatever angle was measured when servo_connect was called.

Parameters
pinControl pin used in servo360_connect call.
Returns
Degree offset from the mechanical 0 degrees (0 to 360).

◆ servo360_getControlSys()

int servo360_getControlSys ( int  pin,
int  constant 
)

Check control system constant. See the servo360_setControlSys function for more info.

Parameters
pinControl pin used in servo360_connect call.
constantConstant name of value to change.
Returns
value Value of the control system constant.

◆ servo360_getCsop()

int servo360_getCsop ( int  pin)

Csop is an abbreviation for control system operation, which could be speed, position, or goto control. During a servo360_goto maneuver, this function will return S360_GOTO. When the maneuver has completed, it will return S360_POSITION.

Parameters
pinControl pin used in servo360_connect call.
Returns
S360_SPEED (1), S360_POSITION, (2), or S360_GOTO (3), or -1 if the I/O pin is not valid servo control or feedback pin.

◆ servo360_getMaxSpeed()

int servo360_getMaxSpeed ( int  pin)

Get the max speed setting.

Parameters
pinControl pin used in servo360_connect call.
Returns
Current max speed setting in degrees per second.

◆ servo360_getRampStep()

int servo360_getRampStep ( int  pin)

Get current acceleration setting in terms of degrees per second per 50th of a second. For a more straightforward implementation, use servo360_getAcceleration instead.

Parameters
pinControl pin used in servo360_connect call.
Returns
stepSize Max velocity change in degrees per second per 50th of a second.

◆ servo360_getSpeed()

int servo360_getSpeed ( int  pin)

Measure the current speed. For best results, take the average of multiple measurements.

Parameters
pinControl pin used in servo360_connect call.
Returns
The speed in degrees per second.

◆ servo360_getTurns()

int servo360_getTurns ( int  pin)

Get the number of times the output shaft has turned in a full circle since the application started (either by power-on or press/release RESET). The turns value is positive for counterclockwise turns or negative for clockwise.

Parameters
pinControl pin used in servo360_connect call.
Returns
360 degree turns since the application started.

◆ servo360_getUnitsFullCircle()

int servo360_getUnitsFullCircle ( int  pin)

Get the number of units in a full circle. By default, this value is 360, but it can be changed with servo360_setUnitsFullCircle, and checked with this function. See servo360_setUnitsFullCircle for more info.

Parameters
pinControl pin used in servo360_connect call.
Returns
units The number of degrees in a full circle. The valid range is 32 to 360.

◆ servo360_goto()

int servo360_goto ( int  pin,
int  position 
)

Go to a certain number of degrees from the current position. Positive values are counterclockwise, negative values are clockwise. This is a "set it and forget it" function that returns immediately after the maneuver has been initiated. The maneuver's progress can be monitored with servo360_getCsop and also with servo360_getAngle.

Parameters
pinControl pin used in servo360_connect call.
positionThe new position in terms of degrees from the current position.
Returns
0 or higher if the goto maneuver has been successfully initiated.

◆ servo360_set()

int servo360_set ( int  pinControl,
int  time 
)

Use pulse width control to set servo speed without feedback. Make sure to call serov360_feedback(pin, 0) before making any calls to this function.

Parameters
pinControlpinControl used in servo360_connect call.
timeControl pulse time in microseconds (1280 to 1720) of high time that will be repeated every 20 ms.
Returns
0 or higher if success.

◆ servo360_setAcceleration()

int servo360_setAcceleration ( int  pin,
int  unitsPerSecSquared 
)

Set acceleration in terms of degrees per second squared. The default is 3600 degrees per second squared, which allows the servo to accelerate as fast as it can, regardless of power supply. To exert control over acceleration, use values in the 180 to 1800 range.

Parameters
pinControl pin used in servo360_connect call.
unitsPerSecSquaredAcceleration in degree units per second squred.
Returns
0 or higher if success.

◆ servo360_setAngleCalc()

int servo360_setAngleCalc ( int  pin,
int  angle 
)

During servo360_speed maneuvers, the target position gets recalculated every 50th of a second. The control system code compares this calculated position against the measured position from servo360_getAngle to make adjustments to maintain a given speed. This call is typically used in applications where there is some difference between the calculated and actual position due to external factors, such as a robot pushing against a wall. If the wall prevents the wheels from turning, this calculated angle can be changed to the result of the servo360_getAngle function to make the control system stop applying pressure to the wall, without making the application reverse the wheel direction for a certain amount of time.

Parameters
pinControl pin used in servo360_connect call.
angleThe new target angle value in terms of servo360_setUnitsFullCircle units. The default is degrees -360ths of a full circle. If this function is called for an ActivityBot 360 servo after calling an abdrive360.h function, the angle for either of its drive servos will be 64ths of a full circle.
Returns
0 or higher if success.

◆ servo360_setAngleCtrlSpeedMax()

int servo360_setAngleCtrlSpeedMax ( int  pin,
int  speed 
)

Set the maximum speed at which the servo is allowed to turn while adjusting to a new angle set point.

Parameters
pinControl pin used in servo360_connect call.
speedMaximum speed in degrees per second.
Returns
0 or higher if success.

◆ servo360_setAngleLimits()

int servo360_setAngleLimits ( int  pin,
int  ccwMax,
int  cwMax 
)

Set the angle limits the servo is allowed to turn to during position control. These limits only affect angle control, not speed or goto control. The default angle limits are +/- 524287 degrees.

Parameters
pinControl pin used in servo360_connect call.
ccwMaxLimit for counterclockwise rotation.
cwMaxLimit for clockwise rotation.
Returns
0 or higher if success.

◆ servo360_setAngleOffset()

int servo360_setAngleOffset ( int  pin,
int  angle 
)

Set the offset from the servo's mechanical 0 degree position. If this function is not called, the 0 degree position is the angle measured when servo_connect is called.

Parameters
pinControl pin used in servo360_connect call.
angleDegree offset from the mechanical 0 degrees (0 to 360).
Returns
0 or higher if success.

◆ servo360_setControlSys()

int servo360_setControlSys ( int  pin,
int  constant,
int  value 
)

The servo360.h library is designed to use Proportional, Integral and Derivative (PID) control to maintain both speed and position. The default values are mainly for no load or a light load. This function can be used to change those settings to accommodate different loads or make the responses more peppy (at the expense of possible oscillations when the set point has been reached). An example of calling this function to restore the original proportional control setting would be servo360_setControlSys(pin, S360_SETTING_KPV, 500).

Control System Settings

Error units are in terms of 4096ths of a full circle, and the settings listed below multiply by 1000ths. For example, if the angular distance error during a 1/50th of a second speed measurement is 128 4096ths of a circle, the effect of proportional control with the default setting will be (500 * 128) / 1000 = 64. The result is that the control system will try to increase the speed by 64/4096ths of a full circle per second.

Velocity Control System Constants

Proportional
constant name: S360_SETTING_KPV, default value: 500.
Integral
constant name: S360_SETTING_KIV, default value: 0.
Derivative
constant name: S360_SETTING_KDV, default value: 0.
Max Integral Output
constant name: S360_SETTING_KIV_MAX, default value: 0.

Angular Control System Constants

Proportional
constant name: S360_SETTING_KPA, default value: 12000.
Integral
constant name: S360_SETTING_KIA, default value: 600.
Derivatively
constant name: S360_SETTING_KDA, default value: 6000.
Max Integral Output
constant name: S360_SETTING_KIA_MAX, default value: 1000.

Parameters
pinControl pin used in servo360_connect call.
constantConstant name of value to change.
valueNew control system constant.
Returns
0 or higher if success.

◆ servo360_setCoupleScale()

int servo360_setCoupleScale ( int  pinA,
int  pinB,
int  scale 
)

Change the scale factor in a pair of servos that were coupled with the servo360_couple call. The scale factor is how much the control system subtracts from the faster servo's drive level in response to differences between two coupled servos distances from their respective distance set points during a given 50th of a second. The default scale value is 2000, which multiplies a distance error in 4096ths of a circle by 2 and adds/subtracts it to/from the requested drive speed to reduce the faster servos lead in its progress to the final angle.

Parameters
pinAControl pin of one of the two coupled servos.
pinBControl pin of the other coupled servo.
scalevalue by which the faster servo is slowed down.
Returns
0 or higher if success.

◆ servo360_setMaxSpeed()

int servo360_setMaxSpeed ( int  pin,
int  speed 
)

Set the maximum servo speed in terms of degrees per second.

Parameters
pinControl pin used in servo360_connect call.
speedSpeed in degrees per second.
Returns
0 or higher if success.

◆ servo360_setRampStep()

int servo360_setRampStep ( int  pin,
int  stepSize 
)

Set acceleration in terms of degrees per second per 50th of a second.
For a more straightforward implementation, use servo360_setAcceleration.

Parameters
pinControl pin used in servo360_connect call.
stepSizeMax velocity change in degrees per second per 50th of a second.
Returns
0 or higher if success.

◆ servo360_setTurns()

int servo360_setTurns ( int  pin,
int  turns 
)

Change the number of turns that have elapsed since the application has started. Use this function to reset to zero if the number of revolutions since the application started running approaches 524,000 under speed and/or goto control. For angular control, use it if the angle approaches +/- 524,287 degrees. When the application is restarted with either RESET or by turning power off and back on, the turns return to zero automatically.

Parameters
pinControl pin used in servo360_connect call.
turnsThe new number of turns that have elapsed since the start of the application.
Returns
0 or higher if success.

◆ servo360_setUnitsFullCircle()

int servo360_setUnitsFullCircle ( int  pin,
int  units 
)

Set the number of units in a full circle. By default, this value is 360.
This function does not actually change acceleration or other settings. IMPORTANT: This function DOES change the degrees value in any function called after the new degree value has been set. For example, the default max speed setting is 720 degrees per second = 2 revolutions per second. If you change the units to 64 degrees per full circle, the max speed will still be 2 revolutions per second, but for max speed, the speed supplied to servo360_speed will have to be 128 instead of 720. This applies to all other control, setting, and monitoring functions -they will be in terms of 64 (or whatever value you choose) instead of 360.

Parameters
pinControl pin used in servo360_connect call.
unitsNumber of degrees in a full circle. The valid range is 32 to 360.
Returns
0 or higher if success.

◆ servo360_speed()

int servo360_speed ( int  pin,
int  speed 
)

Set servo rotation speed in degrees per second. The default max values range from 720 degrees per second (full speed counterclockwise) to 0 (stop) to -720 degrees per second (full speed clockwise).

Max speed can be set with servo360_setMaxSpeed. Acceleration can be set with a call to servo360_setAcceleration. Max distance is 524,000 revolutions before a turns reset is needed. Use servo360_getTurns if your application could potentially exceed this limit in a single session and servo360_setTurns(pin, 0) to accommodate another half million turns!

Parameters
pinControl pin used in servo360_connect call.
speedSpeed in degrees per second.
Returns
0 or higher if success.

◆ servo360_stop()

int servo360_stop ( int  pin)

Stop servo motion if it is turning. It is equivalent to a call to servo360_speed(pin, 0).

Parameters
pinControl pin used in servo360_connect call.
Returns
0 or higher if success.