ActivMedia Robotics Pioneer 2 Arm User manual

Pioneer2Arm

ii
Copyright © 2001, ActivMedia Robotics, LLC. All rights reserved.
Under international copyright laws, this manual or any portion of it may not be copied or
in any way duplicated without the expressed written consent of ActivMedia Robotics.
The software on disk and on the microcontroller ROM, which accompany the Pioneer 2
Arm and are available for network download by ActivMedia Robotics customers, are
solely owned and copyrighted or are licensed products distributed by ActivMedia
Robotics.
Developers and users are authorized by revocable license to develop and operate
custom software for personal research and educational use only. Duplication,
distribution, reverse-engineering, or commercial application of the ActivMedia Robotics
or licensed software and hardware without the expressed written consent of ActivMedia
Robotics is explicitly forbidden.
The various names and logos for products used in this manual are often registered
trademarks or trademarks of their respective companies. Mention of any third-party
hardware or software constitutes neither an endorsement nor a recommendation.
ActivMedia Robotics Pioneer 2 Arm Manual v1, October 2001

ActivMedia Robotics
iii
Important Safety Instructions
! Read the installation and operations instructions before using the equipment.
! Avoid using power extension cords.
! To prevent fire or shock hazard, do not expose the equipment to rain or moisture.
! Refrain from opening the unit or any of its accessories.
! Keep equipment away from hair or fur.
Inappropriate Operation
Inappropriate operation voids your warranty! Inappropriate operation includes, but is
not limited to:
! Dropping the equipment
! Overloading the Arm above its payload capacity
! Getting the equipment wet
! Continuing to run the equipment after hair, yarn, string, or any other items have
become wound in one or more of its joints
! All other forms of inappropriate operation or care

iv
Table of Contents
CHAPTER 1 INTRODUCTION.................................................................................................................1
THE PIONEER 2 PLATFORM..........................................................................................................................1
THE PIONEER 2 ARM....................................................................................................................................1
CONTROL HARDWARE AND SOFTWARE .......................................................................................................2
ARM PACKAGE ............................................................................................................................................2
Basic Components (all shipments)..........................................................................................................2
User-Supplied Components / System Requirements................................................................................3
ADDITIONAL RESOURCES ............................................................................................................................3
Software ..................................................................................................................................................3
Newsgroups.............................................................................................................................................4
Support....................................................................................................................................................4
CHAPTER 2 INSTALLATION & OPERATION.....................................................................................5
MOUNTING THE ARM TO YOUR PIONEER 2 ROBOT......................................................................................5
POWER TO THE ARM ....................................................................................................................................6
Arm Safety at Home ................................................................................................................................6
SOFTWARE...................................................................................................................................................7
Generic versus P2OS Server Programming............................................................................................7
DEMONSTRATION AND DEVELOPMENT SOFTWARE......................................................................................7
P2ArmDemo............................................................................................................................................7
SAFETY WATCHDOGS ..................................................................................................................................8
Power and Connection-Related Automatic Shutdown ............................................................................8
Timed Shutdown......................................................................................................................................8
Gripper Release Timer............................................................................................................................9
Warm Reset.............................................................................................................................................9
CHAPTER 3 PROGRAMMING...............................................................................................................10
GENERIC CONTROLS..................................................................................................................................10
Generic Control Mode Commands .......................................................................................................10
Generic Servo Positioning Mode Commands .......................................................................................11
P2OS HOST to AUX Serial Port Communications...............................................................................11
P2OS ARM SERVERS.................................................................................................................................11
P2OS ARM COMMANDS ............................................................................................................................12
ARM_INFO and ARMINFOpac............................................................................................................13
ARM_STAT and ARMpac......................................................................................................................13
ARM_POWER.......................................................................................................................................14
ARM_SPEED and ARM_POS...............................................................................................................14
ARM_SPEED Limits.............................................................................................................................14
ARM_HOME and ARM_PARK............................................................................................................15
ARM_INIT, ARM_CHECK, and Warm Reset Protocol ........................................................................15
SAPHIRA PLUGIN .......................................................................................................................................16
CHAPTER 4 ARM FLASH PARAMETERS ..........................................................................................18
ARM PARAMETERS ....................................................................................................................................18
WHERE TO GET P2OS SOFTWARE .............................................................................................................18

