Documentation update

Addition of ribbon assembly detail
Addition of sdcard creation guide
Update to the image
Make sure it's PlanktoScope everywhere

docs/README.md

@@ -19,6 +19,7 @@ You can find here more information about how to build your own PlanktoScope.
 ## Under the hood:
  - [Software architecture](software_architecture.md)
  - [MQTT Messages](mqtt_messages.md)
+ - [Create Master SD Card or backup your PlanktoScope](create_sd.md)
  - How does the segmentation works (soon)
 
 ## Contribute

docs/assembly_guide.md

@@ -16,7 +16,7 @@
 - Super glue
 - Standoffs (M2.5), M3 screws and nuts
 
-Make sure you have your screwdriver kit, soldering iron, and components ready. Also, remember to flash the Planktonscope image disk on the SD card before installing the Raspberry Pi.
+Make sure you have your screwdriver kit, soldering iron, and components ready. Also, remember to flash the PlanktoScope image disk on the SD card before installing the Raspberry Pi.
 
 If you are not familiar with any process, such as soldering, tapping, or wiring, try and familiarize yourself with the topics first.
 
@@ -233,7 +233,22 @@ Secure the laser cut sides to the base plate **A** with the screws and nuts.
 
 You can now connect the camera flex cable into the connector on the camera board. Once again, gently pull up the tensioners, insert the cable in the right orientation, and push the tensioners back in place to set the cable. Try not to kink or fold the flex cable too much as it is possible to damage it.
 
-## Step 29: Insert the ribbon cable
+## Step 29: Assemble the GPIO ribbon cable
+If you didn't get an already assembled ribbon cable, you need to build it yourself.
+
+The orientation of the connector does not really matter. However, you need to make sure that both connectors are oriented in the same direction and are on the same side of the ribbon.
+
+To assemble, slide the ribbon in its connector and close it off. You need to tighten it really hard. It's very warmly recommended to use a vice to do so.
+
+!!! warning
+    Once assembled, the ribbon should NOT look like this:
+    ![Ribbon wrong](assembly_guide/pictures/ribbon_wrong.webp)
+
+    It should rather look like this:
+    ![Ribbon good](assembly_guide/pictures/ribbon_good.webp)
+
+
+## Step 30: Insert the ribbon cable
 ![Step28](assembly_guide/render/step28.webp)
 
 Attach the GPIO ribbon to connect the cooling fan HAT to the GPS HAT.
@@ -242,7 +257,7 @@ Attach the GPIO ribbon to connect the cooling fan HAT to the GPS HAT.
     You can try to route the flat ribbon from the camera under the ribbon cable you are connecting now.
     ![Step31](assembly_guide/pictures/step31.webp)
 
-## Step 30: Fluidic assembly
+## Step 31: Fluidic assembly
 ![Step29](assembly_guide/render/step29.webp)
 
 Feed in the tubing from syringe 1 to form the fluidic path as shown.
@@ -257,18 +272,18 @@ Feed in a length of tubing as shown through motor mount **H** and illumination m
 
 ![Step34](assembly_guide/pictures/step34.webp)
 
-## Step 31: Close your PlanktoScope
+## Step 32: Close your PlanktoScope
 
 !!! warning
     Take a moment to check your wiring one last time. Also check the routing, make sure the LED wires and the pump stepper wires are in their dedicated channel.
 
 ![Step33](assembly_guide/render/step33.webp)
 
-Place the top **L** into the slots on the Planktonscope body. Secure it in place with screws and nuts.
+Place the top **L** into the slots on the PlanktoScope body. Secure it in place with screws and nuts.
 
 ![Step34](assembly_guide/render/step34.webp)
 
-## Step 32: Enjoy!
+## Step 33: Enjoy!
 
 Congratulations on a job well done. You can have some rest, get a tea and some biscuits!
 

docs/create_sd.md

