The Navigator Module (navigator)

The CARMEN navigator module. More...

Files
file	conventional.h
	Library for shortest-path motion planning.
file	navigator_interface.h
	Definition of the interface of the module navigator.
file	navigator_messages.h
	Definition of the messages for this module.
file	planner_interface.h
	Definition of interface to the shortest-path motion planner library.
Data Structures
struct	carmen_navigator_status_message
struct	carmen_navigator_plan_message
struct	carmen_navigator_set_goal_message
struct	carmen_navigator_set_goal_triplet_message
struct	carmen_navigator_autonomous_stopped_message
struct	carmen_navigator_map_request_message
struct	carmen_navigator_map_message
struct	carmen_navigator_placename_message
struct	carmen_navigator_return_code_message
struct	carmen_navigator_display_config_message
struct	carmen_planner_path_t
struct	carmen_planner_status_t
Defines
#define	CARMEN_NAVIGATOR_STATUS_QUERY_NAME   "carmen_navigator_status_query"
#define	CARMEN_NAVIGATOR_PLAN_QUERY_NAME   "carmen_navigator_plan_query"
#define	CARMEN_NAVIGATOR_STOP_NAME   "carmen_navigator_stop"
#define	CARMEN_NAVIGATOR_GO_NAME   "carmen_navigator_go"
#define	CARMEN_NAVIGATOR_STATUS_NAME   "carmen_navigator_status"
#define	CARMEN_NAVIGATOR_STATUS_FMT   "{int,int,{double, double, double},{double, double, double, double, double},double,string}"
#define	CARMEN_NAVIGATOR_PLAN_NAME   "carmen_navigator_plan"
#define	CARMEN_NAVIGATOR_PLAN_FMT   "{<{double, double, double, double, double}:2>,int,double,string}"
#define	CARMEN_NAVIGATOR_SET_GOAL_NAME   "carmen_navigator_set_goal"
#define	CARMEN_NAVIGATOR_SET_GOAL_FMT   "{double,double,double,string}"
#define	CARMEN_NAVIGATOR_SET_GOAL_TRIPLET_NAME   "carmen_navigator_set_goal_triplet"
#define	CARMEN_NAVIGATOR_SET_GOAL_TRIPLET_FMT   "{{double,double,double},double,string}"
#define	CARMEN_NAVIGATOR_AUTONOMOUS_STOPPED_NAME   "carmen_navigator_autonomous_stopped"
#define	CARMEN_NAVIGATOR_AUTONOMOUS_STOPPED_FMT   "{int,double,string}"
#define	CARMEN_NAVIGATOR_MAP_REQUEST_NAME   "carmen_navigator_map_request"
#define	CARMEN_NAVIGATOR_MAP_REQUEST_FMT   "{int,double,string}"
#define	CARMEN_NAVIGATOR_MAP_NAME   "carmen_navigator_map"
#define	CARMEN_NAVIGATOR_MAP_FMT   "{<char:2>,int,int,{int,int,double,string},int,double,string}"
#define	CARMEN_NAVIGATOR_SET_GOAL_PLACE_NAME   "carmen_navigator_set_goal_place"
#define	CARMEN_NAVIGATOR_SET_GOAL_PLACE_FMT   "{string,double,string}"
#define	CARMEN_NAVIGATOR_RETURN_CODE_NAME   "carmen_navigator_return_code"
#define	CARMEN_NAVIGATOR_RETURN_CODE_FMT   "{int,string,double,string}"
#define	CARMEN_NAVIGATOR_DISPLAY_CONFIG_NAME   "carmen_navigator_display_config"
#define	CARMEN_NAVIGATOR_DISPLAY_CONFIG_FMT   "{string, int, string, int, double, string}"
Typedefs
typedef carmen_default_message	carmen_navigator_status_query_message
typedef carmen_default_message	carmen_navigator_plan_query_message
typedef carmen_default_message	carmen_navigator_stop_message
typedef carmen_default_message	carmen_navigator_go_message
typedef *	carmen_planner_path_p
typedef *	carmen_planner_status_p
Enumerations
enum	carmen_navigator_reason_t { CARMEN_NAVIGATOR_GOAL_REACHED_v, CARMEN_NAVIGATOR_USER_STOPPED_v, CARMEN_NAVIGATOR_UNKNOWN_v }
enum	carmen_navigator_map_t {   CARMEN_NAVIGATOR_MAP_v, CARMEN_NAVIGATOR_ENTROPY_v, CARMEN_NAVIGATOR_COST_v, CARMEN_NAVIGATOR_UTILITY_v,   CARMEN_LOCALIZE_LMAP_v, CARMEN_LOCALIZE_GMAP_v }
Functions
void	carmen_conventional_dynamic_program (int goal_x, int goal_y)
void	carmen_conventional_find_best_action (carmen_map_point_p curpoint)
void	carmen_conventional_end_planner (void)
double *	carmen_conventional_get_utility_ptr (void)
double *	carmen_conventional_get_costs_ptr (void)
double	carmen_conventional_get_utility (int x, int y)
double	carmen_conventional_get_cost (int x, int y)
void	carmen_conventional_build_costs (carmen_robot_config_t *robot_conf, carmen_map_point_t *robot_posn, carmen_navigator_config_t *navigator_conf)
void	carmen_navigator_subscribe_status_message (carmen_navigator_status_message *status, carmen_handler_t handler, carmen_subscribe_t subscribe_how)
void	carmen_navigator_subscribe_plan_message (carmen_navigator_plan_message *plan, carmen_handler_t handler, carmen_subscribe_t subscribe_how)
void	carmen_navigator_subscribe_autonomous_stopped_message (carmen_navigator_autonomous_stopped_message *autonomous_stopped, carmen_handler_t handler, carmen_subscribe_t subscribe_how)
int	carmen_navigator_query_status (carmen_navigator_status_message **status)
int	carmen_navigator_query_plan (carmen_navigator_plan_message **plan)
int	carmen_navigator_set_goal (double x, double y)
int	carmen_navigator_set_goal_triplet (carmen_point_p goal)
int	carmen_navigator_set_goal_place (char *name)
int	carmen_navigator_stop (void)
int	carmen_navigator_go (void)
int	carmen_navigator_get_map (carmen_navigator_map_t map_type, carmen_map_t *map)
int	carmen_planner_update_robot (carmen_traj_point_p new_position, carmen_navigator_config_t *nav_conf)
int	carmen_planner_update_goal (carmen_point_p new_goal, int any_orientation, carmen_navigator_config_t *nav_conf)
int	carmen_planner_next_waypoint (carmen_traj_point_p waypoint, int *is_goal, carmen_navigator_config_t *nav_conf)
void	carmen_planner_set_map (carmen_map_p map, carmen_robot_config_t *robot_conf)
void	carmen_planner_reset_map (carmen_robot_config_t *robot_conf)
void	carmen_planner_update_map (carmen_robot_laser_message *laser_msg, carmen_navigator_config_t *nav_config, carmen_robot_config_t *robot_conf)
void	carmen_planner_update_grid (carmen_map_p new_map, carmen_traj_point_p new_position, carmen_robot_config_t *robot_conf, carmen_navigator_config_t *nav_conf)
carmen_navigator_map_message *	carmen_planner_get_map_message (carmen_navigator_map_t map_type)
void	carmen_planner_get_status (carmen_planner_status_p status)
double *	carmen_planner_get_utility (void)
int	carmen_planner_goal_reachable (void)