ActivMedia Robotics
v
INSTALLING THE P2OS UTILITIES .............................................................................................................18
CONFIGURING P2OS OPERATING PARAMETERS........................................................................................ 19
Step 1. Serial Connection from Computer to Robot..............................................................................19
Step 2: Enable FLASH..........................................................................................................................19
Step 3: Put Microcontroller into Download Mode...............................................................................19
Step 4: Run p2oscf................................................................................................................................19
Step 5: Changing Configuration Parameters .......................................................................................20
Step 6: Save Your Work........................................................................................................................ 20
EDITING P2OS ARM PARAMETERS............................................................................................................ 21
CHAPTER 5 MAINTENANCE & REPAIR............................................................................................23
FACTORY REPAIRS ....................................................................................................................................23
APPENDIX A.............................................................................................................................................. 24
SPECIFICATIONS ...............................................................................................................................24
INDEX.........................................................................................................................................................25
WARRANTY & LIABILITIES ................................................................................................................ 26

vi

ActivMedia Robotics
1
Chapter 1 Introduction
IntroductionIntroduction
Introduction
Congratulations on your purchase of ActivMedia Robotics’ multi-jointed Arm for the
Pioneer 2 family of mobile robots.
This manual provides both the general and technical details you need to operate your
Pioneer 2 Arm and to begin developing your own control software integrated with other
mobile robot activities.
The Pioneer 2 Platform
Pioneers are small, intelligent mobile
robots originally designed by Kurt
Konolige, PhD, of SRI International, Inc.,
and available exclusively through
ActivMedia Robotics, LLC. The basic
Pioneer 2 platform contains all of the
components of an intelligent mobile
robot for sensing and navigation in a
real-world environment, including battery
power, drive motors and wheels, position
encoders, and range-finding ultrasonic
sonar transducers—all managed via an
onboard Siemens C166-based micro-
controller board.
The Pioneer 2-DX, DXE, PeopleBot, and CE models are two-wheel, differential-drive
mobile robots intended for indoor, albeit less-than-ideal surface operation (wheel-chair
accessible areas, for example). The Pioneer 2-AT is a four-wheel drive, differential skid-
steering version intended for outdoor, all-terrain (AT) operation. Otherwise, the platforms
are nearly identical and share accessories, including the Pioneer 2 Arm.
All Pioneers come with onboard robotics server software (Pioneer 2 Operating System)
and an open API for client software control of the robot’s systems and accessories. Users
access the onboard servers through an RS-232 serial communication port from their client
workstation connected wirelessly, or via a piggyback laptop or integrated onboard PC.
The Pioneer 2 Arm
The Pioneer 2 Arm is an accessory for Pioneer 2-DX/DXE and AT robots. It is relatively low-
cost for use in research and in the classroom. Driven by six open-loop servo motors, the
five degrees-of-freedom (5-DOF) Pioneer 2 Arm’s end-effector is a gripper whose foam-
lined fingers allow for firm grasp and manipulation of objects as large as a soda can and
as heavy as 150 grams throughout the arm’s envelope of operation.
Joints include:
! rotating base
! pivoting shoulder
! pivoting elbow
! rotating wrist
! pivoting gripper mount
! gripper fingers
All servo-driven joints, except for the gripper fingers, pivot or rotate at least 180 degrees.
Mounted to the front of the robot’s top plate, the Pioneer 2 Arm has a very wide
envelope of operation, reaching 50 centimeters from the center of its rotating base to
Figure 1. The Pioneer 2 Arm

Introduction
2
the tip of its closed fingers. The Pioneer 2 Arm’s reach, therefore, lets you pick up objects
from the floor in front of your Pioneer 2 robot and place them on its back.
Control Hardware and Software
The Pioneer 2 Arm comes with its manufacturer’s PIC-based controller and servo-driver
hardware and software. These are housed inside the DX/DXE on top of the battery box
or inside a special “backpack” accessory that is mounted at the rear of the Pioneer 2-AT
robot’s top-plate. The backpack also holds two 12 volts, direct-current (VDC) batteries
for additional power to the Arm and the AT’s systems.
The Pioneer 2 Arm’s controller is attached to the Pioneer 2 microcontroller’s AUX serial
port and supported by generic (“pass-through”), as well as custom Pioneer 2 Operating
System (P2OS) servers. Your client software communicates with and controls the Arm
through these P2OS servers.
Arm Package
Your Pioneer 2 Arm is factory installed. Our experienced manufacturing staff put your
Pioneer 2 Arm and its support accessories through a “burn in” period and carefully tested
them before shipping the products to you. We detach the Arm itself from the robot and
ship them separately for safety.
Even though we’ve made every effort to make your Arm package complete, please
check the components carefully after you unpack them from the shipping crate.
Basic Components (all shipments)
! This manual
! One fully assembled Pioneer 2 5-DOF Arm
! Arm control electronics, signal and power cabling installed in your robot
! Arm power “backpack” installed on the Pioneer 2-AT
! Mounting hardware and cabling
! CD-ROM containing P2OS updated for Arm support, Arm demonstration and
development software, and documentation
Figure 2. The Pioneer 2 Arm’s horizontal reach

