Develop CI/CD Processes

| DockerHub Image Build | Unit Tests Workflow | Sonar Code Quality | |———————-|———————|———————| | | |

CARMA

CARMA^SM advances research and development to accelerate market readiness and deployment of cooperative driving automation, while advancing automated driving technology safety, security, data, and artificial intelligence. It encourages collaboration and participation by a community of engineers and researchers to advance understanding of cooperative driving automation using open source software (OSS) and agile project management practices.

CARMA is a reusable, extensible platform for controlling SAE level 2 connected, automated vehicles (AVs). It provides a rich, generic API for third party plugins that implement vehicle guidance algorithms to plan vehicle trajectories. It is written in C++ and runs in a Robot Operating System (ROS) environment on Ubuntu. The platform can be reused on a variety of properly equipped vehicles. Migration has begun from the ROS 1 framework to ROS 2.

This readme updated: October 23, 2020

What Is CARMA Platform

Managing automated vehicle motion involves three aspects. The first is navigation, also known as localization, which is the act of determining where the vehicle currently is with respect to the earth and with respect to the desired path of travel (its planned route). The second is guidance, also known as trajectory planning, which includes the processes of determining how the vehicle is to move from its current location to its destination. The destination and route will be handed to the guidance algorithms, and they then determine how the vehicle’s motion needs to be adjusted at any time in order to follow the route. The third aspect of automated vehicle motion is control, which covers the actuation of the vehicle’s physical devices to induce changes in motion (for land vehicles these are typically causing the wheels to rotate faster or slower and turning the steering wheel). Therefore, the navigation solution becomes an input to the guidance function, and the guidance solution becomes an input to the control function. As the vehicle moves, obviously its location changes so that the navigation function constantly needs to update its solution and the cycle iterates as quickly as necessary to produce a smooth and accurate vehicle motion. The rate of iteration is largely determined by the expected speed of the vehicle.

CARMA Platform provides the navigation and guidance functions for its host vehicle, as well as some of the control functions. It depends on low level controller hardware to provide the rest of the control function. The current version of CARMA Platform provides SAE level 3+ autonomy, with both speed and steering control.

Documentation

Documentation of the setup, operation, and design of the CARMA Platform can be found on the project Confluence pages. Additional documentation can be found on the Doxygen Source Code Documentation page.

Release Notes

The current version and release history of the CARMA software platform: CARMA Release Notes

Repo Structure Note: The master and develop branches of this repo (and all other repos in the usdot-fhwa-stol GitHub organization) now reflects the third generation of CARMA code and documentation, called CARMA3. It uses Autoware to provide SAE level 2 and 3 automation capability. The legacy CARMA2 code is still being supported. It was used extensively by FHWA during 2018 for SAE level 1 experiments. To work with that code base, please check out the CARMA2-integration branch and make pull requests to it (using the contribution process outlined below).

ROS Version Note: Release 3.11 was the final version of CARMA Platform to contain only ROS1 code. The develop branches and future versions will contain a mix of ROS1 and ROS2 code in a mixed system until all code has been fully ported to ROS2. You can learn more about this system and the ROS2 migration efforts on confluence here: CARMA Platform ROS2 Docs

Roadmap

The current CARMA ecosystem development direction and release plans can be found here: CARMA Roadmap

Current Status of ROS 1 and ROS 2 Packages

The current CARMA Platform system operates as a hybrid of ROS 1 Noetic and ROS 2 Humble components. While nearly all components have been upgraded to ROS 2 Humble, a small amount of ROS 1 Noetic content still exists within the system, including some packages in this repository. For more information, please see the relevant documentation in the carma-config repository.

Architecture Guide

The documentation describes the software architecture within a single CARMA vehicle. There may be several of these vehicles operating in concert, communicating with each other through a V2X radio or cellular means. They can also communicate with roadside infrastructure using a V2X radio or cellular. The communication among software components within a single vehicle, however, is mostly done via the Robot Operating System (ROS) framework. There are no ROS communications between neighboring vehicles. CARMA3 System Architecture

For information on the CARMA2 architecture, please see CARMA2 System Architecture

Detailed Design Documents

Please see the Detail Design document page for detailed design specification for CARMA and other additional information. Detail Design Page

Developers Guide

Useful development documentation and instructions for the setup of a development environment for CARMA Platform can be found at the following pages:

