Mechanical-Advantage/AdvantageTrack

Automated attendance tracking system

AdvantageTrack

AdvantageTrack is an attendance system built to combine a manual sign-in interface with automated tracking of student and mentor devices. Data storage and analysis are handled using Google Sheets, updated by the local Python server. The server runs a local web app for sign-ins & status, and it monitors the active devices on the local network using intermitent flood pings. Each team member can opt-in to the automatic tracking by registering their device's MAC address with the system.

The local server can run on Linux, Windows, or macOS. No special hardware or network access is required for automatic monitoring. The frequency of flood pings is configurable, though it requires a network where ICMP echo requests are allowed. Both iOS and Android currently use randomized MAC addresses by default, but the system will guide users through disabling this feature for a single network (meaning there is no impact to device security on other networks). This step is required because both operating systems will reset the MAC address used on a network under some conditions.

More Screenshots

Installation & Setup

1. Set up a Google Cloud Project using these instructions.

2. In Google Drive, make a copy of this Google Sheet and create a new folder for background images. Share these items to the service account email from your Google Cloud Project (the folder requires at least view access and the sheet requires at least edit access).

   • Note: The provided spreadsheet uses eastern time by default. You can update the time zone under "File" > "Settings" > "Time zone". This time zone must match the selected time zone on the local server for the system to function properly.

3. Check the configuration in the "Config - General" sheet (hover over each key for a detailed explanation). In particular, make sure to update the IP address range and background folder ID. You can also update the list of registered people in the "Config - People" sheet. Note that the some of the sheets include sample rows. Don't delete these rows during setup; they are required for the server to correctly update the sheets.

4. Add some JPEG or PNG images to the backgrounds folder. These will be automatically downloaded by the server (and updated periodically).

5. Clone the AdvantageTrack repository to the device which will run the server (Linux, Windows, or macOS). We recommend using a dedicated device for this purpose, such as a Raspberry Pi.

6. Copy the JSON credentials from the Google Cloud Project to the following path: AdvantageTrack/data/google_credentials.json

7. Update the SPREADSHEET_ID at the top of the main.py script. This is the Google Drive ID of the main AdvantageTrack spreadsheet (the last part of the URL).

8. Ensure that the following tools are installed and available on your PATH:

   • Python 3.6 or later

   • A modern browser of your choice

   • arp

   • fping (Installation instructions)

9. Install the Python dependencies. We recommend using a virtual environment for this purpose:

Linux/macOS

python -m venv venv
source ./venv/bin/activate
pip install -r requirements.txt

Windows

python -m venv venv
venv\Scripts\activate.bat
pip install -r requirements.txt

9. Launch the main.py script in the virtual environment and navigate to http://127.0.0.1:8000 in a browser. The status of the system will be displayed at the bottom of the page. If the background folder was linked correctly, your custom images will appear on this page once the downloads finish (a default set will be used temporarily).

10. If desired, configure the OS to automatically log in, start the main.py script, and open a browser.

Development

The code is formatted using the Python and Prettier VSCode extensions (recommended for this workspace). Python is configured with autopep8 while HTML, CSS, and JS use Prettier.

The server functionality is divided into Python modules at the root level (launched from main.py). All of the HTML, CSS, and JS code is under the www folder.

The server interfaces with Google Drive using gspread and the official Google Python API. The web server uses CherryPy with ws4py. Most communication between the web server and browser runs over a WebSocket connection. The monitoring system invokes fping and arp using subprocess (it can also be disabled for testing using the ENABLE_MONITOR constant in main.py).