|
| 1 | +# Setup |
| 2 | + |
| 3 | +Clone this repo into the home directory of the pi, s.t. there is a directory |
| 4 | +called /home/pi/bus-timetables. |
| 5 | + |
| 6 | +Create symlinks to `.xinitrc` and `.xbindkeysrc`: |
| 7 | + |
| 8 | +``` |
| 9 | +$ ln -s ~/bus-timetables/.xinitrc ~/.xinitrc |
| 10 | +$ ln -s ~/bus-timetables/.xbindkeysrc ~/.xbindkeysrc |
| 11 | +``` |
| 12 | + |
| 13 | +Add the following line to `/etc/profile` to launch the X server on startup, but |
| 14 | +not when logging in from SSH. |
| 15 | + |
| 16 | +``` |
| 17 | +if [[ -z $SSH_CONNECTION ]]; then xinit -- -nocursor; fi |
| 18 | +``` |
| 19 | + |
| 20 | +# How It Works |
| 21 | + |
| 22 | +In essence, we launch an instance of chromium with the tab bar hidden. Each tab |
| 23 | +acts as a "screen", which renders a webpage that takes up the whole monitor when |
| 24 | +displayed. We define macros which automatically scroll through the tabs, giving |
| 25 | +the impression of cycling through screens, which are actually just webpages. |
| 26 | + |
| 27 | +This way, each screen is a webpage on a tab in chrome - the system is built to |
| 28 | +make this not too obvious. |
| 29 | + |
| 30 | +## Step by Step |
| 31 | + |
| 32 | +At startup, the X server is run with xinit. This runs the commands in .xinitrc |
| 33 | +from our home directory when the X server is done initializing. Because we |
| 34 | +symlink'd ~/.xinitrc to ~/bus-timetables/.xinitrc in the setup, the .xinitrc in |
| 35 | +this repo gets run. |
| 36 | + |
| 37 | +The .xinitrc starts by adding the bus-timetables repository to its path, so all |
| 38 | +of the scripts in the repository's top level are available to run. |
| 39 | + |
| 40 | +Then it launches and forks off the Python server via `timetable-server-proxy &` |
| 41 | +that serves the bus timetable, and if we aren't in debug mode launches |
| 42 | +`xbindkeys` and `autoscroll`. |
| 43 | + |
| 44 | +xbindkeys is a regular program that lets us bind mouse clicks and keyboard |
| 45 | +events to scripts via the ~/.xbindkeysrc file, which again is symlink'd to the |
| 46 | +file in our repo. In our case, the .xbindkeysrc file overrides the three mouse |
| 47 | +clicks (left, right, middle) to run the three scripts we've defined in the repo: |
| 48 | +left-click, right-click, and middle-click. These three buttons are rebound to |
| 49 | +run the next-tab and prev-tab scripts, which tells Chrome to cycle to the next |
| 50 | +tab or previous tab by sending it the Ctrl+tab or Ctrl+shift+tab keys |
| 51 | +respectively. |
| 52 | + |
| 53 | +autoscroll is a script which cycles to the next-tab once every 10 seconds, again |
| 54 | +using the next-tab script. This keeps chrome cycling through screens. |
| 55 | + |
| 56 | +Finally, the chrome browser is run. It is run in kiosk mode (unless debug mode |
| 57 | +is on), which means that it is full screened and has no tab list. We also |
| 58 | +disable web security (we assume we will only run our own websites with hand |
| 59 | +written code and inputs) in order to access the filesystem easily. |
| 60 | + |
| 61 | +The chrome browser is handed a list of URLs (these can be localhost, or file |
| 62 | +urls, or anything else that it can open). Each URL will open in a separate tab, |
| 63 | +which will act as a "screen" that we can flick through with right or left |
| 64 | +clicking. Currently, chrome is pointed at the bus timetable server on |
| 65 | +localhost:5000 and the under construction page in ./under-construction |
| 66 | + |
| 67 | +## The Bus Timetable Webpage |
| 68 | + |
| 69 | +The bus timetable webpage itself is served from localhost:5000 by |
| 70 | +timetable-server-proxy. It consists of two parts: |
| 71 | + |
| 72 | +- A Flask webserver, in proxy.py, which serves the index.html webpage and |
| 73 | + proxies the TfE API |
| 74 | +- A webpage, index.html, which requests the TfE API via the proxy, and renders |
| 75 | + it into a template using VueJS |
| 76 | + |
| 77 | +# Development |
| 78 | + |
| 79 | +## Adding a new screen |
| 80 | + |
| 81 | +To add a new screen, add a new URL to the list of URLs that chromium opens at |
| 82 | +the end of `.xinitrc`, and make sure that URL resolves to the thing you'd like |
| 83 | +to show. |
| 84 | + |
| 85 | +## Debug Mode |
| 86 | + |
| 87 | +It can be annoying when debugging a new screen to have to contend with the |
| 88 | +automatic screen switcher, a missing cursor, and overridden right and left |
| 89 | +click. In order to disable these, you can create the file ~/kiosk-debug, which |
| 90 | +.xinitrc will check for. |
| 91 | + |
| 92 | +Make sure to remove the file once you're done debugging! |
| 93 | + |
| 94 | +# TODO |
| 95 | + |
| 96 | +- We still need to make middle-click pause the autoscroll. |
| 97 | +- Showing some indicator of the time to next autoscroll would be nice. |
| 98 | +- The autoscroll should back off when the next/prev screen buttons have recently |
| 99 | + been clicked. |
0 commit comments