• CARMA Development Resources
• Development Environment Setup

A plug-in developers guide for CARMA3 will be coming soon.

For a description of the approach to develop a plug-in for CARMA2, please see CARMA 2.7 Developers Guide

Users Guide

A user guide for CARMA3 will be coming soon.

For a description of the functionality specific to CARMA2 on the Cadillac SRX, see CARMA User Guide

Administrator Guide

An administrator guide for CARMA3 will be coming soon.

For administrative information on CARMA2, including vehicle and developer PC configuration, build, deployment and testing steps necessary to install and run CARMA Platform, please see Administrator Guide

Other CARMA Packages

CARMA Platform^SM is a downloadable, open source software (OSS) platform architected to be extensible and reusable for a wide variety of research purposes to advance innovation for cooperative driving automation. It enables communication between vehicles, road users such as pedestrians, bicyclists, and scooters, and infrastructure devices capable of communication. It promotes collaboration between a community of engineers and researchers to accelerate the development, testing, and evaluation of cooperative driving automation while advancing the safety, security, data, and use of artificial intelligence in automated driving technology.

The CARMA Platform is distributed as a set of multiple independent packages hosted in separate Github repositories. These packages facilitate operation of the CARMA Platform with different hardware configurations or allow it to support different modes of operation. To include one of these packages in your build of the CARMA Platform system please clone the Github repository into the same Catkin workspace src/ folder as this repository. The Catkin build system will verify that dependencies are resolved appropriately and build the newly included package when you next run catkin_make. An incomplete listing of available packages for CARMA3 includes:

Vehicle Controller Interface Drivers

• carma-ssc-interface-wrapper
• dataspeed_controller_driver (Externally managed)
• dataspeed_can_driver (Externally managed)

Sensor Drivers

• v2x-ros-driver
• carma-velodyne-lidar-driver
• avt_vimba_camera
• carma-delphi-srr2-driver
• novatel_gps_driver
• gstreamer_camera_driver (Externally managed)
• ouster_lidar_driver (Externally managed)
• inertiallabs_gnss_driver (Externally managed)

General System Utilites

• carma-web-ui
• carma-msgs
• carma-utils

Vehicle Configurations

• carma-config

A full list of available packages may be found at in the USDOT FHWA STOL Github organization.

CARMA Cloud^SM is a downloadable, cloud-based open source software (OSS) service that provides information to support and enable cooperative driving automation. It enables communication with cloud services and vehicles, road users such as pedestrians, bicyclists, and scooters, and infrastructure devices capable of communication. It promotes collaboration between a community of engineers and researchers to accelerate the development, testing, and evaluation of cooperative driving automation while advancing the safety, security, data, and use of artificial intelligence in automated driving technology. The source code for CARMA Cloud can be found here on GitHub.

Contribution

Welcome to the CARMA contributing guide. Please read this guide to learn about our development process, how to propose pull requests and improvements, and how to build and test your changes to this project. CARMA Contributing Guide

Code of Conduct

Please read our CARMA Code of Conduct which outlines our expectations for participants within the CARMA community, as well as steps to reporting unacceptable behavior. We are committed to providing a welcoming and inspiring community for all and expect our code of conduct to be honored. Anyone who violates this code of conduct may be banned from the community.

Attribution

The development team would like to acknowledge the people who have made direct contributions to the design and code in this repository. CARMA Attribution

License

By contributing to the Federal Highway Administration (FHWA) Connected Automated Research Mobility Applications (CARMA), you agree that your contributions will be licensed under its Apache License 2.0 license. CARMA License

Code.gov Registration Info

Agency: DOT

