BaseArnl Documentation

1.7.1

Introduction to the ARNL SDK and BaseArnl libary

ARNL is MobileRobots Inc.'s software development kit for localizing and intelligently navigating mobile robots. ARNL performs two major tasks: Localization uses sensor information together with robot odometry data, and a prepared environment map to find the most probable position of the robot within the map, and resets ArRobot's pose to reflect that position within the map's coordinate system. Path Planning and Navigation uses the robot's position and the map to determine a safe route from the current robot position to any given goal position. The path planning task also will drive robot along the planned path, adjusting the path to avoid unmapped obstacles on the way.

The SDK consists of the BaseArnl package (containing the BaseArnl, AriaForArnl and ArNetworkingForArnl libraries), plus a set of packages that contain libraries implementing various localization methods.

BaseArnl includes the path planning and navigation component of ARNL, as well as common features used by the localization libraries.

Path planning is described in more detail in Introduction to Path Planning.

Which localization libraries you have will depend on what software options were purchased. The 'Arnl' localization library contains ArLocalizationTask which uses data obtained from a scanning laser range finder (SICK LMS-200 or comparable) to localize. Arnl is part of the "Laser Navigation" accessory package. The 'SonArnl' localization library contains ArSonarLocalizationTask which uses the sonar (ultrasonic range sensors) for more approximate localization. SonArnl is included with any MobileRobots robot platform and can be used with any MobileRobots robot equipped with sonar. The 'MOGS' localization library contains ArGPSLocalizationTask which uses data from a GPS receiver to correct for odometry error and to locate the robot in a georegistered map. GPS localization is part of the "MOGS Outdoor Navigation" accessory package. It is also possible to use more than one localization tequnique simultaneosly, merging them into a unified result, though this feature is still experimental. (See Fusing Multiple Localizations with the ARNL Localization Manager more information about combining multiple localization.) All of the localization task classes from the various libraries are derived from ArBaseLocalizationTask in the BaseArnl library.

This reference manual describes the contents of the BaseArnl library, with references to the AriaForArnl and ArNetworkingForArnl libraries. For documentation on the localization libraries, see the reference manuals included with those packages.

ARIA (Advanced Robotics Interface for Applications) is the core MobileRobots library for operating the robot and accessory devices. ArNetworking is a framework for network communication, and among other uses allows remote clients such as MobileEyes to view the robot in its map with sensor data visualizatition, and to teleoperate the robot and change its configuration settings.

Note:: To ensure correct compatibility, programs using ARNL should link to the AriaForArnl and ArNetworkingForArnl libraries, rather than the seperately available plain Aria and ArNetworking libraries.

Programs using ARNL and ARIA typically run on a robot's onboard computer, and ARIA uses a serial port connection to communicate with the robot platform; or during development and testing, the program may run on a workstation and automatically communicate with the MobileSim simulator instead. The map (ArMap, in the Aria library) used in localization and planning contains several types of data and objects. Maps may include designated forbidden areas, goals and a "home" poses. You can build maps using the Mapper3 (tm) application from MobileRobots. The two tasks run in background threads. See below for more discussion.

Important note regarding required configuration changes for %Arnl 1.5 and later

It is _VERY_ important to note that ARNL 1.5 and later drives and path plans very differently (and much better!) than older versions, but that you may need to adjust some parameters to get this to happen. If you use old parameters the path planning may actually be worse but will at least be much much slower.

The new version follows the path much more closely than older versions. This version uses all of the movement parameters to determine how fast it needs to go at each point in the path. This means it uses the rotVelMax, rotAccel, rotDecel, transAccel, and transDecel to see how fast it can go around a corner, and when it has to start decelerating to make the turn. versions. This version uses all of the movement parameters to determine how fast it needs to go at each point in the path. This means it uses the rotVelMax, rotAccel, rotDecel, transAccel, and transDecel to see how fast it can go around a corner, and when it has to start decelerating to make the turn.

