diff --git a/README.md b/README.md index 69d25bf014aa647bcf43e6bd2e3cea25bdc87fa9..10b8d7df38f675da3b08b87bf7a8bfd4aa0dfb08 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,93 @@ -# localization VROB -This projects deals with the localization of a race car on the race trace. -This is a students project from the Bochum University of Applied Sciences. -Author: -Jessica Dreyer, Sebastian Böttger +# Toolkit for locating a vehicle on the race track +This project deals with the localization of a vehicle on a race track. +This is a student project from Bochum University of Applied Sciences. +The main approach of localization is based on locating the vehicle based on the current and already travelled section types. +A section type can be a right turn, a left turn and straight. -## Getting started +## Robot +The used Robot is the LEGO EV3 Brick as a line follower to test the algorithm. -The main branch contains +The robot use MicroPython. +How to install MicroPython and set up your Visual Studio Code to connect your pc to the robot is documented in this file: +https://assets.education.lego.com/v3/assets/blt293eea581807678a/bltb470b9ea6e38f8d4/5f8802fc4376310c19e33714/getting-started-with-micropython-v2_enus.pdf?locale=de-de -## Name -localization of a race car on the race trace +Important notes regarding the robot: +* The robot has differential drive. +* The motors / sensors are connected to the following ports of the robot: + * Motor: OUTPUT A & OUTPUT B + * ColorSensor: INPUT 4 + * GyroSensor: INPUT 1 -## Description -This projects deals with the localization of a race car on the race trace. -This is a students project from the Bochum University of Applied Sciences. -Currently the project is in development. -Till the development is finished, the branch and the readme will be updatet. +## Getting started +### How to run MicroPython programs on LEGO EV3: +1. Download and flash the EV3 MicroPython image onto a micro SD card +2. Insert the micro SD card into the SD card slot on the EV3 Brick +3. Download, install, and launch Visual Studio Code on your computer +4. Install and activate the LEGO Education EV3 extension +5. Connect the EV3 Brick + * After installing the extension, a device can be connected in Visual Studio Code (at the bottom, left). + * The LEGO EV3 Brick should be listed and can be selected in the list. -## Installation +### The following Python-packages must be installed on the computer to run the algorithm: +* numpy +* pandas +* matplotlib +* tkinter +* socket +* datetime -## Usage +### Preparations before run +Clone this git. Connect the EV3 robot to the same network as your executing device. -## Support +The following adjustments might be necessary, before the algorithm is executable: +* change ip-address in Lokalisierung_LEGO/main.py to the ip-address of the executing device +* insert the sections of the race track in localization.py (get_set_of_section_*()) + * structure of a section: [name, section_type, previous_sections_type] +* if the track plotter is used, insert also a set of track parts in the file grafic (get_set_of_trackparts_*()). + * structure of a section: [URL, name, start position(x,y), start orientation)] + * Images of the race tracks are not included in this git. If interested, please contact the authors. -## Roadmap -Development of a solution +### Run +1. Connect the robot via Visual Studio Code. +2. Start the python file race_management.py + * Now some windows should pop up. + * You can't move this windows until the UDP-connection with the robot is connected. + * __When you want to stop the script you have to restart the python kernel.__ +3. Start the main.py file on the robot. + * To do this, select the file in the Lego-EV window in the lower left corner of Visual Studio Code. Then right click and click on "Run" +4. Now the robot should drive and send data to the pc which plots in the console the current detected section and plot stuff. +5. To stop the robot/program press the left upper button on the robot, or close the dashboard window. -## Contributing +## Description +The main branch contains the following files: +* localization.py: localization algorithm +* driving.py: detection of section type, calculation of odometry, calculation driven distance in section +* grafic.py: graphical output +* race_management.py: main program +* Lokalisierung_LEGO (folder), main.py: programming of the robot LEGO EV3 + +The following measured values are stored and must be adjusted if necessary (in main.py): +* wheel circumference (radumfang) +* wheel spacing (d) + +Notes on constant values (in race_management.py): +* CHAR_RECIVING: number of chars in one UDP-message +**This value should only be changed if the sent string changes.** +* THRESHOLD_LEFT, THRESHOLD_RIGHT: value to detect a left or right turn +**These values can be changed to possibly improve the algorithm.** +* BLOCK_SIZE_DA: number of iterations to analyse the section type +**This value can be changed to possibly improve the algorithm.** +* S = 0, R = 1, L = 2: value for a straight part, a right turn, a left turn of the track +**These values should not be changed in order to maintain the functionality of the algorithm.** ## Authors and acknowledgment Jessica Dreyer, Sebastian Böttger ## License -Projekt is licenend with MIT. -See at LICENSE +This project is licensed under the MIT License - see the LICENSE file for details. ## Project status -Work in progress \ No newline at end of file +Project closed. + +Cordial invitation to further develop this project. \ No newline at end of file