ActivMedia Robot Communication Protocol

What is the ActivMedia Robot Communication Protocol?

The ActivMedia Robot Communication Protocol is the serial packet protocol used to communicate with and command the robot hardware on most ActivMedia robots such as the AmigoBot and the Pioneer. Specifically, robots using the AmigOS and P2OS operating systems use the protocol described by this document.

Using the ActivMedia Robot Communication Protocol allows you to control the motion and operation of an ActivMedia robot from any device that has a serial port and can properly form the packets. For example, this means that you can directly control an AmigoBot or Pioneer robot from a BasicStamp or BasicX, an Atmel AVR processor, a PC, a handheld device (like a Palm Pilot) and many other devices.

When commanding the robot using this protocol, you can:

• Enable and disable the motors
• Drirectly set the speed of the robot's motors (to drive forward/backward/turn)
• Make the robot drive a specified distance
• Make the robot turn a specified amount
• Make the robot play a sound or say a phrase (if this is supported)
• Enable and disable the sonars

It is also possible (but not necessary) to receive packets from the robot to get information such as:

• Robot status
• Range readings from the sonars
• Auxiliary sensor or user hardware readings
• Battery voltage readings

How to make the serial connection to the robot:

As previously mentioned, ActivMedia robots are controlled via a serial port on the robot. This serial port must be connected to a controller which issues the robot movement commands. The controller can be any device which also has a serial port and is capable of properly forming the packets. Example controllers might include PCs, AVR & PIC processors, BasicStamps, BasicX processors, handheld PCs, etc.

• To connect to a Pioneer robot:
  • The control serial port is located on the top of the robot near the Power LED and Reset Button.
  • Connect a serial cable between your controller's serial port and the robot serial port.
  • Your controller must use the baud rate that the robot is expecting. The robot's LCD usually displays the expected baud rate. The default is 9600bps.
• To connect to an AmigoBot robot:
  • The control serial port is located on the underside of the robot near the front. The port is typically plugged into a radiomodem.
  • Connect a serial cable between your controller's serial port and the robot serial port. Disconnect the radiomodem if necessary.
  • Your controller must use the baud rate that the robot is expecting. AmigoBots can operate at 9600, 19200, or 38400 baud. To find out what the current setting is, or to change it, you must use a special program and cable which came with the AmigoBot. Refer to the AmigoBot Technical Manual.

The Communication Protocol:

All robot packets have the following elements and structure:

• Header - indicates the start of a packet
• Length - the number of bytes in the packet (length of user data in bytes + 2 bytes for the checksum)
• Data - this is the user data being sent
• Checksum - see description below

The checksum is calculated according to the following rules:

1. Group the user data into 2 byte pairs to form 16-bit integers, high byte first, low byte second.
2. Sum these integers to get the checksum (discard any bits above 16)
3. If there are an odd number of bytes, take the last byte and XOR it with the checksum

The result of these steps is your packet's checksum. Place the checksum result into your packet with the high byte first and the low byte second [CSH,CSL]. The checksum allows the robot to verify that your packet is valid and error-free. You must calculate the checksum properly otherwise the robot will ignore your packet.

How to send Commands:

• Command Number - 1-byte number of the command you are issuing
• Argument Type - 1-byte number indicating the kind of argument
• Argument - n-bytes of argument data for the command

A complete packet with a command with no arguments:

A complete packet with a command with an integer argument:

A complete packet with a command with a string argument:

Command Reference:

The table below provides a list of typically-used commands, their required arguments, and a description of their function:

Example Code for Sending Commands:

BasicX code for commanding ActivMedia robots:

[an error occurred while processing this directive]

Download this example code:
Example usage, above [arrobottest_basicx.bas]
ArRobot Code Module (required for above code) [arrobot_basicx.bas]