ActivMedia Robotics
3
User-Supplied Components / System Requirements
! Tools for attaching the arm to the robot1
! Client-side PC and robot software, such as ARIA or Saphira
Additional Resources
New ActivMedia Robotics Pioneer 2 and PeopleBot customers get three additional and
valuable resources:
! A private account on our Internet server for software, updates, and manuals
! Access to private robotics newsgroups
! Direct access to the ActivMedia Robotics technical support team
Software
We maintain a 24-hour, seven-day per week Web server where customers may obtain
software and support materials:
http://robots.activmedia.com
Some areas of the website are restricted to licensed customers. To gain access, enter
the username and password written on the Registration & Account Sheet that
accompanied your ActivMedia robot.
1The required tools, particularly the hex wrenches, come with the robot.
Figure 3. Pioneer 2 Arm's vertical reach

Introduction
4
Newsgroups
We maintain several email-based newsgroups through which ActivMedia robot owners
share ideas, software, and questions about the robot and accessories, such as your new
Arm. Visit the support http://robots.activmedia.com website for more details.
To sign up for pioneer-users, for example, send an e-mail message to the –requests
automated newsgroup server:
To: pioneer-users-reques[email protected]
From: <your return e-mail address goes here>
Subject: <choose one command:>
help (returns instructions)
lists (returns list of newsgroups)
subscribe
unsubscribe
Our SmartList-based listserver will respond automatically.
After you subscribe, send your email comments, suggestions, and questions intended for
the worldwide community of Pioneer users to the users group, NOT to the –requests
address. For example:2
To: [e-mail]
From: <your return e-mail address goes here>
Subject: <something of interest to pioneer users>
Access to the pioneer-users newslist is limited to subscribers, so your address is safe
from spam. However, the list currently is unmoderated, so please confine your
comments and inquiries to issues concerning the operation and programming of Pioneer
or PeopleBot robots.
Support
Have a problem? Can’t find the answer in this or any of the accompanying manuals?
Or do you know a way that we might improve our robots and accessories? Share your
thoughts and questions directly with us:
[email protected]
Please include your robot's serial number (look for it beside the Main Power switch)we
often need to understand your robot's configuration to best answer your question. Your
message goes directly to the ActivMedia Robotics technical support team. There a staff
member will help you or point you to a place where you can find help. Because this is a
support option, not a general-interest newsgroup like pioneer-users, we reserve the
option to reply only to questions about problems with your robot or software.
2Notice that the –requests part of the email address is left out when sending messages to the newsgroup?

ActivMedia Robotics
5
Chapter 2 Installation & Operation
The Pioneer 2 Arm’s control electronics and server software are factory installed, but the
Arm is detached and shipped separately for safety.
Mounting the Arm to Your Pioneer 2 Robot
After carefully unpacking and inspecting the Arm, Pioneer 2 robot, and accessories for
shipping damage, manually fold the Arm into its home position. Then secure the Arm to
the prepared top plate at the front of your Pioneer 2-DX/DXE or AT mobile robot:
CAUTION
Always align your Pioneer 2 Arm into it’s HOME position before use.
1. Put the Arm into its “home” position: The tip of the Arm’s V-shaped mounting base
should point towards the rear of the robot, and the arm should be folded towards the
back of its base.
2. Use the hex wrench that came with your robot and one of the mounting screws to
secure the Arm’s base tip to the robot’s top plate just in front of the access port.
Freely rotate the Arm around its base to get access to the mounting holes.
3. Align the two other mounting holes on each side and at the front of the Arm’s base
plate with their respective holes on the robot’s top plate and secure with the
provided mounting screws.