You can adjust the 'Driving*' parameters in the 'Path Planning settings' section, that will change the parameters in such a way that they will only apply when ARNL is path planning (so it won't affect teleop, or other driving you do with the robot). This involves sending those commands down to the robot whenever the path planning takes over, so if you aren't connected directly from the computer this might cause some problems. You can set these same parameters in the new 'Robot config' parameter section and they will only be sent down once, but they will apply to all driving the robot does. If you leave those parameters at their defaults of 0 the value used comes from the firmware. If you want to adjust those or see what that is you can use the configuration program for the microcontroller (ARCOScf, AROScf, p2oscf, etc).

Some values we've used are a rotVelMax of 250, rotAccel of 300, rotDecel of 300, transAccel of 600, transDecel of 600. This isn't appropriate for all robots or situations, but should give you an idea of the range of values, and that the higher you set them the better and faster ARNL will drive. You should obviously find values appropriate to your robot, your robot's payload, your robot's environment, and your robot's task. Note that for some of these you may need to change the *Top value with the configuration program for the microcontroller (some old robots shipped with low Top values). Also note that you that the gyros that we use will only give accurate readings until 300 degrees/sec, so your rotVelMax should never go over that value, and probably shouldn't come close. It is okay if the rotAccel or rotDecel is higher.

If you are using ARCOS you should get the latest version (1.9), since there was a bug in previous versions where rotDecel and rotAccel (or transAccel and transDecel) sent in the same 5 millisecond period would cause the first one to be overwritten which causes problems (especially since the software's idea of how the robot was driving didn't match the robot's idea).

Architecture and Operation

ARNL performs two related tasks, localization and navigation (by planning and following a path). Each of these tasks is performed in its own thread in the background, while your main program continues to execute.

To write a program using ARNL, include the Arnl/Aria.h, Arnl/Arnl.h and, if needed, Arnl/ArNetworking.h header files with your source code and link it with libBaseArnl, libAriaForArnl, and libAriaNetworkingForArnl libraries in Arnl/lib, as well as the appropriate localization library or libraries: libArnl, libSonArnl, libMogs.

You need to include four basic objects to enable localization: ArRobot, ArMap, ArPathPlanningTask, and a localization task object (one of ArBaseLocalization's subclasses -- see above for discussion about the localization task classes and libraries.) Other objects will also be required, such as ArRobotConnector, ArLaserConnector and laser range device objects if you're using laser localization, etc. See the ARIA documentation and example programs.

Aria and Arnl may be configured by modifying arnl/params.p, or through MobileEyes once it's running (if the program includes ArServerHandlerConfig object), or in the program through the global ArConfig object in Aria. For example, you can change the name of the map file used, change speeds and distance thresholds, etc.

Making maps

To localize and navigate, ARNL needs a map of the robot's operating environment showing obstacles to plan around (it will also plan around any obstacles recently sensed using sensor such as the laser or sonar). Maps may also contain logical features such as goal points, forbidden areas, and more.

The mapping process is different for each localization method, though the map files are compatible and can be reused if they contain enough information useful to other methods (for example, laser localization in particular needs an accurate map of laser-sensed obstacles to match with laser readings). See localization library reference manuals and other documentation for details on making maps.

Advanced Features of Path Planning and Navigation

In addition to the basic navigation, ARNL has advanced features which enable the robot to localize and navigate in a more specialized manner. Some of these are as follows. These features are complex to use. If you think you need any of them and have any questions, please ask on the aria-users forum.

Sectors: These are designated areas in the map which can be used to change the robot localization and navigation parameters when the robot enters the sector. For example, they can be used to slow down in certain sectors and speed up in some other sectors in the map. Several other behaviors are possible. Some of the important ones such as one-way areas are listed below.
See ArMap on details of how to define a sector. The user can add sectors such as one way areas to a map using MobileRobots' Mapper3 software.Advanced features such as different types of sectors will be incrementally added to ARNL as and when needed.
One way corridors: These allow the user to restrict the direction of the robot in certain areas of the map to be close to the preferred direction of the one way. The robot path in a one way area will be such that the dot product of the robot motion vector and the direction of the one way it is in is always greater than 0. The one way areas in the map will be defined as such in the given map. Note that the use of one way areas may cause otherwise accessible goals to become inaccessible or be reachable only in circuitous paths.
Re-plan paths using global range devices: These allow the user to setup the robot to use a ArGlobalReplanningRangeDevice which can hold certain range data in memory. This will allow the robot to replan a path when it finds the current path to goal is blocked. This is useful when rooms can be accessed through multiple doors some of which may be found to be closed on arrival.
Restrictive Boundary and Sectors: These are areas and lines in the map where the cost to traverse is higher than normal cells. These constructs can be used to force the robot to plan around unless there is no alternative.
Use of other robots for localization: When multiple robots are operated in the same map using a central server, there can be situations where the robot sees more of other robot boundaries than the map of the environment. In such cases the known poses and radii of the other robots (obtained from the central server) can be used for aiding instead of losing localization. ARNL now has the capability of adding known but unmapped objects in the map and using them for localization.
Inter-robot communication and mutual avoidance (ARNL laser localization package only): The multi-robot networking services allow robots to communicate their positions and path data either in a peer-to-peer fashion, or through a central server, to better avoid each other in a multiple-robot application. To use this feature, you must create an ArServerHandlerMultiRobotPeer or an ArServerHandlerMultiRobot object and configure relevant parameters. See the ArServerHandlerMultiRobotPeer and ArServerHandlerMultiRobot documentation for details.
Localization Manager. ARNL now has the capablility of localizing the robot in a map using multiple methods. When several localizations provide their estimates of the robot pose with varying degrees of accuracy, ARNL uses the localization manager to compute a weighted average of their estimates to find an optimal pose. The weights in the averaging is based on the variance matrices of their respective estimates. The localization manager does the actual move of the robots pose to this optimal pose using the moveTo command. (Earlier, the lone localization task object handled this moveTo).
To use the localization manager, you must construct the separate localization tasks and add each of them to ArLocalizationManager. The act of adding a localization task to the manager suppresses its ability to directly alter the robot pose using moveTo and instead lets the manager do it for them.
See Fusing Multiple Localizations with the ARNL Localization Manager for details

Documentation and Coding Convention

For clarity while you read this technical document, we follow common C++ coding conventions:

Class names begin with a capital letter.
Enums either begin with a capital letter or are all in caps.
Use enums or constant variables instead of preprocessor macros.
Member variables in classes are prefixed with 'my'.
Static variables in classes are prefixed with 'our'.
Member function names start with a lower case.
Capitalize each word except the first one in a name; likeThisForExample.
Write all code so that it can be used threaded.

Tuning Path Planning Parameter

The actual motion of the robot when following a path depends on a number of factors which are as follows.

Low level robot control parameters contained in ARIA such as the maximum allowable linear acceleration, its maximum allowable rotation accelerations etc as set in ARIA's robot parameter files p3dx.p when connected to a robot of type "p3dx".
The localization and path planning parameters used by ARNL such as the maximum linear and rotational velocities set in the configuration.
The degree of crowdedness of the actual environment the robot is moving in.

You can tune many parameters in ARNL to customize the behavior of the robot according to the robot's environment. These parameters are obtained by loading a parameter file using ARIA's ArConfig facility. By default, ARNL will load parameters from arnl.p. Parameters may also be changed on-line through MobileEyes.

For example, if the environment has few unmapped obstacles and is relatively fixed, the user can get away with a lower CollisionDistance parameter which will reduce the collision computation. If the robot has to navigate through narrow passages like doors, the PlanRes can be decreased to allow for more resolution. Changing some of these parameters can result in unintended consequences due to the limited resources such as the speed of the on board computer and memory. For example reducing the PlanRes by a factor will cause path planning computations to increase by the square of the factor. Planning and obstacle avoidance can also fail to operate as expected due to parameter values. (Remember, always test your software carefully in a controlled environment.)

The following subsection will list path-planning and navigation related parameters and their use. The default values are noted in paratheses.

The default parameters in default-arnl.p are meant to drive Pioneer class of robots in office type environments. If you are using a larger and heavier robot such as a Powerbot and especially Seekur, remember to tune the default parameters to your needs.

MaxSpeed: (750 mm/sec) Maximum speed during path following in mm/sec.
MaxRotSpeed: (100 degs/sec) Maximum rotational speed in degs/sec.
GoalDistanceTol: (200 mm) Distance in mm to the goal that will be considered as reached.
GoalAngleTol: (10 deg) Angle in degs to the goal orientation that will be considered as done with orientation.
GoalSpeed: (250 mm/sec) Maximum speed at which end move to goal is executed. (This value and the robot's inertia will decide the actual goal positioning accuracy).
GoalRotSpeed (33.3 degs/sec) Maximum rotational velocity at which end move to goal is executed. This value and the robot's inertia will decide the goal positioning accuracy. (A value of 0 will keep the normal driving value).
GoalTransAccel: (200 mm/sec/sec) Maximum linear acceleration at which end move to goal is executed. (A value of 0 will keep the normal driving value).
GoalTransDecel: (33.3 degs/sec/sec) Maximum linear deceleration at which end move to goal is executed. (A value of 0 will keep the normal driving value).
GoalRotAccel: (200 degs/sec/sec) Maximum rotational acceleration at which end move to goal is executed. (A value of 0 will keep the normal driving value).
GoalRotDecel: (33.3 mm/sec/sec) Maximum rotational deceleration at which end move to goal is executed. (A value of 0 will keep the normal driving value).
GoalSwitchTime: (0.4sec) Time in secs to switch into end move mode in addition to the coasting time. (To allow for slack in the ramping down of the velocity to zero).
GoalUseEncoder: (true) For fine positioning at goal, the robot can switch to moving based on its encoder pose only. This flag decides this.
GoalOccupiedFailDistance: (1000 mm) When the sensors see that the goal is occupied the robot will still be allowed to drive this close to the goal anyway. This is meant for cases where the robot encounters ramps which show up as obstacles from far away but will need to be traversed to get to the goal.
HeadingRotSpeed: (50 degs/sec) There will be some points on the path where the robot will be exclusively rotating to reach a heading. The user may wish to set the rotational speed in this situation to lower than normal especially when dealing with heavier robots like the Powerbot. (A value of 0 will keep the normal driving value) (This will not override the GoalRotSpeed).
HeadingRotAccel: (50 degs/sec/sec) There will be some points on the path where the robot will be exclusively rotating to reach a heading. The user may wish to set the rotational acceleration in this situation to lower than normal especially when dealing with heavier robots like the Powerbot. (A value of 0 will keep the normal driving value) (This will not override the GoalRotAccel).
HeadingRotDecel: (50 degs/sec/sec) There will be some points on the path where the robot will be exclusively rotating to reach a heading. The user may wish to set the rotational deceleration in this situation to lower than normal especially when dealing with heavier robots like the Powerbot. (A value of 0 will keep the normal driving value) (This will not override the GoalRotDecel).
PlanRes: (106.25 mm) The resolution of the grid used for path planning in mm. It is best to use an integral fraction of the robot half width to allow for more free space. Reduce the PlanRes to allow the robot to traverse through tight spaces such as doorways. Note that decreasing the PlanRes by 2 will increase computation by a factor of 4.
UseLaser: (true) Use the laser for collision avoidance?
UseSonar: (true) Use the sonar for collision avoidance? Due to the sonar inaccuracies the obstacles may appear larger. This flag can be used to set the sonar off when the robot has to navigate through narrow openings such as doors.
PlanFreeSpace: (425*3/2) Preferred distance from side of robot to obstacles. The path planner marks each grid cell depending on its distance to the nearest obstacle. Any cell within half the robot width of an occupied cell will still be non traversable by the robot. The cell at half robot width will be traversable but will have the maximum cost. The cost of the cells beyond half width will progressively decrease. The PlanFreeSpace is the distance from the side of the robot beyond which the cell cost stops decreasing and remains constant. Larger values will cause larger excursions around obstacles, (This variable is related to the FreeSpacing variable in previous versions of ARNL which was measured from the center of the robot).
FrontClearance: (100 mm) Front clearance in mm of the robot while avoiding obstacles.
SlowSpeed: (100 mm/sec) Speed below and at which is considered slow.
SideClearanceAtSlowSpeed: (100 mm) Side clearance in mm of the robot while avoiding obstacles when it is moving at or below the slow speed.
FrontPaddingAtSlowSpeed: (100 mm) Distance in addition to the front clearance of the robot while avoiding obstacles when it is moving at or below the slow speed. In this padding the super max translation deceleration will be allowed to engage to keep the obstacle away before slamming on eStop.
FastSpeed: (1000 mm/sec)Speed at or above which is considered fast.
SideClearanceAtFastSpeed: (1000 mm) Side clearance in mm of the robot while avoiding obstacles when it is moving at or above the fast speed.
FrontPaddingAtFastSpeed: (1000 mm) Distance in addition to the front clearance of the robot while avoiding obstacles when it is moving at or above the fast speed. In this padding the super max translation deceleration will be allowed to engage to keep the obstacle away before slamming on eStop.
SuperMaxTransDecel: (1000 mm/sec/sec) The maximum translational deceleration allowed for avoiding obstacles. This is used in conjunction with the padding parameters to limit the wear and tear if emergency deceleration is unlimited.
CollisionRange: (2000 mm) The distance from the robot within which the obstacles seen by the sensor and those on the map are used to compute the local path. A smaller collision range will result is lesser computation but may increase revision of path if the environment is constantly changing.
HeadingWt: (0.8) Heading weight for DWA. Unlike the heading objective computed from a destination pose on the path, as in the conventional DWA, we use a path matching function to match the arc made from the velocities with the desired computed path.
DistanceWt: (0.1) Distance weight for DWA. Distance refers to the distance to collision if any if the robot continues on the path computed from the velocities.
VelocityWt: (0.1) Velocity weight for DWA. Velocity refers to the linear velocity only.
SmoothingWt: (0.0) Smoothing weight for DWA. This is the weight given to smoother paths. The smoothing objective minimizes the changes in the linear and rotational velocities from this cycle from the velocities used in the previous cycle. This is probably useful only when smoothness not speed is more important. Set this to 0.1 or so for smoothly traversing narrow passages such as doors.
NforLinVelIncrements: (1) If N is the value of this parameter, the no of linear velocity increments of the search table is 2*N+1 for the DWA.
NforRotVelIncrements: (8) If N is the value of this parameter, the no of rotational velocity increments of the search table is 2*N+1 for the DWA.
SmoothWindow: (2) Smoothing window size for DWA. The sum of the various objectives for each element in the velocity table is far from smooth and a smoothing filter is used over the raw data.
ObsThreshold: (0.1) The threshold value of the occupancy grid to consider as occupied for path planning.
MatchLengths: (2.0) The DWA path matching distance is computed as a multiple of the robot lengths. This parameter decides the multiplier for this purpose. Shorter path lengths may be appropriate for driving through narrow openings such as doors at low speeds.
CheckInsideRadius: (true) If this flag is false, then the robot path tracking module will ignore any objects it sees inside its radius and still keep moving to its local goal point. This may be useful in case the user wants to reproduce such behavior in older versions of ARNL.
MaxExpansionFactor: (1.0) When the local path planner cannot find a path to a local goal due to an unmapped obstacle, it will look further down the path to an limited extent. If the user wants to force the planner to to look by bigger factor, this variable must be set to a value greater than one.
UseCollisionRangeForPlanning: (false) The robot plans ahead locally for a distance based on its speed. This may not be sufficient in some cases where the user may want it to look ahead till the CollisionRange of the sensors. This flag will enable the user to force the robot to look at least as far as the distance the sensors data is incorporated.
SecsToFail: (8secs) The time in seconds for which local search will continue trying to replan when it fails to find a safe local path to move and is motionless.
AlignAngle: (30 degs) When the robot is stopped, this is the minimum angle it will rotate in place to align to the planned path before it will move linearly.
AlignSpeed: (10 mm/sec) This is the velocity below which the robot will do the aligning to path direction before linear motion.
SplineDegree: (3) Degree of the B-Splines used to smooth local path.
NumSplinePoints: (5) The number of points that will be used to subdivide the look ahead in the local path which will then serve as the knots for the spline to form over.
CenterAwayCost: (1) Added cost of being away from the central spine of the one way areas. A zero would cause it to not consider centering at all.
Resistance: (2.0) Multiplied cost of traversing a cell in restrictive areas and lines. The normal cost for regular non-restrictive cell is 1.
ClearOnFail: (true) If this flag is true, any failure in the local path planning will force the cumulative range buffers to be cleared.
UseEStop: (true) If this flag is true, any obstacle in the path which cannot be avoided by regular robot deceleration will cause the software emergency stop to be engaged which will result in an almost instantaneous stop. (May not be suitable for platforms like the wheelchair).
CurvatureSpeedFactor (1.0) ARNL modulates the linear speed of the robot when it is negotiating a curve by using the curvature of the path and the maximum allowable velocities and accelerations (rotation & linear) for that robot. Despite this, it might be necessary to modulate the linear velocity further by this factor for user defined purposes. Increasing it beyond 1.0 will cause it to go slower on the curves and decreasing it to below 1.0 will cause it to go faster (and probably overshoot its desired path).
LocalPathFailDistance (1000.0 mm) When the sensors see that the local path is blocked, the robot will still be allowed to drive this close to the block. This is meant to help in cases where the robot senses false obstacles from afar and stops too soon such as on ramps. (The distance at which the robot actually stops will depend on the velocity of the robot).
MarkOldPathFactor (0.75) When the robot operates in an environment where there are a number of unmapped obstacles, the local path it plans may flip from one side of the obstacle to the other between cycles. To avoid this, ARNL marks the old path by reducing the costs of its cells by this factor. This factor should be a value between 0 and 1.
DrivingTransVelMax, DrivingRotVelMax ...: (0) These seven parameters related to vehicle velocity, acceleration and deceleration allow a user to override the default driving parameters when it is set to a value other than 0.

More Information

For more information on localization or path planning, read the module documentation below or in the "Modules" menu to the left.

Generated on Thu Aug 6 09:40:13 2009 for BaseArnl by

1.5.1