From dc36e151bb8d5b6f420530ce05f86e03a80fbe22 Mon Sep 17 00:00:00 2001 From: Chris Davoren Date: Sat, 21 Oct 2023 14:22:13 +1000 Subject: [PATCH] Added Installation and Usage section to README, with small additions to other sections. --- README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/README.md b/README.md index f1726a6..9073451 100644 --- a/README.md +++ b/README.md @@ -50,9 +50,43 @@ However, despite it's large feature set, Django has no native support for long b The UI is a simple web page that calls polls for updates from the server. Due to the use of locks to avoid race conditions, this can induced minor delays (milliseconds at worse) in the processing and updates of traffic light information in the simulation thread. The main loop is designed in such a way that this will not cause cumulative delays in traffic light timing. However, it is worth considering that another approach may be desirable (such as pushed client updates rather than polling) if, for instance, many clients were expected to be making simultaneous requests of the server. +The main frontend web page, including the JavaScript polling code, is specified in its entirety in `trafficlightfrontend/templates/trafficlightfrontend/index.html`. The code responsible for encoding and dispatching responses can be found in `trafficlightfrontend/views.py`. Other files not described in this README are largely Django default scaffolding. + +# Installation and Usage + +## Pre-requisites + +The project requires Python 3.8 and Django 4.2. A virtual environment is recommended, but is only *required* when it is undesirable to install Django into your main Python package repository (most real-life cases, to avoid different Django version conflicts). Basic instructions for virtual environments can be found [here](https://docs.python.org/3/library/venv.html). Once the virtual environment has been created and **activated**, the following command will install the version used in the project: + +``` +pip install -r requirements.txt +``` + +Python 3.11.2 and Django 4.2.6 during development. Django 4.2 supports Python 3.8 to 3.11 inclusive. It should be noted that 3.12 introduces a number of syntax extensions that might cause problems when using 4.2.6. Version 4.2.7 is [expected to support Python 3.12](https://forum.djangoproject.com/t/django-4-2-lts-compatibility-with-python-3-12/24508/2) in future. + +## Execution + +Django can be run in a production environment, but this project is runnable and testable using the local debug server. This can be invoked using the following command, executed in the top-level directory: + +``` +python manage.py runserver 0.0.0.0:8000 +``` + +This server can then be accessed via http://localhost:8000/frontend/, and can be terminated from the command-line using Ctrl-C. + +## Configuration + +Project settings are in the standard Django location, `trafflights/settings.py`. Much of this file is default Django scaffolding. Of interest for this specific project are the following: + +1. **SIMULATION_DATA_FILE**: The file containining the period/state data for traffic light behaviour. +1. **SIMULATION_START_TIME**: The internal time at which the simulation starts, in ISO text format. By default this is 07:59 for demonstration purposes. +1. **SIMULATION_TIME_FACTOR**: The time "acceleration" factor (floating point) for the simulation. A factor of 1.0 will run in real-time, and higher factors will run faster. Default is 4.0. + # TODO List 1. Add instructions for installation/execution to README (including pre-requisites) 1. Add configuration options for periods data file, start time, and time factor 1. Change print statements to formal logging 1. Remaining refinements for frontend (font, remove debug visual aids, time remaining) +1. Move algorithm testing file to simulation directory, and change to use SimulationThread +1. Consider variable naming to better delineate similation vs real time variables