Installation & Operation
6
Figure 4. Your Pioneer 2 Arm safe at home
4. Remove the plastic plug from the robot’s top-plate access port. Just inside, find the
two Arm power and signal connectors. Mate with the signal and power connectors
attached to the Arm. Insert wired harnesses back into the body of the robot and
replace the plastic cap.
Power to the Arm
Main power for the Pioneer 2 Arm is from both your robot’s Main Power and from the Arm
power switch found on the DX/DXE side panel. On the Pioneer 2-AT, the Arm power
switch is built into the back of the backpack.
Your robot’s Main Power switches power to all onboard systems; the Arm power switch
controls power to the Arm’s controller electronics. A software-enabled switch on the
Arm’s controller board provides power to the Arm’s servo motors. For power
conservation and safety reasons, the relay normally is deactivated so that the servo-
driven joints normally are not engaged—all the joints are “limp” and easily rotated and
swiveled manually. When engaged, the servo motors will resist your efforts to move them.
When your software enables
power to the Arm servos, all joints
simultaneously and as quickly as
possible “jump” to their positions
last programmed into the con-
troller. And, if power is removed
from the servos, the Arm will fall
into its mechanically limpest
position.
Since the Arm’s joint positions
cannot be known, they are
assumed by their generic
controller to be in a default
center position. When you apply
power to the servos, the arm
thereby snaps fully extended into
a “salute” nowhere near any
reasonable limp configuration.
This snap-to-salute draws
excessive power and can swing
the joints into nearby objects.3
Arm Safety at Home
Fortunately, on start up or reset, your Pioneer 2 robot’s P2OS-based Arm servers establish
communication and reset the joints to be in a low-energy, folded “home” position.
When limp in that same position, no joint is far from its home position when servo power
gets applied. This way, the snap-to-position jolts characteristic of servo motors when first
powered up are minimized.
Accordingly, when operating the Pioneer 2 Arm, be sure to manually place it in its home
resting position before applying power to its servos, and be careful to have it resume its
home position before removing power. Failure to do so may cause damage to the Arm
or to nearby people, animals, and other things.
3Some may argue that this presents a fine opportunity to perfect your robot’s “dope slap” maneuver made
famous by Click and Clack, the Tappet Brothers, on their infamous National Public Radio show, Car Talk©.

ActivMedia Robotics
7
Figure 5. The P2ArmDemo lets you operate the
Pioneer 2 Arm quickly and easily.
And for safety, the Arm normally should ride on the moving robot in its home resting
position with servo power OFF, unless involved in manipulation activities. It only makes
good sense to protect the arm from damage and to conserve power; the servos draw
precious battery power while holding a position as well as while moving, and the Arm
can go dangerously limp if you carelessly withdraw power from it.
Software
The Pioneer 2 Arm’s controller is attached to and controlled through your Pioneer 2
robot’s onboard microcontroller AUX serial port. The Pioneer 2 microcontroller, on the
other hand, is connected with your robotics programs through its HOST serial port. This
means that your command and control software communicates with your Pioneer 2 Arm
through the Pioneer 2 microcontroller and its HOST serial port; not directly.
Generic versus P2OS Server Programming
We connect the Arm through the robot’s microcontroller for several reasons: It means
that you need only a single communication channel for all client-server communications
with your robot and its accessories, thereby obviating the need for additional wireless
modems or an expensive onboard PC with multiple serial ports. Perhaps more
importantly, we’ve included special servers in P2OS that provide control features and
watchdogs not available with the Arm’s generic control software and not easily
performed from a standard PC.
Even so, P2OS also supports “pass-through” servers that transfer serial communications to
and from the HOST and AUX ports directly, so that you may control your Pioneer 2 Arm
with its generic command set, if you prefer.
Demonstration and Development Software
A Pioneer 2 Arm control software
demonstration program, P2ArmDemo,
comes on the CD-ROM that accom-
panies the system. Use it with the
keyboard arrows or a joystick to select
and move the individual joints.
Also on the CD-ROM and available to
customers through the http://robots.
activmedia.com support website are
useful development libraries, demon-
stration programs, and source code for
ARIA-based Arm control software, as
well as a Saphira 6.2 plug-in that lets
develop your own Saphira C- and
Colbert-based Arm clients. See the
Programming chapter for details.
P2ArmDemo
On startup, the P2ArmDemo program
automatically makes a client
connection with your Pioneer 2 robot
through the COM1 (/dev/ttyS0 with

Installation & Operation
8
Linux) serial port.4It then graphically displays the Arm on your PC screen along with a set
of control buttons and operating values.
Red dots indicate the current control joint. Change joints by clicking the joystick fire
button, with the up or down arrow key, or by clicking the mouse. Move the selected
joint’s position with the right or left arrow key or with the joystick (active when fire button
pressed). Or click a control button with the mouse to automatically center or move a
joint to its center, home, maximum, or minimum positions. Press the STOP! button or the
space bar at any time to stop the Arm from moving.
Deploy for Pickup sends the Arm around and to the floor, ready to pick up some item
you may place in its gripper. Carry Item sends the Arm up and around to place the
item it has in its gripper on the back of the robot.
The arm servos automatically power up when you select to operate a joint. The Power
Off button automatically homes the arm to its power off position.
Safety Watchdogs
It is important to well manage the Arm to minimize its power consumption and to protect
it and its surroundings from inadvertent damage. P2OS supports important features that
monitor Arm activity and automatically, if enabled, act to protect your Pioneer 2 Arm.
These watchdogs include a client connection-related automatic shutdown server, a
release timer for the gripper, and a warm-reset server.
Power and Connection-Related Automatic Shutdown
Because it is attached to the Pioneer 2 microcontroller, your software may command
and control the Pioneer 2 Arm only while it has an established client-server connection
with P2OS. Moreover, you must explicitly software-command the Arm to power its servos:
The Arm’s default state is in the home position with servo power OFF.
With servo power ON and in a position other than home, the Arm automatically returns to
its home position when your client software tells its P2OS servers to remove power from
the servos.5Otherwise, the Arm might flop into an awkward and potentially damaging
position when you remove power to its positioning servos.
Similarly, P2OS automatically will send the Pioneer 2 Arm to its home position and remove
power from its servos immediately following severance of a client-server connection.
See the P2OS CLOSE server descriptions in the Pioneer 2 Operations Manual for more
details about client-server connections.
The automated shutdown service may be disabled with a special P2OS command and
FLASH parameter setting. See following chapters for details.
Timed Shutdown
Another P2OS Arm watchdog tests the amount of time that may lapse while the robot is
connected with a client PC and the Arm is in service but has not moved. If that time is
excessive, the P2OS AutoParkTimer server automatically sends the Pioneer 2 Arm to its
home position and removes power to its servos. This guards against forgetful neglect.
4See the Pioneer 2 Operations Manual for details on how to attach your PC to the robot and make a client-
server connection.
5You may override some of P2OS’ Arm servers with direct, generic Arm commands.

