Kangaroo Library for Arduino
Use reliable Packet Serial to communicate with your Kangaroo.
Public Member Functions | List of all members
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
serialThe KangarooSerial whose serial port the controller is on.
nameThe 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'.
addressThe 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
baudRateThe 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
intervalMSThe 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
timeoutMSThe command timeout, in milliseconds.
KangarooStatus KangarooChannel::get ( KangarooGetType  type,
KangarooGetFlags  flags = KANGAROO_GET_DEFAULT 
)

Issues a 'get' request.

Parameters
typeThe type of the 'get' request.
flagsFlags 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
flagsFlags 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
flagsFlags 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
flagsFlags 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
flagsFlags 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
flagsFlags 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
flagsFlags 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
positionThe position to move to.
speedLimitThe speed limit for the move.
flagsModifiers 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
positionIncrementThe amount to increment the current position by.
speedLimitThe speed limit for the move.
flagsModifiers 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
velocityThe speed to move at.
rampLimitThe max rate at which to change the commanded speed.
flagsModifiers 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
millisecondsThe 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
velocityIncrementThe amount to increment the current speed by.
rampLimitThe max rate at which to change the commanded speed.
flagsModifiers 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
systemCommandThe command to set.
expectReplyWhether 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.
valuesThe parameters of the command.
valueCountThe 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
desiredUnitsThe amount in your units that correspond to the specified amount of machine units.
machineUnitsThe 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.