---

Detailed Description

The CARMEN navigator module.

The CARMEN navigator module the provides path planning module to guide the robot through the environment.

The navigator module consists of 4 main components:

1. A motion planning library, contained in libconventional.a. This library computes the shortest path through the current map by computing a utility function, and extracting from the utility function a sequence of grid cells that arrives at the goal with the shortest path.
2. A planner abstraction that allows laser data to update the internal map representation, recomputes any additional structures (e.g., the cost map and utility functions as a result of the updated map), and returns a path as a sequence of way points by greedy split-and-merge on the grid cell path sequence.
3. A navigator abstraction that manages IPC, and uses a P-D loop to servo the robot towards the next waypoint in the path.
4. A navigator GUI that reports on the state of the robot, path, etc.

---

Function Documentation

void carmen_conventional_build_costs (  carmen_robot_config_t *  robot_conf, carmen_map_point_t *  robot_posn, carmen_navigator_config_t *  navigator_conf )

Converts the occupancy grid map into a cost map by incorporating the width of the robot, and adding additional penalties for getting close to obstacles.

void carmen_conventional_dynamic_program (  int  goal_x, int  goal_y )

Computes the utility function using dynamic programming. carmen_conventional_build_costs must have been called first.

void carmen_conventional_end_planner (  void   )

Frees memory structures.

void carmen_conventional_find_best_action (  carmen_map_point_p  curpoint  )

Takes in the current position (as a map grid cell) and replaces the argument with the best neighbour grid cell to visit next. carmen_conventional_dynamic_program must have been called first.

double carmen_conventional_get_cost (  int  x, int  y )

Returns the value of the cost map at a specific point.

double* carmen_conventional_get_costs_ptr (  void   )

Returns the cost map as an array of doubles with the same dimensions as the map in row-major order.

double carmen_conventional_get_utility (  int  x, int  y )

Returns the value of the utility function at a specific point, that is, the cost-to-goal.

double* carmen_conventional_get_utility_ptr (  void   )

Returns the utility function as an array of doubles with the same dimensions as the map in row-major order.