Short Description: Cooperative Automation Research Mobility Applications (CARMA) is an open source software (OSS) platform that runs on a computer inside of a vehicle, and the computer interacts with the vehicle’s devices to enable cooperative automated vehicle research, development, and testing. The computer then gives the vehicle the information needed in order to interact and cooperate with infrastructure and other vehicles.Phase I of this project initiated the next generation of the CARMA fleet by developing a common platform infrastructure that will support the FHWA’s strategic vision for Cooperative Automated Driving Systems (CADS). Phase I also developed the Integrated Highway Prototype (IHP) by integrating the existing applications and a new vehicle type, the heavy truck, into the CARMA fleet. The following five applications are major research areas: (1) Vehicle Platooning, (2) Signalized Intersection Approach and Departure, (3) Infrastructure guided Speed Harmonization, and (4) Cooperative Lane Change, and (5) Cooperative Ramp Merge.Phase II of this project will advance CADS, which was developed on the FHWA’s CARMA research platform to allow testing of arbitration and negotiation strategies. Ultimately, this project will enhance infrastructure efficiency and reduce traffic congestion. One of the goals of this project is to accelerate the technology transfer and deployment of cooperative vehicle applications through open source collaboration with industry and stakeholders. This project will enable Society of Engineers (SAE) Level 2 and Level 3 (L2/3) light vehicle testing capabilities and develop a fleet of four SAE L2/3 heavy vehicles. The project will also develop a high-level concept for Transportation System Management and Operations (TSMO) around the use of automated driving technology. Furthermore, this project will identify Traffic Incident Management (TIM) scenarios that provide strategy improvements and new strategies for first responder use cases interacting with ADS and using ADS. The new FHWA fleet will be used to prototype a scenario for each of the following use case categories: (1) Basic Travel, (2) Work Zone, (3) Traffic Incident Management and (4) Weather. These tests will provide objective data to inform stakeholders about the impacts of ADS and possible strategies to use ADS to improve operations.

Status: Beta

Tags: transportation, cooperative driving automation, connected vehicles, intelligent transportation systems, C++, java, python, docker

Labor hours: 200

Contact Name: James Lieu

Contact Phone: (202) 366-3000

Contact

Please click on the CARMA logo below to visit the Federal Highway Adminstration(FHWA) CARMA website. For more information, contact CAVSupportServices@dot.gov.

Support

For technical support from the CARMA team, please contact the CARMA help desk at CAVSupportServices@dot.gov.

CARMA Collaboration Opportunities

Developed on a Robot Operating System (ROS), a flexible framework for writing software, the CARMA initiative will transform transportation, improving efficiency and safety through automated vehicles (AVs) working together.

To academic transportation researchers, public agencies, original equipment manufacturers (OEMs), and infrastructure owner operators (IOOs), CARMA is the Federal Highway Administration’s (FHWA’s) multimodal initiative using open source software (OSS) for the collaborative research and development (R&D) of cooperative driving automation (CDA) to advance the safety, efficiency, and capacity of the entire transportation system. The FHWA developed technology agnostic software for CARMA to enable flexibility and interoperability across original equipment manufacturers (OEMs) and infrastructure owner operators (IOOs) as well as to enable continuous improvement, productivity and greater quality. The CARMA Collaborative was established in 2019 to create an active community of users advancing CDA. Through a growing community of CARMA users, prospective users, and other stakeholders, the CARMA Collaborative facilitates the application of CARMA OSS and features to accelerate R&D and encourage industry adoption.

How to Contribute

Welcome to the CARMAPlatform contributing guide. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.

Contribution Tasks

• Reporting Issues
• Making Changes
• Submitting Changes
• Merging Changes
• Register as a collaborator

Reporting Issues

• Make sure you have a GitHub account.
• Ensure the issue was not already reported by searching CARMA Platform Issues
• If you’re unable to find an open issue addressing the problem, open a new one.
• Submit a CARMAPlatform issue.
  • Clearly describing the issue
    • Provide a descriptive summary
    • Explain the expected behavior
    • Explain the actual behavior
    • Provide steps to reproduce the actual behavior

Making Changes

Fork the Repository

• First, you need a local fork of the CARMA repository of interest, so go ahead and press the “Fork” button in GitHub. Read the article “Fork a repo” on GitHub.
• This will create a copy of the repository in your own GitHub account and you’ll see a note that it’s been forked underneath the project name.
• With the repository forked, you’re ready to clone it so that you have a local working copy of the code base.

Clone the Repository

Then clone a local copy of this forked branch.

• You can alternatively copy the URL by using the green “Clone or download” button from your repository page that you just forked from the original repository page. Read the article “Cloning a repository” on GitHub.
• Once you click the button, you’ll be able to copy the URL by clicking the binder button next to the URL:

Create a New Branch

The number one rule is to put each piece of work on its own branch.

• Check out the branch you want to make modifications to (normally this is the develop branch).
• Create a branch specific to the issue being addressed. Read the article “Creating and deleting branches” on GitHub.
• For enhancements, name the branch according to the feature e.g. feature/123-auto-activate.
• For bug fixes, name the branch according to the fix e.g. fix/321-admin-notices.
• For code that addresses an existing issue, add the Issue number as a prefix e.g. feature/123-auto-activate or fix/321-admin-notices.