ActivMedia Robotics
9
AutoParkTimer is set from a parameter stored in the robot’s FLASH memory and altered
through the p2oscf configuration utility. That timer default also can be disabled,
lengthened, or shortened with a P2OS Arm-related client command. It gets reset every
time your client software sends a motion-control command through the Arm’s P2OS
servers, too.
Gripper Release Timer
The Pioneer 2 Arm’s gripper servo can be subjected to overheating and stress while
grasping an object and holding it for excessive periods of time. Accordingly, like the
automatic shutdown timer, P2OS supports a special watchdog that automatically opens
the gripper to its default home position after it has been closed for a FLASH-parameter
set (GripperParkTimer) period of time. A special P2OS command lets you reset the
gripper timer, thereby overriding its immediate effects, as needed6, although we
recommend that you don’t grasp objects for longer than five minutes at a time, with
healthy rest periods in between.
CAREFUL!
Unless carefully managed by your software, the Arm gripper timer may
act to drop an object prematurely.
Like AutoParkTimer, the gripper’s watchdog timer GripperParkTimer is a parameter
stored in your Pioneer 2’s FLASH memory and modified with the p2oscf configuration
utility. The timer defaults to five minutes and can be disabled. The timer gets reset every
time your software opens the gripper to or near its home position.
Warm Reset
Another P2OS watchdog keeps track of the connection between it and the Arm
controller. This is most important for when the connection between the Arm’s controller
and the P2OS servers is not enabled while establishing a client-server connection, or is lost
during a client-server session; for instance, if you inadvertently left the power switch to the
Arm OFF. In these rare circumstances, P2OS assumes the Arm is disabled and not in its
home position, and thereby goes into an Arm-disabled state that requires a special
protocol for recovery. This special handling is done to protect the Arm since P2OS
cannot know the nature or the status of the Arm when communications with the Arm
controller is disrupted, and therefore must assume the worst.
The protocol for recovery from a communications failure is either a cold-reset of the P2OS
controller or through the Warm Reset protocol of commands from a connected client.
Of course, take the latter approach if your client software already is connected and
controlling the robot. In all cases, be sure to put the Arm into its home position before
resetting the system.
6Holding some nearly closed position, but not grasping an object, for example.