int carmen_navigator_get_map (  carmen_navigator_map_t  map_type, carmen_map_t *  map )

Asks for one of the navigator maps. The navigator maintains its own internal occupancy grid, updated with recent laser measurements. The cost map and utility function can also be queried.

int carmen_navigator_go (  void   )

Starts the robot moving toward the goal.

int carmen_navigator_set_goal (  double  x, double  y )

Using this function causes the robot to reach the goal, without regard to its final orientation. This function does not start the robot moving: carmen_navigator_go() must be called.

int carmen_navigator_set_goal_place (  char *  name  )

Using this function causes the robot to try and reach specific place, as specified in the current map. The navigator queries the current set of places defined in the map (usually provided by the param_daemon, but possibly by some other map server process). If the place is specified only as an (x,y) pair then the robot's final orientation will not be controlled. If the place is specified as an (x,y,theta) triplet or an (x, y, theta) (sigma x, sigma y, sigma theta) 6 dimensional location, the planner will try for a final orientation matching the specified theta as well.

int carmen_navigator_set_goal_triplet (  carmen_point_p  goal  )

Using this function causes the robot to reach a final pose, including orientation. This function does not start the robot moving: carmen_navigator_go() must be called.

int carmen_navigator_stop (  void   )

Causes the navigator to stop trying to reach the goal. This also causes an autonomous_stopped message to be emitted. The goal position is unaffected. The trajectory can be resumed by calling carmen_navigator_go() again.

void carmen_navigator_subscribe_autonomous_stopped_message (  carmen_navigator_autonomous_stopped_message *  autonomous_stopped, carmen_handler_t  handler, carmen_subscribe_t  subscribe_how )

An autonomous stopped message is emitted whenever the robot stops trying to reach a goal. This can happen because the robot reached its goal, the navigator was told to stop navigating, or some unmodelled failure.

void carmen_navigator_subscribe_plan_message (  carmen_navigator_plan_message *  plan, carmen_handler_t  handler, carmen_subscribe_t  subscribe_how )

A plan message is emitted whenever the plan changes.

void carmen_navigator_subscribe_status_message (  carmen_navigator_status_message *  status, carmen_handler_t  handler, carmen_subscribe_t  subscribe_how )

Status messages are emitted whenever an odometry, front laser or global position message is received.

carmen_navigator_map_message* carmen_planner_get_map_message (  carmen_navigator_map_t  map_type  )

A helper function for extracting the internal representation of the map, cost map or utility function.

void carmen_planner_get_status (  carmen_planner_status_p  status  )

Returns the current state of the plan.

double* carmen_planner_get_utility (  void   )

A helper function for getting the current utility function. Probably subsumed by carmen_planner_get_map_message, but returns the utility function as an array of doubles of same size as the map, in row-major order.

int carmen_planner_goal_reachable (  void   )

A utility function for determining whether or not the goal is accessible from the current robot position. Returns 1 if the goal has been set and a feasible path exists from the robot to the goal, returns 0 otherwise.

int carmen_planner_next_waypoint (  carmen_traj_point_p  waypoint, int *  is_goal, carmen_navigator_config_t *  nav_conf )

Assumes value of waypoint passed in is current robot position. Regenerates trajectory, searches along path for next waypoint that is more than nav_conf->goal_dist away from the current robot position. If this is the goal point, also checks to see if robot needs to turn to face goal orientation (only matters if the goal was specified with an orientation. Returns 1 if robot reached goal, returns -1 if no path exists, otherwise returns 0 and fills in next destination waypoint.

void carmen_planner_reset_map (  carmen_robot_config_t *  robot_conf  )

Clears any local modifications the planner may have made to its internal map.

void carmen_planner_set_map (  carmen_map_p  map, carmen_robot_config_t *  robot_conf )

Updates the planner to have a new map.

int carmen_planner_update_goal (  carmen_point_p  new_goal, int  any_orientation, carmen_navigator_config_t *  nav_conf )

Updates the current goal, replans and regenerates the trajectory. Returns 1 if a new path was generated, otherwise returns 0

void carmen_planner_update_grid (  carmen_map_p  new_map, carmen_traj_point_p  new_position, carmen_robot_config_t *  robot_conf, carmen_navigator_config_t *  nav_conf )

A helper function for replacing the map and initializing the robot function.

void carmen_planner_update_map (  carmen_robot_laser_message *  laser_msg, carmen_navigator_config_t *  nav_config, carmen_robot_config_t *  robot_conf )

Adds a laser scan to the planner's internal map using ray-tracing. Scans are forgotten over time, or can be removed using carmen_planner_reset_map.

int carmen_planner_update_robot (  carmen_traj_point_p  new_position, carmen_navigator_config_t *  nav_conf )

Updates the internal position of the robot inside the planner and regenerates the trajectory. Returns 1 if a new path was generated, otherwise returns 0

---