abdrive360.h File Reference

This library provides a simple set of functions for making the ActivityBot 360 go certain distances and speeds.


For more information, go here:

http://learn.parallax.com/activitybot/navigation-basics

More...

#include "simpletools.h"
#include "servo360.h"

Include dependency graph for abdrive360.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	ABD360_GOTO_BUSY   1
#define	ABD360_GOTO_CLEAR   0
#define	ABD360_GOTO_BLOCK   0
#define	ABD360_GOTO_SET_FORGET   1
#define	AB360_NEITHER   0
#define	AB360_LEFT   1
#define	AB360_RIGHT   2
#define	FOR_GOTO   1
#define	FOR_SPEED   0
#define	OFF   0
#define	ON   1
#define	SIDE_LEFT   0
#define	SIDE_RIGHT   1
#define	SIDE_BOTH   2
#define	ABD60_PIN_CTRL_L   12
#define	ABD60_PIN_FB_L   14
#define	ABD360_PIN_CTRL_R   13
#define	ABD360_PIN_FB_R   15
#define	ABD360_UNITS_REV   64
#define	ABD_RAMP_STEP   12
#define	ABD_SPEED_LIMIT   128
#define	ABD_GOTO_SPEED_LIMIT   64
#define	ABD_GOTO_RAMP_STEP   8
#define	_AB360_EE_Start_   63418
#define	_AB360_EE_Pins_   12
#define	_AB360_EE_mVccwL_   28
#define	_AB360_EE_bVccwL_   32
#define	_AB360_EE_mVcwL_   36
#define	_AB360_EE_bVcwL_   40
#define	_AB360_EE_mVccwR_   44
#define	_AB360_EE_bVccwR_   48
#define	_AB360_EE_mVcwR_   52
#define	_AB360_EE_bVcwR_   56
#define	_AB360_EE_End_   _AB360_EE_Start_ + 60

Functions
void	drive_init (void)
void	drive360_ticksPerRev (int units)
void	drive_speed (int left, int right)
	Set wheel speeds in "ticks" per second. A tick is 1/64th of a revolution, and makes an ActivityBot 360 wheel roll 3.25 mm. The maximum speed for each wheel is +/- 128 ticks/second. Positive values are for forward motion; negative values are for reverse. More...
void	drive_goto (int distLeft, int distRight)
	Make the wheels travel a certain distance, measured in ticks. Each "tick" is a 64th of a wheel turn, and corresponds to an ActivityBot 360 rolling distance of about 3.25 mm. Ramp up, cruise, ramp down and stop are coordinated so that different left/right distances result in curves. Same distances are straight lines, and same distances with opposite +/- signs cause the ActivityBot 360 to turn in place. This function does not return until the maneuver has completed. If needed, you change that default with the drive_gotoMode function. The default cruising speed is 64 ticks/second, which can be adjusted with the drive_setMaxVelocity function. More...
void	drive_getTicks (int *left, int *right)
	Get the measured number of ticks each servo has traveled since the program started running. Each "tick" is a 64th of a wheel turn, and corresponds to an ActivityBot 360 rolling distance of about 3.25 mm. More...
void	drive_getTicksCalc (int *left, int *right)
	Get the calculated number of 1/64th wheel revolution ticks the abdrive360 control system thinks each servo should have traveled. More...
Settings
void	drive_servoPins (int controlPinLeft, int controlPinRight)
	Sets servo pins to values other than the default P12 for the left servo and P13 for right servo. Stores values in EEPROM, so you only need to call this function at the start of one program. Programs after that will get the modified port numbers from EEPROM. More...
void	drive_encoderPins (int encPinLeft, int encPinRight)
	Sets feedback pins to values other than the default P14 for left and P15 for right. Stores values in EEPROM, so you only need to call this function at the start of one program. Programs that are run after that will get the modified port numbers from EEPROM. More...
void	drive_setMaxVelocity (int forGotoOrSpeed, int ticksPerSec)
	Set the maximum velocity used by either drive_goto or drive_speed. The defaults are 128 ticks per second for drive_speed, and 64 ticks per second for drive_goto. A tick is a 64th of a turn, and causes an ActivityBot 360 wheel to roll for 3.25 mm. The valid range is 32 to 128 ticks per second. More...