Programming
10
Chapter 3 Pr
PrPr
Programming
ogrammingogramming
ogramming
Because it is attached to the robot’s microcontroller, all Pioneer 2 Arm software
commands, controls, and responses pass through the onboard operating system
software, P2OS. P2OS1_H and later versions have a set of Arm-special servers that
provide convenient and advanced control of the Pioneer 2 Arm from your robotics
software clients. There also is a way to bypass these P2OS servers and manage the Arm
through its generic controller commands. In all cases, command and control of the
Pioneer 2 Arm needs an established client-server connection between P2OS and your
software running on a host PC.
Generic Controls
The Pioneer 2 Arm’s generic controller responds to a simple set of commands that
enable/disable power to the servos and position the servo-driven joints. They also let you
query the controller software version number and accessory digital I/O.
However, the Pioneer 2 Arm’s generic software has no provision for controlling joint
speeds. The servo motors adjust to their new position as fast as they can, leading to
some pretty wild swings unless you are careful. Nor, with the generic commands, can
you query for the current position of a joint. The P2OS Arm support servers, on the other
hand, give you control over joint speeds and maintain current position information, as
well as a variety of other advanced and convenient features. Which is why we
recommend that you program to the P2OS Arm servers and not to the Arm’s generic
command set.
The Pioneer 2 Arm’s generic control protocols consist of a header byte (0xFF) followed by
a command byte and one or two command parameters. The most significant bit (b7) of
the command byte determines the mode—set the bit for Control Mode; clear it for Servo
Positioning commands. The next three most significant bits of the command byte (b4-6)
select the board number; always 0 for the Pioneer 2 Arm. The remaining bits of the
command byte depend on the command mode.
Generic Control Mode Commands
The Pioneer 2 Arm’s generic Control Mode lets you enable/disable power to the servos,
and query for the controller’s software version number. The native Arm controller
supports three digital control bits and two analog input channels. Only digital channel 0
is connected, and it controls power to the Arm’s servo motors.
Table 1. Pioneer 2 Arm generic Control Mode commands
Control Mode
Command Bytes Description Board Response
0xFF, 0xC1 Servo Power ON None
0xFF, 0xC0 Servo Power OFF None
0xFF, 0x80 Request version number ASCII-encoded version number,
followed by 0x0D, 0x0A7
0xFF, 0x85 Read digital port states 0-7 corresponding to ports 0, 1 and
2, followed by 0x0D, 0x0A
7Carriage return (0x0D) and line-feed (0x0A) characters.

ActivMedia Robotics
11
Generic Servo Positioning Mode Commands
You may use the Pioneer 2 Arm’s generic Servo Positioning command to position a joint.
The command consists of three bytes: the header (0xFF), a servo-selector byte, and the
position value byte. The servo-selector byte’s most significant bit (b7) always is off (0) to
distinguish servo-positioning commands from control-mode commands. Its remaining bits
(b0-6) select the servo number, for a total of up to seven joints. Only joints one—the base
swivel—through six—the gripper—are active with the Pioneer 2 Arm.
The servo-positioning byte allows up to 255 different servo positions, although in practice,
the range of positions for any individual joint and depending on the individual Arm varies
to roughly 200 positions around values 25-235. Our P2OS-based servers let you set realistic
position boundaries (min and max) and center offsets, so that your client-side code is
portable from Arm to Arm. See following sections for details.
For example, using the generic command to turn the Pioneer 2 Arm fully clockwise
around its base (servo number 1), you may send the generic command byte sequence:
0xFF, 0x1, 0xFF
P2OS HOST to AUX Serial Port Communications
To send generic control and servo-positioning commands from your client software to the
Pioneer 2 Arm controller, you need to use the P2OS TTY2 command number 42 with an
integer (two-byte) or string argument. This is necessary since all generic commands from
your software to the Pioneer 2 Arm pass through your Pioneer 2’s HOST serial port and
through P2OS to the Arm-attached AUX serial port on the robot’s microcontroller.
Similarly, to retrieve responses from the Arm controller using generic commands, use the
P2OS GETAUX command number 43 and corresponding SERAUXpac server information
packet. Command and packet details are in the Pioneer 2 Operations Manual. The
various client-development environments for Pioneer 2 support these functions, including
Saphira and ARIA.
For example, to raise the Arm up (joint servo number 2) to roughly its center position, you
may use the Saphira client sequence:
unsigned char pos_servo[3] = {0xFF, 0x00, 0x00};
pos_servo[1] = 0x02; /* Select servo number 2 */
pos_servo[2] = 0x7F; /* Center position */
sfRobotComStrn(42,pos_servo,3); /* Saphira creates command packet and sends it;
P2OS transfers string out through AUX port to Arm */
You see easily how quickly Pioneer 2 Arm control through its generic command set
becomes tedious. We leave the details for retrieving generic command responses, such
as for the Arm version number, to the astute reader; we don’t recommend using the
generic Arm controls, and don’t want to belabor the point…
P2OS Arm Servers
P2OS version 1_H introduces advanced control functions for safe and convenient
operation of the Pioneer 2 Arm. These include commands to enable and disable power
to the Arm’s servos, to move the Arm to a new position—joint-by-joint and each at a
controllable speed—and to query for current arm position and status. The servers also
include safety watchdogs that monitor Arm status and functions, and which act to
minimize power consumption as well as help protect your Pioneer 2 Arm and
surroundings from damage.

