Overview

Hello and welcome to the official documentation of Autonomy Lab at The Cooper Union for the Advancement of Science and Art!

License

Autonomy Lab's documentation is distributed under the CC BY-NC-SA 4.0.

Getting Started

selfdrive is a rather complicated repo.

If you've never worked on a project of this scale, it can be daunting to know where to start. The goal of this guide is to give you enough of a foothold to start asking the right questions and to begin your adventure here at Autonomy Lab.

Fundamentals

Before we even get to cloning selfdrive, you need to have the basic mechanical skills required to traverse a shell. MIT's Missing Semester serves as a great starting point for just this. The following table lists the lectures you should watch if you plan to work on a specific Autonomy Lab group:

Note: an * denotes you should also do the associated exercises.

At a minimum, to clone selfdrive, you should watch and do the exercises for Course overview + the shell and Version Control (Git), as these lectures provide you the fundamentals to hit the ground running.

System Configuration

Since selfdrive consists of software written in different programming languages with a wide variety of dependencies, we've made an effort to make getting your machine ready as painless as possible with the Nix package manager and direnv. You can find cloning instructions and system setup information on the repo's README.md.

Repo Layout

Currently, selfdrive does not respect this structure. We're in the process of migrating over to this layout. Sorry for the time being.

selfdrive/
+-- can/
|   +-- network.yml
|
+-- docs/
|
+-- components/
|   +-- component/
|   |   +-- docs/
|   |   +-- src/
|   |   +-- component.toml
|   |
|   +-- ...
|
+-- lib/
|
+-- projects/
|   +-- project/
|   |   +-- docs/
|   |   +-- project.toml
|   |
|   +-- ...
|
+-- ...

There's quite a bit to unpack here, so let's get to it!

components/

The components/ directory contains components that serve as the building blocks of a project.

Each component has a docs/ directory that contains symlinks to relevant documentation. These symlinks need to stay up to date as they will automatically get triggered for manual review on pull requests to ensure that documentation stays up to date. Having these symlinks also ensures that anyone who wishes to get up to speed on a component has a quick list of relevant documentation to read.

The src directory contains the source files. The contents and layout of this directory highly depend on the component language(s) and use case. It is best to see existing components to get a feel for it.

Finally, component.toml contains metadata related to the component.

can/

can/ describes the CAN networks of our projects. Here, you'll find definitions for networks, messages, and signals for OpenCAN to process.

docs/

The contributing guidelines cover the structure for documentation. You may notice that it closely follows the structure of selfdrive itself.

lib/

The lib/ directory contains shared libraries used in components. Since these are generalized pieces of software, the contents of each directory can wildly vary. Feel free to explore these directories if you're curious.

projects/

The projects/ directory contains projects that are composed of various components. Like a component, each project has a docs/ directory with symlinks to relevant documentation and a project.toml with related metadata.

What About Everything Else?

It'd be impractical to cover every last file and directory in selfdrive. Unfortunately, there's no shortcut to knowing where you can find everything or how various bits of code interact, but there are tools that can help!

• fd: a simple, fast and user-friendly alternative to find
• fzf: a command-line fuzzy finder
• rg: ripgrep recursively searches directories for a regex pattern

So What's Next?

Now that you have a general idea of how selfdrive works, it's time to move on to group-specific getting started guides. Feel free to move along to these without finishing all of the suggested missing semester lectures; however, understand they do nothing but benefit you!

Contributing

Thank you for taking time out of your day to contribute! We're excited to have you contribute to our documentation, but before you do, let's go over how best to contribute.

Before You Start

Before you get to writing anything, ask yourself a few questions:

• Can existing documentation be improved?
• If the existing documentation is insufficient, can it be expanded?
• Have you generalized to a reasonable degree?
• Is what you're about to write correct to the best of your knowledge?

As an aside, no documentation is better than wrong documentation!

Writing Style

Active voice over passive voice where possible.

Passive voice is less concise than the active voice, making documentation difficult to read. More importantly, passive voice can hide the agent of a sentence, diminishing your contribution to the work you put so many hours into!

Talk to the reader.

Remember, we read documentation far more often than we write it. That said, write documentation that's easy to read; this means talking to the reader to engage them with the material. We've all read dry documentation before; let's avoid it here at Autonomy Lab.

You're writing on behalf of Autonomy Lab.

Since we're a lab, avoid the word I. Work done for the lab, although individual at times, can become collaborative in an instant. There's no need to worry about your contribution getting lost in the chaos as it'll always be traceable with git blame and git log.

Be professional, but don't be afraid to have some fun!

selfdrive is a public repo: any contribution you make gets tied to your name forever on the internet, so be professional! That said, don't be afraid to have some fun! Humor is always welcome where appropriate to give our work some life!

Formatting

We use mdbook to render our documentation. If this is your first time using mdbook, please read over its documentation to get a feel for how to navigate it.

We've also decided to normalize our markdown using mdformat. If your markdown isn't normalized, it will trigger our pre-commit hook. To normalize a markdown file, it suffices to run the following in the root of selfdrive:

$ mdformat path/to/file.md

Each markdown file should, at the very least, look like this:

# Title

Introductory blurb...

## First Topic

...

Directory Structure

Our documentation has the following directory structure:

docs/
+-- components/
|   +-- complicated-component/
|   |   +-- README.md
|   |   |
|   |   +-- ...
|   +-- component.md
|
+-- concepts/
|   +-- complicated-concept/
|   |   +-- README.md
|   |   |
|   |   +-- ...
|   +-- concept.md
|
+-- projects/
|   +-- project/
|       +-- complicated-topic/
|       |   +-- README.md
|       |   |
|       |   +-- ...
|       +-- topic.d/
|       |   +-- figure.png
|       +-- topic.md
|
+-- README.md
+-- SUMMARY.md
|
+-- ...

Typically, a new addition to our documentation is a single markdown file. If we split the documentation into multiple files, we can represent it as a directory with a README.md, which serves as the introductory point.

All file paths should be lowercase (except for README.md), and use dashes for spaces.

If you need to include a file (i.e. a figure) but are only using a single markdown file, a folder with the same base name but suffix .d can be created (i.e. topic.md -> topic.d). Otherwise, included files specific to the documentation should reside in the same folder.

Figures

When creating figures, make them in such a manner that they're editable at a later time. The exception to this are images. When adding images, make sure they don't contain any personally identifiable EXIF data (i.e. the location of your house) before adding it to selfdrive!

When adding figures not created by Autonomy Lab, they must be appropriately accredited. Only link to such figures, and do not add them to the selfdrive repo. External figures must also be compatible with the CC BY-NC-SA 4.0.

Additionally, if the figure you add is a binary file track it with Git LFS.

When in Doubt, Look at Existing Work

Not sure how to do something? Check if there's already existing work that achieves a similar pattern. If you can't find anything that quite matches what you're looking to write, take your own stab at it. The nice part of having PRs is that the Lab can give you feedback on your work so that we can all converge on an ideal solution.

Remember to Credit Yourself

Most important of all, don't forget to credit yourself! No matter how small your contribution, make sure to add your name, in alphabetical order, to the list of contributors! At the end of the day, it's people like you that make this resource a possibility!

Contributors

Here is a list of the contributors who have helped in writing our documentation, huge shout-out to them!

• Jacob Koziej (EE '25)