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
Other documentation
- Quick start source control (git) - Quick start guide for source control with git.
- SensoDrive explanation - Some remarks, explanations, and 'best practices' for working with a SENSOWheel SD-LC
Want to contribute?
- Guidelines - Guidelines if you want to add to JOAN
- Coding Standard - Coding standard for JOAN (we try)