1. Principles and practices / Project management¶
Assignment:
- Plan and sketch a potential final project.
1a. Principle and practices¶
Presentation of my final project¶
Concept¶
For my final project to complete the Fab Academy program I have decided to work on a Puzzle Box (also called a “Secret Box” or a “Trick Box”). The idea is to manage opening the box as fast as possible by resolving a series of puzzles, and is thus purely for entertainment purposes. Technically this game can be solved by a single person, but it is more fun to tackle it as a team of friends or family, especially as collaboration is often key for success.
Sketch¶
Motivation¶
As mentioned in the “About Me” section, I like playing all sorts of games, and among those I had the chance to participate in a dozen of escape room adventures. The idea is very much similar to the Puzzle Box in the sense that participants have a certain amount of time to resolve a series of puzzles to complete a given mission, with the main difference that players are physically locked in one or several rooms, which definitely offers a more immersive experience.
I am really keen on those type of adventures because your brain is solicited to such an extent that after only a few minutes playing you feel completely focused in the mission that has been assigned to you. Moreover tricks are usually so complex that all players ideas are necessary to lead the team to the success. Communication and collaboration are of paramount importance, and this explains why those games are frequently chosen for team building events.
With my Puzzle Box, I wish I can offer to my family and friends a very special moment together. This project may also be an excellent opportunity for me to continue working on such mechanisms on my own or even join a company involved in those activities.
Game scenario¶
As fablab active members, your team is convinced that globally sharing knowledge is the only way to save humanity, especially in a time of pandemic crisis. After several weeks of preparation and thanks to your precious skills in digital fabrication you have successfully managed at night to break in the “Covid 19 Task Force Room” of one of the world’s biggest pharmaceutical company who recently officially announced positive results with the vaccine they developed against Covid-19. Your goal is to get ahold of the vaccine manufacturing method to share it around the world so that the vaccine can be produced everywhere and in sufficient quantities in many local labs to stop the pandemic before it is too late. Money should definitely not be the primary source of concern in such a situation ! After few minutes of inspection in this room, it seems that you have located a safe where the vaccine manufacturing method could well be stored. Look closely for any information that could help you opening this safe, but be careful as some security mechanisms have most likely be implemented to protect it.
Think hard and hurry up to get your mission completed, you are at risk here!
Main guidelines¶
Fab Academy requirements¶
In the final project, at least 5 of the digital fabrication skills developed during the Fab Academy program must be used. Here are the technics I integrate in my puzzle box : - Electronics design and production - 4 digits display - LCD - Magnetic sensors - Lock mechanisms - Switches - LEDs - Embedded programming - Arduino language to control mechanisms logics - 2D/3D modelling - Box design - Laser cutting - Box realization - 3D scanning and printing - Scanning the magnetic keys to integrate them inside customized elements
The project must be build using a “spiral model” approach. The model is often used by software engineers and enables gradual releases and refinement of a product through each phase of the spiral as well as the ability to build prototypes at each phase. This means that basic features are addressed first, and then extra features are added little by little in such a way that the project often comes back to a state where the product is operative.
I feel that my puzzle box project is particularly aligned with this philosophy as I will be in measure to remove/add puzzle mechanisms based on the progression of my project.
Personal guidelines to design the project¶
General guidelines :
- Safety: There must be no eletrical risk for the users.
- Size: Must be portable, but big enough so that several players can interact with it at the same time.
- Sequence of operations: Mechanisms cannot be solved in parralel, but rather one after the other.
- Number of mechanisms: It must be easy to add/remove mechanisms to the project.
- Scenario: The puzzle box should be built around a story and should not only be a succession of unrelated puzzles.
- Cosmetic appearance: Plan to integrate a false back to the box/drawers/doors to hide as much as possible the electronic circuits and cables.
- Robustness: It must always be possible to open the lock mechanisms (all mechanisms should open upon power supply failure, or there should be a manual way to open any mechanism).
Mechanisms that I want to integrate :
- Mastermind based puzzle
- Switches
- Engraved Text
- Countdown + Buzzer
- Magnetic keys
- Electrical locks
- One key element should be hidden in a constituent element of the box
References¶
Further information on my final project realization can be found here.
The escape room concept has turned to be so attractive that it has been declined in many different forms:
- Real-life escape rooms.
- Board games.
- Puzzle boxes.
- Virtual escape rooms.
- Movies.
Real-life escape room :
Board game :
Movie :
1b. Project management¶
Assignments:
- Work through a git tutorial.
- Build a personal site in the class archive describing you and your final project.
Work environment¶
Operating System (OS)¶
Even though I am much more familiar with Windows OS since I have used it for my entire life, I have decided to complete the Fab Academy program using Ubuntu (which is based on Linux Debian distribution). It is not brand new to me as I used it my previous job to communicate with the automotive infotainment systems I was working with.
I made this choise because I feel that this Linux environment is more appropriate for developers as it allows to build scripts and speed up many actions using command lines. Moreover, I much appreciate the concept of open source OS and applications. I am convinced that the skills I will develop using those tools will definitely be useful for the rest of my carreer and personal life.
Ubuntu 20.04 - Desktop view
Ubuntu 20.04 - Applications view
Setup¶
In order to quickly set up my computer, I executed this very useful script, available on the Facademy website.
I continue to regularly enrich this file on my local computer based on my personal needs.
Version control¶
Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later.
Git and Gitlab presentation¶
Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. It handles source code versioning, tracking of local file changes and content sharing with a remote repository.
GitLab is an open source end-to-end software development platform which offers git repository management in addition with code reviews, issue tracking, activity feeds and wikis. In that sense, it is rather considered as a Code Collaboration And Version Control tool.
To access the Fab Academy Gitlab project use the following link : https://gitlab.fabcloud.org/.
In order to get familiar with Gitlab I have watched several videos recorded for the Fab Academy 2021 Boot Camp explaining Version Control (Git Basics and Gitlab), and I have also read this tutorial.
Link between local repository and server repository¶
As can be seen on the picture below, Git has three main states that files can reside in: modified (in the working directory), staged, and committed.
Git states
- Modified: means that you have changed the file but have not committed it to your database yet.
- Staged: means that you have marked a modified file in its current version to go into your next commit snapshot.
- Committed: means that the data is safely stored in your local database.
SSH keys¶
In order to establish a safe communication between the local repository and the server repository, the SSH protocol is used. It combines asymmetric cryptography and symmetric cryptography so that client and server can exchange encrypted messages. This protocol is really well described in this website (in french).
Here are the steps I followed to establish the communication between my local computer and the server where my Gitlab files are hosted.
1- Generated a pair of SSH keys (one private key, one public key) in my local computer. Warning: the private SSH key must never be shared with anybody.
sudo apt-get install ssh-tools
ssh-keygen -t ed25519 -C "COMMENT"
Folder showing the 2 SSH key files
2- Opened the file containing the public key in my computer, copied/pasted it in the SSH menu of my Gitlab account and validated by clicking on the “Add key” button.
My computer public key
Gitlab page to add SSH public key
Local repository configuration¶
1- Installed git
sudo apt-get install git
git config --global user.name "Quentin BENETHUILLERE"
git config --global user.email "quentin.benethuillere@gmail.com"
Git configuration
3- As the Fab Academy administration has already configured a repository (with documents to get started) on the Gitlab server for each student, the next step was to clone (=copy) my repository into a folder of my local computer. In order to do so, in my Gitlab account I opened my Fab Academy project, clicked on the clone button and copied the link below “Clone with SSH”. This SSH_URL has then be used in the clone command that you see below.
Gitlab repository SSH link
cd /home/quentin/Documents/FabAcademy/Git_Folder
git clone git@gitlab.fabcloud.org:academany/fabacademy/2021/labs/digiscope/students/quentin-benethuillere.git
Main commands to update files¶
Here is the work sequence I will need to follow with the associated git commands.
- Everytime, before starting working on my local repository, I need to make sure that my local repository is up to date compare to the server repository :
git pull - Modify/add/remove files in my local repository.
- Check the files that have been added/removed/modified before updating them on the server repository :
git status - If needed check the modifications details :
git diff FILE_PATH - Add the files that I want to update on my server repository to the intermediate staging area :
git add .Note: Replace the “.” by given FILE(S)_NAME(S) in order to add only some file(s) to the stage area and not all modified/added/removed ones). - Save the modifications in the commited area (which means that modifications are saved in my local version control system) :
git commit -m "COMMENT_ABOUT_THE_MODIFICATIONS_PERFORMED - Save the modifications in the server repository :
git push
And now some screenshots of when I updated some documents for my website :
“Tracking modifications in the local repository
“Updating modified files in the Gitlab server repository
In order to see all the commit history, it can be quite convenient to use a graphical repository browser such as gitk.
Gitk view - Graphical repository browser
I will spend more time soon to experiment with the branching mechanism, revert actions, etc.
Personal website¶
The documents already available in my Fabacademy Gitlab repository at start were mainly documents for providing me with an operational personnal website template. To facilitate the students first steps writing a website, it has been generated with the MkDocs software, based on the Markdown markup language.
Please find below a screenshot of the original website provided to each student.
Original website when starting Fab Academy
Updates performed¶
Then I have started to modify the documents on my local repository to change the layout and content of my website.
In order to preview the modifications I make in the “.md” files I use the mkdocs serve and then load the following address : http://127.0.0.1:8000/ in my browser.
The main elements I have updated in my website are : theme colors, fonts, credentials, social media links, and of course general content. At the time I write those lines, here is how my website looks like.
My website “Home” page - 2021/02/02
My website “About Me” page - 2021/02/02
My website “Assignment 01” page - 2021/02/02
To give you an idea, here below is presented side by side an extract of an “.md” file in the text editor view and in a browser view :
Notepadqq text editor and Firefox browser views side by side
Issues encountered¶
Resolved¶
In the beginning I was unable to perform this preview because the mkdocs serve was giving me two error messages. As the template we have been given uses the “Material” theme (which is not MkDocs default theme), I first had to install this package on my computer, as well the “git-revision-date-localized” plugin which was also called in my website configuration.
sudo apt-get -y install python3-pip
sudo apt-get -y install mkdocs
pip3 install mkdocs-material
pip3 install mkdocs-git-revision-date-localized-plugin
Update 2023/03/15 :
Although the command lines described above allowed me to overcome the issue I had, it is not advised to install the missing packages this way. Indeed, when I recently updated my computer from Ubuntu v20.04 to v22.04.2 LTS, I encountered several issues :
- Issues during the ubuntu update.
- Issues to publish my FabAcademy website. Although I could see my content modifications on the local server, they would not appear on my website after pushing my work on my Git repository. To solve this issue I had to work on my Python configuration and also update some configuration files on my Git repository.
Following the recommandations of a friend who is really knowledgeable in this field, it is better to create a Python virtual environment for each project we are working with. This for example allows to work on several projects with different python configurations.
1 - Create a new clone of the git repo :
git clone git@gitlab.fabcloud.org:academany/fabacademy/2021/labs/digiscope/students/quentin-benethuillere.git
2 - Create a Python virtual environment. This will especially allow to later add dependencies that do not exist in the Ubuntu basics ditribution.
sudo apt install venv
python3 -m venv .venv
Warning : Complete the “.gitignore” file in your repo with a line “.venv” so as to never include the Python virtual environment into your Git repo.
3 - Activate the Python virtual environment :
source .venv/bin/activate
. .venv/bin/activate
4 - Install the desired packages for your project (this will automatically install the latest version of the package available) :
pip install mkdocs
pip install mkdocs-material
pip install mkdocs-git-revision-date-localized-plugin
Note: To install a specific version of a package :
pip install mkdocs==1.4.2
pip install mkdocs==
5 - Test that the local server can be opened without any issue.
mkdocs serve
6 - Update the “requirements.txt” file located on the Git repository, with the latest versions of the package installed.
Note: This file is useful to setup the required configuration for a project on a new environment, not really for the person who has already installed the necessary packages on its environment following the steps described hereabove.
To install the required configuration on a new environment, simply run this command :
pip install -r requirements.txt
7 - Update the “.gitlab-ci.yml” file located on the Git repository. This file is the one that handles the publication of the website. On this file, simply update the first line with the Python version installed on your system. Only the first 2 numbers are necessary, for example with version “XX.YY.ZZ”, no need to precise the “ZZ” information.
Note: To determine which version of Python is installed on your system, run the command :
python3 --version
Everything is now updated ! Take into account that, all the steps described here need to be run after each system update.
Also I had issues related to youtube video content. Here is what I could observe in Firefox :
Link to Youtube video issue - 2021/02/02
The problem was related to the url used in my link :
NOT working: https://www.youtube.com/watch?v=ORsOucrpSOE
Working: https://www.youtube.com/embed/ORsOucrpSOE
Unresolved¶
1 - I did not manage to replace my website logo with an image of my choice even though I managed to change my favicon. I would expect both features to work exactly the same way but it turns out not to be the case.
Here is what I tried in my “mkdocs.yml” file:
theme
icon:
logo: images/Fab_Academy_Logo.jpeg
2 - I did not manage to make the tabs (Home, About, Assignments, etc) always displayed, even when scrolling down the page.
Here is what I tried in my “mkdocs.yml” file:
theme
features:
- navigation.tabs
- navigation.tabs.sticky
3 - I did not manage to hide neither the table of content (currently displayed on the right hand side of my website), nor the side bar (displayed on the left hand side of my website).
Here is what I tried in my “mkdocs.yml” file:
markdown_extensions:
- extra
- smarty
- admonition
- codehilite:
- toc:
permalink: true
- meta
<center>
<hr style="border-top:2px solid gray" width="80%">
</center>
hide:
- navigation
- toc
<center>
<hr style="border-top:2px solid gray" width="80%">
</center>
4 - I did not succeed in creating a table without header (empty cells with grey color in background in the screenshot below) and without separators between lines.
Table on my website “Home” page - 2021/02/02
Other tools¶
Collaboration¶
The collaboration platform Mattermost will be used throughout the program. As it can be seen on the screeshot below, it offers the possibility to communicate :
- On public channels
- One channel with all the members involved in the Fab Academy 2021.
- One channel with all the persons involved in the Digiscope fablab where I am enrolled.
- On private channels
- For clarity purposes, my fab manager has created one channel per week assignment with all the members of our fablab.
- With direct messages
- 2 persons or more.
My Mattermost page
Text Editor¶
As I am familiar with Notepad++ on Windows, I have at the moment decided to use the same SW called Notepadqq in Ubuntu.
Notepadqq text editor layout
Image/Video processing¶
Fab Academy coordination rightly attaches great importance to the limitation of data stored within students repository. As a consequence we are strongly encouraged to use images and videos editors to compress our media files.
So far I have used gnome-screenshot software to reduce my images size.
Here is an example of command line I used to compress images :
convert -resize 1280x720 -quality 65 IMG_UNCOMPRESSED.jpg IMG_COMPRESSED.jpg
As for video I have not added any to my website yet, but I have started to get familiar with ffmpeg software.
Update 2023/03/13 :
During the whole FabAcademy program I have spent quite a lot of time to compress my pictures with different image qualities in order to reduce as much as possible the size of the files to be stored on my repository. Recently I have added new content to my website, and I finally decided to take some time to write a couple of bash scripts to automate this activity. The scripts can be downloaded by clicking on the links below :
Script - Aspect Ratio filtering
Project management¶
In order to manage my time during this intense program, I have decided to work with a Gantt planning.
Gantt planning with GanttProject tool - 2021/02/08
Currently I am using GanttProject software but I will soon give it a try to Ganttlab, Trello and Mermaid*.
References¶
In order to modify my website layout using Mkdocs Material theme, I referred mainly to this website