Make Changes Locally

Do the work, write good commit messages.

• Open up the project in your favorite text editor, select the file you want to contribute to, and make your changes.
• If your changes include functionality that requires new testing, write the tests as well.
• Commit your changes using a descriptive commit message that begins with the issue number being addressed.
• When you have finished making your changes, you’ll need to push up your changes to a topic branch in your fork of the repository. Read the article “Committing and reviewing changes to your project” on GitHub.
• With them all committed, push them, this pushes everything in that branch up.

Submit Changes

Let you tell others about changes you’ve pushed to a GitHub branch.

• A Pull Request is the way to notify the project maintainers that you have some work that they should review and add to the project.
• You’re requesting that they pull your changes in. Read the article “Using Pull Requests” on GitHub.
• Then you can go back to your forked branch and issue a pull request to the repository and choose the correct original branch (should be develop).
• To create one, go to your fork of the project, click on the Pull Requests tab, and click the big green “New Pull Request” button.

Merge Changes

We want your help to make CARMA Platform Project great.

• All pull requests will be reviewed by the CARMAPlatform team.
• During the review of your pull request the team member will either merge it, request changes to it, or close it with an explanation.
  • Remember: we are unable to add untested code to CARMA, as it will add to the CARMA team’s technical debt.
• For major changes the reviewer may require additional support from the team, which could cause some delay.
• We’ll do our best to provide updates and feedback throughout the process.
• Feel free to open pull requests, and the CARMAPlatform team will communicate through it with any comments.

  Become a Collaborator

  Four Contribution Levels

  1. Informative Group Contributor. This level is for stakeholders interested at an informational level to keep up-to-date on CARMA activities advancing CDA. This level receives CARMA news, product updates, and first access to public CARMA events.
  2. Prospective User. This level is for stakeholders who are interested in contributing to CARMA research, development, and testing in the future. This level receives the benefits of Informative Group Contributors, and additionally, this level may request support to prepare to contribute to CARMA and will receive first access to select CARMA group events.
  3. User. This level is for contributors who have contributed code and/or have a vehicle capable of utilizing CARMA. These contributors will also likely be using ROS Discourse for advancing CDA through open and active collaboration. This level receives the benefits of Prospective Users as well as advanced support and access to technical working groups.
  4. Accelerator. This level is for contributors who are committed to using CARMA, active contributors to GitHub code, provide questions and feedback using ROS Discourse for advancing CDA, and have an automated vehicle with CARMA installed for research, development, and testing. This level receives the benefits of Users as well as dedicated one-on-one support and the ability to work closely with CARMA product development partners.

Branching Model

Vincent Driessen’s “git flow” branching model is a git branching and release management workflow that helps developers keep track of features, hotfixes and releases in a software projects. We will follow this model and mainly use five branches - master, develop, feature, release, and hotfix.

master

• This branch contains production-ready code of CARMAPlatform.
• This branch should be kept stable at all times

develop

• When the features/fixes are finished they are merged into develop, where we bring them together for testing, before the final push onto master.

feature/fix

• These branches are created from develop; each feature/fix branch is used to implement a single task. After completing the task, the feature/fix branch must be merged into develop.
• To avoid ambiguity, we use a specific naming convention for feature/fix branches − they always begin with feature/fix followed by the issue number being addressed and a description based on the functionality implemented by the feature/fix. For example: feature/123-sign-up-with-email-and-password or fix/321-admin-notices.
• Thanks to this naming, team members can easily tell what code each branch contains.

release

• A release branch is created whenever a set of functionality is ready for production release. It is normally created from develop and is used to keep the contents stable for final acceptance testing while other development activities may continue on other branches.
• Once the release is accepted, it will be merged into the master branch and versioned, then merged into develop.
• The naming convention for this branch starts with release/ followed by its version. For example: release/v1.0.1..

hotfix

• This branch is created for handling emergency situations – it allows developers to quickly fix something in production. This branch uses master as the parent branch and merges into both master and develop.
• The name of this branch starts with hotfix/ followed by its version. For example: hotfix/v0.1.1.

The End

Hope this guide helps you get started in contributing to the CARMAPlatform project!