Merge pull request #201 from iavofficial/documentation/add_how_to_con…

…figure_vehicle_images

Documentation/add how to configure vehicle images

doc/Configuration/How to configure vehicle images.md

@@ -0,0 +1,51 @@
+# How to configure vehicle images
+
+> [!IMPORTANT]  
+> When using your own Anki cars (that are not pre-configured / no matching images exist), you must configure the images to be used in the ui's.
+
+You can add and use your own vehicle images for displaying vehicles on the car map as well as in the DriverUi.
+
+## Add and configure images for your own Anki cars
+The assignment of images to the Anki cars is done via the MAC address of the vehicles.
+This can be determined through the StaffUi.
+There, found or connected vehicles are displayed.
+
+To display a matching image of the vehicle in the DriverUi, a corresponding image in **.webp** format must exist in the directory [src/UserInterface/static/images/Real_Vehicles](../../src/UserInterface/static/images/Real_Vehicles).
+The name of the image must match the MAC address (without colons ":").
+
+> [!NOTE]
+> Example:  
+> MAC address of a vehicle: CE:27:5C:6C:64:6C -> corresponding image: CE275C6C646C.webp
+
+For the standard Anki vehicles (red and blue), appropriate images are provided ([red.webp](../../src/UserInterface/static/images/Real_Vehicles/red.webp) and [blue.webp](../../src/UserInterface/static/images/Real_Vehicles/blue.webp)), which can be copied and renamed.
+Instructions on how to convert .png or .jpeg images to .webp images can be found [here](../Images_high_resolution/README.md).
+To ensure that the correct images are used on the virtual track as well, the images to be used must be stored in the configuration.
+How this works is explained in the following section.
+
+## Add and configure images for your virtual race
+The images to be used on the virtual track can be configured via the [config_file.json](../../src/config_file.json).
+In the virtual_cars_pics section, the images are assigned to the vehicles.
+The images must exist in the directory [src/UserInterface/static/images/Virtual_Vehicles](../../src/UserInterface/static/images/Virtual_Vehicles).
+It is recommended to use top-down views of the vehicles.
+For real vehicles, the assignment is done via the MAC address of the vehicle as the key in the json file.
+
+> [!NOTE]
+> Example:  
+> "CE:27:5C:6C:64:6C": "CE275C6C646C.svg"
+
+For virtual vehicles, the assignment is done via the ID for the vehicle (**Virtual Vehicle** x, with x as an integer >0). 
+
+> [!NOTE]
+> Example:  
+> "Virtual Vehicle 1": "VirtualVehicle1.svg"
+
+In both cases, the name of the image file can be arbitrary, and the format is not specified.
+However, the image must have a transparent background.
+For the standard Anki cars ([red.svg](../../src/UserInterface/static/images/Virtual_Vehicles/red.svg) and [blue.svg](../../src/UserInterface/static/images/Virtual_Vehicles/blue.svg)), images are also provided and can be used as follows:
+
+> [!NOTE]
+> Example:  
+> "D1:FF:AF:51:CB:30": "blue.svg",
+> "Virtual Vehicle 1": "red.svg"
+
+Any number of real and virtual vehicles can be configured.

doc/Configuration/README.md

@@ -1,6 +1,6 @@
 # Configuration File
 There are a bunch of parameters that can be configured in the [config_file.json](../../src/config_file.json).
-The config_file.json is a json file that includes all configurable parameters for IAV-Distortion.
+The config_file.json is a json file that includes all configurable parameters for IAV Distortion.
 The json is structured according to different main topics which include the corresponding parameters.
 These parameters will be described in the following.
 

doc/UtilityScripts/README.md

@@ -16,12 +16,12 @@ To be able to run all of the following scripts properly the following programs n
 >This script requires an active internet connection and *git* installed on the system.
 
 This script serves as a sort of installer.
-It can be downloaded and run on the target system to obtain IAV-Distortion from GitHub and install it subsequently.
+It can be downloaded and run on the target system to obtain IAV Distortion from GitHub and install it subsequently.
 The script performs the following tasks:
-1. Checks if a folder named "IAV-Distortion" already exists and asks if it should be used for installation. (**WARNING:** All data within this folder will be overwritten!)
+1. Checks if a folder named "IAV Distortion" already exists and asks if it should be used for installation. (**WARNING:** All data within this folder will be overwritten!)
 If no such folder exists or if the existing one should not be used for installation, it asks for the desired installation path.
 If multiple such folders exist, an additional warning is issued.
-2. Queries which branch from the IAV-Distortion repository should be used.
+2. Queries which branch from the IAV Distortion repository should be used.
 3. Clones the desired branch from the repository.
 4. Makes utility scripts in /src directory executable.
 5. Optionally: Executes the installation script (refer to install.sh).
@@ -30,20 +30,20 @@ If multiple such folders exist, an additional warning is issued.
 >[!IMPORTANT]
 >This script requires an active internet connection.
 
-This script undergoes the process to establishing all necessary preconditions and requirements to properly run IAV-Distortion.
+This script undergoes the process to establishing all necessary preconditions and requirements to properly run IAV Distortion.
 The script accomplishes the following tasks:
 1. Configures the password for the StaffUI.
 2. Execute *get_dependencies.sh* to install pipenv and download external resources
-3. Creates a Desktop Item, from which IAV-Distortion can be initiated.
+3. Creates a Desktop Item, from which IAV Distortion can be initiated.
 4. Makes the remaining utility scripts in the /src directory executable.
-5. Checks for configured autostarts of other installations of IAV-Distortion and gives a warning if some were found.
+5. Checks for configured autostarts of other installations of IAV Distortion and gives a warning if some were found.
 6. Optionally configures the program's auto-start feature (using a cron job).
 
 ### update.sh
 >[!IMPORTANT]
 >This script requires an active internet connection.
 
-This script will update IAV-Distortion by discard all local changes and pulling the latest verion of the installed branche. Add files like images of cars won't be affected.
+This script will update IAV Distortion by discard all local changes and pulling the latest verion of the installed branche. Add files like images of cars won't be affected.
 Afterwards *get_dependencies.sh* is executed to update external resources.
 
 ### get_dependencies.sh
@@ -53,7 +53,7 @@ Afterwards *get_dependencies.sh* is executed to update external resources.
 This script installs the virtual pipenv environment and will download further further required external resources (such as JavaScript libraries).
 
 ### run_IAV-Distortion.sh
-This script will run IAV-Distortion in it's virtual pipenv environment.
+This script will run IAV Distortion in it's virtual pipenv environment.
 
 ### quit.sh
 This script will identify running processes of main.py and terminate them.
@@ -65,7 +65,7 @@ This script will identify running processes of main.py and terminate them.
 This script will immediately restart the host system.
 
 ### restart_IAV-Distortion.sh
-Restart IAV-Distortion by first terminating the running instances using *quit.sh* afterwards restart IAV-Distortion using *run_IAV-Distrotion.sh*.
+Restart IAV Distortion by first terminating the running instances using *quit.sh* afterwards restart IAV Distortion using *run_IAV-Distrotion.sh*.
 
 ### shutdown_system.sh
-Terminate all running instances of IAV-Distortion and shutdown the host system.
+Terminate all running instances of IAV Distortion and shutdown the host system.

installer.sh

@@ -66,13 +66,13 @@ then
         # dir=$(dirname "$dir")
         echo "$repo_name will be cloned to: $dir"
     else
-        echo -e "\033[0;33m Please make sure that you have no duplicates of IAV-Distortion running in parallel.\033[0m"
+        echo -e "\033[0;33m Please make sure that you have no duplicates of IAV Distortion running in parallel.\033[0m"
         request_directory
     fi
 
 elif [[ $copy_exists -gt 1 ]]
 then
-    echo -e "\033[0;33mMultiple directories named IAV_Distortion have been found. Please make sure that you have no duplicates of IAV-Distortion running in parallel.\033[0m"
+    echo -e "\033[0;33mMultiple directories named IAV_Distortion have been found. Please make sure that you have no duplicates of IAV Distortion running in parallel.\033[0m"
     for copy in $existing_copies
     do
         echo $copy

readme.md

@@ -1,15 +1,15 @@
-# IAV-Distortion
+# IAV Distortion
 ## About the project
