servo360 library v0.9.1 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...

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

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