@@ -0,0 +1,96 @@
+# How to create a new SD master card, or backup efficiently your existing card
+
+If you want to backup your machine, or prepare an image from the golden machine to share it to the world (or your students), you may want to follow those steps. 
+
+!!! tip
+    The golden machine is the machine on which the setup is made. Everything is prepared according to your needs. Once it's ready, you just cleanly shut it down, pop the SD card out, and copy it to share the love!
+
+
+Everything in this guide is written by using a Linux computer in which the sdcard is inserted.
+
+## Find and unmount your sd card
+Firsts things firsts, we need to know where is our sdcard in the linux filesystem.
+
+To find the device, open a terminal and type in `sudo fdisk -l`.
+
+In the output, there will be a section looking like this:
+```
+Disk /dev/mmcblk0: 58.29 GiB, 62587404288 bytes, 122241024 sectors
+Units: sectors of 1 * 512 = 512 bytes
+Sector size (logical/physical): 512 bytes / 512 bytes
+I/O size (minimum/optimal): 512 bytes / 512 bytes
+Disklabel type: dos
+Disk identifier: 0xa2033091
+```
+
+There is a very high probability that the device name we are looking for starts with `mmcblk`. To make sure this is the device we are looking for, use the size displayed (in this case, it is a 64GB sdcard).
+
+We are now going to make sure the device is not mounted on your system (some OSes mount inserted sdcards automatically).
+
+Simply type `sudo umount /dev/mmcblk0p1` and `sudo umount /dev/mmcblk0p2` to unmount the disk.
+
+If the devices were not mounted, you may see an error message that you can ignore. The message looks like this:
+```
+umount: /dev/mmcblk0p2: not mounted.
+```
+
+## Copy the sdcard to your disk
+
+Choose and navigate to an appropriate directory on your computer.
+
+We are going to use `dd` to copy the sdcard. The command to type is the following:
+```sh
+sudo dd if=/dev/mmcblk0 of=planktoscopeimage.img bs=4M status=progress
+```
+
+- `if`: stands for `input file`, this is the input that we want to copy FROM
+- `of`: stands for `output file`, this is where the image is going to be written
+- `bs`: chooses a block size of 4M, this helps to speeds up the copy
+- `status`: just display a progression of the copy
+
+
+The copy may take more than 15 minutes to complete, so you can go get a coffee or something.
+
+Congratulations, you now have a complete copy of your sdcard!
+
+However it's big. Huge even. We are going to resize it to make its storage and sharing easier.
+
+## Shrink and share!
+
+Before shrinking the image, let's sanitize it first and remove eventual secrets stored in it (like wifi passwords for example).
+
+```sh
+mkdir mnt
+sudo mount -o loop,rw,offset=$((532480 * 512)) planktoscopeimage.img ./mnt/
+```
+
+You can now cleanup the image. The `mnt` directory is the same as the root of your sdcard. You should find your way from there.
+
+Notably, do not forget to edit/remove the following files:
+
+- `mnt/etc/wpa_supplicant/wpa_supplicant.conf`: wifi configuration and network secrets
+- `mnt/home/pi/.ssh/authorized_keys`: public ssh keys authorized to connect to this planktoscope
+- `mnt/home/pi/data/`: this folder has all the images taken before by your machine, you may want to clean it up too
+
+Once your cleanup is done, unmount the image with `sudo umount mnt`.
+
+Now, let's shrink the image! To do so, we are going to use [PiShrink](https://github.com/Drewsif/PiShrink).
+
+You can install the script using the following:
+```sh
+wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
+chmod +x pishrink.sh
+```
+
+Now, starts PiShrink on your image, and watch it do its magic:
+```sh
+sudo ./pishrink.sh -z -a -p planktoscopeimage.img
+```
+
+The following flag are recommened, but you can change them depending on your needs:
+
+- `-z -a`: compress the image to a gz file using the multithread version of gz
+- `-p`: remove logs, apt archives, and similar things
+
+You now have a compressed that should be between 10 and 100 times smaller than the one you started with. You can distribute it, archive it, do whatever you please with it!
+

docs/easy_install.md

@@ -2,7 +2,7 @@
 
 ## Download the image
 
