Axolotl is a completely modular system, with the user interface, data logging system, and media subsystems each managing their own subcomponents. This guide will explain how these subsystems and subcomponents work, and where to go in order to modify certain things. Additionally, some insight into our design will be provided, as well as some options explored during development.

Note: This guide assumes you have correctly followed the instructions outlined in the Installation Guide to set up your Jetson TX2 and Raspberry Pi(s). Please consult the Installation Guide if problems are encountered before attempting modifications or submitting an issue.

Connectivity

Axolotl uses the Jetson's WiFi antennas to broadcast an 802.11n AP network at 2.4GHz; AP WiFi mode is required for camera functionality. Similarly, the Raspberry Pi(s) controlling the camera modules must be connected to the Jetson's AP network AxolotlWLAN to broadcast their streams. The Raspberry Pis must connect to the Jetson before the streams are started, otherwise corrupt dashcam footage and backup camera feeds may result.

The Jetson's WiFi is managed by two scripts in the source/data_logging/wmanager directory:

• set_ap_n.sh puts the Jetson in AP WiFi host mode.
• set_client.sh puts the Jetson in default client mode.

Note: Both scripts are persistent, meaning that either mode will persist even after the Jetson is rebooted.

Note: Only use set_client.sh if wireless internet connection is desired for development/debugging. Otherwise, return the Jetson to host mode with set_ap_n.sh. It may be easier to use a wired Ethernet connection and/or USB to SSH into the Jetson TX2 Development Kit and/or the Raspberry Pis for development.

LTE

LTE connectivity may be desired. Use of a Huawei LTE modem connected to the Jetson via Mini-PCIe Express combined with a prepaid US Mobile SIM card for IoT devices was considered but not implemented. Adding LTE support may resolve frame drop problems in the camera streams by resolving the clock skew between the Jetson and the Raspberry Pi(s).

Data Logging System

The data logging system is self-contained and can function independently as a black box system. Simply run the daemon manager from the terminal via ./daemon_manager, and exit it with SIGINT.

Daemon Manager (daemon_manager.cpp and daemon_manager)

Manages the entire data logging subsystem. The daemon manager is forked and executed as a child process of main Qt UI process, or it can be executed on its own for black box functionality only.

On execution, the daemon manager builds the logging directory for the current boot cycle on the relevant log volume. By default, the log volume is ~/axolotl/data if there is no external storage drive connected, or /media/nvidia/AXOLOTLDCV/axolotl/data if an external storage drive is connected AND named AXOLOTLDCV.

After directory creation, the daemon manager initializes the data logging and dashcam daemons before then entering an infinite loop that constantly checks the value of gpio298, toggling the backup camera on (if the value is 1) or off (if the value is 0).

Signals