void	drive_setAcceleration (int forGotoOrSpeed, int ticksPerSecSq)
	Set the acceleration used by either drive_goto or drive_speed. More...
void	drive_gotoMode (int mode)
	Set the mode of the drive_goto call to blocking (default) or interruptible. For calls in interruptible mode, sufficient time must be allowed for the maneuver to complete before issuing another drive_goto or drive_speed call. The drive_gotoStatus function can also be polled to find when a given maneuver is done. More...
int	drive_gotoStatus (int side)
	After using drive_gotoMode(0) to cause the drive_goto function to not wait until the maneuver is done before returning, checking the status of a given maneuver can be useful. This function reports the status of maneuver initiated by the most recent drive_goto call. More...
void	drive_feedback (int enabled)
	Enables or disables encoder feedback for speed control. More...
void	drive_suppress_eeprom (int state)
	Enables or disables ignore calibration settings stored in EEPROM. This feature allows an ActivityBot application to initialize using I/O pins that are different from the ones stored in EEPROM. More...
Deprecated
void	drive_setMaxSpeed (int speed)
	Modifies the default maximum top speed for Feedback 360 high speed servos. For calls to drive_speed, the default is 128 ticks/second = 2 revolutions per second (RPS). This value can be reduced, but not increased. Note: drive_setMaxVelocity is recommended in place of this function. More...
void	drive_setRampStep (int stepsize)
	Overrides the default 12 ticks/second per 50th of a second for ramping. Note: drive_setAcceleration is recommended in place of this function. More...
void	drive_rampStep (int left, int right)
	This function allows your code to ask for a speed repeatedly in a loop, but each time your code asks for that speed, it takes a step toward the speed. This helps cushion sudden maneuvers in sensor navigation, where the conditions might change more rapidly than you would want your ActivityBot 360's speed to change. Note: drive_speed has built-in ramping and is recommended in place of this function. It can be called repeatedly the same way applications call this function. More...
void	drive_ramp (int left, int right)
	This function ramps up to a given speed and blocks execution until the speed is reached. In practice, a call to drive_speed followed by a pause to reach the desired speed will have the same effect but does not have practical applications. More...

Variables
volatile int	abd360_initialized
volatile int	abd360_unitsPerRev
volatile int	abd360_pinCtrlLeft
volatile int	abd360_pinCtrlRight
volatile int	abd360_pinFbLeft
volatile int	abd360_pinFbRight
volatile int	abd360_speedLimit
volatile int	abd360_rampStep
volatile int	abd360_setRampStep
volatile int	abd360_speedLimitGoto
volatile int	abd360_rampStepGoto
volatile int	abd360_gotoMode

Detailed Description

This library provides a simple set of functions for making the ActivityBot 360 go certain distances and speeds.


For more information, go here:

http://learn.parallax.com/activitybot/navigation-basics

Author

Parallax Inc.

Copyright

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

Core Usage

A single additional core takes care of ActivityBot 360 servo angle monitoring, control system algorithm execution, and servo control signaling.

EEPROM Usage

Reads from addresses 63418..65470.

Memory Models

Use with CMM.

Help Improve this Library

Please submit bug reports, suggestions, and improvements to this code to edito.nosp@m.r@pa.nosp@m.ralla.nosp@m.x.co.nosp@m.m.

Definition in file abdrive360.h.

Function Documentation

drive_encoderPins()

void drive_encoderPins	(	int	encPinLeft,
		int	encPinRight
	)

Sets feedback pins to values other than the default P14 for left and P15 for right. Stores values in EEPROM, so you only need to call this function at the start of one program. Programs that are run after that will get the modified port numbers from EEPROM.

IMPORTANT This function should be called before any adbrive360 control functions (drive_speed, drive_goto, etc).

Parameters

encPinLeft	I/O pin number for the left encoder signal connection.
encPinRight	I/O pin number for the right encoder signal connection.

Sets feedback pins to values other than the default P14 for left and P15 for right. Stores values in EEPROM, so you only need to call this function at the start of one program. Programs that are run after that will get the modified port numbers from EEPROM.

IMPORTANT This function should be called first, before any adbrive control functions (drive_speed, drive_goto, etc).

Parameters