Programming
12
P2OS Arm Commands
P2OS commands for control of the Pioneer 2 Arm originate in your client software and
thereby require that you establish a client-server connection between your PC-based
client software and the Pioneer 2 microcontroller-based P2OS. After connecting, your
client software must tell the P2OS servers to power the Arm’s servos before you can send
position commands. Note that the Arm always starts a client-server connection in its
home position and automatically returns to that home position when servo power is set
to OFF, including at the termination (CLOSE) of a client-server connection session.
Table 2. Pioneer 2 Arm P2OS command set
P2OS
Command Command Number Value(s) Description
_INFO 70 none
Request an ARMINFOpac server-information packet
_STAT 71 0, 1 or 2 Request one or a continuous stream (one per P2OS cycle) of
ARMpac server information packets; 0 stops continuous
_INIT 72 none Warm-reset the Arm
_CHECK 73 none Has P2OS servers check to make sure Arm still responding
to commands; reflects in status byte of ARMpac.
_POWER 74 0 or 1 Switches power off (0) or on (1) to all the servos
_HOME 75 1-6 or 255 Sends all (255) or specified joint to the home position
_PARK 76 none Sends all joints to their home positions and shuts power off.
_POS 77 two bytes:
1-6, 0-255 Sends joint (1st byte) to the position specified in the 2nd byte, subject to end-limits specified in FLASH parameters
_SPEED 78 two bytes:
1-6, 1-127 Delay in milliseconds (2nd byte) between incremental steps to control the speed and motion of the joint (1st byte)
_STOP 79 1-6 or 255 Stop the specified (1-6) or all (255) moving joints
_AUTOPARK 80 0-65535 Disable the autopark watchdog (0) or reset it to some time
in seconds other than default AutoParkTimer in FLASH
_GRIPPARK 81 0-65535 Disable the gripper watchdog (0) or reset it to some time in
seconds other than the default GripperParkTimer
Once connected, you may query for status, current servo positions, and other salient
information as included in special Arm server-information packets, as well as modify joint
speeds. But the Arm will not move nor will the servers update joint positions unless P2OS
verifiably has communication with the Arm’s controller and the Arm’s servo power is
enabled. There is a special warm-reset protocol your client must perform in the case that
the Arm controller is not in contact with P2OS when your client software requests to
enable servo power, or in the case that communication between P2OS and the Arm
controller is lost during an active session.
Your client software must package P2OS Arm commands into a special communication
packet, and retrieve and decode the Arm-related server-information packet (SIP), as
described in the Pioneer 2 Operations Manual and supported in part by various Pioneer 2
development software, such as ARIA and Saphira.
For example, to enable power to the Arm and then raise its first joint, establish a client-
server connection between a Saphira client and your Pioneer 2 equipped with the Arm.
Then, from the Colbert interaction window, type:
sfRobotComInt(74,1); /* Apply power to the servos */
sfRobotCom2Bytes(77, 1, 127); /* Extend the 1st joint out to its mid position */
The sfRobotCom Saphira functions8package the P2OS command number, parameter
type and parameters (if needed), and a computed checksum characteristic of a valid
8sfRobotCom(cmd), sfRobotCom2Bytes(cmd, byte, byte), sfRobotComInt(cmd, int), sfRobotComStr(cmd,
string), sfRobotComStrn(cmd,string,strlen).

