Software description
Here a general overview of the software used in the ADC competition is presented, including both the real and simulated robots. The links to a more detailed description of each one of the parts are also included.
Throughout all the software description, there will mainly exist three types of software modules that will be color marked to easily distinguish them:
-
Base modules: these are the software modules provided by IRI that have to be used as they are, not being able to modify them or use an alternative implementation. These modules are marked in red in the following diagrams.
-
Optional modules: these are the other software modules provided by IRI as an example of a simple and basic implementation of all the functionalities required for the ADC competition. These modules may be enough to complete very simple tasks, but in order to complete the ADC competition challenges you will need to upgrade them or use your own software modules. These modules are marked in green in the following diagrams.
-
External modules: these are general ROS packages that are used to complete the functionality provided by the IRI software modules. These modules are marked in blue in the following diagrams.
Both the base and optional software modules provided have been extensively tested, however it is still possible to find some bugs. In order to improve the software for all teams, if you find some possible bug, please report it using the slack application:
If you don't have access to the ADC slack group, you may also use the issues mechanism of the IRI Gitlab or email us at:
with the necessary information to solve the bugs.
The next image shows the hierarchical structure of all software associated with the ADC competition:

At the lowest level, the model car framework provides the general tools needed to use the car in general applications, as well as a common ROS interface for both the real and simulated robots so that they can be used indistinctly. The ADC competition frameworks builds on the model car framework to provide application specific tools required for the ADC competition, including the tools to handle the real and simulated environments.
Additionally, both the model car and ADC competition frameworks use a set of C++ libraries (tools) to implement some of the required functionalities.
The two frameworks and the general tools will be described in more detail in the next sections.
Tools
This includes several C++ libraries with useful tools for some IRI ROS packages. The next diagram shows the provided libraries and the relationship between them:

Next, a brief description of each of the software modules shown in the previous image is presented. Follow the corresponding link for further documentation.
-
OpenroadEd: this is a simple application designed to create both logical (OpenDRIVE standard) and geometrical (OpenSceneGraph) descriptions of road networks.
-
autonomous_driving_tools: Set of useful tools for autonomous driving of car-like robots. At the moment the tools included in this library are a gradient algorithm, a G2 spline implementation, the Dijkstra algorithm and an Opendrive format parser.
-
opendrive_to_gazebo: C++ library to parse an OpenDrive 1.4 road file format and extract the signals and objects to be used in the Gazebo simulator.
-
opendrive_road_map: This library is intended to find the shortest path between two points on a road (defined by the OpenDrive format) and then generate the geometric trajectory so it can be used as a global plan for a navigation framework.
Real world robot and ADC environment
This group includes all C++ drivers and ROS packages needed to operate the real robot and handle the different elements in the ADC competition environment such as semaphores. The next diagram shows all these software modules and the relationship between them:

Next, a brief description of each of the software modules shown in the previous image is presented. Follow the corresponding link for further documentation.
-
model_car_drivers: This C++ library includes the Linux drivers to handle the four Arduino based control boards present in the model car (actuators, egomotion, batteries and ultrasounds).
-
rgb_leds_driver: This C++ library includes the Linux drivers to handle both the car lights and the semaphores in the environment.
-
iri_model_car_actuators_driver: This ROS package is a wrapper of the model car actuators C++ driver. It accepts the desired speed and steering angle and sends the necessary command to the Arduino board. It also publishes the joint state information of the wheels and steering joints defined in the URDF file.
-
iri_model_car_egomotion_driver: This ROS package is a wrapper of the model car egomotion C++ driver. It publishes the IMU and wheel encoder data from the model car.
-
iri_model_car_battery_driver: This ROS package is a wrapper of the model car battery C++ driver. It publishes the current state of both payload and motor batteries.
-
iri_model_car_ultrasounds_driver: This ROS package is a wrapper of the model car ultrasounds C++ driver. It publishes the range distance of each ultrasonic sensor in a separate topic.
-
iri_model_car_bringup: This package provide the necessary launch files and configuration files to start up the model car.
Simulated robot and ADC environment
This group includes all the ROS packages needed to operate the simulated robot and create an ADC simulated environment taking all the information from the opendrive road description file. The next diagram shows all these software modules and the relationship between them:

Next, a brief description of each of the software modules shown in the previous image is presented. Follow the corresponding link for further documentation.
-
iri_model_car_controller: This package is a Gazebo plugin to control the model car in simulation and provides the same interface as the real model car.
-
iri_model_car_gazebo: This ROS package contains the simulation worlds and the main launch and configuration files for the simulated model car.
-
iri_sign_description: This package contains the urdf and launch files to load road sign images, which can be used in simulation.
-
iri_object_description: This package contains the urdf and launch files to load box and cylinder objects wich can be used in simulation.
-
iri_road_description: This package contains the urdf and launch files to load road images, which can be used in simulation.
Model car framework
The model car framework can be split into two parts: the general framework that provides the necessary tools to use the model car robot (either simulated or real) in a ROS environment, and the navigation framework that provides the necessary tools to plan an execute a path using a map.
Both frameworks are described in more detail in the next two sections.
General framework
This framework provides the necessary tools to:
-
Geometrically describe the car and to publish TF information between all frames.
-
Make all sensor data available using both standard and specific ROS messages (2D LIDAR, front and rear cameras, encoders, etc).
-
Control the motion of the model car using a standard Twist ROS message (cmd_vel).
-
Basic estimation of the robot's odometry fusing the wheel encoders and the IMU sensor using the robot_localization ROS package.
-
Set of launch files to easily use the car in several common settings (teleop, etc.)
The next diagram shows all these software modules and the relationship between them:

Next, a brief description of each of the software modules provided by IRI and shown in the previous image is presented. Follow the corresponding link for further documentation.
-
iri_model_car_msgs: Package containing ROS message definitions for the model car
-
iri_model_car_control: This ROS package generates the motion commands to the platform (both forward speed and steering angle) from a standard Twist ROS message.
-
iri_model_car_odometry: This ROS package generates the odometry information from the encoder provided by the platform.
-
iri_model_car_description: This ROS package contains the physical description of a 1:8 scale model car used for the ADC competition. This description can be used either in the real model car or in the simulated model.
-
iri_model_car_launch: This package provide some user launch files and configuration files to start up the model car and run some advanced functionalities.
A more detailed description of the local and global localization can be found in this tutorial
Navigation framework
This framework provides with:
-
A command velocity multiplexer to accept motion commands from the teleop, navigation and other interfaces with pre-defined priorities.
-
Globally localize the robot using a map using the AMCL and the robot_localization ROS packages.
-
The SBPL global planner ROS package to generate a path using a map.
-
A custom local planner to take into account the ackermann kinematic constraints of a car-like robot.
-
A set of launch files to easily use the car in several common settings (navigation with or without map, mapping, etc.)
The next diagram shows all these software modules and the relationship between them:

Next, a brief description of each of the software modules provided by IRI and shown in the previous image is presented. Follow the corresponding link for further documentation.
-
iri_model_car_rosnav: This package contains navigation related parameters and launch files particular to the model car robot.
A more detailed description of the local and global localization can be found in this tutorial
A more detailed description of the general navigation framework can be found in this tutorial
ADC competition framework
The ADC competition framework, mainly provides the same feature of the model car framework with the specific configuration for the ADC competition. Additionally, it also provides a new navigation framework using Opendrive based maps and the communication framework with the jury.
Both frameworks are described in more detail in the next two sections.
Opendrive navigation framework
This framework provide the necessary tools to:
-
Globally localize the robot using a map using the AMCL, a custom localization module using visual markers, and the robot_localization ROS packages.
-
A custom global planner using the geometric description of a road defined by the Opendrive standard.
-
A custom local planner to take into account the ackermann kinematic constraints of a car-like robot.
-
Set of launch files to easily use the car in several common settings (navigation with or without map, mapping, etc.)
-
A set of example road descriptions to use as an example.
The next diagram shows all these software modules and the relationship between them:

Next, a brief description of each of the software modules provided by IRI and shown in the previous image is presented. Follow the corresponding link for further documentation.
-
iri_opendrive_global_planner: This package is a move base global planner plugin that uses the Opendrive road description format to generate a path.
-
iri_adc_launch: This package provide some ADC participant oriented launch files and configuration files to start up the model car and run some advanced functionalities.
-
iri_adc_landmarks_slam_solver: This node provides a global localization by landmarks.
-
iri_adc_circuit_example: This package contains some ADC participant oriented example circuits and the related files to work with.
Jury communication framework
This framework provide the necessary tools to:
-
Handle the communications between the jury and the car. This communication includes:
- Send the set of goals to reach for each challenge.
- Signal the start condition.
- Signal any other condition depending on the challenge,
-
Handle the communication between the car and the jury. This communication includes:
- Real time telemetry of the current position and speed of the car.
- Notification of all required event depending on the challenge.
- Compressed images for display purposes.
The next diagram shows all these software modules and the relationship between them:

Next, a brief description of each of the software modules shown in the previous image is presented. Follow the corresponding link for further documentation.
-
iri_adc_msgs: Package containing ROS message definitions for the ADC competition.
-
iri_adc_gui: Package to run a ROS web based graphical user interface as the one that will run in the jury computer.
-
iri_adc_jury_server: Simple example of action server and service server needed to communicate with jury computer.
-
iri_adc_jury: This package performs the ADC jury ROS communications with the model car platform. DEPRECATED
Basic and optional software modules
As a summary, here is a list of software modules that must be used by all teams and can not be modified:
On the other hand, the optional modules that can be modified, upgraded or substituted by user defined software modules are: