Chronos GUI2 Readme

GUI2 is a Python replacement for the C++-based camApp. The original camApp was designed as a monolith, handling the low-level register manipulation through to the high-level GUI. It was decided to break the monolithic camApp apart into two pieces โ€“ an API and a GUI โ€“ which have clearer responsibilities.

This GUI, which can be found on github, relies on the Chronos D-Bus API to run. (Although as of time of writing, this is still being split out.)

Project Overview

There are five major components to the Chronos project. From lowest level to highest, we have:

This project implements the back-of-camera user interface. The back-of-camera interface itself has has several components:

Historical Context

Why did we decide to rewrite our firmware?

In early 2018, our initial implementation of the Chronos 1.4 camera software was starting to cause problems. It wasโ€”quite reasonably at the timeโ€”built as a monolith using Qt 4. This got the kickstarter products out the door. As the product was refined, and more people started working on the code, long-running FPGA projects began conflicting with long-running GUI projects. Refactoring the code became quite difficult, so it was decided to split the initial camera software, the camApp, in to two components. One would take care of the FPGA, and one would take care of the UI. They would talk over a D-Bus API.

In the summer of 2018, it became apparent that we would be switching operating systems from Arago Linux to Debian Linux. To enable wifi on the camera, a WIFI dongle can be plugged into the USB port. However, as Arago Linux seems to have ceased development in in 2013, none of the dongles available in 2018 have supported drivers. Running Debian, driver support is much better.

Running Debian also means we can compile modern libraries for our use, which was effectively impossible under Arago. To this end, as we were planning a redesign of the user interface anyway, we decided to take the opportunity to upgrade our GUI library to Qt 5 from Qt 4, and from C++ to Python. This repository contains the "vanilla" Qt 5 Python port. (A Qt Quick 5 Python port is also in the works. One will be chosen as the winner at some point, when we have more experience with both of them.)

Design Considerations

Setup and Running

Setup

On your camera, or in a virtual machine, set up Python 3.6.5+ and QT 5.10+ on Debian 7. After configuring your environment to your liking and installing any missing imports required by src/cam-ui.py, you can start the UI with python3 src/cam-ui.py. If you have some trouble with this, don't worry! This is normal. It took me about 150 discreet steps and two or three weeks to get everything working properly the first time. Luckily for you (hopefully), you can find my edited notes in chronos debian setup instructions.txt. Good luck. ๐Ÿ˜ฌ

Running

Manual: Copy this repository to the camera. Then, run python3 src/cam-ui.py on the camera, from the root folder of this project.

Automatic: The above is process is automated by the watch-*.sh scripts, in the util folder, to automatically deploy and run the app as files change during development. (See util/readme.txt for more details on which file is what.) There are two options: Deploy to camera, or deploy to a testing VM. For each option, there are two scripts. One script automates copying the files to the destination, and the other script automatically reruns the application when it notices a file has been updated.

There are two scripts because the destination side will work regardless of OS, but Mac or Windows may need to write a different upload-to-destination script. The scripts, to some extent, also deal with separate concerns.

Assuming we're uploading files to the camera, as opposed to a VM, we'll want to run ~util/watch-computer.sh. Looking in that file with our favourite text editor, we see it has three major components: a loop, find feeding into entr, and rsync. Entr is a program which watches the filesystem for change events, and runs a program when something changes. You may need to install with sudo apt install entr. In our script, entr watches the files which we seach for with find. The loop is because entr stops running if a folder is changed, so find can search for files in that folder and watch them too. The final component is the rsync invocation, which copies updated files to the camera.

Action: Rsync needs to know two things. First, where to put the changed files. By default, it uploads to cam. This preset is defined in ~/.ssh/config. You will need to add it as a preset yourself. My block looks like this: #Debian, on the physical camera itself Host cam User root HostName 192.168.12.1 ConnectTimeout 1 cam is the name of the destiantion. We may need to change the HostName if the camera is not accessible via ssh root@192.168.12.1. (192.168.12.1 is the default IP address if you plug the Chronos in to your computer with MiniUSB.) You can test that your preset works by running ssh cam.

Second, rsync needs to know the login credentials to the camera. To do this, rsync is set to use sshpass. (You may need to install it with sudo apt install sshpass.) sshpass references the $CHRONOS_PASSWORD environment variable, which you can set in your ~/.bashrc file. (Or whatever startup file your shell is using, for example ~/.zshrc for zshell.) In my .bashrc, I have the following line to do this: export CHRONOS_PASSWORD="chronos" #๐Ÿ‘Œ๐Ÿ‘Œ๐Ÿ‘Œ๐Ÿ”’ At some point, we'll make it so you have to actually *set* your own password before SSH is enabled at all, but for now you are simply advised to disallow incoming connections from the internet at large on the network level.

In the root of the project, on your computer, you can now run util/watch-computer.sh. This will watch for file changes and upload them to the camera.

The second step is running the new files on the camera. First, we'll log in to the camera. There, cd gui to go to the newly-deployed project. Instead of running python3 src/cam-ui.py, we'll run util/watch-camera.sh which will run and rerun the command for us. (Under the hood, this script starts a bash loop running the python3 command. It uses watchdog (pip3 install watchdog) to restart the script when a file changes. Watchdog is configured in the inline python script near the bottom of the file.) To help debug the GUI script, an interactive prompt will be brought up in this ssh session when an error is encountered.

Editing

It is strongly encouraged to set your favourite editor up with some sort of Python linter, such as Anaconda, if it does not already support Python linting. However, any editor or IDE on any operating system may be used. This means the code may be edited using vi directly on the camera, which may be simpler than setting up your own development environment.

The .ui files are editable with QT Designer. It needs some env vars set to pick up the custom widgets, so the easiest way to run Designer is to run util/designer.sh.

For an explanation of how to approach the codebase, see doc/how-to-approach.html

Contributing

Contributions are welcome! Thank you! Before diving in and changing things, it's a good idea to tell us what you'd like to do on the forums. Since we are familiar with the codebase, we can help get you started in the right direction. ๐Ÿ™‚

Known Issues

See https://github.com/krontech/chronos-gui-2/issues.