README.md

   1 # IID Coffee Terminal
   2
   3 This repo contains git submodules with all source code of this coffee
   4 terminal. Fetch it with:
   5
   6         git submodule update --init
   7
   8 The [`coffee-flask`](coffee-flask.git) directory contains the server
   9 application, which runs on [rtime](https://rtime.felk.cvut.cz/coffee)
  10 server.
  11
  12 `terminal` directory contains the code running on the terminal. It is
  13 based on a standard [buildroot](https://buildroot.org/) distribution.
  14 The most important piece of code here is the `mtaio` application from
  15 [`terminal/src/mt-apps`](./mt-apps.git), which contains the web server
  16 powering the GUI of the terminal – a web browser. Among other things,
  17 it informs the browser about physical events captured by the terminal
  18 from the card reader and coffee machine buttons.
  19
  20 A more detailed documentation is available in [Jiří Matěják's Master
  21 thesis](https://dspace.cvut.cz/handle/10467/76276).
  22
  23 ## Collected data
  24
  25 Data collected by the terminal are stored in an sqlite database on the
  26 rtime server. Users with SSH access to that server have read-only
  27 access to the database. For example, the whole database can be dumped
  28 with this command:
  29
  30     sqlite3 /home/coffee/coffee-flask/coffee.db .dump
  31
  32 ## Hacking on the code
  33
  34 To improve the terminal, you can run all the relevant code on your
  35 Linux computer.
  36
  37 First install all prerequisites:
  38
  39     apt install python3-flask libev-dev cmake
  40         pip3 install flask_cors
  41
  42 Alternatively, you can install [Nix package manager][] and run
  43 `nix-shell` in the `main` directory. This ensures that correct version
  44 of all needed dependencies are available in the shell (until you
  45 exit).
  46
  47 Then compile and run all the software components:
  48
  49 1. Compile _mtaio_ simulator: `make -C terminal/src/mt-apps SIM=1`
  50 2. Run mtaio: `cd terminal/src/mt-apps && ./build/mtaio`
  51 3. Run the server application: `cd coffee-flask && FLASK_APP=app.py FLASK_DEBUG=1 flask run`
  52 4. Point your web browser to http://localhost:8080/
  53 5. Pressing keys in _mtaio_ window simulates various activities.
  54    Numbers are cards of different users, letters A through F are
  55    different coffee machine buttons.
  56
  57 The size of the terminal window is 960×560 px.
  58
  59 ### Submitting patches
  60
  61 Send patches by email (preferably with [git send-email][]) to
  62 `coffee@rtime.felk.cvut.cz` [mailing list][]. You can subscribe the
  63 [mailing list][] to discuss the patches sent by others.
  64
  65 It is recommended to run the [`setup_git`][sg] script in your local
  66 repository to configure git optimally for patch submission.
  67
  68 [git send-email]: https://rtime.felk.cvut.cz/wiki/index.php/Configuring_git_send-email
  69 [mailing list]: https://rtime.felk.cvut.cz/mailman/listinfo/coffee
  70 [sg]: main.git/blob/HEAD:/setup_git
  71 [Nix package manager]: (https://nixos.org/guides/install-nix.html)