JOAN documentation

Welcome to the JOAN human-automated vehicle interaction simulator documentation! This documentation should get you up and running with JOAN and CARLA.

JOAN is an open-source software framework that builds upon CARLA, a simulator made to study automated driving, by making CARLA also useful for human-in-the-loop experiments of human drivers and other road users interacting with automated vehicles.

Among others, we build JOAN to enable you to

quickly set up (human-in-the-loop) experiments with repeatable conditions
define repeatable traffic scenarios
easily log data
implement haptic driver-automated vehicle interaction

Check out the table of content below for installation instructions and more information on JOAN. Also check out the repository for current issues, etc.

Note

We tested JOAN with CARLA 0.9.9, not (yet) with the latest version. If you tested JOAN with the latest CARLA build (and it works), awesome! Please let us know through the issue tracker!

JOAN is developed by members of the Human-Robot Interaction group at Cognitive Robotics of Delft University of Technology.

Please use the following reference if you end up using JOAN for your work (and do not forget to reference CARLA too!)

Beckers, N., Siebinga, O., Giltay, J., & Van der Kraan, A. (2021). JOAN, a human-automated vehicle experiment framework. Retrieved from https://github.com/tud-hri/joan

We created a video showcasing JOAN and CARLA for the Symbiotic Driving Simulator for one of our research projects on haptic shared control in driving:

Useful links

Because JOAN depends heavily on CARLA, we strongly recommend you to check out the CARLA documentation.
You can find the JOAN repository here. The underlying framework of JOAN is finished, so that core functionality will not change to ensure backward compatibility.

Table of content

Setup JOAN and CARLA

A thorough guide on setting up JOAN and CARLA:

Setting up CARLA on Windows - The most important steps from the CARLA documentation
Setting up JOAN -- Install JOAN
Setup JOAN on a TUD computer - a guide on how to install your project on TUD shared hardware (probably your first step)
Example usage and testing - example of JOAN usage and test whether everything works

First steps

If you want to build up an understanding of JOAN the sections below are a good place to start:

JOAN Overview - Core, Modules, Dataflow
Quick Start Running Joan and CARLA - Quickstart on how to run JOAN and CARLA
Quick start CARLA environment - Quickstart on CARLA and the Unreal Editor

Using the JOAN modules

Several modules are included with JOAN by default, the way to use them is described in their separate sections:

Important

Please check the documentation on the usage of the shared variables, a very important step is described there concerning setting and getting shared variables.

Data Recorder - The data recorder is a module that can record data.
CARLA Interface - CarlaInterface manages the different agents you can add in simulation.
Hardware Manager - The hardware manager is a module that manages hardware inputs.
Experiment Manager - The experiment manager is a useful tool for performing experiments
Haptic Controller Manager - The haptic controller manager is a module that manages haptic (steering wheel) controllers.
Data Plotter - The data plotter is a module that easily makes data insightful at runtime.

Advanced steps

If you want to know more and add to JOAN yourself you can have a look at these sections:

How to create a custom JOAN module - Guide on how to create your own JOAN modules
JOAN module settings - JOAN uses Settings to save you to set up every module
JOAN state machine - Info on JOAN's state machine

Want to contribute?

Guidelines - Guidelines if you want to add to JOAN
Coding Standard - Coding standard for JOAN (we try)