• SIGINT kills the data logging and dashcam daemons by sending them SIGTERM signals and exit cleanly.
• SIGBUS causes the daemon manager to propagate this signal to its subservient data logging daemon.
• SIGUSR1 commands the daemon manager to delete all black box data (except for the current session's log) from the current log volume.

Data Logging Daemon (data_logger.cpp and datad)

Manages OBD2 and AHRS logging; forked and executed as a child process of the daemon manager process.

Signals

• SIGTERM commands the data logging daemon will close any of its subservient logging processes and exit cleanly.
• SIGUSR1 pauses the data logging system (killing all subservient processes but keeping the daemon alive).
• SIGUSR2 restarts the data logging system.
• SIGBUS pauses the data logging system, fetches/processes diagnostic trouble codes and fuel efficiency data, and automatically restarts logging. (This is to avoid overwhelming the OBD2 dongle with commands. May be subject to future deprecation, as the OBD2 logger now operates in asynchronous non-blocking mode.)

data_logger_pyhelper.cpp and data_logger_pyhelper

Helper process that runs data_obd_logger.py as a separate process, allowing for easy killing/restart of the OBD logger.

data_obd_logger.py

Python script that handles all OBD2 logging. Recompilation is not required after modifying this script.

Arguments

• A command snapshot, telling the script to operate in OBD snapshot mode (subject to future deprecation, previously, data_obd_logger.py and data_obd_dtc.py were written as the same script).
• A string containing the path to the logging directory (where the OBD2 data and diagnostic trouble codes will be saved).
• The process ID of its parent data logging daemon process. This allows the Python script to automatically quit when its parent process is killed.

data_obd_dtc.py

Python script that handles fetching DTC data from the OBD2 port. DTC data will be saved to the ~/axolotl/ directory for processing and display; a copy will also be added to the current logging directory for future reference. Recompilation is not required after modifying this script.

Arguments

• A string containing the path to the logging directory (where the OBD2 data and diagnostic trouble codes will be saved).

AHRS Logger (imu.cpp and imu)

Utilizes a CHR-UM6 robot orientation sensor in conjunction with a CHR-UM6 driver implementation by Isaac Silva using Clearpath Robotic's stock (deprecated) driver, implemented in C++.

Attempts a serial connection on /dev/ttyUSB0 in order to access the orientation sensor (waits for confirmation of OBD2 connection success or failure before attempting the connection by checking for the existence of an obd_log.csv in the current black box directory). Once the sensor has been accessed, the logger will loop: reading Euler angles from the sensor, converting to degrees, and then appending them to the log. This is done approximately 7 times per second.

Arguments

• A string containing the path to the logging directory (where the AHRS data will be saved).

Data Collator (data_collator.py)

Python script that handles the collation of textual data logs after Axolotl exit. The Data Collator script will scan for an OBD2 log, and then append AHRS data to each line if there is an AHRS record with the same timestamp, in turn producing a master_log.csv with both sets of data. master_log.csv will only be generated if there is an obd_log.csv file in the current logging directory.

Arguments

• A string containing the path to the logging directory (where master_log.csv generation will take place).

Dashcam Daemon (dashcam_logger.cpp and dashcamd)

Manages dashcam logging and operates the backup camera after being signaled to do so. Forked and executed as a child process of the daemon manager. Please read the Camera System section for more on how the camera system works.

Arguments

• A string containing the path to the logging directory (where dashcam footage will be saved).
• A string containing the daemon's memory management mode, decided by the daemon manager.

Memory Management Mode

• Memory management mode "1" will be passed if the system has not detected an external storage device suitable for the black box. In this mode the daemon will automatically clear storage space on internal storage for new dashcam footage if remaining capacity is less than 2GB.
• Memory management mode "0" will be passed if valid external storage is detected (see User Guide on how to use external storage devices). In this mode, the daemon will not attempt to clear older footage in this situation.

Signals

• SIGTERM commands the dashcam daemon will close any of its subservient logging processes and exit cleanly.
• SIGUSR1 pauses the dashcam system (killing all subservient processes but keeping the daemon alive). This does not affect the backup camera.
• SIGUSR2 restarts the dashcam system.
• SIGBUS toggles the backup camera on/off.

In all cases, a Bluetooth signal will be sent to the corresponding Raspberry Pi(s), telling Raspberry Pi camera daemons to close the relevant camera streams by killing streaming processes.

Camera System

Note: Camera streaming uses gstreamer. Here's a quick overview of gstreamer pipelines for the uninitiated.

Design

Implemented

The Jetson broadcasts a 802.11n WiFi access point, and the cameras connect to it.

Camera RPi (client) >> 802.11n WiFi >> Jetson TX2 (host)

The Jetson must "open" the pipeline on a port by executing a gst-launch-1.0 command using a record_helper or backup_camera_helper before a Raspberry Pi executes a corresponding gst-launch-1.0 command on the same port to "close" the pipeline. Video only starts streaming from the Raspberry Pi(s) after the pipeline has been "closed".

Theoretical, Type 1

The cameras broadcast streams to the Jetson via peer-to-peer WiFi, leaving the Jetson free to connect to the internet via a smartphone hotspot, router, or modem.

Camera RPi >> P2P WiFi >> Jetson TX2 >> Smartphone/Router/Modem >> Internet

Theoretical, Type 2

Same as the implemented design, but with added connectivity.

The Jetson broadcasts a 802.11n WiFi access point, and the cameras connect to it. The Jetson connects to the Internet via a LTE modem connected over PCIe or a secondary WiFi adapter connected via Ethernet or USB, sharing the connection with the Raspberry Pi(s) managing the camera modules.

Camera RPi (client) << 802.11n WiFi >> Jetson TX2 (host) >> LTE Modem/Secondary WiFi Adapter >> Internet

Note: This may address clock skew between the Raspberry Pis and the Jetson, reducing the latency of the camera streams.

rpidashcams

Files in this folder are designed to be run on Raspberry Pi 3 Model B's flashed with Raspbian (specifically, a Raspberry Pi and Raspberry Pi Camera Module pair). Please run make after modifying these files and reboot the Raspberry Pi for the changes to take effect.

Note: Only attempt make on the Raspberry Pi. Raspberry Pis use an ARM processor that cannot run programs compiled on x64 or x86 systems.

bchelper and bchelper.cpp

Helper process that runs a gst-launch-1.0 command to close the backup camera pipeline.

Modifiable properties:

• Bitrate
• Resolution (default 1920x1080)
• Frame Rate (default 30 fps)
• Horizontal/Vertical Flip
• Port (default 9003)
• Streaming pipeline (note, changing this will require doing the same on backup_camera_helper.cpp and makeing its corresponding executable backup_camera_helper on the Jetson, and vice versa).

c1helper.cpp, c1helper, c2helper.cpp, c2helper

Helper processes that run a gst-launch-1.0 command to close the camera pipelines for the front dashcam c1helper and/or rear dashcam c2helper. These programs are virtually identical to bc_helper, but use different ports (port 9001 for c1helper, port 9002 for c2helper).

Modifiable properties:

• Bitrate
• Resolution (default 1920x1080)
• Frame Rate (default 30 fps)
• Horizontal/Vertical Flip
• Port (default 9001 for front dashcam, 9002 for rear dashcam)
• Streaming pipeline (note, changing this will require doing the same on record_helper.cpp and makeing its corresponding executable record_helper on the Jetson, and vice versa).

Note: Only the front dashcam is used as of 1.0 release.

rpi1dcd.cpp, rpi1dcd, rpi2dcd.cpp, rpi2dcd

Camera daemons that run on the Raspberry Pi(s) controlling the front camera rpi1dcd.cpp and rear camera rpi2dcd.cpp after boot into Raspbian. These programs essentially function as a Bluetooth server, accepting a Bluetooth connection from the Jetson and then executing commands involving the camera helpers based on the Bluetooth command received.

source/data_logging

backup_camera_helper.cpp and backup_camera_helper

Helper process that opens the pipeline for the backup camera.

Arguments

• A string describing the port to be used by the backup camera.
• A string describing the run type (deprecated, previously backup_camera_helper and record_helper were one program).
• A string containing the path to the logging directory (deprecated, previously backup_camera_helper and record_helper were one program).

record_helper.cpp and record_helper

Helper process that opens the pipeline for the dashcam(s). This helper can open either the front or rear dashcam pipelines, simply specify the desired port (the corresponding camera helper programs in rpidashcams must then stream to that port).

The following dashcam footage properties may be modified here:

• Maximum file size (default time-limited by 5-minute chunks)
• Naming scheme (default "front_dashcam.mp4")
• File format (default .mp4)

Arguments

• A string describing the port to be used by the dashcam.
• A string describing the run type (deprecated, previously backup_camera_helper and record_helper were one program).
• A string containing the path to the logging directory (where dashcam footage will be saved).

UI

UI files are located in Axolotl1.1. Each .ui file correlates to an interface's internal stylesheet and layout, whereas each .cpp correlates to functionality embedded within that interface. There is one .ui, .h, and .cpp for each tab in the graphical user interface.

Please use QtCreator to work on these files. Documentation on QtCreator can be found here.