encPinLeft	I/O pin number for the left encoder signal connection.
encPinRight	I/O pin number for the right encoder signal connection.

Definition at line 208 of file servoPins.c.

drive_feedback()

void drive_feedback

(

int

enabled

)

Enables or disables encoder feedback for speed control.

Parameters

enabled

Set to 1 to enable feedback (default) or 0 to disable.

Definition at line 5 of file feedback.c.

drive_getTicks()

void drive_getTicks	(	int *	left,
		int *	right
	)

Get the measured number of ticks each servo has traveled since the program started running. Each "tick" is a 64th of a wheel turn, and corresponds to an ActivityBot 360 rolling distance of about 3.25 mm.

Parameters

*left	Pointer to variable to receive the measured left distance.
*right	Pointer to variable to receive the measured right distance.

Get the measured number of ticks each servo has traveled since the program started running. Each "tick" is a 64th of a wheel turn, and corresponds to an ActivityBot 360 rolling distance of about 3.25 mm.

The system samples the encoders at 400 times per second.

Parameters

*left	Pointer to variable to receive the measured left distance.
*right	Pointer to variable to receive the measured right distance.

Definition at line 9 of file getticks.c.

drive_getTicksCalc()

void drive_getTicksCalc	(	int *	left,
		int *	right
	)

Get the calculated number of 1/64th wheel revolution ticks the abdrive360 control system thinks each servo should have traveled.

Parameters

*left	Pointer to variable to receive the measured left distance.
*right	Pointer to variable to receive the measured right distance.

Get the calculated number of 1/64th wheel revolution ticks the abdrive360 control system thinks each servo should have traveled.

The system samples the encoders at 400 times per second.

Parameters

*left	Pointer to variable to receive the calculated left distance.
*right	Pointer to variable to receive the calculated right distance.

Definition at line 15 of file getticks.c.

drive_goto()

void drive_goto	(	int	distLeft,
		int	distRight
	)

Make the wheels travel a certain distance, measured in ticks.
Each "tick" is a 64th of a wheel turn, and corresponds to an ActivityBot 360 rolling distance of about 3.25 mm. Ramp up, cruise, ramp down and stop are coordinated so that different left/right distances result in curves.
Same distances are straight lines, and same distances with opposite +/- signs cause the ActivityBot 360 to turn in place. This function does not return until the maneuver has completed. If needed, you change that default with the drive_gotoMode function. The default cruising speed is 64 ticks/second, which can be adjusted with the drive_setMaxVelocity function.

Parameters

distLeft	Left wheel distance in 1/64th revolution ticks.
distRight	Right wheel distance in ticks.

Make the wheels travel a certain distance, measured in ticks.
Each "tick" is a 64th of a wheel turn, and corresponds to an ActivityBot 360 rolling distance of about 3.25 mm. Ramp up, cruise, ramp down and stop are coordinated so that different left/right distances result in curves.
Same distances are straight lines, and same distances with opposite +/- signs cause the ActivityBot 360 to turn in place. This function does not return until the maneuver has completed. If needed, you change that default with the drive_gotoMode function. The default cruising speed is 64 ticks/second, which can be adjusted with the drive_setMaxVelocity function.

Parameters

distLeft	Left wheel distance in ticks (spoke to space and space to spoke transitions). Each "tick" transition is 1/64th of a wheel revolution, causing the wheel to roll approximately 3.25 mm.
distRight	Right wheel distance in ticks.

Definition at line 38 of file goto.c.

drive_gotoMode()

void drive_gotoMode

(

int

mode

)

Set the mode of the drive_goto call to blocking (default) or interruptible. For calls in interruptible mode, sufficient time must be allowed for the maneuver to complete before issuing another drive_goto or drive_speed call. The drive_gotoStatus function can also be polled to find when a given maneuver is done.

Parameters

mode	Interruptible (0) or blocking (1). By default, the drive_goto function is set to blocking, and does not return until the maneuver has completed.

Set the mode of the drive_goto call to blocking (default) or interruptible. For calls in interruptible mode, sufficient time must be allowed for the maneuver to complete before issuing another drive_goto or drive_speed call. The drive_gotoStatus function can also be polled to find when a given maneuver is done.

Parameters

mode	interruptible (0) or blocking (1). By default the drive_goto function blocks until the maneuver has completed.

