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"

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

Copyright: Copyright (C) Parallax Inc. 2017. All Rights MIT Licensed. See end of file.

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

pin	Control pin used in servo360_connect call.
position	Angle 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

pinControl	I/O pin connected to the servo's white control signal line.
pinFeedback	I/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

pinA	The control pin of one of the two coupled servos.
pinB	The 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

pin	Control pin used in servo360_connect call.
state	1 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

pin	Control pin used in servo360_connect call.
state	1 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

pin	Control 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

pin	Control 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

pin	Control 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

pin	Control 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

pin	Control pin used in servo360_connect call.
*ccwMax	Maximum counterclockwise degree angle limit.
*cwMax	Maximum 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

pin	Control 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

pin	Control pin used in servo360_connect call.
constant	Constant 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

pin	Control 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

pin	Control 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

pin	Control 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

pin	Control 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

pin	Control 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

pin	Control 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

pin	Control pin used in servo360_connect call.
position	The 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

pinControl	pinControl used in servo360_connect call.
time	Control 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

pin	Control pin used in servo360_connect call.
unitsPerSecSquared	Acceleration 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

pin	Control pin used in servo360_connect call.
angle	The 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

pin	Control pin used in servo360_connect call.
speed	Maximum 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

pin	Control pin used in servo360_connect call.
ccwMax	Limit for counterclockwise rotation.
cwMax	Limit 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

pin	Control pin used in servo360_connect call.
angle	Degree 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

pin	Control pin used in servo360_connect call.
constant	Constant name of value to change.
value	New 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

pinA	Control pin of one of the two coupled servos.
pinB	Control pin of the other coupled servo.
scale	value 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

pin	Control pin used in servo360_connect call.
speed	Speed 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

pin	Control pin used in servo360_connect call.
stepSize	Max 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

pin	Control pin used in servo360_connect call.
turns	The 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

pin	Control pin used in servo360_connect call.
units	Number 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

pin	Control pin used in servo360_connect call.
speed	Speed 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

pin	Control pin used in servo360_connect call.

Returns: 0 or higher if success.

Functions

Detailed Description

Function Documentation

◆ servo360_angle()

◆ servo360_connect()

◆ servo360_couple()

◆ servo360_enable()

◆ servo360_feedback()

◆ servo360_getAcceleration()

◆ servo360_getAngle()

◆ servo360_getAngleCalc()

◆ servo360_getAngleCtrlSpeedMax()

◆ servo360_getAngleLimits()

◆ servo360_getAngleOffset()

◆ servo360_getControlSys()

◆ servo360_getCsop()

◆ servo360_getMaxSpeed()

◆ servo360_getRampStep()

◆ servo360_getSpeed()

◆ servo360_getTurns()

◆ servo360_getUnitsFullCircle()

◆ servo360_goto()

◆ servo360_set()

◆ servo360_setAcceleration()

◆ servo360_setAngleCalc()

◆ servo360_setAngleCtrlSpeedMax()

◆ servo360_setAngleLimits()

◆ servo360_setAngleOffset()

◆ servo360_setControlSys()

◆ servo360_setCoupleScale()

◆ servo360_setMaxSpeed()

◆ servo360_setRampStep()

◆ servo360_setTurns()

◆ servo360_setUnitsFullCircle()

◆ servo360_speed()

◆ servo360_stop()