KangarooChannel Class Reference

Lets you send commands to and get position, speed, etc. for a specific channel of the Kangaroo. More...

Public Member Functions
	KangarooChannel (KangarooSerial &serial, char name, byte address=KANGAROO_DEFAULT_ADDRESS)
char	name () const
byte	address () const
KangarooError	start ()
KangarooError	units (int32_t desiredUnits, int32_t machineUnits)
KangarooMonitor	home ()
KangarooMonitor	p (int32_t position, int32_t speedLimit=KANGAROO_UNSPECIFIED_LIMIT, KangarooMoveFlags flags=KANGAROO_MOVE_DEFAULT)
KangarooMonitor	pi (int32_t positionIncrement, int32_t speedLimit=KANGAROO_UNSPECIFIED_LIMIT, KangarooMoveFlags flags=KANGAROO_MOVE_DEFAULT)
KangarooMonitor	s (int32_t velocity, int32_t rampLimit=KANGAROO_UNSPECIFIED_LIMIT, KangarooMoveFlags flags=KANGAROO_MOVE_DEFAULT)
KangarooMonitor	si (int32_t velocityIncrement, int32_t rampLimit=KANGAROO_UNSPECIFIED_LIMIT, KangarooMoveFlags flags=KANGAROO_MOVE_DEFAULT)
KangarooStatus	get (KangarooGetType type, KangarooGetFlags flags=KANGAROO_GET_DEFAULT)
KangarooStatus	getP (KangarooGetFlags flags=KANGAROO_GET_DEFAULT)
KangarooStatus	getPI (KangarooGetFlags flags=KANGAROO_GET_DEFAULT)
KangarooStatus	getS (KangarooGetFlags flags=KANGAROO_GET_DEFAULT)
KangarooStatus	getSI (KangarooGetFlags flags=KANGAROO_GET_DEFAULT)
KangarooStatus	getMin (KangarooGetFlags flags=KANGAROO_GET_DEFAULT)
KangarooStatus	getMax (KangarooGetFlags flags=KANGAROO_GET_DEFAULT)
int32_t	commandRetryInterval () const
void	commandRetryInterval (int32_t intervalMS)
int32_t	commandTimeout () const
void	commandTimeout (int32_t timeoutMS)
boolean	streaming () const
void	streaming (boolean enabled)
void	baudRate (int32_t baudRate)
KangarooError	powerDown ()
KangarooError	powerDownAll ()
KangarooError	serialTimeout (int32_t milliseconds)
KangarooError	systemCommand (KangarooSystemCommand systemCommand, boolean expectReply, int32_t values[], size_t valueCount)

Detailed Description

Lets you send commands to and get position, speed, etc. for a specific channel of the Kangaroo.

Any number of KangarooChannel objects can be associated with a single KangarooSerial object.

Examples:

1.Basics/MixedMode/MixedMode.ino, 1.Basics/Movement/Movement.ino, 1.Basics/SpeedControl/SpeedControl.ino, 2.Settings/SerialTimeout/SerialTimeout.ino, 3.Advanced/PowerDown/PowerDown.ino, 3.Advanced/ProgrammaticTune/ProgrammaticTune.ino, and 3.Advanced/Streaming/Streaming.ino.

Constructor & Destructor Documentation

KangarooChannel::KangarooChannel	(	KangarooSerial &	serial,
		char	name,
		byte	address = KANGAROO_DEFAULT_ADDRESS
	)

Constructs a KangarooChannel object.

Parameters

serial	The KangarooSerial whose serial port the controller is on.
name	The name of the channel (a single character). By default, mixed mode channels are 'D' (Drive) and 'T' (Turn). Independent mode channels are '1' and '2'. You can change these in DEScribe. Mainly this is useful if you have multiple Kangaroos daisy-chained and have 'Enable multi-Kangaroo mode (shared signal lines).' checked, or if your particular application would be clearer if for instance the channels were named 'X', 'Y', and 'Z'.
address	The Packet Serial address of the controller. Normally this can be left at its default. If you daisy-chain the TX/S1 line between your Kangaroo and a Sabertooth or SyRen motor driver set in Packet Serial, however, make sure they aren't both using the same address.

Member Function Documentation

byte KangarooChannel::address ( ) const

inline