-The IAV-Distortion project is an interactive and educational showcase designed to demonstrate the need of automotive cybersecurity in a playful, engaging manner.
+The IAV Distortion project is an interactive and educational showcase designed to demonstrate the need of automotive cybersecurity in a playful, engaging manner.
 This project leverages the fun experience of the Anki Overdrive race track, but with an added twist - your car can be hacked.
 Our primary objective is to highlight the potential impacts of hacking attacks on vehicles, an increasingly relevant issue as technology becomes more integrated into the automotive industry.
 
 
-The IAV-Distortion project is an ideal exhibit for trade fairs or other similar events, attracting attendees with its unique blend of technology and entertainment. 
+The IAV Distortion project is an ideal exhibit for trade fairs or other similar events, attracting attendees with its unique blend of technology and entertainment. 
 It thereby acts as a crowd-puller due to its exciting premise and the opportunity it offers for audience interaction.
 Through this initiative, we aspire to make the sometimes daunting world of cybersecurity accessible to a wider audience, fostering understanding and engagement.
 
-<img src="./images/IAV_Distortion_concept_illustration.jpg" alt="IAV-Distortion concept illustration" style="width:100%;max-width:500px">
+<img src="./images/IAV_Distortion_concept_illustration.jpg" alt="IAV Distortion concept illustration" style="width:100%;max-width:500px">
 
 ## Getting Started
 ### Prerequisites
@@ -48,6 +48,10 @@ sudo chmod +x <path/to/>installer.sh
 >   - make the desktop item executable
 >   - add to autostart as a cronjob (recommended: optionally: you will be asked if you want to)
 
+> [!IMPORTANT]
+> If you are using your own Anki cars, they are not configured in the system yet.
+> You can add and configure your own car as described in the istruction [*How to configure vehicle images*](doc/Configuration/How%20to%20configure%20vehicle%20images.md)
+
 
 ## Usage
 After setting up the project successfully, you can control the system and the cars using any device wich can access a webbrowser and is connected to the same network or hotspot of the system.
@@ -64,7 +68,7 @@ The list shows which player controls which vehicle. If one of the fields is none
 Aside from that the different hacking scenarios can be activated for the cars assigned to a player.
 Therefore chose the scenario for the car you want to apply the effect to, as soon as scenario is preselected the 'Set Scenario' button becomes active and can be used to apply the effect to the vehicle.
 
-<img src="./images/staffUI_activateScenario.png" alt="IAV-Distortion staff ui" style="width:100%;max-width:400px">
+<img src="./images/staffUI_activateScenario.png" alt="IAV Distortion staff ui" style="width:100%;max-width:400px">
 
 Additional to the controls for the game itself, some system configurations and functions can be accessed by switching to the 'Configuration' tab.
 Here the system can be updated to the latest version available in the repository (of the installed branch) or functions like restarting IAV Distortion, the whole system (Raspberry Pi) or shutting down the system can be accessed.
@@ -75,7 +79,7 @@ Additionally, it is now also possible to start an initialization drive with a re
 > - These functions (Update, Restart IAV Distortion, Restart System and Shutdown System) are only available on Unix like systems.
 > - Running an update requires internet connection.
 
-<img src="./images/staffUI_configuration_systemControl.png" alt="IAV-Distortion staff ui - configuration - system control" style="width:100%;max-width:400px">
+<img src="./images/staffUI_configuration_systemControl.png" alt="IAV Distortion staff ui - configuration - system control" style="width:100%;max-width:400px">
 
 ### Driver UI
 The driver ui can be accessed via [&lt;system_iP&gt;:5000/driver]().
