curious.bio/planktoscope
curious.bio
/
planktoscope
8
0
Fork 0
Code Issues 10 Pull Requests Packages Projects 7 Releases Wiki Activity

updated license info

This commit is contained in:
Sebastian Wendel 2023-01-19 22:23:42 +01:00
parent b55990b398
commit 97d7409c2c
No known key found for this signature in database
GPG Key ID: 14ED8B1EC3371ECE
46 changed files with 167 additions and 317 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/changelog.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Changelog
## Image changelog

213
docs/community/trainings.md
View File

@ -8,6 +8,97 @@ The train the trainer program is a training program designed to equip individual
This guide is intended to provide you with a solid foundation of knowledge and understanding about the PlanktoScope, enabling you to confidently develop and deliver your own training program for others. Whether you are an experienced user looking to share your expertise with others or a newcomer to the PlanktoScope looking to learn more about its capabilities and applications, this guide is designed to help you gain the necessary skills and knowledge to successfully teach others about this powerful tool.
## Event types
### Build workshop
Organizing a build workshop can be a challenging but rewarding experience. It requires careful planning and execution to ensure that the workshop is successful. This trainer manual is designed to guide you through the process of organizing a build workshop.
#### Selecting the production site
Choosing the right production site for preparing and manufacturing the PlanktoScope Kits is an important step in the workshop planning process. The production site should have the necessary tools and equipment, as well as the knowledge and expertise to manufacture the PlanktoScope Kits. Here are a few things to consider when choosing a production site:
1. **Check the Manufacturing and Assembly Guides**: Before choosing a production site, make sure to review the PlanktoScope [Manufacturing Guide](/hardware/manufacturing/) and the [Assembly Guide](/hardware/assembly_guide/). These guides will provide detailed information on the necessary tools and equipment required for the production of the PlanktoScope Kits.
1. **Visit [Fablab](https://fablabs.io/labs) and [Hackspaces](https://wiki.hackerspaces.org/List_of_Hacker_Spaces)**: Consider visiting Fablabs or Hackspaces in your region. These organizations often have a culture of openness and may be willing to support you with your project. They may have the necessary tools and equipment to produce the PlanktoScope Kits, as well as the knowledge and expertise to guide you through the production process.
1. **Commercial Manufacturing**: Look for a facility that has the capability to handle small scale production runs, a good quality control process and a logistic plan to ship the product to the final destination. Many
!!! tip
For the PlanktoScope case, for example, you can look for woodworking companies. They often have a CNC machine and are familiar with the process of ditigal production.
#### Material procurement
Building a PlanktoScope requires a specific set of materials. In order to ensure that the workshop runs smoothly and that all attendees are able to successfully build their own PlanktoScope, it is important to properly plan and execute the procurement of materials. The following is a step-by-step guide on how to properly plan and execute the procurement of materials for a workshop:
1. **Prepare the order list**: Use the bill of materials (BOM) as a starting point to create a comprehensive list of all materials needed for the workshop. Expand it with additional columns for suppliers, delivery dates, prices, shipping costs, and import taxes.
2. **Plan for packaging**: Plan for extra packaging so you can assemble the parts as shown in the instructions. Try to minimize plastic as much as possible.
3. **Research suppliers**: Research suppliers and see if there are local options, if you can consolidate orders to save costs and ensure timely delivery.
4. **Compare prices**: Compare the prices of different suppliers to minimize the total cost.
5. **Plan for spare parts**: Plan for spare parts in case something is broken or lost.
6. **Check your Budget**: Check your budget and ensure that you have enough funds to cover the cost of all materials, shipping, and any additional expenses before placing your orders.
7. **Place orders**: Once you have identified the best suppliers, place orders for all of the materials that you need. Be sure to factor in lead time when placing orders to ensure that the materials will arrive in time for the workshop.
8. **Track orders**: Keep track of your orders and expected delivery dates, mark a component when it arrives. Contact suppliers if there are any delays or problems with delivery.
9. **Communicate**: Communicate with participants if there are issues with timely delivery. It may make sense to postpone the workshop if there is not enough time to prepare and test everything. The participants will be grateful and will understand if it helps to ensure that everything runs smoothly.
By following this process, you can ensure that all materials are procured and organized well in advance of the workshop, to avoid any last-minute delays or complications.
!!! note
If you have difficulty finding the components you need, [contact us](https://planktoscope.slack.com/) and we will be happy to help you find the right alternative.
!!! warning
Have a backup plan and be prepared for unexpected events that may occur during the procurement process. Allow two months for delivery, as some specialty parts may travel a long way and require additional time for customs inspection.
!!! tip
Let us know your results, we would love to hear what solutions you found and how cost effective you were able to make the PlanktoScope.
#### Prepare the Kit
Kit preparation for the workshop is an important step in the preparation process. This ensures that participants have the materials and equipment they need to complete the workshop and build their own PlanktoScope. Here are a few things to keep in mind when preparing the kits:
1. **Review the Bill of Materials (BOM)**: Review the Bill of Materials (BOM) for the PlanktoScope to ensure that you have all the necessary parts and materials for the workshop. The parts list can be found in the [Assembly Guide](/hardware/assembly_guide/) and lists all components and quantities needed to build a microscope.
2. **Divide the kit components according to the BOM**: Once the materials have been received, divide the kit components from the orders according to the Bill of Materials (BOM) of the PlanktoScope. This will ensure that each participant receives the correct components and that there are no missing parts.
3. **Have extra components**: Have extra components on hand in case of any missing or damaged parts during the workshop.
4. **Package the kits**: Package the kits in a way that makes it easy for the participants to find and use the components during the workshop.
5. **Label materials**: Label the packages as described in [Assembly Guide](/hardware/assembly_guide/) so that they are easy to find and distribute during the workshop.
6. **Preparation of the housing parts**: Prepare the housing parts by applying the surface sealant and insert the nuts to screw the housing as described in the [Manufacturing Guide](/hardware/manufacturing/#finishing).
7. **Cutting and soldering of electronic cables**: Cut and solder the electronic cables for the PlanktoScope. This will save time during the workshop and ensure that the participants have all the necessary cables to complete the assembly.
8. **Setting up the embedded development environment**: Set up the embedded development environment and flash the eeprom of the PlanktoScope hat. This will ensure that the PlanktoScope hat is ready to be used during the workshop.
9. **Download the Raspberry Pi image**: Download the Raspberry Pi image and flash it to the SD card. This will ensure that the participants have a ready to use image for the PlanktoScope.
10. **Test the kits**: Test the kits before the workshop to ensure that all components are working correctly and that the instructions are clear and easy to follow. This will help to ensure that the participants have a positive and productive experience during the workshop.
!!! tip
Identify any items that are time consuming during the workshop and not particularly important or complex to explain. These tasks can be completed in advance to save time during the workshop. This will make it easier for the participants to assemble the PlanktoScope during the workshop.
#### Conducting the workshop
It's finally here! After all the planning, preparation, and anticipation, the build workshop is about to begin. Take a deep breath and let's go!
1. **Prepare the presentation**: Prepare the presentation device and start your slides.
2. **Check-In**: Once the Participants arrive, complete the check-in, share the agenda and set expectations for the workshop.
3. **Venue**: Provide information about the venue, including where to find restrooms and where to buy food.
4. **Digital tools**: Provide information about the digital tools that will be used during the workshop, such as the platform for collaboration, the survey tool and the chat channel, and how to access them.
5. **Data privacy**: Provide information about the data privacy policy and the forms that need to be signed by the participants.
6. **Introduction**: Begin with a round of introductions and give everyone a chance to introduce themselves, their background, and their interest in the project.
7. **Overview**: Provide details about the project, including the general mode of operation, the working materials such as the kit, the documentation and the git repository.
8. **Kits and Tools**: Provide the Kit and Tools to each participant with a kit and the necessary tools.
9. **Follow your Presentation and ** as described in the "Preparing a Presentation" section
!!! tip
Paint the big picture and communicate progress to the participants. Activate and engage with the participants, and make sure to check-out and wrap up the workshop.
### Field trip
Are you an expert in organizing field trips? Share your skills with the PlanktoScope community by documenting the process! By documenting how you organize a field trip, you can help others create successful events and bring more event options to the PlanktoScope community. Your documentation will be a valuable resource for anyone looking to plan a field trip, and it will also help to grow and strengthen the PlanktoScope community. Don't miss this opportunity to contribute to the community, start documenting your process today!
### Hackathon
Are you a master at organizing Hackathons? Share your knowledge with the PlanktoScope community by documenting the process! By documenting how you organize a Hackathon, you can help others create successful events and bring more event options to the PlanktoScope community. Your documentation will be a valuable resource for anyone looking to host a Hackathon, and it will also help to grow and strengthen the PlanktoScope community. Don't miss this opportunity to contribute to the community, start documenting your process today!
## General planning methods
Organizing a workshop can be a challenging but rewarding experience. It requires careful planning and execution to ensure that the workshop is successful. This trainer module is designed to guide you through the process of organizing any type of event.
@ -115,16 +206,6 @@ The location should be convenient and accessible for the participants, and shoul
4. **Check for food provision**: Consider if there is a possibility to go shopping or how to provide food for the course participants during the workshop.
5. **Check the environment**: Consider the environment of the location, make sure it is comfortable, has enough space and is well-ventilated for the workshop.
### Accommodation
If the workshop is taking place over multiple days and is located in a less populated area, accommodation options may be more limited compared to a larger city. However, it is still important to provide participants with comfortable and convenient accommodations that are close to the workshop location. Here are a few things to consider when planning accommodation for a multi-day workshop in a less populated area:
1. **Research options**: Research all available accommodation options in the area. This includes hotels, bed and breakfasts, vacation rentals, and camping options.
1. **Reach out to local businesses**: Consider reaching out to local businesses such as farmers, innkeepers, or small hotels. They may be able to offer accommodation options that are not listed online.
1. **Communicate the information**: Clearly communicate the options and the information of the accommodation to the participants, providing them with detailed information including contact information, location, and instructions on how to book.
1. **Distance**: Keep in mind that accommodation options may be farther away from the workshop location in a less populated area. Be sure to provide transportation information and options to help participants get to and from the workshop.
1. **Offer options**: Offer a variety of accommodation options to accommodate different preferences and budgets.
### Announcing the event
When announcing the event, it is important to include the following information:
@ -184,6 +265,8 @@ Make sure participants are well informed and can find their way to you by sendin
### Documenting the event
Documenting a PlanktoScope workshop through photography is essential for several reasons. Photos can be used to showcase the workshop activities and the learning process of the participants. This can be useful for sharing information about the workshop with others, and for promoting future workshops.
1. **Equipment**: Make sure you have the necessary equipment to document the event, including a camera (DSLR or mirrorless camera), lenses, memory cards, and batteries.
2. **Backup**: Always make sure to have a backup plan for your equipment and photos, such as bringing extra memory cards and batteries.
3. **Lighting**: Take into account the lighting conditions and make sure to have the right settings for your camera to capture the best possible images.
@ -207,116 +290,6 @@ Follow-up activities are an essential part of the workshop planning process. The
4. **Continual learning**: Provide additional training opportunities or resources for participants to continue their learning after the workshop. This could be through follow-up workshops, webinars, or online tutorials.
5. **Track progress**: Keep track of the progress of the participants, check if they are applying what they learned during the workshop and give feedback to help them improve.
## Event types
### Build workshop
Organizing a build workshop can be a challenging but rewarding experience. It requires careful planning and execution to ensure that the workshop is successful. This trainer manual is designed to guide you through the process of organizing a build workshop.
#### Selecting the production site
Choosing the right production site for preparing and manufacturing the PlanktoScope Kits is an important step in the workshop planning process. The production site should have the necessary tools and equipment, as well as the knowledge and expertise to manufacture the PlanktoScope Kits. Here are a few things to consider when choosing a production site:
1. **Check the Manufacturing and Assembly Guides**: Before choosing a production site, make sure to review the PlanktoScope [Manufacturing Guide](/hardware/manufacturing/) and the [Assembly Guide](/hardware/assembly_guide/). These guides will provide detailed information on the necessary tools and equipment required for the production of the PlanktoScope Kits.
1. **Visit [Fablab](https://fablabs.io/labs) and [Hackspaces](https://wiki.hackerspaces.org/List_of_Hacker_Spaces)**: Consider visiting Fablabs or Hackspaces in your region. These organizations often have a culture of openness and may be willing to support you with your project. They may have the necessary tools and equipment to produce the PlanktoScope Kits, as well as the knowledge and expertise to guide you through the production process.
1. **Commercial Manufacturing**: Look for a facility that has the capability to handle small scale production runs, a good quality control process and a logistic plan to ship the product to the final destination. Many
!!! tip
For the PlanktoScope case, for example, you can look for woodworking companies. They often have a CNC machine and are familiar with the process of ditigal production.
#### Material procurement
Building a PlanktoScope requires a specific set of materials. In order to ensure that the workshop runs smoothly and that all attendees are able to successfully build their own PlanktoScope, it is important to properly plan and execute the procurement of materials. The following is a step-by-step guide on how to properly plan and execute the procurement of materials for a workshop:
1. **Prepare the order list**: Use the bill of materials (BOM) as a starting point to create a comprehensive list of all materials needed for the workshop. Expand it with additional columns for suppliers, delivery dates, prices, shipping costs, and import taxes.
2. **Plan for packaging**: Plan for extra packaging so you can assemble the parts as shown in the instructions. Try to minimize plastic as much as possible.
3. **Research suppliers**: Research suppliers and see if there are local options, if you can consolidate orders to save costs and ensure timely delivery.
4. **Compare prices**: Compare the prices of different suppliers to minimize the total cost.
5. **Plan for spare parts**: Plan for spare parts in case something is broken or lost.
6. **Check your Budget**: Check your budget and ensure that you have enough funds to cover the cost of all materials, shipping, and any additional expenses before placing your orders.
7. **Place orders**: Once you have identified the best suppliers, place orders for all of the materials that you need. Be sure to factor in lead time when placing orders to ensure that the materials will arrive in time for the workshop.
8. **Track orders**: Keep track of your orders and expected delivery dates, mark a component when it arrives. Contact suppliers if there are any delays or problems with delivery.
9. **Communicate**: Communicate with participants if there are issues with timely delivery. It may make sense to postpone the workshop if there is not enough time to prepare and test everything. The participants will be grateful and will understand if it helps to ensure that everything runs smoothly.
By following this process, you can ensure that all materials are procured and organized well in advance of the workshop, to avoid any last-minute delays or complications.
!!! note
If you have difficulty finding the components you need, [contact us](https://planktoscope.slack.com/) and we will be happy to help you find the right alternative.
!!! warning
Have a backup plan and be prepared for unexpected events that may occur during the procurement process. Allow two months for delivery, as some specialty parts may travel a long way and require additional time for customs inspection.
!!! tip
Let us know your results, we would love to hear what solutions you found and how cost effective you were able to make the PlanktoScope.
#### Prepare the Kit
Kit preparation for the workshop is an important step in the preparation process. This ensures that participants have the materials and equipment they need to complete the workshop and build their own PlanktoScope. Here are a few things to keep in mind when preparing the kits:
1. **Review the Bill of Materials (BOM)**: Review the Bill of Materials (BOM) for the PlanktoScope to ensure that you have all the necessary parts and materials for the workshop. The parts list can be found in the [Assembly Guide](/hardware/assembly_guide/) and lists all components and quantities needed to build a microscope.
2. **Divide the kit components according to the BOM**: Once the materials have been received, divide the kit components from the orders according to the Bill of Materials (BOM) of the PlanktoScope. This will ensure that each participant receives the correct components and that there are no missing parts.
3. **Have extra components**: Have extra components on hand in case of any missing or damaged parts during the workshop.
4. **Package the kits**: Package the kits in a way that makes it easy for the participants to find and use the components during the workshop.
5. **Label materials**: Label the packages as described in [Assembly Guide](/hardware/assembly_guide/) so that they are easy to find and distribute during the workshop.
6. **Preparation of the housing parts**: Prepare the housing parts by applying the surface sealant and insert the nuts to screw the housing as described in the [Manufacturing Guide](/hardware/manufacturing/#finishing).
7. **Cutting and soldering of electronic cables**: Cut and solder the electronic cables for the PlanktoScope. This will save time during the workshop and ensure that the participants have all the necessary cables to complete the assembly.
8. **Setting up the embedded development environment**: Set up the embedded development environment and flash the eeprom of the PlanktoScope hat. This will ensure that the PlanktoScope hat is ready to be used during the workshop.
9. **Download the Raspberry Pi image**: Download the Raspberry Pi image and flash it to the SD card. This will ensure that the participants have a ready to use image for the PlanktoScope.
10. **Test the kits**: Test the kits before the workshop to ensure that all components are working correctly and that the instructions are clear and easy to follow. This will help to ensure that the participants have a positive and productive experience during the workshop.
!!! tip
Identify any items that are time consuming during the workshop and not particularly important or complex to explain. These tasks can be completed in advance to save time during the workshop. This will make it easier for the participants to assemble the PlanktoScope during the workshop.
#### Conducting the workshop
<!--
- include brakes
- start on the second day
- departure
- Define the purpose
- Get to know the participants
- Use visual aids.
- Complete a check-in
- Go over the ground rules
- Share the agenda and set expectations
- Build trust with an icebreaker
- Facilitate, don’t control
- Encourage (multimedia) documentation
- Assess goal completion
- Complete check-out
- Communicate the next steps
- Paint the big picture and communicate progress
- Activate and engage
Begin by introducing the concept of open-hardware and the principles that guide its design and development.
Next, provide an overview of the hardware and software components that are commonly used in open-hardware projects, including microcontrollers, sensors, and prototyping platforms such as Arduino and Raspberry Pi.
Introduce best practices for designing and building open-hardware devices, including how to select and source components, how to test and debug hardware and software, and how to document and share your work with others.
Provide hands-on training in building a simple open-hardware device, such as a temperature sensor or a simple robotic system.
Encourage participants to share their own ideas for open-hardware projects and provide guidance and support as they work on their own projects.
Finally, discuss strategies for scaling up open-hardware projects and strategies for getting them into the hands of users and communities that can benefit from them.
- mein Idee ist mehr Hintergrundwissen zum Design zu vermitteln
-->
### Field trip
Are you an expert in organizing field trips? Share your skills with the PlanktoScope community by documenting the process! By documenting how you organize a field trip, you can help others create successful events and bring more event options to the PlanktoScope community. Your documentation will be a valuable resource for anyone looking to plan a field trip, and it will also help to grow and strengthen the PlanktoScope community. Don't miss this opportunity to contribute to the community, start documenting your process today!
### Hackathon
Are you a master at organizing Hackathons? Share your knowledge with the PlanktoScope community by documenting the process! By documenting how you organize a Hackathon, you can help others create successful events and bring more event options to the PlanktoScope community. Your documentation will be a valuable resource for anyone looking to host a Hackathon, and it will also help to grow and strengthen the PlanktoScope community. Don't miss this opportunity to contribute to the community, start documenting your process today!
## Improve this training program
As with any training program, there is always room for improvement. To ensure that this program continues to meet the needs of its attendees, it is important to actively seek feedback and make changes as necessary.

9
docs/contribute/github_workflow.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Contributing
First of all, thank you for contributing to the PlanktoScope! The goal of this document is to provide everything you need to know in order to contribute to PlanktoScope.
@ -41,6 +37,7 @@ This repository is also a good way to get involved. Please fill in an issue if y
In order to use the different tools on this repository, you will first need to:
```sh
```
### Tests and Linter <!-- omit in toc -->
@ -114,5 +111,5 @@ Every PR that is merged to `master` triggers the automated release process, as s
Thank you again for reading this through, we can not wait to begin to work with you if you made your way through this contributing guide ❤️
- pdfimages -all protocols/PlanktoScope\ -\ Setup\ and\ Sampling\ Guide\ VER3.pdf protocols/dumps/PlanktoScope_Setup_and_Sampling_Guide_VER3
sudo apt-get install pandoc texlive-latex-base texlive-fonts-recommended texlive-extra-utils texlive-latex-extra
sudo apt install poppler-utils
sudo apt-get install pandoc texlive-latex-base texlive-fonts-recommended texlive-extra-utils texlive-latex-extra
sudo apt install poppler-utils

6
docs/contribute/software_development.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# How to help development for the PlanktoScope code
We are using the [Github Flow approach](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests) for our development efforts.
@ -32,7 +28,7 @@ By following these steps, you will be able to set up a Node-RED development envi
## Python
![python](../images/logos/python.svg){ width="200" }
![python](../images/logos/python.svg){ width="200" }
The python code is separated in four main processes, each with a specific set of responsibilities:

4
docs/contribute/writing_documentation.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Writing Documentation
The source files are in the main [github repository](https://www.github.com/PlanktonPlanet/PlanktoScope), in the `docs` folder.

4
docs/hardware/accessories.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Plankton Net
A plankton net is a scientific tool used to collect plankton samples from aquatic environments. Plankton are small, drifting organisms that play a vital role in marine ecosystems. They include a diverse range of species, including bacteria, algae, protozoa, and small animals such as crustaceans and mollusks. Plankton nets are designed to capture these tiny organisms as they drift through the water column.

4
docs/hardware/assembly_guide.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Assembly guide of the PlanktoScope
## Content of the Kit

4
docs/hardware/hat_hardware.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# PlanktoScope Hat Hardware
![planktoscope_hero](./images/../../images/hardware/planktoscope_hat_front.png)

10
docs/hardware/manufacturing.md
View File

@ -111,11 +111,11 @@ There are two main types of electronic components that can be mounted onto a PCB
### Manufacturing files
| Files | Description |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [Planktoscope-Hat-bom.csv](https://code.curious.bio/curious.bio/planktoscope/raw/branch/din_spec_3105_1/hardware/hat/Planktoscope-Hat-bom.csv) | The list of used SMD components |
| [Planktoscope-Hat-gerber.zip](https://code.curious.bio/curious.bio/planktoscope/raw/branch/din_spec_3105_1/hardware/hat/Planktoscope-Hat-gerber.zip) | The exported CAD and CAM data of the PCB design |
| [Planktoscope-Hat-assembly.zip](https://code.curious.bio/curious.bio/planktoscope/raw/branch/din_spec_3105_1/hardware/hat/Planktoscope-Hat-assembly.zip) | The SMD assembly instructions |
| Files | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [Planktoscope-Hat-bom.csv](https://code.curious.bio/curious.bio/planktoscope/raw/branch/din_spec_3105_1/hardware/hat/Planktoscope-Hat-bom.csv) | The list of used SMD components |
| [Planktoscope-Hat gerber files](https://code.curious.bio/curious.bio/planktoscope/src/branch/din_spec_3105_1/hardware/hat/assembly) | The exported CAD and CAM data of the PCB design |
| [Planktoscope-Hat assembly files](https://code.curious.bio/curious.bio/planktoscope/src/branch/din_spec_3105_1/hardware/hat/assembly) | The SMD assembly instructions |
### PCB manufacturing process

4
docs/license.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Our work is fully open source
That's the headline, yes.

12
docs/software/create_sd.md
View File

@ -1,13 +1,9 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# 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!
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.
@ -81,8 +77,8 @@ Notably, do not forget to edit/remove the following files:
- `mnt/home/pi/.gitconfig`: git config
!!! info
If you want to distribute the image you created, you need to start the service that will recreate the host ssh keys on startup:
`sudo ln -s /lib/systemd/system/regenerate_ssh_host_keys.service etc/systemd/system/multi-user.target.wants/regenerate_ssh_host_keys.service`
If you want to distribute the image you created, you need to start the service that will recreate the host ssh keys on startup:
`sudo ln -s /lib/systemd/system/regenerate_ssh_host_keys.service etc/systemd/system/multi-user.target.wants/regenerate_ssh_host_keys.service`
Once your cleanup is done, unmount the image with `sudo umount mnt`.
@ -104,6 +100,6 @@ sudo ./pishrink.sh -z -a planktoscopeimage.img
The flags `-z -a` are used to compress the image to a gz file using the multithread version of gzip (pigz).
!!! info
If you want to distribute the image you created, you should use the flag `-p` with PiShrink to remove logs, apt archives, ssh hosts keys and similar things.
If you want to distribute the image you created, you should use the flag `-p` with PiShrink to remove logs, apt archives, ssh hosts keys and similar things.
You now have a compressed image that should be between 10 and 100 times smaller than the one you started with. You can distribute it (don't forget to do the steps above first), archive it, do whatever you please with it!

4
docs/software/easy_install.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# PlanktoScope Simple Setup Guide
## Download the image

20
docs/software/expert_setup.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Expert Setup
## Install and setup Raspbian on your Raspberry Pi
@ -96,20 +92,20 @@ Last steps we need to do is to increase the amount of memory available to the GP
Also, to be able to use the ISO8601 datetime standard, we need to change the locale in use. Choose `5 Localisations Options`, then `L1 Locale` and press space after selecting the `en_DK.UTF8`. Press Enter and then select the en_DK locale as default for your system.
!!!info
The en_DK is a hack where month and day names are in English, but date and time format uses the ISO8601 format. See <https://serverfault.com/questions/17118/how-do-i-set-the-date-format-to-iso-globally-in-linux>
The en_DK is a hack where month and day names are in English, but date and time format uses the ISO8601 format. See <https://serverfault.com/questions/17118/how-do-i-set-the-date-format-to-iso-globally-in-linux>
These steps can also be done from the Raspberry Pi Configuration GUI tool that you can find in `Main Menu > Preferences`. Go to the `Interfaces` tab. Pay attention, here the Serial Port must be enabled, but the Serial Port Console must be disabled.
!!! tip
Optional step: overclocking
It's possible to overclock the machine and get a bit more performance out of it. Open `/boot/config.txt` with `sudo nano /boot/config.txt` and add at the end of the file on two new lines:
Optional step: overclocking
It's possible to overclock the machine and get a bit more performance out of it. Open `/boot/config.txt` with `sudo nano /boot/config.txt` and add at the end of the file on two new lines:
```txt
over_voltage=6
arm_freq=2000
```
```txt
over_voltage=6
arm_freq=2000
```
Those settings were verified to be stable, but if you notice any weird behavior under a high load, remove those lines.
Those settings were verified to be stable, but if you notice any weird behavior under a high load, remove those lines.
Reboot your Pi safely.

4
docs/software/update_devicetree.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Using a flash with the camera
The Pi's camera module includes an LED flash driver which can be used to illuminate a scene upon capture. The flash driver has two configurable GPIO pins:

10
docs/usage/getting_started.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Getting started with using the machine
Congratulations! You have [finished assembling](../hardware/assembly_guide.md) your machine, now is the time to test it and learn how to use it!
@ -16,7 +12,7 @@ As you can see, its name will be similar to `PlanktoScope-Baba*****_*****`. This
Once connected, you will not have acces to the Internet, only to the PlanktoScope interface. You can access the page at [http://planktoscope.local:1880/ui](http://planktoscope.local:1880/ui) from your favorite web browser.
!!! tip
You are able to configure your machine to connect to another network if you want in the [Wifi settings page](ui_guide.md#wifi). If you do this, your machine will be accessible to anybody connected to this network. Please keep in mind your organisation security policies before doing this.
You are able to configure your machine to connect to another network if you want in the [Wifi settings page](ui_guide.md#wifi). If you do this, your machine will be accessible to anybody connected to this network. Please keep in mind your organisation security policies before doing this.
From there, you can have a look at the [UI guide](ui_guide.md) to get a handle on how it works.
@ -29,6 +25,6 @@ However, if you have access to a body of water (even a tiny lake or river is eno
You can then do an acquisition run. **This is the best way to learn about the machine and this process!**
!!! warning
After doing an acquisition, the machine should be cleaned, especially in the fluidic part. One good way to do this is to first flush the machine with clear water (distilled if possible). You can then push through a 5-10% bleach solution, or some alcohol.
After doing an acquisition, the machine should be cleaned, especially in the fluidic part. One good way to do this is to first flush the machine with clear water (distilled if possible). You can then push through a 5-10% bleach solution, or some alcohol.
If needed you can also clean the outside of the objective lens with a soft cloth. You can do the same on the flow cell if there are traces of finger on it too.
If needed you can also clean the outside of the objective lens with a soft cloth. You can do the same on the flow cell if there are traces of finger on it too.

40
docs/usage/mqtt_messages.md
View File

@ -1,24 +1,22 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Details about used MQTT messages
## Topic lists
- [`actuator`](#actuator)
- [`actuator/pump`](#actuatorpump)
- [`actuator/focus`](#actuatorfocus)
- [`imager/image`](#imagerimage)
- [`segmenter/segment`](#segmentersegment)
- [`status`](#status)
- [`status/pump`](#statuspump)
- [`status/focus`](#statusfocus)
- [`status/imager`](#statusimager)
- [`status/segmenter`](#statussegmenter)
- [`status/segmenter/name`](#statussegmentername)
- [`status/segmenter/object_id`](#statussegmenterobject_id)
- [`status/segmenter/metric`](#statussegmentermetric)
- [Details about used MQTT messages](#details-about-used-mqtt-messages)
- [Topic lists](#topic-lists)
- [Topic details](#topic-details)
- [`actuator`](#actuator)
- [`actuator/pump`](#actuatorpump)
- [`actuator/focus`](#actuatorfocus)
- [`imager/image`](#imagerimage)
- [`segmenter/segment`](#segmentersegment)
- [`status`](#status)
- [`status/pump`](#statuspump)
- [`status/focus`](#statusfocus)
- [`status/imager`](#statusimager)
- [`status/segmenter`](#statussegmenter)
- [`status/segmenter/object_id`](#statussegmenterobject_id)
- [`status/segmenter/metric`](#statussegmentermetric)
## Topic details
@ -103,12 +101,12 @@ A camera settings message can also be received here. The fields `iso`, `shutter_
```json
{
"action": "settings",
"settings":{
"settings": {
"iso": 100,
"shutter_speed": 40,
"white_balance_gain": {"red": 100, "blue": 100},
"white_balance_gain": { "red": 100, "blue": 100 },
"white_balance": "auto",
"image_gain": {"analog": 100, "digital": 100}
"image_gain": { "analog": 100, "digital": 100 }
}
}
```
@ -204,7 +202,7 @@ Status of the segmentation. It's a JSON object with:
```json
{
"status": "Started",
"status": "Started"
}
```

20
docs/usage/remote_access.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Remote access via a standalone network
This tutorial is adapted from a tutorial that you can find [here](https://www.raspberryconnect.com/projects/65-raspberrypi-hotspot-accesspoints/157-raspberry-pi-auto-wifi-hotspot-switch-internet).
@ -202,17 +198,17 @@ If no wifi signal is found for a known SSID then the script will shutdown the wi
The script works with SSID's that contain spaces and by entering your routers MAC address it can be used with hidden SSID's.
!!! info
Hidden SSIDs
Hidden SSIDs
If your routers SSID is not broadcast/hidden then find this section in the script
If your routers SSID is not broadcast/hidden then find this section in the script
```txt
#Enter the Routers Mac Addresses for hidden SSIDs, seperated by spaces ie
#( '11:22:33:44:55:66' 'aa:bb:cc:dd:ee:ff' )
mac=()
```
```txt
#Enter the Routers Mac Addresses for hidden SSIDs, seperated by spaces ie
#( '11:22:33:44:55:66' 'aa:bb:cc:dd:ee:ff' )
mac=()
```
and enter you routers MAC address in the brackets of mac=() as shown in the example. Make sure mutiple MAC addresses are seperated by a space.
and enter you routers MAC address in the brackets of mac=() as shown in the example. Make sure mutiple MAC addresses are seperated by a space.
Create a new file with the command `sudo nano /usr/bin/autohotspotN` and add the following:

32
docs/usage/ui_guide.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# User interface guide
Starting with the [release of v2.2](https://github.com/PlanktoScope/PlanktoScope/releases/tag/v2.2), a new user interface brings a whole new user interface. This guide will help you get familiar with it.
@ -14,22 +10,22 @@ As you can see above, when you first connect with your planktoscope at [http://p
From here, you can quickly access any of the available tabs. The buttons are only the most used functionnalities of the machine. Three others tabs are accessible only through the hamburger menu on the top left of the screen (the three horizontal lines):
* Wifi
* Administration
* Hardware Config
- Wifi
- Administration
- Hardware Config
![Tab List](../images/ui_guide/tab_list.webp)
!!! tip
This list is also available from any other tab and allows you to quickly navigate between tabs.
This list is also available from any other tab and allows you to quickly navigate between tabs.
## Machine shutdown
From this page, you can also shutdown the machine when you are done.
!!! warning
It's **very very very important** to **always** shutdown the machine and wait a minute for it to completely shutdown before unplugging the power supply!
**You risk data corruption is you savagely shutdown your machine!**
It's **very very very important** to **always** shutdown the machine and wait a minute for it to completely shutdown before unplugging the power supply!
**You risk data corruption is you savagely shutdown your machine!**
To shutdown the machine, first unlock the shutdown button by clicking on "Unlock Button".
@ -68,7 +64,7 @@ This page allows you to control the optical setup of the acquisition.
In the Optic Characterization block, you can control to turn the light on or not. You also have to choose the optics in use in the machine.
!!! warning
For now, the characteristics shown here are not true values (except if you use the 25mm/16mm lens couple).
For now, the characteristics shown here are not true values (except if you use the 25mm/16mm lens couple).
The Camera Settings block allows you to change the shutter speed, the ISO number and the camera white balance settings. You can set it to automatic, but it's better if you control it by hand to make sure the setting doesn't change when the acquisition is started.
@ -87,7 +83,7 @@ Finally, this is where the magic happens! You will be able to chose the final pa
First of all, change the Fraction Size of your sample. You can then choose a unique ID for your acquisition, the number of pictures you want to take, the pumped volume (in between images), the delay to stabilize the image and the Flowcell thickness. All those settings will influence the Total imaged volume (the total volume captured during the acquisition) and the Total pumped volume.
!!! warning
Make sure the Total pumped volume is lower than the volume of your sample.
Make sure the Total pumped volume is lower than the volume of your sample.
## Gallery
@ -108,16 +104,16 @@ You also can find information about the software version you are using, the mach
Using the USB Backup block, you can backup the data from the machine to a connected USB device.
!!! info
Use one of the center USB ports on the machine, since those are USB3.0. They can be recognized by the blue insert in the middle of the connector. Those ports are faster.
Use one of the center USB ports on the machine, since those are USB3.0. They can be recognized by the blue insert in the middle of the connector. Those ports are faster.
After you connected your drive, click on "Detect Drive" to make it appear in the list. You can then choose "Backup to USB" to launch the copy. Wait until a completion message is displayed.
Before purging the local data, make sure your data has been backed up at least twice!
!!! warning
It's very warmly recommended to use the 3-2-1 backup strategy. 3 copies on 2 devices with at least 1 offsite.
For this machine, this means creating two copies on two different USB drives of the data before purging it from the device.
Also, you should backup your device after each acquisition.
It's very warmly recommended to use the 3-2-1 backup strategy. 3 copies on 2 devices with at least 1 offsite.
For this machine, this means creating two copies on two different USB drives of the data before purging it from the device.
Also, you should backup your device after each acquisition.
## Wifi
@ -132,10 +128,10 @@ Finally, if you are not located in France, please update the Country code in the
Clicking on the button `Reset wifi networks` will erase ALL networks saved previously by the machine. If you do this, it will disconnect immediately from any network it's connected to, and will put up its own network.
!!! info
For now, only WPA/WPA2 Personnal security system is supported. If you need another security system supported, get in touch with us.
For now, only WPA/WPA2 Personnal security system is supported. If you need another security system supported, get in touch with us.
!!! warning
Please be mindful about the security policies of your organisation before connecting your device to a network (either through Wifi or with an Ethernet cable). A lot of research institutions don't allow devices not controlled by them to be connected to their network without first going on an approved list with a least a basic security checkup.
Please be mindful about the security policies of your organisation before connecting your device to a network (either through Wifi or with an Ethernet cable). A lot of research institutions don't allow devices not controlled by them to be connected to their network without first going on an approved list with a least a basic security checkup.
## Administration

1
flake.nix
View File

@ -1,4 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
{
description = "Nix PlanktoScope";
inputs = {

2
mkdocs.yml
View File

@ -1,6 +1,4 @@
---
# SPDX-License-Identifier: CC-BY-SA-4.0
site_name: PlanktoScope
site_description: An open and affordable imaging platform for \
citizen oceanography

11
software/planktoscope-backend/README.md
View File

@ -1,18 +1,15 @@
<!--
SPDX-License-Identifier: GPL-3.0-or-later
-->
# planktoscope-backend
[![PyPI - Version](https://img.shields.io/pypi/v/planktoscope-backend.svg)](https://pypi.org/project/planktoscope-backend)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/planktoscope-backend.svg)](https://pypi.org/project/planktoscope-backend)
-----
---
**Table of Contents**
- [Installation](#installation)
- [License](#license)
- [planktoscope-backend](#planktoscope-backend)
- [Installation](#installation)
- [License](#license)
## Installation

2
software/planktoscope-backend/requirements.txt
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
RPi.GPIO~=0.7.1a4
Adafruit-Blinka~=6.15.0
adafruit-circuitpython-motorkit~=1.6.3

2
software/planktoscope-backend/src/planktoscope_backend/_version.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# coding: utf-8
# file generated by setuptools_scm
# don't change, don't track in version control

2
software/planktoscope-backend/src/planktoscope_backend/display.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Logger library compatible with multiprocessing
from loguru import logger

2
software/planktoscope-backend/src/planktoscope_backend/imager/__init__.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
################################################################################
# Practical Libraries
################################################################################

2
software/planktoscope-backend/src/planktoscope_backend/imager/raspimjpeg.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
################################################################################
# Practical Libraries
################################################################################

2
software/planktoscope-backend/src/planktoscope_backend/imager/state_machine.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Logger library compatible with multiprocessing
from loguru import logger

2
software/planktoscope-backend/src/planktoscope_backend/imager/streamer.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
from loguru import logger
import time

2
software/planktoscope-backend/src/planktoscope_backend/integrity.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# This module calculates the checksum of created files and add them to and file called integrity.check
# The file is composed as follows:
# First, a header that starts by like so:

2
software/planktoscope-backend/src/planktoscope_backend/light.py
View File

@ -1,7 +1,5 @@
#!/usr/bin/env python
# SPDX-License-Identifier: GPL-3.0-or-later
# Turn on using this command line :
# python3.7 path/to/file/light.py on

2
software/planktoscope-backend/src/planktoscope_backend/main.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Logger library compatible with multiprocessing
from loguru import logger
import sys

4
software/planktoscope-backend/src/planktoscope_backend/module.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
################################################################################
# Practical Libraries
################################################################################
@ -95,4 +93,4 @@ class ModuleProcess(multiprocessing.Process):
# This is called if this script is launched directly
if __name__ == "__main__":
# This should be tests of your module
pass
pass

2
software/planktoscope-backend/src/planktoscope_backend/mqtt.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Library for exchaning messages with Node-RED
# We are using MQTT V3.1.1
# The documentation for Paho can be found here:

2
software/planktoscope-backend/src/planktoscope_backend/segmenter/__init__.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
################################################################################
# Practical Libraries
################################################################################

2
software/planktoscope-backend/src/planktoscope_backend/segmenter/ecotaxa.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Logger library compatible with multiprocessing
from loguru import logger

2
software/planktoscope-backend/src/planktoscope_backend/segmenter/encoder.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
import json
import numpy as np

2
software/planktoscope-backend/src/planktoscope_backend/segmenter/operations.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Logger library compatible with multiprocessing
from loguru import logger

2
software/planktoscope-backend/src/planktoscope_backend/segmenter/streamer.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
from loguru import logger
import time

2
software/planktoscope-backend/src/planktoscope_backend/stepper.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Libraries to control the steppers for focusing and pumping
import adafruit_motor.stepper
import adafruit_motorkit

2
software/planktoscope-backend/src/planktoscope_backend/uuidName.py
View File

@ -1,5 +1,3 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Very inspired by https://github.com/bgawalt/uuidBabyName
import re, uuid, random, os

4
software/planktoscope-frontend/flows/README.md
View File

@ -1,5 +1 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
The files present here are Node-RED flows easily shared via this `json` format.

4
software/scripts/README.md
View File

@ -1,7 +1,3 @@
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# Python scripts of the PlanktoScope
This directory contains the various scripts needed for the PlanktoScope to run properly.

4
software/scripts/bash/start_update.sh
View File

@ -1,7 +1,5 @@
#!/bin/bash
# SPDX-License-Identifier: GPL-3.0-or-later
log="echo -e"
CURRENT_BRANCH=$(git --git-dir=/home/pi/PlanktoScope/.git rev-parse --abbrev-ref HEAD)
@ -18,4 +16,4 @@ fi
${log} "Updating the installer script from $BRANCH"
curl "https://raw.githubusercontent.com/PlanktonPlanet/PlanktoScope/$BRANCH/scripts/bash/update.sh" > /tmp/update.sh
chmod +x /tmp/update.sh
exec /tmp/update.sh "$BRANCH"
exec /tmp/update.sh "$BRANCH"

4
software/scripts/bash/update.sh
View File

@ -1,7 +1,5 @@
#!/bin/bash
# SPDX-License-Identifier: GPL-3.0-or-later
log="echo -e"
CURRENT_BRANCH=$(git --git-dir=/home/pi/PlanktoScope/.git rev-parse --abbrev-ref HEAD)
@ -69,4 +67,4 @@ else
${log} "Update is complete, let's restart now."
restart &>> /home/pi/update.log
fi
${log} "Update done!"
${log} "Update done!"

6
software/scripts/bash/usb_backup.sh
View File

@ -1,9 +1,5 @@
#!/bin/bash
# SPDX-License-Identifier: GPL-3.0-or-later
# Stolen from https://github.com/raamsri/automount-usb/blob/master/usb-mount.sh
# This work is licensed under the Unlicense
# This script is based on https://serverfault.com/a/767079 posted
@ -77,7 +73,7 @@ do_mount()
exit 3
else
# Track the mounted drives
echo "${MOUNT_POINT}:${DEVBASE}" | cat >> "/var/log/usb-mount.track"
echo "${MOUNT_POINT}:${DEVBASE}" | cat >> "/var/log/usb-mount.track"
fi
${log} "Mounted ${DEVICE} at ${MOUNT_POINT}"

4
software/scripts/raspimjpeg/macros/error_hard.sh
View File

@ -1,9 +1,7 @@
#!/bin/bash
# SPDX-License-Identifier: GPL-3.0-or-later
sudo killall -15 python3
sudo killall -15 raspimjpeg
sleep 10
sudo killall -9 python3
sudo killall -9 raspimjpeg
sudo killall -9 raspimjpeg