Added Installation and Usage section to README, with small additions to

other sections.
This commit is contained in:
Chris Davoren 2023-10-21 14:22:13 +10:00
parent 3318d809e5
commit dc36e151bb
1 changed files with 34 additions and 0 deletions

View File

@ -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 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 # TODO List
1. Add instructions for installation/execution to README (including pre-requisites) 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. Add configuration options for periods data file, start time, and time factor
1. Change print statements to formal logging 1. Change print statements to formal logging
1. Remaining refinements for frontend (font, remove debug visual aids, time remaining) 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