@@ -85,7 +89,7 @@ The slider on the left controls the speed.
 With the buttons on the right the lanes can be changed or a u-turn can be performed.
 Player controlling a virtual car will get a top down view of the controlled vehicle (as displayed on the [virtual track](#Virtual-Racetrack)).
 
-<img src="./images/driverUI_noHacking.png" alt="IAV-Distortion driver ui" style="width:100%;max-width:600px">
+<img src="./images/driverUI_noHacking.png" alt="IAV Distortion driver ui" style="width:100%;max-width:600px">
 
 > [!NOTE]
 > To performe a lane change or a u-turn the slider as to be released.
@@ -104,7 +108,7 @@ The virtual and real cars are shown on a virtual racetrack.
 The virtual racetrack can be accessed via [&lt;system_iP&gt;:5000/car_map]().
 The virtual track must be defined before the start of the game. Currently, this is done through an initialization drive on the real track with a real vehicle.
 
-<img src="./images/virtual_racetrack.png" alt="IAV-Distortion virtual racetrack" style="width:100%;max-width:600px">
+<img src="./images/virtual_racetrack.png" alt="IAV Distortion virtual racetrack" style="width:100%;max-width:600px">
 
 <!--## Roadmap
 
@@ -113,7 +117,7 @@ The virtual track must be defined before the start of the game. Currently, this
 
 ## License
 ### Third party dependencies
-IAV-Distortion uses some third party dependencies.
+IAV Distortion uses some third party dependencies.
 - Bleak (MIT License)
 - Quart (MIT License)
 - python-socketio (MIT License)

src/CyberSecurityManager/CyberSecurityManager.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE

src/DataModel/Vehicle.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE

src/EnvironmentManagement/ConfigurationHandler.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE

src/EnvironmentManagement/EnvironmentManager.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE

src/UserInterface/DriverUI.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE

src/UserInterface/StaffUI.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE
@@ -436,7 +436,7 @@ async def restart_program() -> Any:
 
             else:
                 logger.warning("Program restart button pressed, but not running on Linux system")
-                message = 'Error restarting IAV-Distortion. Function only available on linux systems.'
+                message = 'Error restarting IAV Distortion. Function only available on linux systems.'
                 return message, 200
 
         @self.staffUI_blueprint.route('/restart_system', methods=['POST'])

src/VehicleManagement/AnkiController.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE

src/VehicleManagement/FleetController.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE

src/VehicleManagement/VehicleController.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE

src/VehicleMovementManagement/BehaviourController.py

@@ -1,6 +1,6 @@
 # Copyright 2024 IAV GmbH
 #
-# This file is part of the IAV-Distortion project an interactive
+# This file is part of the IAV Distortion project an interactive
 # and educational showcase designed to demonstrate the need
 # of automotive cybersecurity in a playful, engaging manner.
 # and is released under the "Apache 2.0". Please see the LICENSE

src/install.sh

@@ -87,31 +87,31 @@ check_existence=$(crontab -l | grep -F "$cronjob")
 
 if [ ! -z "$check_cronjobs" ]; then
     if [ "$check_cronjobs" != "$check_existence" ]; then
-        echo -e "\033[0;33mCronjobs for IAV-Distortion found, that don't match this installation. Please check if these are from different instances of IAV-Distortion. Only one instance of IAV-Distortion should run.\033[0m"
+        echo -e "\033[0;33mCronjobs for IAV Distortion found, that don't match this installation. Please check if these are from different instances of IAV Distortion. Only one instance of IAV Distortion should run.\033[0m"
         echo "$check_cronjobs"
     fi
 fi
 
 
 if [ -z "$check_existence" ]; then
-    read -p "Do you want to add IAV-Distortion to the autostart? (y/n) " -n 1 -r
+    read -p "Do you want to add IAV Distortion to the autostart? (y/n) " -n 1 -r
     echo    # move to a new line
     if [[ $REPLY =~ ^[Yy]$ ]]
     then
         (crontab -l 2>/dev/null; echo "$cronjob") | crontab -
         echo -e "\033[0;32mA cronjob has been created.\033[0m"
     else
-        echo -e "\033[0;33mIAV-Distortion has not been added to the autostart.\033[0m"
+        echo -e "\033[0;33mIAV Distortion has not been added to the autostart.\033[0m"
     fi
 else
-    read -p "IAV-Distortion already in autostart. Do you want to keep it? (y/n) " -n 1 -r
+    read -p "IAV Distortion already in autostart. Do you want to keep it? (y/n) " -n 1 -r
     echo    # move to a new line    
     if [[ $REPLY =~ ^[Yy]$ ]]
     then
-        echo -e "\033[0;32mCronjob kept. IAV-Distortion in autostart.\033[0m"
+        echo -e "\033[0;32mCronjob kept. IAV Distortion in autostart.\033[0m"
     else
         (crontab -l | grep -v -F "$cronjob") | crontab -
-        echo -e "\033[0;33mIAV-Distortion removed from autostart.\033[0m"
+        echo -e "\033[0;33mIAV Distortion removed from autostart.\033[0m"
     fi
 fi