Read Me First

Student, maintainer or just web citizen, welcome! Regardless of your origins, as you are reading this you are most likely interested in using the ASE software and hardware stack to perform your research and make the Rover we provide yours. Before you dive in, we want to highlight a few key points to give you a better understanding of the framework fundamentals and design decisions.

Elias Groot

Software Lead, Course Organizer

Opinionated Abstractions

ASE started as a project to produce race-winning, autonomous cars (see the project history), but since 2024, we've shifted our focus to producing educational tools for systems engineering research in a much broader sense. We have critically reviewed our original stack and majorly revamped it for general use. It is our mission to provide students and enthusiasts with a framework that is intuitive and easy to use and comes with batteries included to reduce the barrier to entry to just pressing a single button when you unpack your Rover.

To allow for this, we have decided on several abstractions, protocols and best practices. Even though we have carefully planned, revised and revamped our ideas throughout the years, one size unfortunately does not fit all and abstractions can come at the cost of losing low-level controls. Controls which you cannot always afford to lose, especially when your research depends on them. That's why - being CS graduates ourselves - we have put great emphasis on using making all our work interoperable, customizable and replaceable. A few examples:

• We provide you with roverctl, a tool you can download on your laptop to automatically sync your codebase to the Rover's filesystem. No scp necessary!
  • ...but if you want to use a different syncing mechanism, that will work too. You can just ssh into your Rover for full control
• All Rovers come installed with roverd, a daemon that exposes a REST API to manage software execution and dependency resolution with mere HTTP requests, no need to manage processes manually!
  • ...but if you like systemctl, the software framework will work fine with that too
• For inter-service communication we have created reusable communication definitions and their (de)serialization functions in many popular languages. Just use rover.write(sensor_data)!
  • ...but if you want to bring your own serialization logic, you can use rover.writeBytes(data) and set up your own communication scheme
• We install an custom ubuntu installation on all Rovers, with important safety features and optimizations, no need to flash SD cards!
  • ...but if you want to install your own OS, that is no problem

The point here is that the framework we offer aims to allow for easy usage out of the box, while not preventing users from more advanced usage. As you develop, you can choose to replace (parts of) the framework with custom implementations while keeping full interoperability. You can get the Rover to drive without ever reading the docs but also install custom kernel modules if need be. In any case, we encourage you to take a look at the abstractions, protocols and practices to interact with our framework where possible, so that you do not need to reinvent the wheel for tasks we already solved for you, allowing you to focus on your research.

Linux Fundamentals

Despite our efforts to make working with the Rover intuitive, it is valuable to understand how some protocols and tools work under the hood. The list below covers some basic concepts in Linux systems that should not scare you. If you find any surprises here, make sure to read up before you continue.

• Using SSH to open a remote shell on the Rover
• Using SCP to copy files to and from the Rover
• Navigating around the Linux filesystem using cd, ls, mv, cp and friends
• Using Makefiles to preview, build and run code
• Environment variables, how to set, unset and print them
• Using the shutdown and reboot command
• Using curl to download files
• Opening, saving and quitting vi or vim

Trying to Understand

As noted above, we have decided on practices that we deemed best. Hopefully, this makes you a little uncomfortable at first. After all, working with conventions in a (large) shared codebase is often a recipe for trouble: does this function modify my buffer? Does this call expect the mutex to be locked already? Does the caller need to free this memory? (Yeah, looking at you C).

To take most of the uncomfortableness away, we try to reduce silent conventions - conventions that are not enforced but do break your implementation if not followed correctly - to a minimum. Where possible, we try to actively enforce conventions that we do rely on. An important theme here is the use of types and (static) type analysis throughout the framework. For example, we define communication standards in standardized YAML or JSON formats (we call these "specs") and compile these specs to specific programming languages using open source tools. For many of our repositories we also provide Devcontainers so that you no longer need to scan a README to understand which tools you need to install (assuming they were available for your platform in the first place).

Why is this important now? You will find yourself learning many new concepts while working with the ASE framework and you might sometimes find that the docs focus much on ideas and rationales instead of practical implementations. Don't lose hope! Know that we have organized most of our conventions and requirements in YAMLs, JSONs, Devcontainers and Dockerfiles. There is no better way to understand the framework we offer than to read the source code, and we have written it in such a style that should be accessible and understandable for all of you, with the docs assisting you to understand the why instead of the what or how. That being said, accessibility should always be judged by the reader, not the writer, so if you have questions, suggestions or remarks, do reach out to us. We value it greatly.

On behalf of the ASE team, good luck - and have fun! We look forward to seeing all your research come to life on the Rover.

~ Elias