Gets the Packet Serial address of the controller.

Returns

The packet serial address of the controller.

void KangarooChannel::baudRate

(

int32_t

baudRate

)

Sets the baud rate. This affects all channels of the controller that receives the command.

Parameters

baudRate

The baud rate to use. Supported rates are 9600, 19200, 38400, and 115200.

int32_t KangarooChannel::commandRetryInterval ( ) const

inline

Gets the command retry interval.

Returns

The command retry interval, in milliseconds.

void KangarooChannel::commandRetryInterval ( int32_t  intervalMS )

inline

Sets the command retry interval.

Parameters

intervalMS

The command retry interval, in milliseconds.

int32_t KangarooChannel::commandTimeout ( ) const

inline

Gets the command timeout.

Returns

The command timeout, in milliseconds.

void KangarooChannel::commandTimeout ( int32_t  timeoutMS )

inline

Sets the command timeout.

Parameters

timeoutMS

The command timeout, in milliseconds.

KangarooStatus KangarooChannel::get	(	KangarooGetType	type,
		KangarooGetFlags	flags = KANGAROO_GET_DEFAULT
	)

Issues a 'get' request.

Parameters

type	The type of the 'get' request.
flags	Flags modifying the 'get' request.

Returns

A KangarooStatus object describing the response.

KangarooStatus KangarooChannel::getMax ( KangarooGetFlags  flags = KANGAROO_GET_DEFAULT )

inline

Gets the maximum position. This corresponds to DEScribe's Nominal Travel maximum.

Parameters

flags

Flags modifying the 'get' request.

Returns

A KangarooStatus object describing the limit.

KangarooStatus KangarooChannel::getMin ( KangarooGetFlags  flags = KANGAROO_GET_DEFAULT )

inline

Gets the minimum position. This corresponds to DEScribe's Nominal Travel minimum.

Parameters

flags

Flags modifying the 'get' request.

Returns

A KangarooStatus object describing the limit.

KangarooStatus KangarooChannel::getP ( KangarooGetFlags  flags = KANGAROO_GET_DEFAULT )

inline

Gets the absolute position.

Parameters

flags

Flags modifying the 'get' request.

Returns

A KangarooStatus object describing the position.

KangarooStatus KangarooChannel::getPI ( KangarooGetFlags  flags = KANGAROO_GET_DEFAULT )

inline

Gets the incremental position (relative to the position when the last command was issued).

Parameters

flags

Flags modifying the 'get' request.

Returns

A KangarooStatus object describing the position.

KangarooStatus KangarooChannel::getS ( KangarooGetFlags  flags = KANGAROO_GET_DEFAULT )

inline

Gets the absolute speed (positive or negative depending on direction).

Parameters

flags

Flags modifying the 'get' request.

Returns

A KangarooStatus object describing the speed.

KangarooStatus KangarooChannel::getSI ( KangarooGetFlags  flags = KANGAROO_GET_DEFAULT )

inline

Gets the incremental speed (relative to the speed when the last command was issued).

Parameters

flags

Flags modifying the 'get' request.

Returns

A KangarooStatus object describing the speed.

KangarooMonitor KangarooChannel::home

(

)

Homes the channel.

Returns

A KangarooMonitor for tracking the homing request. The easiest way to use the KangarooMonitor here is to call KangarooMonitor::wait().

char KangarooChannel::name ( ) const

inline

Gets the channel name.

Returns

The channel name.

KangarooMonitor KangarooChannel::p	(	int32_t	position,
		int32_t	speedLimit = KANGAROO_UNSPECIFIED_LIMIT,
		KangarooMoveFlags	flags = KANGAROO_MOVE_DEFAULT
	)

Moves to the specified absolute position. This command is most useful for absolutely-positioned systems.

Parameters

position	The position to move to.
speedLimit	The speed limit for the move.
flags	Modifiers for the move command.

Returns

A KangarooMonitor for tracking the move request.

KangarooMonitor KangarooChannel::pi	(	int32_t	positionIncrement,
		int32_t	speedLimit = KANGAROO_UNSPECIFIED_LIMIT,
		KangarooMoveFlags	flags = KANGAROO_MOVE_DEFAULT
	)

Makes an incremental move. This command is useful any time you want to make a motion relative to where you are right now. Rovers are a case where this is almost always what you want.

