BeeSoft User's Guide and Reference
4.2 Using baseServer - Non-Guarded Motion
baseServer calls let your user program operate the robot in a form of operation called non-guarded motion. In this mode, the robot does not perform any kind of automatic collision avoidance (as it does under colliServer, discussed later). The robot just moves in response to your program’s commands.
4.2.1 Initializing the Base and starting baseServer
void registerBaseClient (void);
void findBaseServer (void);
4.2.2 Moving the Base with baseServer
You can control both translation and rotation in any of several modes. In the most often used mode, your user program sets a velocity and an acceleration to be used by the base in subsequent motion commands. First, you’d set a specific velocity and acceleration. Then, you’d ask the robot to move forward one meter. Here’s an example of how you might do this:
/* Set acceleration to 100mm/sec². */
setTranslateAcceleration(100);
/* Set velocity to 100 mm/sec. */
setTranslateVelocity(100);
/* Move forward 100 mm. */
translateRelativePos(100);
Simply setting the velocity and the acceleration for an axis of motion does not in itself initiate any motion. Once these values are set, though, they affect most motion already in progress and most subsequent motion commands. In this example, the call to translateRelativePos simply commands the robot to perform that motion, but does not wait for that motion to be completed. Your user program might well issue further motion commands that affect the robot’s translation motion before it reaches that destination one meter (1000 mm) ahead).
The robot’s base also provides additional modes of motion that do not pay attention to the previously-set velocity or acceleration. For example, you can translate with a constant torque. (Torque is the amount of force necessary to cause rotation or twisting about an axis.) When the torque you specified is applied, the velocity and acceleration of the subsequent motion are determined by how difficult is if for the base to move. When used with caution and soundjudgement, torque mode motion can be useful for such activities as pushing objects across the floor.
Sometimes, you just want to stop the robot’s motion altogether, regardless of its current mode of motion. To do this, you’d use a halt function call or a limp function call.
When you call a halt function, the base uses the previously-set acceleration in conjunction with feedback from its motors to bring all motion to a controlled, smoothly-decelerating stop, regardless of the forces being exerted upon the robot’s base by its payload, the grade of the floor surface or any pushing and shoving by the robot’s operator. Once all motion has ceased, the base uses its motors to actively hold its "halted" position.
When you call a limp function, in contrast, the base simply relaxes the motors that control that motion axis, and the laws of physics take over. Unless the robot has been moving at an improbably high speed or on a very steep grade, motion stops rather quickly. Once an axis is "limped," moreover, the robot can be pushed forwards or backwards, or rotated (depending on the axis that is limped) by hand.
If you halt, and then limp, a motion axis, that axis will come to a controlled halt, then be relaxed so that you can move it by hand. You might think that simply setting the velocity to zero would halt base motion. But RWI, Inc., does not recommend doing this. Some robot bases, when their velocity is set to zero, will creep at an almost imperceptible speed when commanded to translate or rotate. (You probably don’t want your robot sneaking away from your lab while you’re out at lunch.)
Every motion of the robot’s base — whether in response to a motion command from your user program or as a result of being moved by hand, updates the base’s internal estimate of its position and orientation. Your program can look at this estimate anytime you want. Also, you can ask the base to notify your program whenever motion is halted.
4.2.3 Odometry and Related Commands
The function calls discussed in this section are based on a standard set of units (radians, seconds and centimeters) and are fully compatible with standard trigonometric functions. These calls, which begin with the letter "b," are meant to replace the old robot motion control commands. These new calls are a part of an ongoing effort to refine the BeeSoft software package. As much as possible, use these "b" calls for all your new development work. More calls will be added to this new set in upcoming releases.
Odometry Locking
Before any of the "b" odometry functions can be used, the client application must have obtained a lock on the odometry system by calling bRequestOdometryLock.
NOTE: The requesting and granting of odometry locks is not a synchronous process. When the client receives a response to a bRequestOdometryLock call, the odometry callback function (registered via a call to bRegisterOdometryLockCallback) is called. In fact, any time there is a change in the state of a lock held by the client function, the odometry callback function is invoked.
Each lock request has a lock request priority. This allows locks to be pre-empted by another application. If the lock held by a client is pre-empted, the odometry callback function is called, in order to notify the client.
Figure 4-1 - Odometry Coordinate System --Units of Distance are Centimeters
NOTE: For calls discussed in this section, positive rotation is counterclockwise in order to be compatible with standard trigonometric functions.
float bGetRotVel ( );
Returns rotational velocity in radians per second. Velocity information comes from the robot base’s status report.
float bGetTransVel ( );
Returns translational velocity in centimeters per second. Velocity information comes from the robot base’s status report.
float bIrAngle (int irCol, int irRow);
Given the ID number of one of the IR sensors, this will return the angle of that IR, relative tothe robot.
float bNormalizeAngle (float radians);
Normalizes an angle that may be < -pi or > pi to fall within the range =/- pi.
Figure 4-2 - Angle, Relative to the Robot, returned by bIrAngle, bSonarAngle and bTactileAngle
bRegisterOdometryLock (int( (*odocallbackType) (int paam) fcn);
Registers a callback to be executed anytime there is a change in the client’s odometry lock status. The callback function is passed the current value of the client’s lock, either B_ODOMETRY_I_HAVE_LOCK or B_ODOMETRY_OTHER_HAS_LOCK.
void bRequestOdometryLock (unsigned short priority);
The single argument is the priority; the higher the number, the higher the priority. NOTE: It is good practice to call bRequestOdometryLock just before updating the odometry position by calling bSetPosition or bUpdatePosition.
float bRobotAngle (float worldAngle, float dt);
Converts an angle in world coordinates to an angle relative to the robot. (Note: See world coordinate system in Figure 4.1) dt is a time increment.
floatbRobotHeading (float dt);
Gets the heading from the robot base’s status report, then does a simple extrapolation into the future or the past, based on the robot’s velocity. For example, the robot wants to know, "Where will I be in 2/10ths of a second?" This depends on how fast it is traveling. dt is a time increment
float bRobotX (float dt);
Returns X position of the robot, in logical world coordinates. dt is a time increment. The allowable range for dead reckoning operations is from 0 to 1.3 km. To ensure that your robot can travel in any direction without hitting these range limits, initially set your robot into the middle of its range: +/- 650 meters.
float bRobotY (float dt);
Returns local Y position of the robot, in logical world coordinates. dt is a time increment. The allowable range for dead reckoning operations is from 0 to 1.3 km. To insure that your robot can travel in any direction without hitting these range limits, initially set your robot into the middle of its range: +/- 650 meters.
Figure 4-3 - Shaded box shows range in which dead reckoning will operate properly. By setting starting coordinates to the center of this range, by calling bSetPosition (0,0), you will avoid overflow problems that can cause undefined results.
void bSetPosition (float X, float Y, float heading);
Unlike loadPosition, which you call to obtain raw dead reckoning data returned from the robot’s base,you use bSetPosition to work with clean, logical coordinates. The simplest invocation is to call bSetPosition with 0,0. This will reset the coordinate system. When you call bRobotX or bRobotY, you will get back these clean, logical coordinates, rather than raw odometry data. Because of the problems inherent in converting raw dead reckoning data into millimeters, overflow problems can occur that cause undefined results. Therefore, it’s prudentpractice to always set your initial position somewhere in the middle of the range in which dead reckoning operates properly. NOTE: It is good practice to call bRequestOdometryLock just before calling bSetPosition.
void bSetVel (float, rotVel, float transVel) ;
Sets the translation and rotation velocities of the robot; units are centimeters per second.
float bSonarAngle (int sonarNum);
Given the ID number of one of the sonar sensors, this will return the angle of that sonar, relative to the robot. (See Figure 4-2.)
float bTactileAngle (int tactileCol int tactileRow);
Given the ID number of one of the tactile sensors, this will return the angle of that tactile, relative to the robot. (See Figure 4-2.)
void bUpdatePosition (float dX, float dY, float dHeading);
Shifts the coordinates, telling you where the robot logically is, based on logical world coordinates, as opposed to where the robot physically is according to the raw dead reckoning data from the motion controller. NOTE: It is good practice to call bRequestOdometryLock just before calling bUpdatePosition.
float bWorldAngle (float robotAngle, float dt);
Converts an angle in coordinates relative to the robot to an angle relative to world coordinates. (Note: See world coordinate system in Figure 4.1)
4.2.4 Base Rotation Commands
The calls in this section use a different coordinate system than the calls discussed above (the ones that begin with b). In this coordinate system, currently used by baseServer, rotation is specified in rotational units. 1024 rotational units constitute one full rotation of the base about its axis. Under this coordinate system, positive rotation is clockwise; negative rotation is counterclockwise.
Because it is non-standard and incompatible with standard trigonometric functions, this coordinate system will be phased out in future releases of BeeSoft. All new development work should use, as much as possible, the new coordinate system based on radians, (that is, the calls that start with b) discussed above in the Odometry section.
void rotateHalt( );
Stops rotation motor and then maintains position. The currently set velocity is ignored. If force is exerted to rotate the base, it will apply the necessary torque to maintain its position, up top the currently set torque limit. (You can set the torque limit with a call to setRotateTorque.)
void rotateLimp( );
Causes rotation motor go "limp." No attempt is made to hold a position, and the base can then be rotated by hand. Previously set velocity and acceleration are ignored.
rotatePowerNeg(unsigned long relative);
Open loop PWM mode. Rotates the base in a counterclockwise direction using the percentage of motor capacity you specify. Specify the percent (0 through 100) of full power you want applied. The base will attempt to apply a constant voltage to the motor; that is, it will apply greater torque if velocity decreases (if, for example, the robot is obstructed by an object), until the currently set torque limit is reached. The previously set acceleration and velocity are ignored.
void rotatePowerPos(unsigned long relative);
Open loop PWM mode. Rotates the base in a clockwise direction using the percentage of motor capacity you specify. Specify the percent (0 through 100) of full power you want applied. The base will attempt to apply a constant voltage to the motor; that is, it will apply greater torque if velocity decreases (if, for example, the robot is obstructed by an object), until the currently set torque limit is reached. The previously set acceleration and velocity are ignored.
void rotateRelativeNeg(unsigned long relative);
Rotate counterclockwise at the previously-set velocity and acceleration until the base has rotated the supplied number of rotational units, or until you issue another rotation command.
Figure 4-4 - Coordinate System for rotation commands under baseServer
void rotateRelativePos(unsigned log relative);
Rotate clockwise at the previously-set velocity and acceleration until the base has rotated the supplied number of rotational units, or until you issue another rotation command.
void rotateTorqueNeg(unsigned long relative);
Open loop torque mode. Rotates the base in a counterclockwise direction, at the percentage of the motor’s torque capacity you specify. The torque applied to the rotation axis will be constant, so that if the rotation is obstructed by some obstacle or force, the velocity will decrease. Previously-set acceleration and velocity are ignored.
void rotateTorquePos(unsigned long relative);
Open loop torque mode. Rotates the base in a clockwise direction, at the percentage of the motor’s torque capacity you specify. The torque applied to the rotation axis will be constant, so that if the rotation is obstructed by some obstacle or force, the velocity will decrease. Previously-set acceleration and velocity are ignored.
void rotateVelocityNeg (void);
Rotate continuously, counterclockwise, at previously-set velocity and acceleration. The base will continue to rotate until you issue a different rotation command. Caution: Do not set therotate velocity to zero to stop rotation, as some robot bases will continue to rotate, albeit very, very slowly. Instead, use rotateHalt.
void rotateVelocityPos(void);
Rotate continuously, clockwise, at previously-set velocity and acceleration. The base will continue to rotate until you issue a different rotation command. Caution: Do not set the rotate velocity to zero to stop rotation, as some robot bases will continue to rotate, albeit very, very slowly. Instead, use rotateHalt.
void setRotateAcceleration(unsigned long relative)
Sets the acceleration used to achieve the desired rotation velocity. The units are rotation units per second per second.
void setRotateTorque(unsigned long torque);
Limits the amount of torque the rotational axis is allowed to develop. The default is 32. A value of 255 effectively provides unlimited torque, up to the torque capacity of the robot’s motors. Units are base dependent.
void setRotateVelocity(unsigned long velocity);
Sets the rotational speed of the base. Units are rotational units per second.
4.2.5 Base Translation Commands
Specify translation distances in millimeters, velocity in millimeters per second, and acceleration in millimeters per second squared.
void translateHalt(void);
Commands the base to cease translation and to maintain its position. The previously-set velocity is ignored. If force is exerted to translate the base, it will apply the torque necessary to maintain its position, up to the currently-set torque limit. (You can set the torque limit with a call to setTranslateTorque.)
void translateLimp(void);
Causes the translation motor to go "limp." The base makes no attempt to hold its position; you can push the base by hand. The previously-set acceleration and velocity are ignored.
void translatePowerNeg(unsigned long);
Commands the base to translate to the rear at the percentage you specify of the translation motor’s capacity. Specify the percentage (0-100) of full power you want applied. The base will attempt to apply a constant voltage to the motor. It will apply greater torque if the velocity decreases (if, for instance, it pushes against an object). The previously-set acceleration and velocity are ignored.
void translatePowerPos(unsigned long);
Commands the base to translate forward at the percentage you specify of the translation motor’s capacity. Specify the percentage (0-100) of full power you want applied. The base will attempt to apply a constant voltage to the motor. It will apply greater torque if the velocity decreases (if, for instance, it pushes against an object). The previously-set acceleration and velocity are ignored.
void translateRelativeNeg(unsigned long);
Commands the base to translate to the rear the distance you specify. Distance unit is millimeters.
void translateRelativePos(unsigned long);
Commands the base to translate forward the distance you specify. Distance unit is millimeters.
void translateTorqueNeg(unsigned long);
Causes the base to translate to the rear at some percentage of the translation motor’s torque capacity. If an object pushes against the base, the velocity will change so that the torque remains constant. Previously-set acceleration and velocity are ignored.
void translateTorquePos(unsigned long);
Causes the base to translate forward at some percentage of the translation motor’s torque capacity. If an object pushes against the base, the velocity will change so that the torque remains constant. Previously-set acceleration and velocity are ignored.
void translateVelocityNeg(void);
Commands the base to translate to the rear at the previously-set acceleration and velocity. The base will continue to translate until you issue some other translate command. Caution: Do not set the translation velocity to zero to stop translation, as some robot bases will continue to creep, albeit very, very slowly at a velocity of zero. Instead, use translateHalt
void translateVelocityPos(void);
Commands the base to translate forward at the previously-set acceleration and velocity. The base will continue to translate until you issue some other translate command. Caution: Do not set the translation velocity to zero to stop translation, as some robot bases will continue to creep, albeit very, very slowly at a velocity of zero. Instead, use translateHalt
void setTranslateAcceleration(unsigned long);
Set acceleration of the translation motor. Units are millimeters per second per second.
void setTranslateTorque(unsigned long);
Limits the amount of torque that can be applied to cause motion on the translation axis.
void setTranslateVelocity(unsigned long);
Sets the velocity at which you want the base to translate. This command affects anytranslation motion currently in progress, and any subsequent translation commands. Units are millimeters per second.
4.2.6 Translation-plus-Rotation Commands
void baseKill(); - Kills both rotation and translation motors.
void loadHeading (unsigned long heading);
Resets the orientation of the controller’s X-Y coordinate system. Supply the number of rotational units clockwise of the Y axis of the coordinate system the robot is currently facing. There are 1024 rotational units in the full circle about the robot’s central axis, numbered clockwise from 0 to 1023. For example, loadHeading (0) specifies that the robot’s current heading is the Y axis of the coordinate system. Forward translation then increases the Y coordinate of the robot’s estimated position, but causes no change in the X coordinate. You might use this command to reset the coordinate system when staring up your BeeSoft client program, or to correct the heading to a known value when a the robot detects a known landmark during its peregrinations.
void loadPosition (unsigned long heading);
Specifies a thirty-two bit value representing the robot’s location relative to the origin of the controller’s X-Y coordinate system. The first 16 bits of the heading value you supply represent the X coordinate; the second 16 are the Y coordinate. This value is what the robot’s base uses to keep track of its odometry. NOTE: loadPosition actually modifies the values in the motion controller. It thus affects your range. If it overflows, it will return invalid and/or undefined data. Base controllers often use unsigned arithmetic, so it is safest to reset each coordinate location to a number which is not in danger of underflow or overflow, such as 0 x 80000.
4.2.7 Indexing
void findRotIndex (void); - Finds the rotational index and sets BaseRelativeHeading.