Definition at line 5 of file gotoMode.c.

drive_gotoStatus()

int drive_gotoStatus

(

int

side

)

After using drive_gotoMode(0) to cause the drive_goto function to not wait until the maneuver is done before returning, checking the status of a given maneuver can be useful. This function reports the status of maneuver initiated by the most recent drive_goto call.

Parameters

side	with options of SIDE_LEFT, SIDE_RIGHT, or SIDE_BOTH.

Returns

value that corresponds to the 0 (done with last drive_goto maneuver or 1 (maneuver still in progress).

After using drive_gotoMode(0) to cause the drive_goto function to not wait until the maneuver is done before returning, checking the status of a given maneuver can be useful. This function reports the status of maneuver initiated by the most recent drive_goto call.

Parameters

side	with options of SIDE_LEFT, SIDE_RIGHT, or SIDE_BOTH.

Returns

value that corresponds to the 0, 1, 2 status of a maneuver

Definition at line 5 of file gotoStatus.c.

drive_ramp()

void drive_ramp	(	int	left,
		int	right
	)

This function ramps up to a given speed and blocks execution until the speed is reached. In practice, a call to drive_speed followed by a pause to reach the desired speed will have the same effect but does not have practical applications.

Parameters

left	Left wheel speed in ticks per second.
right	Left wheel speed in ticks per second.

This function ramps up to a given speed and blocks execution until the speed is reached. In practice, a call to drive_speed followed by a pause to reach the desired speed will have the same effect but does not have practical applications.

Parameters

left	Left wheel speed in ticks per second.
right	Left wheel speed in ticks per second.

Definition at line 7 of file ramp.c.

Here is the call graph for this function:

drive_rampStep()

void drive_rampStep	(	int	left,
		int	right
	)

This function allows your code to ask for a speed repeatedly in a loop, but each time your code asks for that speed, it takes a step toward the speed. This helps cushion sudden maneuvers in sensor navigation, where the conditions might change more rapidly than you would want your ActivityBot 360's speed to change. Note: drive_speed has built-in ramping and is recommended in place of this function. It can be called repeatedly the same way applications call this function.

Parameters

left	Left wheel speed in ticks per second.
right	Right wheel speed in ticks per second.

This function allows your code to ask for a speed repeatedly in a loop, but each time your code asks for that speed, it takes a step toward the speed. This helps cushion sudden maneuvers in sensor navigation, where the conditions might change more rapidly than you would want your ActivityBot 360's speed to change. Note: drive_speed has built-in ramping and is recommended in place of this function. It can be called repeatedly the same way applications call this function.

Parameters

left	Left wheel speed in ticks per second.
right	Left wheel speed in ticks per second.

Definition at line 5 of file rampStep.c.

Here is the call graph for this function:

drive_servoPins()

void drive_servoPins	(	int	controlPinLeft,
		int	controlPinRight
	)

Sets servo pins to values other than the default P12 for the left servo and P13 for right servo. Stores values in EEPROM, so you only need to call this function at the start of one program. Programs after that will get the modified port numbers from EEPROM.

IMPORTANT: This function should be called before any adbrive360 control functions (drive_speed, drive_goto, etc).

Parameters

controlPinLeft	I/O pin number for the left servo signal connection.
controlPinRight	I/O pin number for the right servo signal connection.

Sets servo pins to values other than the default P12 for the left servo and P13 for right servo. Stores values in EEPROM, so you only need to call this function at the start of one program. Programs after that will get the modified port numbers from EEPROM.

IMPORTANT This function should be called first, before any adbrive control functions (drive_speed, drive_goto, etc).

Parameters

servoPinLeft	I/O pin number for the left servo signal connection.
servoPinRight	I/O pin number for the right servo signal connection.

Definition at line 188 of file servoPins.c.

drive_setAcceleration()

void drive_setAcceleration	(	int	forGotoOrSpeed,
		int	ticksPerSecSq
	)

Set the acceleration used by either drive_goto or drive_speed.

Parameters

forGotoOrSpeed	can be set to FOR_SPEED (0) or FOR_GOTO (1).
ticksPerSecSq	The ticks per second squared value to set the acceleration that speed and goto calls use. The default is 600 for drive_speed and 400 for drive_goto. Use increments of 50, up to 2000.
forGotoOrSpeed	can be set to FOR_SPEED (0) or FOR_GOTO (1).
ticksPerSecSq	The ticks per second squared value to set the acceleration speed and goto calls use. The default is 600 for drive_speed and 200 for drive_goto. Use increments of 50.

Definition at line 15 of file setAcceleration.c.

drive_setMaxSpeed()

void drive_setMaxSpeed

(

int

speed

)

Modifies the default maximum top speed for Feedback 360 high speed servos. For calls to drive_speed, the default is 128 ticks/second = 2 revolutions per second (RPS). This value can be reduced, but not increased. Note: drive_setMaxVelocity is recommended in place of this function.

Parameters

speed

Maximum cruising speed for drive_speed.

Modifies the default maximum top speed for Feedback 360 high speed servos. For calls to drive_speed, the default is 128 ticks/second = 2 revolutions per second (RPS). This value can be reduced, but not increased. Note: drive_setMaxVelocity is recommended in place of this function.

Parameters

speed

Maximum cruising speed for drive_distance and drive_goto.

Definition at line 5 of file setMaxSpeed.c.

drive_setMaxVelocity()

void drive_setMaxVelocity	(	int	forGotoOrSpeed,
		int	ticksPerSec
	)

Set the maximum velocity used by either drive_goto or drive_speed.
The defaults are 128 ticks per second for drive_speed, and 64 ticks per second for drive_goto. A tick is a 64th of a turn, and causes an ActivityBot 360 wheel to roll for 3.25 mm. The valid range is 32 to 128 ticks per second.

Parameters

forGotoOrSpeed	can be set to FOR_SPEED (0) or FOR_GOTO (1).
ticksPerSec	The ticks per second value that limits the top velocity, regardless of what calls to drive_speed ask for. The default is 128 for drive_speed and 64 for drive_goto. 128 is the maximum possible.

Set the maximum velocity used by either drive_goto or drive_speed.
The defaults are 128 ticks per second for drive_speed, and 64 ticks per second for drive_goto. A tick is a 64th of a turn, and causes an ActivityBot 360 wheel to roll for 3.25 mm. The valid range is 32 to 128 ticks per second.

Parameters

forGotoOrSpeed	can be set to FOR_SPEED (0) or FOR_GOTO (1).
ticksPerSec	The ticks per second value that limits the top velocity, regardless of what calls to drive_speed ask for. The default is 128 for drive_speed and 64 for drive_goto.

Definition at line 13 of file setMaxSpeed.c.

drive_setRampStep()

void drive_setRampStep

(

int

stepsize

)

Overrides the default 12 ticks/second per 50th of a second for ramping. Note: drive_setAcceleration is recommended in place of this function.

Parameters

stepsize

The size of each step in ticks/second to change every 50th of a second

Overrides the default 12 ticks/second per 50th of a second for ramping. Note: drive_setAcceleration is recommended in place of this function.

Parameters

stepsize

The size of each step in ticks/second to change every 50th of a second

Definition at line 5 of file setRampStep.c.

drive_speed()

void drive_speed	(	int	left,
		int	right
	)

Set wheel speeds in "ticks" per second. A tick is 1/64th of a revolution, and makes an ActivityBot 360 wheel roll 3.25 mm. The maximum speed for each wheel is +/- 128 ticks/second. Positive values are for forward motion; negative values are for reverse.

Parameters

left	Left wheel speed in ticks per second.
right	Right wheel speed in ticks per second.

Set wheel speeds in "ticks" per second. A tick is 1/64th of a revolution, and makes an ActivityBot 360 wheel roll 3.25 mm. The maximum speed for each wheel is +/- 128 ticks/second. Positive values are for forward motion; negative values are for reverse.

Parameters

left	Left wheel speed in ticks per second.
right	Left wheel speed in ticks per second.

Definition at line 138 of file speed.c.

drive_suppress_eeprom()

void drive_suppress_eeprom

(

int

state

)

Enables or disables ignore calibration settings stored in EEPROM.
This feature allows an ActivityBot application to initialize using I/O pins that are different from the ones stored in EEPROM.

Parameters

enabled

Set to 1 to enable or 0 (default) to disable.

Definition at line 40 of file abdrive360.c.