GRL interface to RWI reflex bases

Ian Horswill 2/10/00

These signals and operators are exported by the reflex-iterface package.  The code for them, along with the (largely undocumented) reflex packet protocol driver generator can be found in the RWI subdirectory of the GRL source tree.

Coordinate systems

Coordinates are expressed in either egocentric coordinates (i.e.robot-centered) or global coordinates (world-centered).  In both systems, orientation is counter-clockwise positive, and expressed in radians, so that you can obtain a unit vector in a desired orientation with (cos q, sin q).  Distances is (very approximately) calibrated to millimeters.

(egocentric->global xy-vector)
(global->egocentric xy-vector)
Conversion between egocentric and global coordinates.  These should probably also support poses, but I forgot.

Data types

Poses are groups containing both 2D position information and a heading.

(pose xy-vector  orientation)
(pose x  y  orientation)
Constructors.
(pose-x pose)
(pose-y pose)
(pose-position pose)
(pose-orientation pose)
Accessors.  Pose-position returns an xy-vector.
(pose-tolerance angular-tolerance   distance-tolerance)
(pose-=?
pose1  pose2  &key  tolerance   angular-tolerance  distance-tolerance)
Returns true if the two poses are identical to within the specified tolerances.   Tolerances can be specified independently with the angular-tolerance and distance-tolerance keyword parameters, or can be specified together by passing a pose-tolerance object for the tolerance keyword parameter.  If the angular or distance tolerance is #f, then angle or distance, respectively, will not be considered in comparing the poses.
(latch-pose pose  latch?)
Like latch, but for poses.
(true-nearby? boolean  &key  tolerance   angular-tolerance  distance-tolerance)
Returns true if the last time boolean was true, the robot was within the specified tolerance of its current position.

Base-motor-vectors are groups containing all the information relevant to base motor control.  Specifically, they contain the target velocity for the base, as well as the maximum acceleration and torque the base is allowed to use to achieve it.

(base-motor-vector velocity  &optional   acceleration  torque)
Constructor.  If acceleration and/or torque are unspecified, they will be filled in with default signals.
(base-motor-vector-velocity base-motor-vector)
(base-motor-vector-acceleration base-motor-vector)
(base-motor-vector-torque base-motor-vector)
Accessors.

Low-level interface

bump-switch-state
A vector of booleans, indexed by bump switch number, giving the state of each bump switch.
sonar-readings
A vector of sonar readings read from the base.  These have been corrected with Todd's approximate conversion from sonar units to millimeters.
sonar-reading-base-positions
sonar-reading-orientations
These are vectors indexed by sonar transducer number.  They describe the robot's estimated pose in the global coordinate system at the moment that each tranducer received its last return.  Position is expressed in units of shaft encoder counts.
raw-base-x
raw-base-y
The estimated global position of the robot expressed in units of translational shaft encoder counts.
base-x
base-y
The estimated global position of the robot adjusted to be something close to the same units as the sonars.
base-position
The estimated global position of the robot adjusted to be something close to the same units as the sonars, expressed as an xy-vector.
base-orientation
The estimated global orientation of the robot in radians.
base-pose
The estimated global pose of the robot adjusted to be something close to the same units as the sonars.
base-voltage
Battery voltage of the base.
base-measured-velocity
base-measured-acceleration
base-measured-torque
The current rotational/translational velocity, acceleration, and torque reported by the base, expressed as an rt-vector.

Calibrated sonar pings

The packet driver for the reflex interface stores the estimated global pose of the robot along with each sonar ping it receives.  This allows the GRL code to project the pings into the global coordinate system, and then backproject them back into the robot's egocentric coordinate system, even after the robot has moved.

sonar-orientations
A vector of angles giving the egocentric orientation in which each sonar transducer faces.
global-ping-orientations
A vector of angles giving the global orientation in which each transducer had been facing at the time of its last ping.
global-ping-positions
A vector of xy-vectors giving the estimated global positions of the surfaces that generated the last return for each transducer.
egocentric-ping-positions
The same information backprojected into the current egocentric coordinate system.

Base control

default-base-acceleration
default-base-torque
The default component values used by base-motor-vector.   Both are rt-vectors.
limp-motor-vector
A motor vector with zero velocity and no torque, to be used when you want to limp the base.
(passive-braking target-velocity)
Returns a base-motor-vector signal that tries to achieve target-velocity (an rt-vector).  Rotational velocity control uses the default acceleration and torque parameters.  However, the torque used by the translate motor depends on the current measured translational velocity.  When the target velocity is higher (we want the base to accelerate), the default torque is used.  However, when the target velocity is lower (we want the base to decelerate), a torque of 0 is used so that friction will passively brake the system.  This tends to reduce wear and tear on the batteries and drive train.
(drive-base base-motor-vector)
(drive-base
rt-vector)
(drive-base
behavior ...)
Transmits the specified control information to the base.  If a full base-motor-vector is specified, it is used.  If only an rt-vector is specified, it is used as a target velocity and the default acceleration and torque are used.  If one or more behaviors are specified, then the base uses the motor vector of the leftmost active behavior, or limps itself, if none are active.  Behaviors that use base-motor-vectors and that use rt-vectors can be mixed freely.
(sonar-polling-rate echo-delay  ping-delay   set-delay)
Drives the timing parameters of the sonars with the specified signals.  The semantics of these parameters isn't documented, however, echo-delay is believed to be the time spent waiting for a ping, ping-delay is believed to be the delay between pinging successive transducers, and set-delay is believe to be the delay between successive cycles of polling.

Higher-order operators

(compose-rotation f  behavior)
Returns a behavior identical to behavior, but whose rotational velocitty is the result of applying f to the rotational velocity of behavior.
(compose-translation f  behavior)
Returns a behavior identical to behavior, but whose translational velocity is the result of applying f to the translational velocity of behavior.
(sonar-safe behavior)
Returns a behavior identical to behavior, but which will not drive forward if the sonars read an obstacle nearby in the robot's path, or drive backward is the sonars read an obstacle nearby behind it.