Kangaroo Packet Serial Reference Manual Copyright © 2013 Dimension Engineering LLC
Table of Contents Simplified or Packet Serial? ....................................................... 3 Software Libraries ....................................................................... 4 Packet Format ............................................................................ 5 Example Code ........................................................................................... 6 Channel Names ........................................................................... 8 Commands ............
Simplified or Packet Serial? Kangaroo supports two serial protocols, Simplified Serial and Packet Serial: Simplified Serial An extremely easy way to interact with the Kangaroo from a microcontroller or PC. For example, if you open up a terminal at 9600 baud (8-N-1), and have tuned channel 1 in Independent Mode, the following is actually a completely working sequence of commands: 1,START 1,HOME 1,GETMIN 1,GETMAX 1,P123 1,GETP Mixed mode (tank-style) is similarly easy.
Software Libraries We provide Packet Serial libraries for several platforms: Arduino http://www.dimensionengineering.com/arduino C#, VB.NET, and other .NET Framework languages http://www.dimensionengineering.
Packet Format General Layout Kangaroo packets have the following form: Address (1 byte) The Kangaroo address. By default, this is 128. Address bytes have the high bit set. Command (1 byte) The command number. Data Length (1 byte) The number of bytes n of data. Data (n bytes) The command data. CRC (2 bytes) See the Example Code section. A 14-bit CRC computed from the address (excluding its high bit), command, data length, and data.
Example Code #include /*! Bit-packs a number. \param buffer The buffer to write into. \param number The number to bit-pack. Should be between -(2^29-1) and 2^29-1. \return How many bytes were written (1 to 5).
\param data The command data. \param length The number of bytes of data. \param buffer The buffer to write into. \return How many bytes were written. This always equals 4 + length.
Channel Names Each channel of the Kangaroo has a single-character name. These can be changed with DEScribe. By default, in Independent Mode, the channel names are '1' and '2'. In Mixed Mode, they are 'D' (Drive) and 'T' (Turn).
Commands Closed-Loop Kangaroo supports a variety of commands, detailed in the various pages here. Open-Loop Sabertooth-style open-loop commands are also supported. These can be used if you need to temporarily run a channel open-loop. See the Sabertooth documentation for open-loop packet format and command information. Start Starts a channel. Also, the Kangaroo LED will shine brightly for a third of a second. You must call this before Units, Home, or Move commands will work.
Machine Units (bit-packed number) The amount of machine units (millivolts or lines) corresponding to the specified amount in your units. Home Homes a channel. Channels that require homing will ignore Move commands until they have homed. Command Format The command number for Home is 34. Its data is: Channel Name (1 byte) Flags (1 byte) 0 for no options. 64 if a sequence code is used. Sequence Code (optional, 1 byte) Move Tells the controller to do a motion. Command Format The command number for Move is 36.
Value (bit-packed number) The value for the parameter. Get Gets the current value of a parameter from the controller. Command Format The command number for Get is 35. Its data is: Channel Name (1 byte) Flags (1 byte) 0 for no options. 16 if an echo code is used. It will be sent with the reply. 32 to use raw units. For analog, raw units are millivolts. For quadrature, 4 raw units equal 1 line. 64 for a sequence code to be sent with the reply. Add these to combine options.
Value (bit-packed number) The current value of the parameter. Error Codes Get can return a number of errors: 0 No error occurred. 1 The channel is not started. Command Start on the channel. 2 The channel needs to be homed. Command Home on the channel. 3 A control error has occurred. Command Start on the channel to clear the control error. 4 The controller is in the wrong mode. For example, the DIP switches may be in mixed mode while the tune was done in independent mode. 5 The parameter is unknown.
Sequence Code (optional, 1 byte) System Command Number (1 byte) Parameter(s) (bit-packed numbers) System commands use zero or more bit-packed numbers for all of their parameters. Power Down Powers down the channel. System Command Format The system command number is 0. It has no parameters. Power Down All Powers down all channels of the controller that receives the command. System Command Format The system command number is 1. It has no parameters. Set Baud Rate Sets the baud rate.
Tuning The Packet Serial tuning commands can be used to initiate a tune without touching the Autotune button. This is useful for systems where the Kangaroo is physically inaccessible. DEScribe uses these same commands, and so can be used to initiate a tune remotely without any programming. Enter Mode Enters the desired tune mode. This corresponds to pressing the tune button multiple times to get into the mode you want. System Command Format The system command number is 3.
Go Begins the tune. This corresponds to pressing the tune button after you are in the desired mode. Tuning has an automatic serial timeout for safety reasons. You must continually send packets or it will abort. Get commands in a loop will do the job. System Command Format The system command number is 4. It has no parameters. Abort Aborts the tune. System Command Format The system command number is 5. It has no parameters.
On the Web Click the following link to visit our main website: Dimension Engineering If you have questions, we can be reached via either of the following: Help Desk Contact Us Also, here are some software links you may find useful: DEScribe Libraries for Arduino Libraries for C# and .
Revision History March 29, 2013: Initial public version of the Packet Serial Reference. September 10, 2013: Corrected the buffer length in the C example code.
Index A Arduino 4, 16 B baud rate 2, 13 bit-packed numbers 5, 13 C C# 4, 16 channel names 2, 8 CRC 3, 5, 6, 7 E echo code 5, 11 error codes 2, 12 example code 2, 5, 6, 17 G Get command 5 H Home command 10 L libraries 2, 3, 4, 16 M Move command 7 P packet format 2, 5, 9 Power Down All command 13 Power Down command 13 S sequence code 5, 9, 10, 11, 12, 13 serial timeout 2, 12, 13, 15 Set Baud Rate command 13 Set Serial Timeout command 13 Simplified Serial 3 Start command 9 system commands 13 T tuning
VB.