-For ease of setup, a preconfigured image is provided. You can download it from [here](http://planktonscope.su.domains/Images_raspberry/Raspbian_Buster_Morphocut_WiFi.img).
+For ease of setup, a preconfigured image is provided. You can download it from [here](https://drive.google.com/file/d/1zOmbmXqt5uELQC0FTha1ndjJyMvehGSk/view?usp=sharing).
 
 ## Writing the image to the SD card
 

docs/expert_setup.md

@@ -3,7 +3,7 @@
 ## Install and setup Raspbian on your Raspberry Pi
 
 ### Computer setup
-In order to make it easy to connect to the PlanktoScop, you may want to install [avahi](https://en.wikipedia.org/wiki/Avahi_%28software%29) or the [Bonjour](https://en.wikipedia.org/wiki/Bonjour_%28software%29) service on any computer you will use to access the PlanktoScop interface. This will allow you to connect to the PlantoScop using an address similar such as http://planktoscope.local instead of an IP address.
+In order to make it easy to connect to the PlanktoScope, you may want to install [avahi](https://en.wikipedia.org/wiki/Avahi_%28software%29) or the [Bonjour](https://en.wikipedia.org/wiki/Bonjour_%28software%29) service on any computer you will use to access the PlanktoScope interface. This will allow you to connect to the PlantoScop using an address similar such as http://planktoscope.local instead of an IP address.
 
 ### Download the image
 
@@ -63,11 +63,11 @@ You can now launch the configuration tool:
 sudo raspi-config
 ```
 
-While you're here, a wise thing to do would be to change the default password for the `pi` user. This is very warmly recommended if your PlanktoScop is connected to a shared network you do not control. Just select the first option `1 Change User Password`.
+While you're here, a wise thing to do would be to change the default password for the `pi` user. This is very warmly recommended if your PlanktoScope is connected to a shared network you do not control. Just select the first option `1 Change User Password`.
 
 You may also want to change the default hostname of your Raspberry. To do so, choose option `2 Network Options` then `N1 Hostname`. Choose a new hostname. We recommend using `planktoscope`.
 
-We need to activate a few things for the PlanktoScop to work properly.
+We need to activate a few things for the PlanktoScope to work properly.
 
 First, we need to activate the camera interface. Choose `5 Interfacing Options`, then `P1 Camera` and `Yes`.
 
@@ -88,11 +88,11 @@ Reboot your Pi safely.
 sudo reboot now
 ```
 
-## Install the needed libraries for the PlanktoScop
+## Install the needed libraries for the PlanktoScope
 
 Most of the following happens in a command line environment. If you are using the desktop, please start a terminal emulator.
 
-You can also connect to your PlanktoScop by using ssh using `ssh pi@planktoscope.local`.
+You can also connect to your PlanktoScope by using ssh using `ssh pi@planktoscope.local`.
 
 You can then run the following to make sure your Raspberry has the necessary components to install and build everything it needs and to create the necessary folders:
 
@@ -202,7 +202,7 @@ If the interface is loading and a picture is displayed, you can now stop this in
 
 ### Install Ultimate GPS HAT
 
-You can start by testing that the GPS module is working. Either install your PlanktoScop with a view of the sky, or connect the external antenna.
+You can start by testing that the GPS module is working. Either install your PlanktoScope with a view of the sky, or connect the external antenna.
 
 Now you need to run the following:
 ```sh
@@ -294,7 +294,7 @@ pi@planktoscope:~ $ gpsmon
 
 #### Bonus Configuration: Automatic time update from GPSD
 
-The Adafruit GPS HAT allows your PlanktoScop to automatically sets its time to the GPS received one. Moreover, since the PPS (Pulse Per Second) output is activated, you can even set your PlanktoScope to act as a stratum 1 timeserver.
+The Adafruit GPS HAT allows your PlanktoScope to automatically sets its time to the GPS received one. Moreover, since the PPS (Pulse Per Second) output is activated, you can even set your PlanktoScope to act as a stratum 1 timeserver.
 
 We are first going to make sure that your PlanktoScope receives proper PPS signal. We need to add the following line at the end of `/boot/config.txt`:
 ```
@@ -526,7 +526,7 @@ sudo systemctl start nodered.service
 Make sure Node-RED is correctly installed by reaching the following page from the browser of your pi http://localhost:1880 or http://planktoscope.local:1880 from another computer on the same network.
 
 #### Install the necessary nodes
-These nodes will be used by the PlanktoScop software and needs to be installed:
+These nodes will be used by the PlanktoScope software and needs to be installed:
 ```sh
 cd ~/.node-red/
 npm install node-red-dashboard node-red-contrib-python3-function node-red-contrib-camerapi node-red-contrib-gpsd node-red-contrib-web-worldmap node-red-contrib-interval

mkdocs.yml

@@ -11,6 +11,7 @@ nav:
     - Under the hood:
         - Software architecture: software_architecture.md
         - MQTT Messages: mqtt_messages.md
+        - Create Master SD Card: create_sd.md
     - Contribute:
         - Edit this documentation: edit_this_doc.md
         - Edit the code: edit_the_code.md