ActivMedia Robotics
13
P2OS command packet and sends them along the HOST serial communication port to
the robot’s servers. You may also use the functions provided by the Saphira plugin. See
later sections for details.
ARM_INFO and ARMINFOpac
P2OS maintains detailed information about each servo-driven joint, as well as connection
and power status with the Pioneer 2 Arm. Your client software may request that detailed
information with the ARM_INFO command number 70, which P2OS responds to with an
ARMINFOpac SIP. See the Pioneer 2 Operations Manual for details about P2OS SIPs and
guidelines on how to write client-side packet decoders. Arm-related SIP decoders come
with both the provided ARIA code and the Saphira 6.2 plugin software.
Table 3. ARMINFOpac server information packet contents
Byte Value(s) Description
1 0xA1 ARMINFOpac server information packet ID
2-n string NULL-terminated string containing the Pioneer 2 Arm’s version number
response, or “No arm” if not connected.
n+1 0-7 Number of Pioneer 2 Arm joints; default is six; 0 if no Arm.
n+2 0-127 Servo #1’s speed setting.
n+3 0-255 Servo #1’s home position setting.
n+4 0-127 Servo #1’s minimum position value.
n+5 ~127 Servo #1’s center position value.
n+6 127-255 Servo #1’s maximum position value.
n+7 1-255 Servo #1’s ticks per 90 degree rotation value.
n+8 to n+50 … Servo #’s 2-6 speed, home, minimum, center, maximum, and ticks/90deg
settings.
ARM_STAT and ARMpac
The ARMpac SIP provides current Pioneer 2 Arm servo position information as well as arm
status. Get one or a continuous stream (one per P2OS cycle) of ARMpac SIPs with the
ARM_STAT command.
Table 4. ARMpac contents
Byte Value(s) Description
1 0xA0 ARMpac server information packet ID
2 bit-
endcoded
status
Bit-encoded servo power (b0) and connection (b1) status; respective bit is set
(1) if servo power enabled or a connection established between Arm controller
and P2OS.
3 bit-encoded
status Bit-encoded motion status for each servo-driven joint; bit set (1) if respective joint in motion. Note that only bits 1-6 are active, corresponding to the current
Pioneer 2 Arm’s six servo motors and joints.
4-9 0-255 ea Servos 1-6 current positions.

Programming
14
ARM_POWER
After establishing a client-server connection, you must command P2OS to have power
enabled to the Pioneer 2 Arm’s servos in order to move its joints to positions other than
home (sfRobotComInt(74,1), for example). If you tell P2OS to disable power to your
Arm’s servos (74,0), or if your client disconnects from the P2OS servers when the servos
are enabled, the Arm automatically returns to the home position and disables servo
power.
If, in the case that P2OS cannot communicate with the Arm’s controller, or if it loses
communication while servo power is enabled, the P2OS Arm servers automatically revert
to servo power off and home position, and will not allow restoration of servo power until
reset. See ARM_INIT and Warm Reset Protocols below.
ARM_SPEED and ARM_POS
The P2OS Arm servers move a joint from one position to another in individual steps, rather
than effect an uncontrolled jump from one position to another as happens with the
generic Arm commands. And P2OS controls each joint’s rotational speed by waiting a
particular period of time between each step for much smoother operation.
Accordingly, to move joint #1 from position 100 to position 200, for example, P2OS sends
a sequence of 100 individual position commands to the Arm controller, each
incremented by one position value and separated by an ARM_SPEED number of
milliseconds until the joint reaches its destination.
You may set individual joint speeds on-the-fly with the ARM_SPEED command number 78
or set their start-up defaults through FLASH parameters (see next chapter); 1-127
milliseconds delay each. Speeds may be set at any time, even when the Arm is not
powered, and persist through servo-power and client connection/disconnection cycles.
Their current values are reflected in the ARMINFOpac.
For example, to set the speed of joint #4 to 30 milliseconds,
sfRobotCom2Bytes(78, 4, 30);
When powered, control the Pioneer 2 Arm’s servo positions with the ARM_POS command
number 77. Servos vary. Each joint for your particular Arm is characterized by maximum
and minimum position values which limit its range despite the value you may command,
as well as a center position. Limiting values fore each and every joint are reflected in the
ARMINFOpac, and may be updated in FLASH (see next chapter). Individual servo
positions are reflected in the ARMpac server information packet (see above).
ARM_SPEED Limits
Joint speeds have limits. Generic Arm position commands take two bytes each. Serial
communication with the Arm controller is 9600 baud, which is about 1 byte per
millisecond. Hence, an individual joint may move at the maximal speed if about one
new position every two milliseconds, even though P2OS attempts to update each joint
every millisecond.
The delays are cumulative, too. Move two joints at a time, and the maximal update
rate, due to serial communication delays, is every four milliseconds. And so on.
Fortunately, the worst case—all six joints moving at once and requiring simultaneous
position updates—is rare, for which a complete update cycle takes 2 x 6 = 12