Using CBSystem
From CajunBot Wiki
After compiling all of CBSystem's binaries, you'll want to test that everything is running correctly. There should be a script called test_simulation now installed in the $CBHOME/bin path, which should be accessible in your PATH variable that you've set up.
Run the script:
$ test_simulation
You should see a visualization window pop up similar to the following:
The player will show in this paragraph
Contents |
[edit] Documentation
The documentation directory for CBSystem is located in $CBHOME/docs. Many of the documents in this directory or either outdated or already locatable on this wiki. However, this is the location that the automatic documentation generation script will place its file.
Generating documentation from source
Make sure that you have the optional package doxygen installed (listed on the installation instructions). Run the script create_documentation to generate the html files for the API reference of CBSystem. When complete, the files will be put in your $CBHOME/docs/man4 directory, and a link will be placed on your desktop called cbsystem_documentation.html.
$ create_documentation ... Generating index file in '/home/mark/cbsystem/docs/man4/html'. Creating link on desktop to '/home/mark/cbsystem/docs/man4/html/index.html' create_documentation: quitting.
Here is an example of the documents generated:
[edit] Important Programs
Here is a list and short description of some of the more important programs/scripts in CBSystem.
- cb_remote - used to read remote data queues off of the network (usually from UDP packets) and publish the data to local shared memory queues.
- cbsim - built using ODE to fully simulate CajunBot's world. Vehicle dynamics, sensors, terrain, and other objects are all simulated to create an accurate representation of how the simulated vehicle would behave under real world conditions.
- cbstat - GUI frontend for managing the CajunBot software running on the bot's computers. It manages the startup and shutdown of programs on all the computers, displays queue information, error messages, and allows real time visualization using cbviz.
- cbviz - portal into CajunBot's world. The visualizer is used to view the output of simulation data, playback data from prior runs, or real time data while the bot is operating autonomously. The visualizer allows the user to view the sensor data in an understandable manner, as well as visualize output from other programs such as the planned path.
- clean_shared_mem - used to erase the contents of the shared memory data queues used in cbsystem.
- control_logd - used to enable and disable logging, as well as change the destination log directory.
- daemonize - a UNIX daemon server program that can run processes in the background. It works by using the fork-exec technique used in UNIX/LINUX and then detaching itself as the owner of the child process. This is used for starting the programs on the bot computers without having to maintain a continuous connection open.
- data_logd - used for writing data from the shared memory data queues to disk in the form of binary log files.
- pause_logd - used to suspend the logging operations, has similar functionality to control_logd.
- play_back - used for playback mode in which log data files are read from disk a populated to local shared memory queues.
- provide_blocked_lane - attempts to map sensor input onto traffic lanes to determine which lanes are blocked and where at on the lane the blockage occurred.
- provide_lane - used to populate lane data for the steering controller to follow, such as in the situation where there are sparse GPS waypoints.
- read_log_data - used to convert a binary log file into a human-readable format. The human-readable format is similar to the output that test_shared_mem gives.
- sensor_gp_driver - transforms raw sensor input into a world-referenced frame (global points).
- sick_driver - one of many driver programs that get data directly from sensors, this one in particular from a SICK sensor.
- start_playback - script used for recreating and playing back logged data from either simulation or real world runs.
- start_simulator - script used for starting the simulation world containing the virtual CajunBot and virtual sensors. It also starts all AGV programs normally used while on the bot. The visualizer can be started using this script as well.
- test_shared_mem - used to read and write from shared data queues in cbsystem.
- uc_planner - path planner designed by Team CajunBot for the DARPA Urban Challenge 2007.
- uc_steering - steering controller developed for RaginBot to use in the 2007 Urban Challenge. It is a PID-based controller.
[edit] Important Configuration Files & Directories
Configuration files and directories for CBSystem are located in $CBCONF. Below is a short listing of the more important configuration files and directories, as well as a short description of what they are used for. For a more detailed listing and description of various configuration files, please see Category:CBConf.
Important directories in $CBCONF:
- cajunSim & raginbot - these folders contain mode-specific configuration files needed by various programs in CBSystem. The folder cajunSim is used when simulation runs are being performed in the lab, while raginbot is used while the software is running on the live vehicle. When in playback mode, whichever mode the log files were saved from determines which folder is used. Note that both of these directories will contain all of the same subdirectories and most of the same files, but with different parameters. The list below will describe in further detail the important directories in these folders.
- mdf - contains MDF mission files for the bot to use as the basis for its goals to complete for a specific mission. In short, these files describe the speed limits for each segment and zone listed in the RNDF file being used, and also the required checkpoints that the vehicle must visit to complete a mission.
- objects - contains simulation setup files to populate the simulation with other vehicles and obstacles that the bot needs to interact with. Using the cbtraffic_editor, someone can script various traffic scenarios to test the bot's sensing and planning abilities.
- rndf - contains RNDF map files for the bot to use as the basis for its navigation. In short, these files describe a network of roads and zones at some point on the earth, and their connections. The bot uses this to plan its route when given a mission by the MDF files.
- visualizer - contains configuration files for the visualizer in various situations. Currently, this includes configuration settings for the visualizer while running in simulation, playback and "onbot" modes.
Important directories in $CBCONF/raginbot & $CBCONF/cajunSim:
- machine_configurations - as a subdirectory to the onboard directory, this contains configuration files central to which programs will be start up on which machines. This is the first place to look when wanting to redistribute the workload amongst bot computers.
- navigation - contains configuration files for the navigator (aka path planner). These files have parameters corresponding to costs associated with certain actions, how aggressive the planner should be, radii for certain types of turns, et cetera.
- onboard - sensor related configuration files. Contains an important file cajun.conf (described in next list), as well as sensor-related files containing mounting location and orientation, maximum read range, associated queue id, and machine_configurations directory.
- robot_model - default location to look for the model of the vehicle when obstacle files are not used in the simulator.
- sension_fusion - contains files related to obstacle detection. Parameters to control velocity cutoffs for considering an obstacle as moving and for considering it stationary (because invalid sensor returns may show obstacle as moving when it is not).
- steering - contains files for steering controllers. Parameters include controlling aggressiveness from a stop, rate at which to decelerate, look ahead distance, and many more related to the specific steering controller being used.
- vision - camera related configuration files for edge detection and image saving directory.
Important files in $CBCONF:
- cajun.conf - configuration file used in all modes (onbot, playback, and simulation) that maps physical sensor device addresses to which driver will be interfacing with the sensor and the queue that it will be publishing data to. It also contains the planner algorithm to use, the steering algorithm to use, and other similar parameters.
- cbviz_simulation.conf - This file and other related visualizer configuration files specify what kind of data will be visible in the visualizer, the camera style, and various colors or methods to use when displaying data.
- distributed_mode.conf - contains information about which machines are being used to run the CBSystem software (by IP address), which startup scripts to use from distributed_system, as well as which machines those scripts will be started on. It also defines the startup order for the various scripts so that GPS drivers are started before the path planner, et cetera. This is the place to change the distribution of programs across the bot's machines.
- log_system.map - contains information about which queues to publish and to log. This file can specify the rate at which data is broadcasted and logged and is central to controlling what kind of data is available in the local shared memory queues as well as which data is pushed onto the network to other computers.
- site_visit.mdf - an example mission data file (MDF) used for telling the software what its mission checkpoints are, the order in which it should visit them, as well as the speed limits to obey on each segment and zone of the chosen RNDF file.
- objects.xml - custom object file that can be used in the simulator. The simulator needs an object file for the bot, and robot_object.txt is used by default, but custom files can be used instead. This file has the ability to define static simulated objects, dynamic simulated objects, as well as triangle mesh files made from sensor data.
- site_visit.rndf - an example route network definition file (RNDF) used for telling the software what the road network is with specific latitude and longitude waypoints and the connectivity of each segment (road) and zone in the file, stop signs, etc.
- robot_object.txt - contains the default robot model for simulation of the CajunBot. It uses the old object file format. When creating a custom object file, this file is ignored and the custom object file is used instead.
- scan_gp_driver_0.conf - This file and others like it in the $CBCONF/onboard directory contain information related to the physical position that the sensor is mounted on the bot, the orientation that it is facing, the maximum range of the sensor, the queue id that the driver using it should publish to, and other parameters.
- sensor_fusion.conf - contains parameters for merging various sources of sensor data into a single stream for determining obstacles. For example, a parameter such as min_obstacle_distance_from_lane='1.35' tells the sensor fusion model to not count any sensor data that is further than this distance from a lane as being part of another object.
- steering.conf - parameters for which throttle algorithm or steering algorithm to use, as well as specific parameters related to the chosen algorithm.
- uc_planner.conf - contains configuration parameters that the uc_planner program uses in making its decisions. For example, a couple of the entries include: wait_after_intersection_precedence='1.0' which pertains to how long to wait after the vehicle has gained precedence at an intersection before moving, and max_intersection_speed='7.0' which tells the planner the maximum speed it should use when driving through an intersection.
- velocity.conf - contains parameters used for cutoffs to consider objects as being static or dynamic (moving). For example, a parameter such as static_velocity='0.01' says that any collection of points determined as belonging to the same object with a collective velocity less than this value are to be considered as being static (stationary).
[edit] Examples
Start a simulation with the visualizer enabled using the specified RNDF map file and corresponding MDF mission file, with logging disabled:
$ start_simulator -r $CBCONF/rndf/<rndf_file>.rndf -m $CBCONF/mdf/<mdf_file>.mdf -L
See the data currently be populated to a particular queue:
$ test_shared_mem -d nav queue reader jumped forward (nav) 5.27 592011.01 3342951.54 1.64 0.00 0.00 0.00 W 5.28 592011.05 3342951.58 1.64 0.00 0.00 0.00 W 5.29 592011.09 3342951.61 1.64 0.00 0.00 0.00 W 5.30 592011.13 3342951.64 1.64 0.00 0.00 0.00 W 5.31 592011.17 3342951.67 1.64 0.00 0.00 0.00 W
See a listing of queue choices for test_shared_mem:
$ test_shared_mem
Erase all data queues on the system:
$ clean_shared_mem
Create a template mission file from a map file (output will be sent to stdout):
$ mdf_template $CBCONF/rndf/site_visit.rndf MDF_name /home/mark/cbsystem/conf/rndf/site_visit.mdf RNDF /home/mark/cbsystem/conf/rndf/site_visit.rndf format_version 1.0 creation_date 03/28/2010 checkpoints num_checkpoints 2 1 56 end_checkpoints speed_limits num_speed_limits 3 1 0 30 2 0 30 3 0 30 end_speed_limits end_file
Adding traffic to a simulation:
- Start cbtraffic_editor and follow the instructions here. - Run start_simulator with an additional -O <object file> argument.
