[Documentation] [TitleIndex] [WordIndex

API review

Proposer: Jack O'Quin

Present at review:

The main focus of this review is the new art_msgs/CarControl2 message. We need to define the meanings of all combinations of the parameters.

For convenient reference, here is a copy of the message source file:

# car acceleration control command
# $Id: CarControl2.msg 1161 2011-03-26 02:10:49Z jack.oquin $

float32 acceleration            # (m/s^2), negative is deceleration
float32 goal_velocity           # (m/s), negative is reverse
float32 steering_angle          # steering angle (radians)

# gear numbers
uint8 Drive = 0
uint8 Park = 1
uint8 Reverse = 2

uint8 gear                      # requested gear

Question / concerns / comments

Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.

Preliminary proposal for the final message text:

# Driving command for a car-like vehicle using Ackermann steering.
# $Id: CarDrive.msg -1   $

# Drive at requested speed, limited by acceleration. Speed is a
# non-negative scalar, direction determined by the gear. Zero
# acceleration means as quickly as possible.
float32 speed                   # magnitude of velocity vector (m/s)
float32 acceleration            # acceleration limit (m/s^2)

# Assumes Ackermann steering. This angle is the average yaw of the
# front wheels in the vehicle frame of reference (positive left),
# modeling their slightly differing wheel angles as a tricycle.
float32 steering_angle          # steering angle (radians)

# Gear numbers are defined in the art_msgs/Shifter message. 
# "Reset" means to use the current gear.
uint8 gear                      # requested gear

# Requested behavior.
uint8 behavior
uint8 Run = 0                   # normal driving
uint8 Pause = 1                 # stop issuing servo commands
uint8 Off = 2                   # turn off (some) devices

Meeting agenda

After discussing the API on this wiki page, I'd like to close this review after class next Wednesday, 2011-04-20.

The class discussion was helpful, issues raised there are listed in the conclusions below.

Conclusion

Action items that need to be taken:

To summarize, here are the final, agreed-upon message definitions:

CarDrive:

# Driving command for a car-like vehicle using Ackermann steering.
# $Id: CarDrive.msg 1412 2011-04-30 15:40:53Z jack.oquin $

# Drive at requested speed, acceleration and jerk (the 1st, 2nd and
# 3rd derivatives of position). All are non-negative scalars. 
#
# Speed is defined as the scalar magnitude of the velocity
# vector. Direction (forwards or backwards) is determined by the gear.
#
# Zero acceleration means change speed as quickly as
# possible. Positive acceleration may include deceleration as needed
# to match the desired speed. It represents a desired rate and also a
# limit not to exceed.
#
# Zero jerk means change acceleration as quickly as possible. Positive
# jerk describes the desired rate of acceleration change in both
# directions (positive and negative).
#
float32 speed                   # magnitude of velocity vector (m/s)
float32 acceleration            # desired acceleration (m/s^2)
float32 jerk                    # desired jerk (m/s^3)

# Assumes Ackermann (front-wheel) steering. This angle is the average
# yaw of the two front wheels in the vehicle frame of reference
# (positive left), ignoring their slightly differing angles as if it
# were a tricycle. This is *not* the angle of the steering wheel
# inside the passenger compartment.
#
float32 steering_angle          # steering angle (radians)

Gear gear                       # requested gear (no change if Naught)
PilotBehavior behavior          # requested pilot behavior

Gear:

# ART vehicle transmission gear numbers
#
# Used by several different messages.

# $Id: Gear.msg 1375 2011-04-25 20:59:15Z jack.oquin $

# Gear numbers. 
#
# Naught means: reset all Shifter relays; no change of CarDrive gear.
uint8 Naught = 0
uint8 Park = 1
uint8 Reverse = 2
uint8 Neutral = 3
uint8 Drive = 4
uint8 N_gears = 5

uint8 value             # requested or reported gear number

PilotBehavior:

# ART autonomous vehicle pilot node behaviors.
#
# Normally, the pilot node does Run, continually sending commands to
# the servo device actuators and monitoring their state.  With Pause,
# the pilot becomes passive, allowing a learning algorithm or human
# controller direct access to those devices.  In the Off state,
# various devices are shut down: the transmission in Park, the brake
# released, the throttle at idle.  The engine is not turned off, but
# it could be.

# $Id: PilotBehavior.msg 1434 2011-05-03 15:11:56Z jack.oquin $

# Behavior value
uint8 value

# Behavior numbers:
uint8 Run = 0                   # normal driving
uint8 Pause = 1                 # stop issuing servo commands
uint8 Off = 2                   # turn off devices
uint8 N_behaviors = 3

CarDriveStamped:

# CarDrive message with timestamp.
# $Id: CarDriveStamped.msg 1335 2011-04-22 02:32:41Z jack.oquin $

Header    header
CarDrive  control



2022-05-28 12:26