Parameters

positionIncrement	The amount to increment the current position by.
speedLimit	The speed limit for the move.
flags	Modifiers for the move command.

Returns

A KangarooMonitor for tracking the move request.

KangarooError KangarooChannel::powerDown

(

)

Powers down the channel.

Returns

A KangarooError, usually KANGAROO_NO_ERROR.

KangarooError KangarooChannel::powerDownAll

(

)

Powers down all channels of the controller that receives the command.

Returns

A KangarooError, usually KANGAROO_NO_ERROR.

KangarooMonitor KangarooChannel::s	(	int32_t	velocity,
		int32_t	rampLimit = KANGAROO_UNSPECIFIED_LIMIT,
		KangarooMoveFlags	flags = KANGAROO_MOVE_DEFAULT
	)

Moves at a particular speed.

Parameters

velocity	The speed to move at.
rampLimit	The max rate at which to change the commanded speed.
flags	Modifiers for the move command.

Returns

A KangarooMonitor for tracking the move request.

KangarooError KangarooChannel::serialTimeout

(

int32_t

milliseconds

)

Sets the serial timeout. This affects all channels of the controller that receives the command.

Parameters

milliseconds

The timeout, in milliseconds. A value of zero uses the DEScribe setting. KANGAROO_INFINITE_TIMEOUT disables the timeout.

Returns

A KangarooError, usually KANGAROO_NO_ERROR.

KangarooMonitor KangarooChannel::si	(	int32_t	velocityIncrement,
		int32_t	rampLimit = KANGAROO_UNSPECIFIED_LIMIT,
		KangarooMoveFlags	flags = KANGAROO_MOVE_DEFAULT
	)

Moves at a particular speed, incremental from the current speed. This is useful for cruise control: a negative increment will slow down, a positive increment will speed up, and a zero increment will hold the current speed.

Parameters

velocityIncrement	The amount to increment the current speed by.
rampLimit	The max rate at which to change the commanded speed.
flags	Modifiers for the move command.

Returns

A KangarooMonitor for tracking the move request.

KangarooError KangarooChannel::start

(

)

Starts the channel. Also, the Kangaroo LED will shine brightly for a third of a second.

Returns

A KangarooError. Most commonly, this will be KANGAROO_NO_ERROR if the channel does not require homing, or KANGAROO_NOT_HOMED if it does.

boolean KangarooChannel::streaming ( ) const

inline

Gets whether streaming is enabled.

Returns

True if streaming is enabled.

void KangarooChannel::streaming ( boolean  enabled )

inline

Enables or disables streaming. When streaming is disabled (the default), commands are delivered reliably: a request is sent to the Kangaroo after every command to make sure the command was received. When streaming is enabled, commands are delivered unreliably: no effort is made to verify that they are received.

If you are constantly sending position or speed commands, you may not care if an intermediate one is lost. Enabling streaming can more than double your command rate, at the cost of reduced reliability. If you only have a transmit line and no way to receive data back from the Kangaroo, you should enable streaming. KangarooMonitor::wait() cannot be meaningfully called for a command that was streamed.

KangarooError KangarooChannel::systemCommand	(	KangarooSystemCommand	systemCommand,
		boolean	expectReply,
		int32_t	values[],
		size_t	valueCount
	)

Sends a system command. These are mostly for advanced use cases.

Parameters

systemCommand	The command to set.
expectReply	Whether or not to expect a reply. If a command has an unusual effect on the state of the Kangaroo, expecting a reply may cause the command to retry until it times out.
values	The parameters of the command.
valueCount	The number of parameters.

Returns

A KangarooError.

KangarooError KangarooChannel::units	(	int32_t	desiredUnits,
		int32_t	machineUnits
	)

Sets custom units for the channel. This command may be called after you start the channel but before you home it. If you do not set custom units, the units you have set up in DEScribe will be used. If you haven't set any, machine units will be used.

Parameters

desiredUnits	The amount in your units that correspond to the specified amount of machine units.
machineUnits	The amount of machine units (millivolts or lines) corresponding to the specified amount in your units.

Returns

A KangarooError. Most commonly, this will be KANGAROO_NO_ERROR if the channel does not require homing, or KANGAROO_NOT_HOMED if it does.