diff --git a/docs/assets/PlanktoscopeHat-v0.2-fab.pdf b/docs/assets/PlanktoscopeHat-v0.2-fab.pdf new file mode 100644 index 0000000..1eca4a8 Binary files /dev/null and b/docs/assets/PlanktoscopeHat-v0.2-fab.pdf differ diff --git a/docs/community/code_of_conduct.md b/docs/community/code_of_conduct.md new file mode 100644 index 0000000..45d257b --- /dev/null +++ b/docs/community/code_of_conduct.md @@ -0,0 +1,133 @@ + +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[INSERT CONTACT METHOD]. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/docs/community/community.md b/docs/community/community.md new file mode 100644 index 0000000..abe4d1c --- /dev/null +++ b/docs/community/community.md @@ -0,0 +1,93 @@ +# Getting in touch with the community + +[planktoscope.com/community/](http://planktoscope.com/community/) + +Thank you! You represent the heart of PlanktoScope. Without your support and belief in the PlanktoScope mission, we wouldn't be where we are today. + +The **PlanktoScope Community** interface is our latest project. It consists of: + +- [The People](http://planktoscope.com/community/people/) - you! The people making posts and creating challenges +- [The Feed](http://planktoscope.com/community/) - where new community posts end up +- [Join](http://planktoscope.com/community/wp-login.php?action=register) - the way to register (send this to your friends)! + +After you [register](http://planktoscope.com/community/wp-login.php?action=register) and are verified (we must approve your application), your account will be switched from **subscriber** to **contributor**. After this, you'll be able to create posts and challenges! Posts appear in the [Community Feed](http://planktoscope.com/community/), and challenges appear on the Challenges Page. More on this below. + +## Editing Your Profile + +Upon registering, you should have received an email with your Login/Password. If you did not, reach out to me and I’ll help you recover it. To edit your profile: + +1. Go to the [PlanktoScope Wordpress login](http://planktoscope.com/community/wp-login.php) & enter your Login/Password + +- Navigate to “Profile” on the left-hand side of the admin page +- Add any missing information +- Click the “Save” button to confirm + +**Note**: your profile will not appear on the People Page until you have a first name, last name, and photo. All other info is optional (but encouraged)! + +If your profile is still not showing up on the People Page, reach out to [contact@planktoscope.com.](mailto:contact@planktoscope.com.) We’ll make sure your profile is active and set up as a contributor. + +## Making Posts + +Making a post is a great way to share a cool project, tutorial, or research study that you’ve completed. In general, a post should be something finished (a hack, a lesson, a research study with findings, etc.). + +Our community page is based on the Wordpress platform. If you’ve used Wordpress before, you’ll feel right at home. If not, no worries—it’s easy! Log in the same way you would to edit your profile. When you log in, the Wordpress admin page should appear with an option to see the Posts section. Click on it and select Add New from the menu. Next, follow [this great tutorial](https://www.wpbeginner.com/beginners-guide/how-to-add-a-new-post-in-wordpress-and-utilize-all-the-features/) on how to write a Wordpress post. You are now ready to start sharing your work! + +## On The Horizon + +The PlanktoScope Community interface will be forever under development. We really want your feedback! If you have suggestions, please email [planktoscope@gmail.com](mailto:planktoscope@gmail.com). + +As we move forward, we want to improve the level of interactivity between community members and also provide incentives for posting cool projects and challenges. + +In addition, we are thinking about ways to enable you to request and share biodata with other members of the PlanktoScope Community. Of course the priority will always be that all data exchanged in this way belongs to the individual who generates the data (first and foremost) and will remain open for others access. + +## Final Note + +The PlanktoScope Community is only as strong as its members. We are calling upon you (!) to help us push the PlanktoScope mission forward by collaborating with each other and going the extra step to share the work that you do. The more we all contribute and collaborate, the more the community benefits as a whole! **Let's see what we can build together!** + +## Github + + + +## Mailinglist + + + +## Slack + + + +## Sharing photos + +Please create pages here and show off your favourite micrographs, build pictures, and so on. The more information you add, the better - we'd love to know how you prepared your samples, what configuration of microscope you have, and whether you're happy with your images being reused. We would suggest you add a simple notice somewhere on the page with a license and attribution - e.g. + + + +```txt +Copyright 2020 Your Name, released under CC-BY 3.0 +``` + +Submit an issue with your photos. You need a Github account. You can drag and drop images, and then fill in the copyright details. +Edit the wiki yourself. To edit the wiki you will need to be a project member. Please request access from the link at the top of the project homepage. See the editing guidelines for more details. + +## Ask a question + +If you have questions or suggestions, we would love to know! This helps us improve and document the OpenFlexure Microscope better. + +## These are the best ways to ask questions or provide feedback + +1. Check our [Frequently Asked Questions](../faq.md), and check whether someone has already [raised an issue](https://gitlab.com/openflexure/openflexure-helpdesk/) similar to yours. + +2. Raise an issue on our [Github helpdesk](https://gitlab.com/openflexure/openflexure-helpdesk/-/issues/new). + +3. Join the discussion in our [Discourse forum](https://openflexure.discourse.group). + +4. Chat with us and our community in our [Gitter](https://gitter.im/OpenFlexure-Microscope/Lobby). + +5. Tweet us [@OpenFlexure](https://twitter.com/openflexure). + +6. [Email us](mailto:contact@openflexure.org). + +## Twitter + +- @ThibautPollina +- #PlanktoScope diff --git a/docs/community/trainer.md b/docs/community/trainer.md new file mode 100644 index 0000000..cba5d92 --- /dev/null +++ b/docs/community/trainer.md @@ -0,0 +1,48 @@ +# Trainer notes + +## Organizing a Build Workshop + +### Planing the workshop + +- Definiere die Ziele des Workshops. +- Ermittle die Bedürfnisse der Workshop-Teilnehmer. +- Erstelle einen Ablauf deiner Workshop Präsentation. +- Weise jedem Eintrag auf dem Ablauf eine erwartete Dauer zu. +- Handouts für die Teilnehmer vor. +- Nutze visuelle Mittel. +- Nutze webbasierte Werkzeuge, wenn möglich. +- Richte einen Raum oder Platz ein, um Diskussionen zu fördern. +- Bringe interaktive Aktivitäten in deinen Workshop ein. +- Baue einen Frage/Antwort Teil ein. +- Get to know the participants +- Define the purpose +- Set a clear goal +- Plan for more than just a day +- Prepare for the unexpected +- Set the scene + +#### The site + +### Announcing the workshop + +- on the [community channels](/community) + +### Material procurement + +### Conduct the workshop + +- 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 + +### Follow-up + +Ask for feedback diff --git a/docs/contribute/development_workflow.md b/docs/contribute/development_workflow.md new file mode 100644 index 0000000..3233fc9 --- /dev/null +++ b/docs/contribute/development_workflow.md @@ -0,0 +1,118 @@ + + +# 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. + +There are several ways to join the development effort, share your progress with your build or just ask for help. + +We are using slack as a communication platform between interested parties. You can [request to join by filling this form](https://docs.google.com/forms/d/e/1FAIpQLSfcod-avpzWVmWj42_hW1v2mMSHm0DAGXHxVECFig2dnKHxGQ/viewform). + +This repository is also a good way to get involved. Please fill in an issue if you witnessed a bug in the software or hardware. If you are able, you can also join the development effort. Look through the [issues opened](https://github.com/PlanktonPlanet/PlanktoScope/labels/good%20first%20issue) and choose one that piques your interest. Let us know you want to work on it in the comments, we may even be able to guide your beginnings around the code. + +- [Contributing](#contributing) + - [Assumptions](#assumptions) + - [How to Contribute](#how-to-contribute) + - [Development Workflow](#development-workflow) + - [Git Guidelines](#git-guidelines) + - [Release Process (for internal team only)](#release-process-for-internal-team-only) + +## Assumptions + +1. **You're familiar with [git](https://git-scm.com/) and the [Merge Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)(PR) workflow.** +2. **You've read the PlanktoScope [documentation](https://planktonscope.readthedocs.io/) and the [images/readme](/images/readme.md).** +3. **You know about the PlanktoScope [community on Slack](https://planktoscope.slack.com/). Please use this for help.** + +## How to Contribute + +1. Make sure that the contribution you want to make is explained or detailed in a GitHub issue! Find an [existing issue](https://github.com/PlanktoScope/PlanktoScope/issues) or [open a new one](https://github.com/PlanktoScope/PlanktoScope/issues/new/choose). +2. Once done, [fork the PlanktoScope repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) in your Github account. Ask a mastertainer if you want your issue to be checked before making a PR. +3. [Create a new Git branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). +4. Review the [Development Workflow](#development-workflow) section that describes the steps to mastertain the repository. +5. Make the changes on your branch. +6. [Submit the branch as a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) pointing to the `master` branch of the master fabcity-os-core-chart repository. A mastertainer should comment and/or review your Pull Request within a few days. Although depending on the circumstances, it may take longer. We do not enforce a naming convention for the PRs, but **please use something descriptive of your changes**, having in mind that the title of your PR will be automatically added to the next [release changelog](https://github.com/PlanktoScope/PlanktoScope/releases). + +## Development Workflow + +### Setup + +In order to use the different tools on this repository, you will first need to: + +```sh +``` + +### Tests and Linter + +Each PR should pass the linter to be accepted. + +```sh +make lint +``` + +Each PR should also check if the generated file `manifests/fcoscore.yaml` is updated with the new modifications. +You can generated the manifest with the command line: + +```bash +helm template fcoscore . | grep -v 'helm.sh/chart:\|app.kubernetes.io/managed-by:' > manifests/PlanktoScope.yaml +``` + +Or just by comment the PR: + +```txt +@PlanktoScope sync-manifest +``` + +Additionally, the CI will run a test to check if there are changes introduced to the charts. If changes were introduced, it will require you to update the Chart version. + +## Git Guidelines + +### Git Branches + +All changes must be made in a branch and submitted as PR. +We do not enforce any branch naming style, but please use something descriptive of your changes. + +### Git Commits + +As minimal requirements, your commit message should: + +- be capitalized +- not finish by a dot or any other punctuation character (!,?) +- start with a verb so that we can read your commit message this way: "This commit will ...", where "..." is the commit message. + e.g.: "Fix the home page button" or "Add more tests for create_index method" + +We don't follow any other convention, but if you want to use one, we recommend [this one](https://chris.beams.io/posts/git-commit/). + +### Pull Requests + +Some notes on PRs: + +- [Convert your PR as a draft]() if your changes are a work in progress: no one will review it until you pass your PR as ready for review.
+ The draft PR can be very useful if you want to show that you are working on something and make your work visible. +- The branch related to the PR must be **up-to-date with `master`** before merging. Fortunately, this project [integrates a bot]() to automatically enforce this requirement without the PR author having to do it manually. +- All PRs must be reviewed and approved by at least one mastertainer. +- The PR title should be accurate and descriptive of the changes. The title of the PR will be indeed automatically added to the next [release changelogs](). + +## Release Process (for internal team only) + +PlanktoScope tools follow the [Semantic Versioning Convention](https://semver.org/). + +### Automation to Rebase and Merge the PRs + +This project integrates a bot that helps us manage pull requests merging.
+_[Read more about this]()._ + +### How to Publish the Release + +⚠️ Before doing anything, make sure you got through the guide about [Releasing an Integration](). + +⚠️ Every PR that is merged to `master` introducing changes to the PlanktoScope needs to modify the file [``](), by increasing the version of the chart accordingly. + +Every PR that is merged to `master` triggers the automated release process, as specified at [``](). A GitHub Action will be triggered and publish a new release on the GitHub repository [releases](). This will enable users to start using the new version of the chart immediately after publishing. + +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 diff --git a/docs/contribute/hardware_development.md b/docs/contribute/hardware_development.md new file mode 100644 index 0000000..edf8cc1 --- /dev/null +++ b/docs/contribute/hardware_development.md @@ -0,0 +1,11 @@ +# Hardware Development + +![planktoscope_hero](../images/project_description/planktoscope_versions.png) + +## PlanktoScope Case + +![](../images/logos/autodesk_fusion_360.png){ width="200" } + +## PlanktoScope Hat + +![](../images/logos/autodesk_eagle.png){ width="200" } diff --git a/docs/contribute/software_architecture.md b/docs/contribute/software_architecture.md new file mode 100644 index 0000000..3c6bc1b --- /dev/null +++ b/docs/contribute/software_architecture.md @@ -0,0 +1,26 @@ + + +# Our software architecture + +## Node-Red + +![](../images/logos/node-red.svg){ width="100" } + +[Node-Red](https://nodered.org/) is our main process. We use [the flow](https://nodered.org/docs/developing-flows/flow-structure) to manage our user interface through a dashboard instance. + +## Python + +![](../images/logos/python.svg){ width="200" } + +The python code is separated in four main processes, each with a specific set of responsibilities: + +- The main process controls all the others, starts everything up and cleans up on shutdown +- The stepper process manages the stepper movements. +- The imager process controls the camera and the streaming server via a state machine. +- The segmenter process manages the segmentation and its outputs. + +Those processes all communicates together using MQTT and json messages. Each message is adressed to one topic. The high level topic controls which process receives the message. The details of each topic is at the end of this commit message. You can learn more about the [MQTT Messages here](mqtt_messages). + +The code is architectured around 6 modules and about 10 classes. I encourage you to have a look at the files, they're pretty straightforward to understand. diff --git a/docs/contribute/software_development.md b/docs/contribute/software_development.md new file mode 100644 index 0000000..f43aa98 --- /dev/null +++ b/docs/contribute/software_development.md @@ -0,0 +1,13 @@ + + +# 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. + +If you want to join us, have a look at the [currently opened issues](https://github.com/PlanktonPlanet/PlanktoScope/issues) and pick one where you feel like you can have an impact. Let us know you want to work it in the comments and get started. + +For working on Node-Red, we recommend to install it directly on your development machine to allow for faster cycles of testing (and ease of use). But feel free to setup a Pi Zero as a portable and compact development environment! (One of us is using one configured as usb gadget to do so!) + +If you don't know how to code, [the documentation could use your help](edit_this_doc)! diff --git a/docs/contribute/writing_documentation.md b/docs/contribute/writing_documentation.md new file mode 100644 index 0000000..7eea7ef --- /dev/null +++ b/docs/contribute/writing_documentation.md @@ -0,0 +1,35 @@ + + +# Edit this documentation + +This documentation is hosted by [ReadTheDocs.org](https://readthedocs.org/) at . + +The source files are in the main [github repository](https://www.github.com/PlanktonPlanet/PlanktoScope), in the `docs` folder. + +They are simple [Markdown files](https://www.markdownguide.org/), that you can edit in any text editor of your choice. + +The local development and test is made using [mkdocs](https://www.mkdocs.org/). This allows you to test your documentation changes for styling issues and see what it will look like once rendered. + +```sh +hatch run docs:serve +``` + +After installing mkdocs, you can use `mkdocs serve` in the main folder of this repository to start the development server. + +If you want to include pictures and diagrams in the documentation, please set the pictures in a dedicated folder to the name of the page you are creating (for example, if your page is named `expert_setup.md`, please put all the related pictures in the `docs/expert_setup/` folder). Each picture should be named with a simple yet descriptive name, using jpg or png format if possible. Try to limit the size of the file by limiting the resolution to what is necessary for the picture to be clear on screen. + +Contributions should be made by creating pull requests on [Github directly](https://github.com/PlanktonPlanet/PlanktoScope/pulls). + +## Extensions available + +In addition to the common markdown syntax, several extensions are activated. If you want more information on any of them, please follow the linked guides. + +- [SmartyPants](https://python-markdown.github.io/extensions/smarty/): Converts ASCII dashes, quotes and ellipses to their HTML entity equivalents. +- [Sane Lists](https://python-markdown.github.io/extensions/sane_lists/): Alters the behavior of the Markdown List syntax to be less surprising. +- [Admonition](https://python-markdown.github.io/extensions/admonition/): Adds rST-style admonitions to Markdown documents. +- [Table of contents](https://python-markdown.github.io/extensions/toc/): Generates a Table of Contents from a Markdown document and adds it into the resulting HTML document. +- [Metadata](https://python-markdown.github.io/extensions/meta_data/): Adds a syntax for defining meta-data about a document. +- [Tables](https://python-markdown.github.io/extensions/tables/): Adds the ability to create tables in Markdown documents. +- [Fenced Code Blocks](https://python-markdown.github.io/extensions/fenced_code_blocks/): Adds a secondary way to define code blocks. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..6857aa9 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,37 @@ +# Frequently Asked Questions + +## What material is best to print with? What about print settings? + +This is covered in the [printing instructions](https://build.planktoscope.org/planktoscope-microscope/latest/docs/#/0_printing). Short answer: use PLA, without any support material or adhesion layer. Layers of 0.1-0.3mm should be fine, I usually use 0.24. A brim might be useful, but not for the main body - use the "smart brim" instead. + +## What's the best place to get STL files for a particular version of the microscope? + +We're working on building nice pre-packaged zip archives of each version, but this is trickier than you'd think. In the meantime, the [printing instructions](https://build.planktoscope.org/planktoscope-microscope/latest/docs/#/0_printing) has a collection of lists of the right STL files for each major version. + +## Are there nice simple instructions available for a particular version? + +At the moment, the instructions try to cover all the options. Customised instructions are a [work in progress](https://gitlab.com/planktoscope/planktoscope-microscope/-/issues/24) and if you can help, please join in on that issue thread. Currently, you can most easily find the [current instructions in the online viewer](https://build.planktoscope.org/planktoscope-microscope/latest/docs). + +## What's the magnification (or resolution, or field of view)? + +See [Resolution and Field of View](../Make%20a%20microscope/Resolution%20and%20Field%20of%20View). + +## How can I download a particular STL file? + +The STL files are automatically generated from OpenSCAD and are published [here](https://planktoscope.org/projects/microscope/build). + +## How can I print the microscope without soluble support material? + +The microscope should print fine without any support material, and often without a raft or brim. We've never used soluble support. I have tested this on quite a lot of different plastic extrusion printers (RepRap, Ultimaker, MakerBot, Retr3d, and many more) and they all worked fine. Give the test piece a try first if you are unsure, and read the [issue](https://gitlab.com/planktoscope/planktoscope-microscope/-/issues/55) if you want more details. + +## What's the best way to contact you with questions about the microscope? + +We encourage everyone to [raise an issue](https://gitlab.com/planktoscope/planktoscope-helpdesk) if you have found something confusing or need more information - it means the answer stays online so others can find it. If there's something that, for whatever reason, isn't appropriate for GitLab, contact Richard Bowman at the University of Bath (no emails here to avoid spam, but I'm quite googlable). + +## How do I know if it's printed correctly? + +This isn't documented as nicely as it could be but Richard made together some diagrams of the [quality checks](https://gitlab.com/planktoscope/planktoscope-microscope/-/blob/master/docs/original_images/microscope_body_quality_checks.pdf) he does to make sure it's printed OK. + +## You refer to bits of the microscope and I don't know which bit you mean + +There's a reference sheet on [the names of bits of the microscope](https://gitlab.com/planktoscope/planktoscope-microscope/-/blob/master/docs/original_images/microscope_body_part_names.pdf). This is for an older design, but should be useful. diff --git a/docs/funding.md b/docs/funding.md index e69de29..0b90c31 100644 --- a/docs/funding.md +++ b/docs/funding.md @@ -0,0 +1,3 @@ +# Funding + +The PlanktoScope project has been made possible by the generous support of a number of funders: diff --git a/docs/hardware/assembly_guide.md b/docs/hardware/assembly_guide.md new file mode 100644 index 0000000..cb25c50 --- /dev/null +++ b/docs/hardware/assembly_guide.md @@ -0,0 +1,342 @@ + + +# Assembly guide of the PlanktoScope + +![Complete](../images/assembly_guide/pictures/complete.webp) + +## Step 0: Gather everything you need + +- Laser cut structure +- M12 lenses +- Peristaltic pump and tubing +- Raspberry Pi, motor driver board, GPIO connectors +- Flashed SD card +- Stepper motors +- PiCam and flex cable +- GPIO ribbon connector, headers, HATs, LED +- DC Power terminal +- Magnets +- 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 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. + +Soldering deals with high heat and potentially toxic materials, so make sure to use the proper precautions. + +## Step 1: Laser cutting + +![Step1](../images/assembly_guide/pictures/step1.webp) + +Laser cut all components using the .ai file ensuring all cuts are complete. The current design should have a 5mm material thickness. Start by placing laser cut base A on a flat workspace. Make sure all holes are complete, and negative space is clear. + +!!! warning + If you are doing the laser cutting yourself, please take the time to check the calibration of the machine and its power output for the material you are using. A tight fit is needed between the different plates to avoid unwanted play between critical parts. + +## Step 2: Standoff installation + +![Step2](../images/assembly_guide/pictures/step2.webp) +![Step2 standoff location](../images/assembly_guide/render/Step2.webp) + +Place 8 standoffs (M2.5 6mm) into the designated holes on the laser-cut base A. A pair of pliers make the job more comfortable. Do not overtighten as it is possible to crack the base material. + +![Step3](../images/assembly_guide/pictures/step3.webp) + +## Step 3: Motor HAT preparation + +![Step4](../images/assembly_guide/pictures/step4.webp) + +Insert and solder the terminal blocks and headers onto the motor driver PCB. + +![Step5](../images/assembly_guide/pictures/step5.webp) + +Place the motor driver PCB on to the indicated standoffs. + +## Step 4: Magnets setup + +![Step6](../images/assembly_guide/pictures/step6.webp) + +Now is a good time to think about how the magnets will function within the microscope. The magnets in the sample stage will need to attract to the magnets on the flow cell holder. The magnets in the objective holder will need to attract the magnets on the mount. Keep this in mind as you are adding your magnets and tapping your respective M12 holders so your orientation will be correct. + +![Step8](../images/assembly_guide/pictures/step8.webp) + +You can now fix your magnets into their appropriate holes on sample stage **B**. +It is recommended to glue the magnets in place. If the magnets are too large to fit in, the holes can be widened with a handheld drill. However, they should be quite snug in place. Before you glue them in place make sure that the polarity is maintained, as they will be impossible to remove after gluing. + +## Step 5: Sample stage assembly + +![Step9](../images/assembly_guide/pictures/step9.webp) + +Don’t be alarmed by the color swap, this is the sample stage **B**. You can now fit the pegs on the driver mounts into the corresponding holes on the sample stage. They should be glued in place with superglue or epoxy. You can spin the shaft to align the driver mounts on the 2 steppers if it helps making the process easier. + +![Step10](../images/assembly_guide/pictures/step10.webp) + +You should now have a sample stage and motor assembly that looks like this. + +## Step 6: Lenses tapping and mounting + +![Step12](../images/assembly_guide/pictures/step12.webp) + +You now need to tap the holes for the M12 lenses in stage and mount **M** and **D**. It is helpful for alignment to do both the objeDtive and tube lens mount together. It is important to do this as straight as possible. A drop of mineral or olive oil can help the process. Be careful to use a right-hand tap (that goes down when turning clockwise). + +![Step13](../images/assembly_guide/pictures/step13.webp) +![Step14](../images/assembly_guide/pictures/step14.webp) + +![Step6-2](../images/assembly_guide/render/step6-2.webp) + +You can now screw the objective lens (the 25mm one) in part **D**. +![Step14](../images/assembly_guide/pictures/step15.webp) + +## Step 7: Camera preparation + +You can now unscrew the lens from the Pi camera, being careful not to disturb the sensor below. +![Image22](../images/assembly_guide/pictures/image22.webp) +![Image30](../images/assembly_guide/pictures/image30.webp) + +## Step 8: Camera mount + +![Step17](../images/assembly_guide/pictures/step17.webp) + +You can mount the camera using the appropriate holes on the camera mount **G**. Be careful to avoid getting oil or dust on the sensor. + +## Step 9: LED preparation + +![Step18](../images/assembly_guide/pictures/step18.webp) + +The LED can then be wired up and put into its mount **F**. If you wire the LED yourself, remember to give enough length to reach the motor driver on the other end of the microscope. You can also add a bit of glue to fix **F** to the motor mount **E** at this time to make assembly easier, though it is not required. + +!!! warning + ![Led](../images/assembly_guide/render/led.webp) + + This picture shows the correct wiring for the LED. Please make sure the red wire is on the long pin of the LED. + +## Step 10: Vertical slices assembly + +You can now start placing the motor mount/LED assembly- **B**, +![Step5](../images/assembly_guide/render/step5.webp) + +**C**, +![Step6](../images/assembly_guide/render/step6.webp) + +**D**, +![Step7](../images/assembly_guide/render/step7.webp) + +**E**, +![Step8](../images/assembly_guide/render/step8.webp) + +**F**, +![Step8](../images/assembly_guide/render/step9.webp) + +and **G** into the base **A**. + +## Step 11: Pump setup + +The pump can then be mounted in place on **H**. Thread the wires through the hole with the pump tubing pointed toward the holes on the mount. +![Step19](../images/assembly_guide/pictures/step19.webp) + +Fix the pump in place. +![Step20](../images/assembly_guide/pictures/step20.webp) + +## Step 12: Pump mounting + +You can now mount the pump on base **A**. +![Step15](../images/assembly_guide/render/step15.webp) + +Your setup should look like this. Don't worry about the wiring, we'll have a look at it in the next step! + +![Step21](../images/assembly_guide/pictures/step21.webp) + +## Step 13: Motor HAT wiring + +![Step22](../images/assembly_guide/pictures/step22.svg) + +You will now want to wire the steppers and pump to the terminals on the motor driver board. + +!!! info + The PlanktoScope **uses only bipolar stepper motors** (with 4 wires coming out, and two coils inside), so you need to identify the two wires working together for each coil. The [RepRap Wiki has great information](https://reprap.org/wiki/Stepper_wiring#.22pair.22_wires_on_4_wire_motors) on how to do this, either with a multimeter or without. + + You can find more information about stepper motors and how they work in this [document](http://resources.linengineering.com/acton/attachment/3791/f-00ca/1/-/-/-/-/Stepper%20Motor%20Basics.pdf). + +!!! tip + If your wires are too short, you can invert the pump and the focus wiring. However, you will have to remember to change the configuration later on. + +!!! tip + Make sure the wires are properly connected by pulling on them a little. They should not come loose. + +## Step 14: Raspberry Pi setup and installation + +![Step24](../images/assembly_guide/pictures/step24.webp) + +At this point, you can insert your flashed SD card into your Raspberry Pi. [Consult the guide for flashing your SD card](https://www.planktoscope.org/replicate/assemble-your-kit) before you do this. The heat sink can also be added to the processor. + +!!! note + If you choose the Expert path, you still need to flash your sd card, either with the [lite version](https://downloads.raspberrypi.org/raspios_lite_armhf_latest) of Raspberry OS or with the [desktop version](https://downloads.raspberrypi.org/raspios_armhf_latest). + +![Step16](../images/assembly_guide/render/step16.webp) + +Mount the Raspberry Pi containing the flashed SD card on the standoffs attached to the laser cut base A. + +## Step 15: Standoffs + +![Step17](../images/assembly_guide/render/step17.webp) + +Add 8 standoffs (M2.5 15mm) to fix the motor driver board and the Raspberry Pi to the base. + +![Step25](../images/assembly_guide/pictures/step25.webp) + +## Step 16: Camera flex cable + +![Step26](../images/assembly_guide/pictures/step26.webp) + +At this point you can use the Pi camera flex cable to connect the camera to the Pi. This is done by gently pulling up the tensioners, inserting the cable in the right orientation, then pushing 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 17: Power supply wiring + +![Step29](../images/assembly_guide/pictures/step29.webp) + +The power wires can be wired into place on the motor driver board. + +!!! tip + Make sure the wires are properly connected by pulling on them a little. They should not come loose. + +## Step 18: Prepare the GPS HAT + +![Step18-1](../images/assembly_guide/render/step18-1.webp) + +Insert the battery to power the GPS HAT and solder the terminal mounts in place. + +## Step 19: Install the GPS HAT + +![Step18](../images/assembly_guide/render/step18.webp) + +Mount the GPS HAT over the motor driver PCB using the standoffs attached to the laser cut base **A**. + +## Step 20: Install the Fan HAT + +![Step19](../images/assembly_guide/render/step19.webp) + +Place the cooling fan HAT above the Raspberry Pi by mounting it to the standoffs on base **A**. + +!!! warning + Be careful to slide the camera flat cable in the slot in the HAT above the connector. + +## Step 21: Secure the HATS + +![Step20](../images/assembly_guide/render/step20.webp) + +Secure the cooling fan HAT and GPS HAT by tightening the 8 screws to the standoffs on base A + +## Step 22: Install back panel + +![Step21](../images/assembly_guide/render/step21.webp) + +Insert the laser cut border **I** into base **A**. + +## Step 23: GPS output connector + +![Step22](../images/assembly_guide/render/step22.webp) + +Insert the power and GPS connectors into side plate **J**. + +## Step 24: Install side panel + +![Step23](../images/assembly_guide/render/step23.webp) + +Place the side plate **J** into the designated slots on the base. You can connect the GPS cable to its connector on the board. + +!!! warning + The GPS connector is quite fragile, make sure to align it properly before inserting it. + +## Step 25: Install the other side panel + +![Step25](../images/assembly_guide/render/step25.webp) + +Mount the side plate **K** on base **A** using the assigned slots. + +## Step 26: Secure the sides together + +![Step26](../images/assembly_guide/render/step26.webp) + +Secure the laser cut sides with the screws and nuts. + +## Step 27: Secure the sides to the base plate + +![Step27](../images/assembly_guide/render/step27.webp) + +Secure the laser cut sides to the base plate **A** with the screws and nuts. + +!!! warning + To make this easier, you can turn the assembly upside down or on its side. Be careful when doing so as the plates may fall. + +## Step 28: Insert the camera ribbon cable in the camera + +![Step28](../images/assembly_guide/pictures/step28.webp) + +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: 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](../images/assembly_guide/pictures/ribbon_wrong.webp) + + It should rather look like this: + ![Ribbon good](../images/assembly_guide/pictures/ribbon_good.webp) + +## Step 30: Insert the ribbon cable + +![Step28](../images/assembly_guide/render/step28.webp) + +Attach the GPIO ribbon to connect the cooling fan HAT to the GPS HAT. + +!!! tip + You can try to route the flat ribbon from the camera under the ribbon cable you are connecting now. + ![Step31](../images/assembly_guide/pictures/step31.webp) + +## Step 31: Fluidic assembly + +![Step29](../images/assembly_guide/render/step29.webp) + +Feed in the tubing from syringe 1 to form the fluidic path as shown. + +![Step30](../images/assembly_guide/render/step30.webp) + +Feed in the tubing from syringe 2 to form the fluidic path as shown + +![Step31](../images/assembly_guide/render/step31.webp) + +Feed in a length of tubing as shown through motor mount **H** and illumination mount **FE** + +![Step34](../images/assembly_guide/pictures/step34.webp) + +## 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](../images/assembly_guide/render/step33.webp) + +Place the top **L** into the slots on the PlanktoScope body. Secure it in place with screws and nuts. + +![Step34](../images/assembly_guide/render/step34.webp) + +## Step 33: Enjoy + +Congratulations on a job well done. You can have some rest, get a tea and some biscuits! + +![Step35](../images/assembly_guide/render/step35.webp) + +You can now plug the machine in and test it. If you have choose the Expert's path, now is a good time to [finish setting up your machine](../software/expert_setup.md). + +## Step 34: Read the getting started guide + +[A guide to get started with your machine use is available!](../usage/getting_started.md) diff --git a/docs/hardware/chapter_1.md b/docs/hardware/chapter_1.md new file mode 100644 index 0000000..a770634 --- /dev/null +++ b/docs/hardware/chapter_1.md @@ -0,0 +1,62 @@ +# Chapter 1 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +!!! warning + + ⚠ Be extremely careful because this is very sharp. + +## Detach the **Parts** from **panels** by cutting the **tabs** + +![Image title](https://dummyimage.com/600x400/eee/aaa){ align=left } + +### 👁 Locate the **panel S1** and discover the 5 differents **Parts F, P, K, J and I** + +### 🎬 Flip your panel S1 + +### 🔴 Locate the outer **tabs** on the edges of the different **Parts** + +### 🟠 B2. Razor blade + +!!! warning + + ⚠ Be extremely careful because this is very sharp. + +### 🟣 Use the **razor blade** to cut the outer tabs located on the edges of the different Parts + +❌ Do not cut the inner tabs present inside the different Parts for now and focus on the outer tabs attaching the Parts to the main panel. + +Position your **razor blade** on the tab as close to the piece as possible to avoid residual tab after cutting. + +Press firmly on the razor blade, being very careful with your finger, to cut your first tab. + +Make sure you don't damage your table by placing a flat, rigid support under the **S1 panel**. + +Keep going with the other tabs of this piece F. + +Once you have removed your **Part** from the main panel by cutting off all the tabs holding it, inspect it for potential residual tabs. + +🟣 Here is a **residual tab** that will need to be removed. +🟠 Here there is no **residual tab** which is perfect. + +🟣 Place your razor **blade flat** on the edge of your piece being very careful with your fingers and cut the residual tab. + +Repeat the cutting of the **tabs** on all the **Parts F, P, K, J and I** present on the **panel S1**. +⚠ Be extremely careful because this is very sharp. + +🔴 Locate the **inner tabs** on the edges of the different **Parts**. + +Cut out the **tabs** inside of all the **Parts F, P, K, J and I** detached from the **panel S1**. + +✅ Good way of cutting inner tabs +❌ Wrong way of cutting inner tabs + +Repeat the process on the **panel S2**. + +󰔞 Discover the 11 differents **Parts**. diff --git a/docs/hardware/chapter_10.md b/docs/hardware/chapter_10.md new file mode 100644 index 0000000..e883e4d --- /dev/null +++ b/docs/hardware/chapter_10.md @@ -0,0 +1,78 @@ +# Chapter 10 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Mount the **Raspberry Pi Camera HQ** on **Part B** + +🟣 Locate the 4 holes on the top of the **Part B**. + +--- + +🔵 **A2**. Standoff M2.5 - 15mm - Brass + +--- + +Insert the four **Standoff M2.5 - 15mm**. + +--- + +The result should be similar to the picture. + +--- + +🟢 **B4**. Wrenches for standoffs + +--- + +Using the small side of the **Standoff Wrench**, secure the **4 M2.5 - 15mm Standoffs** + +--- + +* ✅ Make sure to screw until the **Standoff** is properly tightened into the hole. +* ❌ Do not stop screwing before. + +--- + +󰔞 Locate the **Raspberry Pi Camera HQ** + +--- + +Remove the lens cap **Raspberry Pi Camera HQ**. + +--- + +!!! warning + + ⚠ Make sure your camera lens is clean. If it is not, gently wipe using cotton swab for this task. + +--- + +Place the **Raspberry Pi Camera HQ** on top of the four **Standoffs** installed on **Part B**. + +🟣Ensure correct orientation of the **Raspberry Pi Camera HQ**. The **black connector** where the **Ribbon Cable** was removed is on the same side as the 🟢slot circled in green + +--- + +🟠 **A4**. Screw M2.5X5mm CHC - SS + +--- + +🟡 **B3**. Allen key 2mm + +--- + +Use the allen key and tighten the **Raspberry Pi Camera** to the **Standoffs**. + +--- + +The result should be similar to the picture. + +!!! info + + 🎬 Store this assembly for later. diff --git a/docs/hardware/chapter_11.md b/docs/hardware/chapter_11.md new file mode 100644 index 0000000..2c381c8 --- /dev/null +++ b/docs/hardware/chapter_11.md @@ -0,0 +1,62 @@ +# Chapter 10 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Mount the **Linear Stepper Motor** on **Part E** + +󰔞 Locate the Stepper Motors ⚠ Avoid touching the metal rods on the Stepper Motors + +🟣 You can touch the gold stands + +--- + +🟡 **A5**. Screw **M2.5X10mm** CHC - SS + +--- + +🟡 **B3**. Allen key 2mm + +--- + +🔴 Lay the **Part E** down and make sure the pockets in these holes are +facing upwards. + +🟣 Locate the four holes on **Part E** and place four M2 Screws in the holes. + +--- + +Attach the stepper motors to the screws we have just placed with the 🔴 pockets positioned on opposite to the cabling. + +The result should be similar to the picture. + +--- + +Use the 2mm allen key to fix the **Stepper Motors**. + +The result should be similar to that picture. + +--- + +The result should be similar to the picture. + +--- + +Repeat the process on the other side with the other **Stepper Motor**. + +--- + +Repeat the process on the other side with the other Stepper Motor. + +--- + +The result should be similar to the picture. + +!!! info + + 🎬 Store this assembly for later. diff --git a/docs/hardware/chapter_2.md b/docs/hardware/chapter_2.md new file mode 100644 index 0000000..a072413 --- /dev/null +++ b/docs/hardware/chapter_2.md @@ -0,0 +1,19 @@ +# Chapter 2 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Place the 4 **Adhesive Pads** under the **Part I** + +👁 Take the Part I. +🟠 Take the four adhesive pads present in the bag A. +🟣 Locate the four pockets that will receive the four adhesive pads. + +Remove the paper and place the four adhesive pads in the pockets by pressing firmly on them, sticky-side down. + +🎬 Store this assembly for later. diff --git a/docs/hardware/chapter_3.md b/docs/hardware/chapter_3.md new file mode 100644 index 0000000..e590f49 --- /dev/null +++ b/docs/hardware/chapter_3.md @@ -0,0 +1,32 @@ +# Chapter 3 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Screw the four **Standoffs** into **Part A** + +👁 Grab the **Part A**. +🟣 Locate the **four holes** on **Part A**. + +🟢 **A1. Standoff M2.5 - 6mm**- Brass + +🟢 **B4**. Wrenches for standoffs + +🟣 Place the Standoff M2.5 - 6mm in the small side of the wrenches for +standoffs B4. + +🟠 Do not use the big side of the wrenches for standoffs since the standoff will be loose in it. + +Place the standoff in the hole and start rotating **by hand** in a clockwise direction until secure. + +Then tighten with the wrench. + +✅ Make sure to screw until the standoff is properly inserted in the hole. +❌ Do not stop screwing before. + +Keep going for each of the **four holes**. diff --git a/docs/hardware/chapter_4.md b/docs/hardware/chapter_4.md new file mode 100644 index 0000000..ab1382e --- /dev/null +++ b/docs/hardware/chapter_4.md @@ -0,0 +1,27 @@ +# Chapter 4 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Mount the **Heat Sinks** on the **Raspberry Pi** + +󰔞 Locate the **Raspberry Pi 4 Model B** packaging. + +!!! warning + + ⚠ Be careful removing it from its packaging. + +Place the **four Heat Sinks** next to your **Raspberry Pi** and mark the locations of the **Heat Sinks** on the **Raspberry Pi**. + +🟠 & 🔵 **Small Heat Sinks** +🟢 **Medium Heat Sink** +🟣 **Big Heat Sink** + +Remove the protective labels under a **Heat Sink** and place the **Heat Sink** on the slot of the **Raspberry Pi**. + +Remove the protective labels under all the **Heat Sinks** and place all the **Heat Sinks** on the slots of the **Raspberry Pi**. diff --git a/docs/hardware/chapter_5.md b/docs/hardware/chapter_5.md new file mode 100644 index 0000000..9d4e005 --- /dev/null +++ b/docs/hardware/chapter_5.md @@ -0,0 +1,22 @@ +# Chapter 5 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Insert the **micro SD card** in the **Raspberry Pi** + +* 󰔞 Locate the **SD card adapter** in the **bag K**. +* The **micro SD card** is inserted in the SD card adapter. +* 🟣 Remove the **micro SD card** from the **SD card adapter**. + +* Flip your **Raspberry Pi**. +* 🟠 Locate the **micro SD port**. +* 🟣 Insert the **micro SD card** in the **Raspberry Pi**. + +* Push the **micro SD card** in the **Raspberry Pi** port to a point of resistance. +* If you notice that the **micro SD card** protrudes about 2mm from its slot, this is normal. diff --git a/docs/hardware/chapter_6.md b/docs/hardware/chapter_6.md new file mode 100644 index 0000000..306a5d2 --- /dev/null +++ b/docs/hardware/chapter_6.md @@ -0,0 +1,25 @@ +# Chapter 6 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Mount the **Raspberry Pi** on the **Part A** + +* ✅ Make sure to position the Raspberry Pi properly on the four standoffs screwed on the Part A. +* ❌ Do not invert the position of the Raspberry Pi on the four standoffs screwed on the Part A. + +* 🟣 **A3. Standoff M2.5 - 16mm** - SS + +* Screw by hand a Standoff M2.5 - 16mm on the **Raspberry Pi**. + +* Screw by hand all Standoffs M2.5 - 16mm on the **Raspberry Pi**. +* Make sure you insert all four standoffs by hand and tighten slightly. +* 🟢 **B4**. Wrenches for standoffs + +* 🟠 Secure the Standoff M2.5 - 16 mm - SS **A3** in the big side of the wrenches for standoffs **B4**. +* 🟣 Do not use the small side of the wrenches for standoffs since the standoff won’t fit in it. diff --git a/docs/hardware/chapter_7.md b/docs/hardware/chapter_7.md new file mode 100644 index 0000000..48e6c97 --- /dev/null +++ b/docs/hardware/chapter_7.md @@ -0,0 +1,58 @@ +# Chapter 7 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Attach the **Ribbon Cable** to the **Raspberry Pi** + +󰔞 Locate the **Raspberry Pi Camera HQ** packaging. + +!!! warning + + ⚠ Be careful removing it from its packaging. + +--- + +Lay your **Raspberry Pi Camera** face down on a suitable surface. + +🔴 The **black connector** is simply a push/pull fit. To disengage the cable, pull the two corners of the black connector down, away from the camera board. It will unclip to about 3mm, make sure you don't pull it off! If you're struggling, try pulling off one corner of the connector at a time. + +!!! warning + + ⚠ Be careful with this, this part is delicate. Lift the black connector gently + +--- + +Once the connector has been disengaged from the Raspberry Pi camera board, the cable will simply slide out! + +* 🟣 Put aside Camera the Raspberry Pi +* 🟢 Keep the Ribbon Cable for next step. + +--- + +* 🔴 Locate the **black connector** present on the **Raspberry Pi**. + +--- + +🔴 The **black connector** is simply a push/pull fit. To disengage the cable, pull the two corners of the black connector down, away from the camera board. It will unclip to about 3mm, make sure you don't pull it off! If you're struggling, try pulling off one +corner of the connector at a time. + +!!! warning + + ⚠ Be careful, this part is delicate. Gently prise the black connector with nail or fingertip and thumb. + +--- + +Insert the **Ribbon Cable** you just detached from the **Raspberry Pi Camera** in the **Raspberry Pi**. + +✅ Make sure to insert in as much as you can. +🟣 Blue rectangle on **Ribbon Cable** should face the same direction as the arrow below. + +--- + +🔴 Secure the Ribbon Cable in the Raspberry Pi by pressing firmly on the black connector. diff --git a/docs/hardware/chapter_8.md b/docs/hardware/chapter_8.md new file mode 100644 index 0000000..1e4efb1 --- /dev/null +++ b/docs/hardware/chapter_8.md @@ -0,0 +1,58 @@ +# Chapter 8 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Mount the PlanktoScope HAT on the Raspberry Pi + +### Locate + +󰔞 Locate the **PlanktoScope HAT** present in **bag I**. + +### Ribbon cable + +🔴Thread the **Ribbon cable** through the **PlanktoScope HAT** slot from the +underside. + +!!! warning + + ⚠ Make sure the two 🟣black connectors are aligned before threading through the ribbon. + +### Plug + +Plug the **PlanktoScope HAT** into the **Raspberry Pi**. + +!!! warning + + ⚠ Make sure the two black connectors are aligned before attaching them together. + +### Connect + +Press the **PlanktoScope HAT** against the **Raspberry Pi** until it is no longer possible to move them closer together. + +!!! warning + + ⚠ Continue to feed through the Ribbon Cable and do not crush it while pressing the PlanktoScope HAT against the standoffs. + +--- + +🟠 **A4**. Screw **M2.5X5mm** CHC - SS + +--- + +🟣 Locate the 4 holes on the top of the **PlanktoScope HAT** and insert the four **M2.5X5mm** + +--- + +🟡 **B3**. Allen key 2mm + +--- + +Screw the four **A4** screws through the **PlanktoScope HAT** onto the **Standoff M2.5 - 16mm**. + +🎬 Store this assembly for later. diff --git a/docs/hardware/chapter_9.md b/docs/hardware/chapter_9.md new file mode 100644 index 0000000..c2af377 --- /dev/null +++ b/docs/hardware/chapter_9.md @@ -0,0 +1,30 @@ +# Chapter 9 + +## Notes + +| Topic | Description | +| --------- | ----------- | +| **Time** | | +| **Tools** | | +| **Parts** | | + +## Place the **Power Socket** on **Part M** + +󰔞 Locate the **DC Power Jack** from the **Bag K**. + +Remove the **Lock Ring** from the **DC Power Jack** + +--- + +* 🔴 Lay the **Part M** down and make sure the pockets in these holes are facing upwards. +* 🟣 Locate the **Power Socket** hole on **Part M**. + +--- + +🔴 Insert the cable inside of the hole by being sure of the orientation of the **Part M**. + +--- + +* 🟣 Flip the **Part M** and secure the **DC Power Jack** by hand on the **Part M** by screwing the **Lock Ring**. +* ⚠ Make sure the **Lock Ring** doesn’t spin on itself. +* 🎬 **Store this assembly for later**. diff --git a/docs/hardware/collection_devices.md b/docs/hardware/collection_devices.md new file mode 100644 index 0000000..8c7d86e --- /dev/null +++ b/docs/hardware/collection_devices.md @@ -0,0 +1,11 @@ + + +# Plankton Net + +![network list](../images/hardware/planktoscope_collecting_device.png) + +The simplest device you can use is a plankton net. It should be made of a fine mesh, down to 20 micron. It can be towed behind a boat at low speed (less than 2 knots) or towed by hand in a river or a lake. + +Plankton nets can be made easily with a good sewind machine and some hardware. diff --git a/docs/hardware/content_of_the_kit.md b/docs/hardware/content_of_the_kit.md new file mode 100644 index 0000000..63c3762 --- /dev/null +++ b/docs/hardware/content_of_the_kit.md @@ -0,0 +1,39 @@ +# Content of the Kit + +* note on the mapping of the component in the task to number in the BOM + +## Bag A + +## Bag B + +## Bag C + +## Bag D + +## Bag E + +## Bag F + +## Bag G + +## Bag H + +## Bag I + +## Bag J + +## Bag K + +## Bag L + +## Bag M + +## X1 + +## X2 + +## X3 + +## X4 + +## X5 diff --git a/docs/hardware/disposal_recycling.md b/docs/hardware/disposal_recycling.md new file mode 100644 index 0000000..4e142f0 --- /dev/null +++ b/docs/hardware/disposal_recycling.md @@ -0,0 +1 @@ +# Disposal and recycling diff --git a/docs/hardware/hat_hardware.md b/docs/hardware/hat_hardware.md new file mode 100644 index 0000000..ca56335 --- /dev/null +++ b/docs/hardware/hat_hardware.md @@ -0,0 +1,64 @@ + + +# PlanktoScope Hat Hardware + +## Buses and GPIO pinout + +### I2C1 Bus + +#### RTC RV-3028-C7 + +Address 0x52 +Configured through a kernel driver. + +#### OLED Display + +Address 0x3c + +#### LED control: LM36011 + +Address 0x64 +Control through specific software, current range from 0 to 376mA in normal mode, up to 1.5A in flash mode. + +### SPI0 Bus + +#### Motor Controller 0: TMC5160 + +Chip Enable: SPI0_CE0 +Motor Enable: GPIO23 + +Diagnostic output: +GPIO16 for Error output +GPIO20 for Stall output + +#### Motor Controller 1: TMC5160 + +Chip Enable: SPI0_CE1 +Motor Enable: GPIO5 + +Diagnostic output: +GPIO16 for Error output +GPIO20 for Stall output + +### GPIO + +#### Fan control + +PWM1 control through GPIO13 + +#### LED Output selection + +GPIO18: high for LED1, low for LED2 + +#### LED Strobe + +GPIO22 for pulse + +### I2C0 Bus + +#### EEPROM M24C32 + +Address 0x50 +For HAT information only. diff --git a/docs/hardware/maintenance_repair.md b/docs/hardware/maintenance_repair.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/hardware/manufacturing.md b/docs/hardware/manufacturing.md new file mode 100644 index 0000000..6046d16 --- /dev/null +++ b/docs/hardware/manufacturing.md @@ -0,0 +1,11 @@ +# Manufacturing + +## PlanktoScope Case + +![](../images/hardware/planktoscope_case_parts_00.png) +![](../images/hardware/planktoscope_case_00.png) + +## PlanktoScope Hat + +![](../images/hardware/planktoscope_hat_front.png) +![](../images/hardware/planktoscope_hat_back.png) diff --git a/docs/hardware/supply_chain.md b/docs/hardware/supply_chain.md new file mode 100644 index 0000000..fb16237 --- /dev/null +++ b/docs/hardware/supply_chain.md @@ -0,0 +1,98 @@ + + + + + + + +Die Sorgfaltspflichten der Unternehmen erstrecken sich auf die gesamte Lieferkette – vom Rohstoff bis zum fertigen Verkaufsprodukt. + +Die Anforderungen an die Unternehmen sind nach den unterschiedlichen Stufen in der Lieferkette abgestuft: + +eigener Geschäftsbereich, +unmittelbarer Zulieferer, +mittelbarer Zulieferer. +Und nach: + +Art und Umfang der Geschäftstätigkeit, +dem Einflussvermögen des Unternehmens auf den Verursacher der Verletzung, +der typischerweise zu erwartenden Schwere der Verletzung, +der Art des Verursachungsbeitrags des Unternehmens. +Die Anforderungen sind nach dem Einflussvermögen der Unternehmen in der Lieferkette abgestuft. + +Unternehmen müssen sowohl im eigenen Geschäftsbereich als auch beim unmittelbaren +Zulieferer folgende Maßnahmen umsetzen: + +Grundsatzerklärung zur Achtung der Menschenrechte verabschieden. +Risikoanalyse: Verfahren zur Ermittlung nachteiliger Auswirkungen auf die Menschenrechte durchführen. +Risikomanagement (inklusive Präventions- und Abhilfemaßnahmen) zur Abwendung potenziell negativer Auswirkungen auf die Menschenrechte +Beschwerdemechanismus einrichten. +Transparent öffentlich Bericht erstatten. +Im eigenen Geschäftsbereich müssen Unternehmen im Fall einer Verletzung im Inland unverzüglich Abhilfemaßnahmen ergreifen, die zwingend zur Beendigung der Verletzung führen. + +Beim unmittelbaren Zulieferer muss das Unternehmen einen konkreten Plan zur Minimierung und Vermeidung erstellen, wenn es die Verletzung nicht in absehbarer Zeit beenden kann. + +Bei mittelbaren Zulieferern: + +Hier gelten die Sorgfaltspflichten nur anlassbezogen und nur wenn das Unternehmen Kenntnis von einem möglichen Verstoß erlangt. + +In dem Fall hat das Unternehmen unverzüglich: + +Eine Risikoanalyse durchzuführen. +Ein Konzept zur Minimierung und Vermeidung umsetzen. +Angemessene Präventionsmaßnahmen gegenüber dem Verursacher zu verankern. Die Umsetzung von Brancheninitiativen ist hierbei eine Möglichkeit. + +Das Gesetz gilt auch für Zweigniederlassungen ausländischer Unternehmen in Deutschland, wenn sie insgesamt mehr als 3.000 Mitarbeitende (ab 2023) beziehungsweise 1.000 Mitarbeitende (ab 2024) in Deutschland beschäftigen. +Der Geschäftsbereich deutscher Unternehmen wird erweitert: Kontrollierte Tochterunternehmen im Ausland werden zum eigenen Geschäftsbereich gerechnet und gelten nicht als erster Zulieferer. +Ein weiteres Umweltabkommen, das Basler Abkommen zu Abfallexporten, wurde ergänzt. Dieses dient auch dem Schutz der menschlichen Gesundheit. +Beim mittelbaren Zulieferer gelten Brancheninitiativen als angemessene Präventionsmaßnahme. +Betriebsräte müssen über die Umsetzung des Gesetzes informiert werden. +Klarstellung: Eine Verletzung der Pflichten aus diesem Gesetz begründet keine zivilrechtliche Haftung. Eine unabhängig von diesem Gesetz begründete zivilrechtliche Haftung bleibt unberührt. +Klarstellung: Wenn ein Produktionsland internationale Abkommen nicht ratifiziert hat, ist das per se kein Grund, die Geschäftsbeziehungen in dieses Land abzubrechen. +Ein neuer Titel: Lieferkettensorgfaltspflichtengesetz (LkSG). + +- The total number of suppliers and sites in your supply chain, and how they are distributed around the world +- Non-compliances by country and type +- Worker type analysis ie agency workers that represent a vulnerable group +- Gender breakdown, and issues that disproportionately affect men and women +- Suppliers at risk of lapsing their Sedex membership +- When suppliers are due for an audit + +- +- +- +- +- +- +- #**bgbl**%2F%2F\*%5B%40attr_id%3D%27bgbl121s2959.pdf%27%5D\_\_1671334142633 +- + +## Components + +### Raspberry Pi + +| Criteria | Description | +| --------------------- | ----------- | +| Article | | +| Manufacturer | | +| Production country | | +| Production conditions | | +| Local availability | | +| Transportation | | +| Raw materials | | +| Recycling | | +| Waste | | +| Risk | | +| Alternatives | | +| Implications | | + +### Source + +- business@raspberrypi.com +- + +### Notes + +### Camera Module + +- diff --git a/docs/images/hardware/linear_stepper_motor_00.png b/docs/images/hardware/linear_stepper_motor_00.png new file mode 100644 index 0000000..dd2b815 Binary files /dev/null and b/docs/images/hardware/linear_stepper_motor_00.png differ diff --git a/docs/images/hardware/linear_stepper_motor_01.png b/docs/images/hardware/linear_stepper_motor_01.png new file mode 100644 index 0000000..dddca12 Binary files /dev/null and b/docs/images/hardware/linear_stepper_motor_01.png differ diff --git a/docs/images/hardware/linear_stepper_motor_02.png b/docs/images/hardware/linear_stepper_motor_02.png new file mode 100644 index 0000000..16f36cb Binary files /dev/null and b/docs/images/hardware/linear_stepper_motor_02.png differ diff --git a/docs/images/hardware/planktoscope_case_00.png b/docs/images/hardware/planktoscope_case_00.png new file mode 100644 index 0000000..6ba1db3 Binary files /dev/null and b/docs/images/hardware/planktoscope_case_00.png differ diff --git a/docs/images/hardware/planktoscope_case_01.png b/docs/images/hardware/planktoscope_case_01.png new file mode 100644 index 0000000..1bbf653 Binary files /dev/null and b/docs/images/hardware/planktoscope_case_01.png differ diff --git a/docs/images/hardware/planktoscope_case_02.png b/docs/images/hardware/planktoscope_case_02.png new file mode 100644 index 0000000..314ad7c Binary files /dev/null and b/docs/images/hardware/planktoscope_case_02.png differ diff --git a/docs/images/hardware/planktoscope_case_parts_00.png b/docs/images/hardware/planktoscope_case_parts_00.png new file mode 100644 index 0000000..4eb0bac Binary files /dev/null and b/docs/images/hardware/planktoscope_case_parts_00.png differ diff --git a/docs/images/hardware/planktoscope_case_parts_01.png b/docs/images/hardware/planktoscope_case_parts_01.png new file mode 100644 index 0000000..cab0634 Binary files /dev/null and b/docs/images/hardware/planktoscope_case_parts_01.png differ diff --git a/docs/images/hardware/planktoscope_collecting_device.png b/docs/images/hardware/planktoscope_collecting_device.png new file mode 100644 index 0000000..22f2932 Binary files /dev/null and b/docs/images/hardware/planktoscope_collecting_device.png differ diff --git a/docs/images/hardware/planktoscope_hat_back.png b/docs/images/hardware/planktoscope_hat_back.png new file mode 100644 index 0000000..60513ce Binary files /dev/null and b/docs/images/hardware/planktoscope_hat_back.png differ diff --git a/docs/images/hardware/planktoscope_hat_front.png b/docs/images/hardware/planktoscope_hat_front.png new file mode 100644 index 0000000..41ab33b Binary files /dev/null and b/docs/images/hardware/planktoscope_hat_front.png differ diff --git a/docs/images/hardware/planktoscope_hat_layers.png b/docs/images/hardware/planktoscope_hat_layers.png new file mode 100644 index 0000000..510686f Binary files /dev/null and b/docs/images/hardware/planktoscope_hat_layers.png differ diff --git a/docs/images/hardware/raspberry_pi_4b_00.png b/docs/images/hardware/raspberry_pi_4b_00.png new file mode 100644 index 0000000..0925cae Binary files /dev/null and b/docs/images/hardware/raspberry_pi_4b_00.png differ diff --git a/docs/images/hardware/raspberry_pi_4b_01.png b/docs/images/hardware/raspberry_pi_4b_01.png new file mode 100644 index 0000000..8303fdb Binary files /dev/null and b/docs/images/hardware/raspberry_pi_4b_01.png differ diff --git a/docs/images/hardware/raspberry_pi_high_quality_camera_00.png b/docs/images/hardware/raspberry_pi_high_quality_camera_00.png new file mode 100644 index 0000000..cabce49 Binary files /dev/null and b/docs/images/hardware/raspberry_pi_high_quality_camera_00.png differ diff --git a/docs/images/hardware/raspberry_pi_high_quality_camera_01.png b/docs/images/hardware/raspberry_pi_high_quality_camera_01.png new file mode 100644 index 0000000..9638323 Binary files /dev/null and b/docs/images/hardware/raspberry_pi_high_quality_camera_01.png differ diff --git a/docs/images/logos/autodesk_eagle.png b/docs/images/logos/autodesk_eagle.png new file mode 100644 index 0000000..ed578a0 Binary files /dev/null and b/docs/images/logos/autodesk_eagle.png differ diff --git a/docs/images/logos/autodesk_fusion_360.png b/docs/images/logos/autodesk_fusion_360.png new file mode 100644 index 0000000..632c4c0 Binary files /dev/null and b/docs/images/logos/autodesk_fusion_360.png differ diff --git a/docs/images/logos/node-red.svg b/docs/images/logos/node-red.svg new file mode 100644 index 0000000..0131399 --- /dev/null +++ b/docs/images/logos/node-red.svg @@ -0,0 +1,30 @@ + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/logo-white.png b/docs/images/logos/planktoscope_white.png similarity index 100% rename from docs/images/logo-white.png rename to docs/images/logos/planktoscope_white.png diff --git a/docs/images/logos/python.svg b/docs/images/logos/python.svg new file mode 100644 index 0000000..1c7fd6b --- /dev/null +++ b/docs/images/logos/python.svg @@ -0,0 +1,35 @@ + + +Python programming language logo + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/planktoscope_hat/PlanktoscopeHat-v1.0-diagram.png b/docs/images/planktoscope_hat/PlanktoscopeHat-v1.0-diagram.png new file mode 100644 index 0000000..2d5e8e2 Binary files /dev/null and b/docs/images/planktoscope_hat/PlanktoscopeHat-v1.0-diagram.png differ diff --git a/docs/images/planktoscope_hat/PlanktoscopeHat-v1.0-fab.png b/docs/images/planktoscope_hat/PlanktoscopeHat-v1.0-fab.png new file mode 100644 index 0000000..d1d5c8c Binary files /dev/null and b/docs/images/planktoscope_hat/PlanktoscopeHat-v1.0-fab.png differ diff --git a/docs/images/planktoscope_hat/PlanktoscopeHat-v1.0-layers.png b/docs/images/planktoscope_hat/PlanktoscopeHat-v1.0-layers.png new file mode 100644 index 0000000..510686f Binary files /dev/null and b/docs/images/planktoscope_hat/PlanktoscopeHat-v1.0-layers.png differ diff --git a/docs/images/project_description/planktoscope_architecture.png b/docs/images/project_description/planktoscope_architecture.png new file mode 100644 index 0000000..9caaaac Binary files /dev/null and b/docs/images/project_description/planktoscope_architecture.png differ diff --git a/docs/images/project_description/planktoscope_assembly.png b/docs/images/project_description/planktoscope_assembly.png new file mode 100644 index 0000000..8036cf6 Binary files /dev/null and b/docs/images/project_description/planktoscope_assembly.png differ diff --git a/docs/images/project_description/planktoscope_field_usage.png b/docs/images/project_description/planktoscope_field_usage.png new file mode 100644 index 0000000..b77ca92 Binary files /dev/null and b/docs/images/project_description/planktoscope_field_usage.png differ diff --git a/docs/images/project_description/planktoscope_hero.png b/docs/images/project_description/planktoscope_hero.png new file mode 100644 index 0000000..69319cf Binary files /dev/null and b/docs/images/project_description/planktoscope_hero.png differ diff --git a/docs/images/project_description/planktoscope_kit_parts.png b/docs/images/project_description/planktoscope_kit_parts.png new file mode 100644 index 0000000..5cefdf6 Binary files /dev/null and b/docs/images/project_description/planktoscope_kit_parts.png differ diff --git a/docs/images/project_description/planktoscope_versions.png b/docs/images/project_description/planktoscope_versions.png new file mode 100644 index 0000000..5c0b6c2 Binary files /dev/null and b/docs/images/project_description/planktoscope_versions.png differ diff --git a/docs/images/project_description/planktoscope_workflow.png b/docs/images/project_description/planktoscope_workflow.png new file mode 100644 index 0000000..e98b463 Binary files /dev/null and b/docs/images/project_description/planktoscope_workflow.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-000.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-000.jpg new file mode 100644 index 0000000..a7f4d26 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-000.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-015.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-015.png new file mode 100644 index 0000000..eefde5d Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-015.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-019.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-019.png new file mode 100644 index 0000000..1f37e31 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-019.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-020.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-020.png new file mode 100644 index 0000000..601a8b5 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-020.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-023.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-023.png new file mode 100644 index 0000000..736278c Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-023.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-024.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-024.jpg new file mode 100644 index 0000000..d2a7f9a Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-024.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-027.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-027.png new file mode 100644 index 0000000..59bd55d Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-027.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-028.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-028.jpg new file mode 100644 index 0000000..8f8b7b9 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-028.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-031.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-031.png new file mode 100644 index 0000000..13e5723 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-031.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-032.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-032.jpg new file mode 100644 index 0000000..db464f6 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-032.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-035.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-035.jpg new file mode 100644 index 0000000..b18aa57 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-035.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-036.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-036.png new file mode 100644 index 0000000..ce1fc10 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-036.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-039.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-039.jpg new file mode 100644 index 0000000..30b4a52 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-039.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-040.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-040.jpg new file mode 100644 index 0000000..94bb731 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-040.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-043.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-043.jpg new file mode 100644 index 0000000..30f75b5 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-043.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-044.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-044.jpg new file mode 100644 index 0000000..f0a268f Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-044.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-047.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-047.jpg new file mode 100644 index 0000000..1dbd361 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-047.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-048.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-048.jpg new file mode 100644 index 0000000..ae17704 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-048.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-051.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-051.jpg new file mode 100644 index 0000000..16ee0f7 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-051.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-054.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-054.png new file mode 100644 index 0000000..e0e6102 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-054.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-055.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-055.jpg new file mode 100644 index 0000000..fd6bead Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-055.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-058.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-058.jpg new file mode 100644 index 0000000..05b8dec Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-058.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-059.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-059.jpg new file mode 100644 index 0000000..57c4b7a Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-059.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-062.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-062.jpg new file mode 100644 index 0000000..f30a188 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-062.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-063.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-063.jpg new file mode 100644 index 0000000..77b6e07 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-063.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-066.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-066.jpg new file mode 100644 index 0000000..155863f Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-066.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-069.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-069.jpg new file mode 100644 index 0000000..010e374 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-069.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-070.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-070.jpg new file mode 100644 index 0000000..594e246 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-070.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-073.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-073.jpg new file mode 100644 index 0000000..d762356 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-073.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-074.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-074.jpg new file mode 100644 index 0000000..64b19b4 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-074.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-077.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-077.jpg new file mode 100644 index 0000000..5510d0e Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-077.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-078.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-078.jpg new file mode 100644 index 0000000..cd6e304 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-078.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-083.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-083.jpg new file mode 100644 index 0000000..bcce40f Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-083.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-086.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-086.jpg new file mode 100644 index 0000000..d927647 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-086.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-087.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-087.jpg new file mode 100644 index 0000000..c4dd0b2 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-087.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-090.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-090.jpg new file mode 100644 index 0000000..b9f99a6 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-090.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-091.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-091.jpg new file mode 100644 index 0000000..53f4587 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-091.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-096.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-096.jpg new file mode 100644 index 0000000..2bc4923 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-096.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-097.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-097.jpg new file mode 100644 index 0000000..68e85ad Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-097.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-100.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-100.jpg new file mode 100644 index 0000000..c5e6582 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-100.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-101.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-101.jpg new file mode 100644 index 0000000..23b589c Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-101.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-104.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-104.jpg new file mode 100644 index 0000000..d09d4c5 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-104.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-105.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-105.jpg new file mode 100644 index 0000000..722f180 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-105.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-108.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-108.png new file mode 100644 index 0000000..277cec9 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-108.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-109.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-109.png new file mode 100644 index 0000000..2348d77 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-109.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-112.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-112.jpg new file mode 100644 index 0000000..bcab292 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-112.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-113.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-113.jpg new file mode 100644 index 0000000..3c51273 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-113.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-118.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-118.jpg new file mode 100644 index 0000000..cda8ccf Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-118.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-119.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-119.png new file mode 100644 index 0000000..646e01b Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-119.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-124.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-124.jpg new file mode 100644 index 0000000..cd6e304 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-124.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-127.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-127.png new file mode 100644 index 0000000..8d3d66e Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-127.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-128.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-128.png new file mode 100644 index 0000000..544a942 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-128.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-131.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-131.png new file mode 100644 index 0000000..3e919cd Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-131.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-132.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-132.png new file mode 100644 index 0000000..08df32a Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-132.png differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-137.jpg b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-137.jpg new file mode 100644 index 0000000..011d23f Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-137.jpg differ diff --git a/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-138.png b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-138.png new file mode 100644 index 0000000..73d32f0 Binary files /dev/null and b/docs/images/protocol_primer/PlanktoScope_Setup_and_Sampling_Guide_VER3-138.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..dcb135c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,11 @@ +![planktoscope_hero](images/project_description/planktoscope_hero.png) + +An open and affordable imaging platform for citizen oceanography + +# What is this? + +The PlanktoScope is an open-source, affordable imaging platform for citizen oceanography. It's built around a Raspberry Pi, a couple of HATs, some stepper motors and a few centimeters of silicon tubes. Its cost is at about $800 in parts. + +The goal of the PlanktoScope is to allow citizen to engage in scientific programs, either at sea or onshore. You can use the PlanktoScope to image the different species of Plankton living in a body of water. + +![planktoscope_hero](images/project_description/planktoscope_hero.png) diff --git a/docs/introduction/device_specification.md b/docs/introduction/device_specification.md new file mode 100644 index 0000000..8f335dd --- /dev/null +++ b/docs/introduction/device_specification.md @@ -0,0 +1,58 @@ +# Device Specifications + +## Size + +* height: 150 mm +* wide: 350 mm +* depth: 150 mm + +## Hardware + +* 4 Core ARM-Cortex-A72 Processor with 1,50 GHz +* 4 GB Arbeitsspeicher (depending on the purchased version) +* 64 GB Flash memory (depending on the purchased version) +* [Sony IMX477R](https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/) Image sensor with 12.3MP +* M12-Mount Optiken mit 16 und 25 mm Linsen +* Automatic focus via linear guide +* automatic sampling via peristaltic pump +* the case is made of wood fiberboard + +## Software + +* [Debian](https://www.raspberrypi.com/software/operating-systems/) based Embedded Linux operating +* [Node-Red](https://nodered.org/) based user interface +* [Python](https://www.python.org/) Image processing service and cloud connection + +## Characteristic + +* Magnification ??? +* Focus stage control +* Pump control +* Automatic image capture +* Automatic segmentation, optimization and object detection +* 4,200 images, 41,000 objects, ~ 1 minute +* Control via smartphone or tablet + +## License + +* Hardware: CERN Open Hardware Licence +* Software: GNU General Public License +* Dokumentation: Creative Commons Attribution-ShareAlike + +## Certification + +* [DIN SPEC 3105-1: Open Source Hardware](https://www.researchgate.net/publication/342564027_DIN_SPEC_3105-1_Open_Source_Hardware) + +## Areas of Application + +* Plankton analysis of small animals and algae living in water +* Mobile use via external power supply + +## System Requirements + +* a Web-Browser to control the device (like a Notebook, Smartphone or tablet) + +## Accessories + +* [Collector device]() +* [12v Power Bank]() diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md new file mode 100644 index 0000000..df1599e --- /dev/null +++ b/docs/introduction/introduction.md @@ -0,0 +1,47 @@ + + +# Welcome to the PlanktoScope build and use documentation + +![PlanktoScope](../images/readme/planktoscope_cad.webp) + +You can find here more information about how to build your own PlanktoScope. + +## Setup + +- [How to setup your PlanktoScope the easy way](../software/easy_install.md) +- [How to setup your PlanktoScope the hard way (also known as the Expert's path)](../software/expert_setup.md) +- [Some information about how to setup a remote access](../usage/remote_access.md) + +## Build your machine + +- [Assembly Guide](../hardware/assembly_guide.md) + +## Usage + +- [Information about collection devices](../hardware/collection_devices.md) + +## Under the hood + +- [Software architecture](../contribute/software_architecture.md) +- [MQTT Messages](../usage/mqtt_messages.md) +- [Create Master SD Card or backup your PlanktoScope](../software/create_sd.md) +- How does the segmentation works (soon) + +## Changelog + +- [Changelog](../changelog.md) + +## Contribute + +- [Find out how to contribute to this documentation and help edit it](../contribute/writing_documentation.md) +- [Contribute to the code, here is the getting started](../contribute/software_development.md) + +## License of our work + +- [More information about the licenses that we use](../license.md) + +## Design History + +## Architecture diff --git a/docs/introduction/research.md b/docs/introduction/research.md new file mode 100644 index 0000000..8591dc3 --- /dev/null +++ b/docs/introduction/research.md @@ -0,0 +1,13 @@ +# Research + +## Plankton Planet: ‘seatizen’ oceanography to assess open ocean life at the planetary scale + +* assets/2020.08.31.263442v1.full.pdf + +## PlanktoScope: Affordable Modular Quantitative Imaging Platform for Citizen Oceanography + +* assets/fmars-09-949428.pdf + +## PlanktonScope: Affordable modular imaging platform for citizen oceanography + +* assets/2020.04.23.056978v1.full.pdf diff --git a/docs/protocols/basic_primer.md b/docs/protocols/basic_primer.md new file mode 100644 index 0000000..2fab62a --- /dev/null +++ b/docs/protocols/basic_primer.md @@ -0,0 +1,651 @@ +Plankton imaging with the PlanktoScope: A +setup and sampling guide +Forked from Planktoscope protocol for plankton imaging + +Lombard Fabien, Will Major +1 Works for me +Will Major + +ABSTRACT + +This is a instructional manual for setting up the PlanktoScope (V2.5) for regular data +collection and processing, as well as a step-by-step guide for running samples. +ATTACHMENTS +Pollina et al 2020 +2020.04.23.056978v1.full. +pdf + +EXTERNAL LINK + + +PROTOCOL INFO + +Lombard Fabien, Will Major . Plankton imaging with the PlanktoScope: A setup and +sampling guide. protocols.io + +MANUSCRIPT CITATION please remember to cite the following publication along with this protocol + +Pollina T, Larson A, Lombard F, Li H, Colin S, Vargas C de, Prakash M (2020) +PlanktonScope: Affordable modular imaging platform for citizen oceanography. +bioRxiv 2020.04.23.056978. doi: 10.1101/2020.04.23.056978 +FORK FROM + +Forked from Planktoscope protocol for plankton imaging, Lombard Fabien +KEYWORDS + +plankton, PlanktoScope, imaging, microscope +IMAGE ATTRIBUTION + +Fabien Lombard, Thibaut Pollina, Will Major +CREATED + +Mar 07, 2022 +LAST MODIFIED + +Jul 14, 2022 +1 + + PROTOCOL INTEGER ID + +59150 +GUIDELINES + +PlanktoScope is an optical instrument. Its optical elements (camera, lenses, flowcell) are +highly sensitive to dust and dirt. We recommend that you never touch any of those +component with fingers and store the PlanktoScope in a dust free and humidity free area +(or in a box when not used). +MATERIALS TEXT + +PlanktoScope +Plankton Net +200 µm sieve +Optical paper +Pine Pollen in Water and Pine Pollen dry +SAFETY WARNINGS + +Planktoscope is an electronic device, powered with electricity. It is therefore sensitive to +water. + +- Place it in an environment where water can not enter in contact with the instrument and +secure its electrical part. +- Be careful when manipulating samples, take care of having the exhaust tube in a "trash" +contained to avoid spillage. +- Glass parts are present (flowcell) and should be handled with caution (to avoid injury) +and kept clean (avoid touching it with fingers). +BEFORE STARTING + +Make sure to read through an entire subsection before taking any action. +Initial connection and setup + +1 + +Powering, connecting to and configuring the PlanktoScope. +This section will introduce you to using your PlanktoScope: + +- subsections 1.1 and 1.2 cover turning on and connection to the machine; +- subsections 1.3 - 1.7 will cover running the necessary tests to make sure your PlanktoScope is +working as we +expect. +Please ensure you carefully read through each subsection before you take any action. + +1.1 + +Power your Planktoscope by connecting power cable to the power input and +turning on the wall switch. Within 1 minute of turning on your PlanktoScope, you +should see the LED flash once. +After a few minutes, you should see a new option for Wi-fi appearing on your +2 + + computer. Connect to it using the password: "copepode". +For more information and alternative methods of connection, see the designer's +Connectivity Tutorial here: + +1.2 + +PlanktoScope - Connectivity Tutorial.pdf + +Open the PlanktoScope's User Interface (UI) on your web browser (Chrome, +Firefox, Edge etc.) using the following webpage link (either click on the link or +copy and paste into your browser): + +There are several tabs on the UI that can be used to adjust setting, run samples +and take images. To navigate around the UI, all tabs are available from the Home +tab, including the Shutdown button which we will use when we have finished +using the PlanktoScope. +We can also use the 'Hamburger Menu', situated in the top-left corner of the UI, to +navigate between tabs. + +The 'Home' tab of PlanktoScope's User Interface. + +The 'Hamburger Menu' icon, situated in the top-left corner of the screen, can be used to +navigate around the User Interface + +1.3 + +Once the UI has loaded on your browser, navigate to the Optic Configuration tab +and we will make sure the PlanktoScope is operating correctly . + +To test the PlanktoScope, navigate to the Optic Configuration tab: + +3 + + The Optic Configuration tab which can be used to adjust the camera settings. If only Preview is visible +on your screen, the other options should be available below by scrolling down or by adjusting 'Zoom' +on your browser (usually Ctrl + scroll UP or DOWN on Windows or command + scroll UP or DOWN on +Mac). + +a) Under Optic Characterisation, switch on the Light by clicking 'On'. You should +see the Preview image turning from dark to light. The Preview image could be +any colour so do not worry if yours does not show blue; it will be adjusted later. + +The red box highlights the location for turning on the LED. You will need to do this every time you use +your PlanktoScope. + +b) Under Focus Adjustment, click 'UP 1MM' and 'DOWN 1MM' to ensure focus +buttons turn the focus motor. You should see the mount moving further from (UP) +or closer to (DOWN) the camera. + +4 + + Red boxes highlight 'UP 1MM' and 'DOWN 1MM' that will move the Mount (pictured below). + +Green arrows highlight the movement of the Mount when using Focus Adjustment buttons on the Optic +Configuration tab. 'UP 1MM' will move the Mount towards the right-hand side of the picture, while +'DOWN 1MM' will move the Mount to the left-hand side of the picture. + +c) Under Fluidic Manual Manipulation, click clockwise arrow to check that the +Peristaltic Pump is working. You should see the pump rotating in an clockwise +direction. + +5 + + The red square highlights the location of the clockwise arrow that will rotate your Peristaltic Pump in +the same direction. + +The clockwise arrow from the Fluidic Manual Manipulation section should rotate your PlanktoScope's +Peristaltic Pump in a clockwise direction. + +d) Under Camera Settings, change the ISO value. You should see changes to the +Preview image. After this test, Set ISO to 100 . +6 + + The red box highlights the location of the ISO setting. You should see your Preview image change +colour when you adjust this setting. Make sure it is set to 100 once you have tested this. + +1.4 + +Now we will align the lenses in your PlanktoScope . To do this: +a) Remove the Fluidic Path from the mount and gently lay to the side. + +Remove the Fluidic Path and lay to the side + +7 + + Remove the Fluidic Path and lay to the side + +b) Make sure we have enough space to remove the lenses by clicking the 'UP +1MM' button under Focus Adjustment. + +Red box highlights 'UP 1MM' button that will move the Mount away from the lenses. + +8 + + Move the Mount away from the lenses using the 'UP 1MM' button to allow for outer lens removal. + +c) Remove the outermost lens (16MM). + +9 + + Remove the outermost (16MM) lens. + +d) On the Preview image on the Optic Configuration tab, you should see a light +spot surrounded by darkness. By moving the 25MM lens on your PlanktoScope, +you can move the light spot on the Preview image. Try to get the light spot as +close to the centre of the Preview image as possible. + +With the 16MM lens removed, your Preview image should resemble this picture. If the light spot is not +centred, gently reposition the 25MM lens until it is as close to centre as you can get it. + +10 + + Gently reposition the inner (25MM) lens. + +e) Once centred, place the outermost lens back to where you removed it from +in step 3. + +Place the outer (16MM) lens back into position. + +11 + + f) On the Preview, you may see darker areas in the corners. To get rid of the +darker areas in the corner, reposition the outermost lens (16MM) while holding +the innermost lens (25MM) steady; the darker corners should disappear. Try to +achieve homogenous light across the Preview image. +g) Place the Fluidic Path back into position. + +1.5 + +Manually adjust the white balance of your PlanktoScope . Try pressing the +Auto White Balance button to its 'on' and 'off' positions on the Optic Configuration +tab; you will likely see the Preview image changing colour. +We need to achieve the Preview image colour that the Auto White Balance +feature provides, without using the Auto White Balance. Not using Auto White +Balance enhances the performance of the PlanktoScope over time. +To manually set to the White Balance, turn off the Auto White Balance and adjust +WB: Red and WB: Blue until it looks white. Then switch AWB back on to see if it +matches. Repeat this process until there is no colour change when clicking the +AWB button. +Set the AWB button to 'off' once you have completed this step. + +12 + + The red box highlights how to manually adjust the white balance of the Preview image. In this example, +the correct setting was WB: Red = 4 and WB: Blue = 1.21. The AWB button should be set to 'off' once +you have completed this step. + +1.6 + +Setup the 'Bubbler' : + +Locate the Bubbler. + +13 + + Tie a knot in the Bubbler. + +Plug the Bubbler into one of the USB ports on the PlanktoScope. + +14 + + Place the tubing into the Syringe so that it reaches the bottom. + +Affix the tubing to the Syringe using an elastic band, string or similar. + +15 + + 1.7 + +Load in a practice sample and manually adjust the focus of the camera . +a) Locate the Pine Pollen in Water sample and a Pasteur Pipette. + +b) Shake the Pine Pollen in Water sample, remove the lid, and use the Pasteur +Pipette to transfer roughly 10 mL into the Syringe. Take this opportunity to check +that your Bubbler is working appropriately: you should see no more than 4-5 +bubbles per second. Tighten the knot in the tubing to reduce the airflow if you +need to. + +16 + + c) From the Optic Configuration tab, run the Peristaltic Pump so that the Flow +System is filled with the sample. Double-check that the tubing from your +Peristaltic Pump runs into the Waste (Test Tube with dark blue lid). + +d) On the Optic Configuration tab under Focus Adjustment, use the 'UP 1MM' +and 'DOWN 1MM' to adjust course focus , and 'UP 100UM' and 'DOWN 100UM' to +17 + + adjust fine focus . You will likely need to use the 'DOWN 1MM' to move the +Mount close to the lenses before using the fine focus buttons. You should see +small dark particles on the Preview image; these particles need to be in perfect +focus, adjust until correct. + +Pine pollen particles in perfect focus in the Preview image. + +You may see the edge of the flow system in your Preview image (see the red box). To fix this, simply +reposition the outer lens (16MM) as we did in step 1 .5 f . + +NB: if you do not see any particles, try adding a very small amount more of Pine +Pollen to your Syringe by dipping the handle of a teaspoon into your dry Pine +Pollen sample, and then into your Syringe sample. Then run the Peristaltic Pump +once more to pass the sample with a higher concentration of Pine Pollen in front +of the camera. Wash the spoon thoroughly after use. + +18 + + The handle of a teaspoon dipped into dry Pine Pollen sample. Less is mo re! + +1.8 + +To finish the setup , run the Pump from the Optic Configuration tab until all of +the Pine Pollen sample has passed into the Waste. Fill the Syringe with tap water +and run it through into the Waste to clean the PlanktoScope (you may need to +empty the Waste into the sink/toilet before you do this). +Shut down the PlanktoScope by navigating to 'Home', click the 'Unlock Button' +and then click 'Shutdown'. Leave for one minute before turning off your +PlanktoScope at the wall plug. + +Get your sample + +2 + +Using a net to collect a sample + +2.1 + +Remove the net from its bag and set aside the 200 µm sieve. +19 + + Within the net bag you will find the net (left of photo) and 200 µm sieve (right of photo). + +- Position yourself close to but a safe distance from the water's edge and ensure +a stable footing. +- Unspool the rope. +- Hold the lead weight on the rim of the net along with the cod end in your +throwing hand while holding the plastic handle tightly with your other hand, throw +the net into the water. +- Gently pull the net back towards you just before it hits the water to orientate it. +Pull the net back towards to at a speed so that it is submerged but does not sink. +For areas of fast flow, you may only have to perform one cast. With areas of +sluggish or no flow, two or three casts may be necessary. + +2.2 + +To get the sample from the net: + +- remove the cod end and spray its mesh sides with water from the Pasteur +Pipette. + +20 + + Remove the cod end from the net by twisting in an anti-clockwise direction. Ensure to keep the cod +end upright. + +Spray mesh sides of the cod end with water from the Pasteur Pipette to ensure all particles move +down into your sample. + +- Once you are satisfied that any particles are no longer stuck to the mesh sides, +21 + + you are ready to transfer your sample into a Falcon Tube. While holding the +200µm sieve above a Falcon tube, slowly pour your sample so that it passes +through the sieve and into the tube. Label your Sample and keep a record of its +date, time and location. + +Position the 200 µm sieve above the Falcon Tube + +Pour your sample from the cod end, through the sieve and into your Falcon Tube. + +- Make sure you label your sample and keep a log of when and where you have +collected it. +22 + + - Ensure to rinse your net and sieve in fresh water before the next use. +Running a sample + +3 + +This section covers your regular use of the PlanktoScope, and the setup and procedure you will +undertake each time you want to run a sample. + +3.1 + +Navigate to the Sample tab to set up running a sample through the +PlanktoScope. + +The Sample tab on the PlanktoScope's UI + +a) Begin inputting Sample Identification information. + +Fill the entries shown by the red box: +Project name = MAPPS +Name of the operator = Your Name +Station ID = Your sample location e.g River Thames or Southampton Water. + +b) Input the 'Net Throw Location' information including Latitude, Longitude, +Date and Time before clicking the 'VALIDATE' button. The format for this section +is strict and can be a bit of a fiddle; if you have not input the information perfectly +23 + + when you click 'VALIDATE', you will have to input the information from scratch. +The next few images will show you how to input these pieces of information. + +b) i. Latitude and Longitude +Use your web browser and navigate to + +ii. Click on your sample collection location on Google Maps and you should see a grey symbol that +matches that in the red circle. If you do not see this symbol, try to adjust the position of your click +slightly. +iii. You will see coordinates in the red square (above), click on these numbers. + +24 + + iv. The relevant information is the numbers in the red box (above) that are separated by a comma. +Copy (Ctrl + C for Windows or command + C for Mac) the first number and paste (Ctrl + V for +Windows or command + V for Mac) it into the Latitude entry on the Sample tab. +The second number may have a minus sign before it. Do not include this. Copy the second number +(without the minus sign) and paste it into the Longitude entry on the Sample tab. +You then need to include °N in the Latitude box, and °E or °W depending on whether there was a minus +sign before the number (minus = °W; no minus = °E). The easiest way to enter the degree symbol will +be to copy and paste it from this document. Alternatively, on Windows you can press Alt + 0176 and +on Mac you can press Shift + Option + 8. + +v. Then enter the Date (and time) of your data collection (as in, the date and time +you had your net in the water) in the format listed e.g. 2022-03-11 12:00 +vi. Then enter Time e.g. 12:00. Please ensure that the time in the Date section +and Time sections match. +vii. Click 'VALIDATE' + +3.2 + +Run a sample by navigating to the Fluidic Acquisition tab. +In the red box pictured below, update the following parameters: +a) Acquisition Unique ID should be a three-digit number starting with 001 and +25 + + increasing with each sample you run. +b) Number of images to acquire should be 100 +c) Pumped Volume (mL) should be around 0.1 +d) Delay to stabilise image should be 0.5 +e) Flowcell should be 300 μm Capillary. + +Once you have updated the parameters correctly, click 'UPDATE CONFIG'. Then, +click 'START ACQUISITION' and the Pump and imager should start. + +3.3 + +Once you have run your sample and collected the images, you will need to +segment them (separate each image into images of individual particles). +Navigate to the Segmentation tab. + +1. Click on the "update acquisition's folder list" +2. Select the samples you wish to segment +3. Setup the different options of the segmenter (see below for idealised setup). +26 + + - Recursive folder means that it will segment all samples within a selected +sample + +- Ecotaxa archive: it will create a zip file containing all files needed for a easy +importation within ecotaxa +- Force rework: if yes it will re-segment samples already segmented +- Keep objects: it will keep the final segmented images visible in the planktoscope +(that could be accessed by the gallery in the objects folder) + +The idealised Control setup for segmenting images within the PlanktoScope User Interface + +4. Scroll down and clic on start segmentation +5. Wait for the segmenter status to turn to "Done" + +6. Finally, download your segmented images from the PlanktoScope using +FileZilla (described in section 4) +Download your Plankton images + +4 +You will need a computer connected to the planktoscope together with free software FileZilla +() +Open FileZilla +Either click on the top right to create a new connection or use the quick-connection fields +below +Enter the following informations: +Host: s (192.168.4.1 should also works) +27 + + Username: pi +Password: copepode +Port: 22 + +click on connect +on the bottom panels you have (on the left) the access to what is in your computer and (on the +right) the access to what is in the planktoscope (click and slide to transfer data in between +both) + +Exports file for EcoTaxa are in /home/pi/data/export/ecotaxa +Raw images files are in /home/pi/data/img +Different control files to check the segmentation process (../images after background substraction, +masks of the different objects etc) are in /home/pi/data/clean +Final vignettes are in /home/pi/data/objects +Once you have downloaded the images, you can clean and shutdown your PlanktoScope (see the +next section), and reconnect to the internet. +Clean the planktoscope + +5 + +1. Drain the sample out of the syringe +2. Disconnect the syringe and clean it with tap water (or even distilled water) +3. Pump (at high speed!) the full content of the fluidic system to remove any liquid +4. Reconnect the syringe +5. Fill it with tap water (or distilled water) +6. Pump (at high speed!) while regularly pinch the tubing to detach any plankton in the system +(see + +) + +7. Drain again the syringe (repeat steps 7.2-7.7 at least 2 more times until no plankton is +visible on the camera) +8. Finally drain the system +Shut down the PlanktoScope by navigating to 'Home', click the 'Unlock Button' and then clicking +'Shutdown'. Leave for one minute before turning off your PlanktoScope at the wall plug. +28 + + Upload your images on EcoTaxa + +6 +At First connection: +Create an account on EcoTaxa () by clicking on the top right "log +in/register" + +Put your real name and a valid mail so that you can be contacted + +29 + + 6.1 + +Once logged you can consult the project on which you are registered by clicking +onto "contribute to a project " on the main page. +Our project is called #4970 PlanktoScope - MAPPS - 2021 +You must first notify a project manager who will assign you permissions + +6.2 + +upload the ecotaxa archives (see step 4) on the EcoTaxa ftp +using Filezilla (see + +) create a connection by using the following information: + +Select File > Site Manager... +Create a New Site called : Ecotaxa_VLFR +In General tag : +Host : plankton.obs-vlfr.fr +Protocol : FTP – File Transfer Protocol +Encryption : Only use plain FTP (insecure) +Logon Type : Normal +User : ftp_plankton +Password : Pl@nkt0n4Ecotaxa +30 + + Once this is done you could use FileZilla to load the Zip files downloaded from the +Planktoscope onto the EcoTaxa ftp server (e.g. +/Ecotaxa_Data_to_import/PLANKTONSCOPE) + +Please eventually create your own folder to "try" to keep it clean and +tidy +Please think to regularly remove those temporary files from the ftp, +at this point they are not secured at all and everybody can access +them (and disk space is not free) + +6.3 + +In the project on your 'Project' options button, select import images and metadata + +6.4 + +locate your file on the ecotaxa ftp folders and import it (only works for one zip file +at a time for now) + +31 + + Maintenance of your planktoscope + +7 + +Clean tubing and flowcell from inside +imaging plankton will lead to have a lot of organic material and seawater in the fluidic system. +Some may clog or accumulates in some parts of the fluidic system. + +1. Don't let it dry and try to get rid of it as soon as possible (if its occurs during sample acquisition, +even abort this latter, take care of the clog, maybe dilute the sample +acquisition while noting that the sample got diluted in the metadata + +and restart +) + +2. Pump tap or distilled water with high pumping rates helps to unclog the system. make sure no +plankton organisms remain in the fluidic system and especially on the internal walls of the +flowcell. If it is the case don't hesitate to pinch (during 1-2 second) and release the tubing +between the flowcell and the pump while pumping to create a sudden variation of pressure +(e.g. + +) + +3. Over time, wet conditions and organic matter may create favorable condition for the growth of +a bacterial film. The flowcell and tubing will look dirty from the inside. You can avoid this by +pumping diluted bleach sometimes, let it act for 1-2 hours and carefully rinse the whole +system +4. Water, bacteria, and bleach together may favour the apparition of a calcium carbonate film +inside the tubing and flowcell. It may either appear as dispersed cristals attached inside the +flowcell or a white coating inside the tubing. To remove and clean this, pump some acidic +solution (vinegar, citrus juice or other kind of other acids), let it rest for a few hours and rinse +the system +Clean flowcell outside: +The flowcell is an optical critical component, keeping it clean is an absolute necessity. Don't touch +it with fingers or other kind of dirty material. If dirty: +1. if only dry dusts are present, gently blow the flowcell (ideally with dry gas dispenser at a large +distance - dry gas dispenser are also creating thermal chocs if used from too close, test it on +other material before) +2. if dirt in not only dry dusts it could be cleaned with optical paper and ethanol. DO NOT USE +CLASSICAL WIPING PAPER which are usually enriched in silica fibers for solidity ... and +may create scratches on the flowcell. (disposable nose tissue are better alternative if optical +paper is not available) + +Clean optical lenses +as for the flowcell, optical lenses are critical elements of your planktoscope and should be kept as +clean as possible. It starts by never touching them with fingers (cleaning those would requires a +lot of patience, efforts and may even lead to unexpected disappointments) + +1. dry dust: dry gas (with even more caution than previously +2. others: only used optical paper +clean the camera sensor +... critical part if any, NEVER touch it, only use dry gas +regularly calibrate the pump +External links + +8 + +Planktoscope website + +32 + + Planktoscope github + +Planktoscope complete assembly guide and complete documentations + +Planktoscope Slack channel (to exchange ideas/protocols/solutions) + +Plankton Planet website + +EcoTaxa tutorials: + + + + +33 diff --git a/docs/software/create_sd.md b/docs/software/create_sd.md new file mode 100644 index 0000000..f3d0e45 --- /dev/null +++ b/docs/software/create_sd.md @@ -0,0 +1,109 @@ + + +# 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: + +```txt +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: + +```txt +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 +- `mnt/home/pi/.*history`: bash and python history +- `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` + +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 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. + +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! diff --git a/docs/software/easy_install.md b/docs/software/easy_install.md new file mode 100644 index 0000000..21c2900 --- /dev/null +++ b/docs/software/easy_install.md @@ -0,0 +1,41 @@ + + +# PlanktoScope Simple Setup Guide + +## Download the image + +For ease of setup, a preconfigured image is provided. You can download it from [here](https://drive.google.com/file/d/1y0k_NDXN0yT5caZrXhjLYXgQVxu-D5ql/view?usp=sharing). + +## Writing the image to the SD card + +Download the latest version of [balenaEtcher](https://www.balena.io/etcher/) and install it. + +Connect an SD card reader with the micro SD card inside. + +Open balenaEtcher and select from your hard drive the previously downloaded img file file you wish to write to the SD card. + +Select the SD card you wish to write your image to. + +Review your selections and click 'Flash!' to begin writing data to the SD card. + +## Inserting the SD card + +Once flashing is over, you can unmount the SD card from the computer (usually done by right clicking on the card icon in the taskbar). + +Insert now the card in the Raspberry installed in your PlanktoScope. + +## Install a mDNS client + +To access the PlanktoScope services through your browser, you need to install a mDNS client. + +If you are running a linux machine, you are in luck. Avahi-client is probably already installed on your machine. Check with your package manager. + +If you are running a Windows machine, you will need to install the Bonjour service. It's a client developped by Apple. However, if you already use iTunes, Skype or even Photoshop, you may already have a client installed. Try skipping to the next step. If you can't access the linked page, come back here! + +To install the client, download the installer [here](https://download.info.apple.com/Mac_OS_X/061-8098.20100603.gthyu/BonjourPSSetup.exe) and launch it. + +## Start playing + +Start up your PlanktoScope and connect to its WiFi network. You can now access the webpage at to start using your machine! diff --git a/docs/software/expert_setup.md b/docs/software/expert_setup.md new file mode 100644 index 0000000..0704a6e --- /dev/null +++ b/docs/software/expert_setup.md @@ -0,0 +1,787 @@ + + +# Expert Setup + +## Install and setup Raspbian on your Raspberry Pi + +### Computer setup + +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 instead of an IP address. + +### Download the image + +The latest Raspbian version can always be downloaded from [the Raspberry Pi Downloads page](https://www.raspberrypi.org/downloads/raspbian/). +For a first build, it's recommende to download an image of Raspbian Buster with desktop. + +#### Writing an image to the SD card + +Download the latest version of [balenaEtcher](https://www.balena.io/etcher/) and install it. + +Connect an SD card reader with the micro SD card inside. + +Open balenaEtcher and select from your hard drive the image zip file you just downloaded. + +Select the SD card you want to write your image to. + +Review your selections and click `Flash!` to begin writing data to the SD card. + +#### Prepare your Raspberry Pi + +[Getting Started with your Raspberry Pi](https://projects.raspberrypi.org/en/projects/raspberry-pi-getting-started/) + +Plug the SD Card in your Raspberry Pi and connect your Pi to a screen, mouse and a keyboard. Check the connection twice before plugging the power. + +The first boot to the desktop may take up to 120 seconds. This is normal and is caused by the image expanding the filesystem to the whole SD card. DO NOT REBOOT before you reach the desktop. + +#### Finish the setup + +Make sure you have access to internet and update/upgrade your fresh Raspbian install. + +Update your Pi first. Open up a terminal, and do the following: + +```sh +sudo apt update -y +sudo apt full-upgrade -y +sudo apt install git +``` + +You can now reboot your Pi safely. + +```sh +sudo reboot now +``` + +## Raspberry Pi configuration + +### Clone this repository + +First of all, and to ensure you have the latest documentation available locally, you should clone this repository using git. + +Simply run the following in a terminal: + +```sh +git clone https://github.com/PlanktonPlanet/PlanktoScope/ +``` + +### Enable Camera/SSH/I2C in raspi-config + +You can now launch the configuration tool: + +```sh +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 PlanktoScope is connected to a shared network you do not control. Just select the first option `1 System Options`, the `S3 Password`. + +You may also want to change the default hostname of your Raspberry. To do so, choose option `1 System Options` then `S4 Hostname`. Choose a new hostname. We recommend using `planktoscope` as this name will then appear. + +We need to activate a few things for the PlanktoScope to work properly. + +First, we need to activate the camera interface. Choose `3 Interface Options`, then `P1 Camera` and `Yes`. + +Now, you can go to `3 Interface Options`, then `P2 SSH`. Choose `Yes` to activate the SSH access. + +Again, select `3 Interface Options`, then `P4 SPI`. Choose `Yes` to enable the SPI interface. + +One more, select `3 Interface Options`, then `P5 I2C`. Choose `Yes` to enable the ARM I2C interface of the Raspberry. + +Finally, select `3 Interface Options`, then `P6 Serial`. + +This time, choose `No` to deactivate the login shell on the serial connection, but then choose `Yes` to keep the Serial port hardware enabled. + +Last steps we need to do is to increase the amount of memory available to the GPU. Select `4 Performance Options`, then `P2 GPU Memory`. Write `256` in the field and choose OK. + +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 + +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: + + ```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. + +Reboot your Pi safely. + +```sh +sudo reboot now +``` + +## AutoHotSpot Setup + +See the document [Remote Access](../usage/remote_access.md) + +## 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 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: + +```sh +sudo apt install build-essential python3 python3-pip +sudo update-alternatives --install $(which python) python $(readlink -f $(which python2)) 1 +sudo update-alternatives --install $(which python) python $(readlink -f $(which python3)) 2 +sudo update-alternatives --config python +# Choose line 0 +mkdir test libraries +``` + +### Install all python libraries + +To simplify setup, we provide requirements.txt: + +```sh +pip3 install -U -r /home/pi/PlanktoScope/requirements.txt +``` + +### Add to python path + +We need to do this to make sure we can call the modules from any path in the system, and not just from the `scripts` folder: + +``` +ln -s /home/pi/PlanktoScope/scripts/planktoscope /home/pi/.local/lib/python3.7/site-packages/planktoscope +ln -s /home/pi/PlanktoScope/scripts/shush /home/pi/.local/lib/python3.7/site-packages/shush +sudo mkdir -p /root/.local/lib/python3.7/site-packages +sudo ln -s /home/pi/PlanktoScope/scripts/planktoscope /root/.local/lib/python3.7/site-packages/planktoscope +sudo ln -s /home/pi/PlanktoScope/scripts/shush /root/.local/lib/python3.7/site-packages/shush +``` + +### [ADAFRUIT VERSION] Check CircuitPython's install + +Start by following [Adafruit's guide](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi). You can start at the chapter `Install Python Libraries`. + +#### Testing the installation and the wiring + +It is recommended to test this setup by creating this small script under the name `test/blinkatest.py` and running it (you can use the editor nano if you are using the terminal). If you are using the image provided, you may find that the script is already there. + +```python +#!/usr/bin/python3 +import board +import digitalio +import busio + + +print("Hello blinka!") + +# Try to great a Digital input +pin = digitalio.DigitalInOut(board.D4) +print("Digital IO ok!") + +# Try to create an I2C device +i2c = busio.I2C(board.SCL, board.SDA) +print("I2C ok!") + +# Try to create an SPI device +spi = busio.SPI(board.SCLK, board.MOSI, board.MISO) +print("SPI ok!") + +print("done!") +``` + +To start the script, just run the following: + +```sh +chmod +x test/blinkatest.py +./test/blinkatest.py +``` + +The output should be similar to this: + +```sh +pi@planktoscope:~ $ ./test/blinkatest.py +Hello blinka! +Digital IO ok! +I2C ok! +SPI ok! +done! +``` + +Also, to make sure the wiring is good, we are going to use `sudo i2cdetect -y 1` to see if our devices are detected: + +```sh +pi@planktoscope:~ $ sudo i2cdetect -y 1 + 0 1 2 3 4 5 6 7 8 9 a b c d e f +00: -- -- -- -- -- -- -- -- -- -- 0d -- -- +10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +30: -- -- -- -- -- -- -- -- -- -- -- -- 3c -- -- -- +40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +60: 60 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +70: 70 -- -- -- -- -- -- -- +``` + +The device appearing at addresses 60 and 70 is our motor controller. Address `0d` is the fan controller and `3c` is the oled screen (we'll set up both a bit further down). Your version of the RGB Cooling Hat may not have the screen, it's fine as the screen is not necessary for proper operation of the Planktoscope. + +In case the motor controller does not appear, shutdown your Planktoscope and check the wiring. If your board is using a connector instead of a soldered pin connection (as happens with the Adafruit Bonnet Motor Controller), sometimes the pins on the male side need to be bent a little to make good contact. In any case, do not hesitate to ask for help in Slack. + +### [PSCOPE_HAT VERSION] Test the stepper controllers + +After wiring the steppers, please run the following script, you can create it in `~/test/stepper_controller.py`: + +```python +#!/usr/bin/python3 +import shush +import time + +m1 = shush.Motor(0) +m1.enable_motor() +m2 = shush.Motor(1) +m2.enable_motor() + + +# This function takes the target position as an input. +# It prints the current position and the iteration. +# The motor spins until it gets to the target position +# before allowing the next command. +def spin(motor, target): + motor.go_to(target) + + i = 0 + + while motor.get_position() != target: + print(motor.get_position()) + print(i) + i += 1 + + +while True: + # Spin 5 rotations from start + spin(m1, 256000) + + time.sleep(0.5) + # Spin back 5 rotations to starting point + spin(m1, 0) + + time.sleep(0.5) + # Spin 5 rotations from start + spin(m2, 256000) + + time.sleep(0.5) + # Spin back 5 rotations to starting point + spin(m2, 0) + + time.sleep(0.5) +``` + +To start the script, just run the following: + +```sh +chmod +x ~/test/stepper_controller.py +~/test/stepper_controller.py +``` + +The pump should run in one direction then in the other, and the focus stage should move in one direction and then in another. + +### Deactivate steppers + +Create `sudo nano /etc/systemd/system/gpio-init.service`: + +``` +[Unit] +Description=GPIO Init +DefaultDependencies=false + +[Service] +Type=oneshot +ExecStart=/usr/bin/stepper-disable +Restart=no + +[Install] +WantedBy=sysinit.target +``` + +And activate with `sudo systemctl enable autohotspot.service`. + +Create the script with `sudo nano /usr/bin/stepper-disable`: + +```sh +#!/bin/sh -e + + +# Initialise GPIO 4 and 12 to output to deactivate the steppers +if [ ! -e /sys/class/gpio/gpio4 ]; then + echo "4" > /sys/class/gpio/export +fi + +if [ ! -e /sys/class/gpio/gpio12 ]; then + echo "12" > /sys/class/gpio/export +fi +echo "out" > /sys/class/gpio/gpio4/direction +echo "out" > /sys/class/gpio/gpio12/direction +echo "1" > /sys/class/gpio/gpio4/value +echo "1" > /sys/class/gpio/gpio12/value +``` + +### Install Ultimate GPS HAT + +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 +sudo apt install gpsd gpsd-clients +stty -F /dev/serial0 raw 9600 cs8 clocal -cstopb +cat /dev/serial0 +``` + +If the GPS works, you should now see NMEA sentences scrolling: + +``` +$GPGGA,000908.799,,,,,0,00,,,M,,M,,*7E +$GPGSA,A,1,,,,,,,,,,,,,,,*1E +$GPGSV,1,1,00*79 +$GPRMC,000908.799,V,,,,,0.00,0.00,060180,,,N*44 +$GPVTG,0.00,T,,M,0.00,N,0.00,K,N*32 +$GPGGA,000909.799,,,,,0,00,,,M,,M,,*7F +$GPGSA,A,1,,,,,,,,,,,,,,,*1E +$GPRMC,000909.799,V,,,,,0.00,0.00,060180,,,N*45 +$GPVTG,0.00,T,,M,0.00,N,0.00,K,N*32 +$GPGGA,000910.799,,,,,0,00,,,M,,M,,*77 +$GPGSA,A,1,,,,,,,,,,,,,,,*1E +$GPRMC,000910.799,V,,,,,0.00,0.00,060180,,,N*4D +$GPVTG,0.00,T,,M,0.00,N,0.00,K,N*32 +``` + +Until you get a GPS fix, most of the sentences are empty (see the lines starting with GPGSA and with lot of commas). + +We are going to use gpsd to parse the GPS data. We need to set it up by editing `/etc/default/gpsd`. This file is source just before starting gpsd and allows to configure its working. + +```sh +sudo nano /etc/default/gpsd +``` + +Change the `USB_AUTO` line to read `false` + +```sh +USBAUTO="false" +``` + +Also change the `DEVICES` line to add the device we are going to use `/dev/serial0`: + +```sh +DEVICES="/dev/serial0" +``` + +Finally, we want to add the parameter `-n -r` to `GPSD_OPTIONS`: + +```sh +GPSD_OPTIONS="-n -r" +``` + +Save your work, and restart gpsd by running the following: + +```sh +sudo systemctl restart gpsd.service +``` + +If you wait a bit, you can run `gpsmon` to check that your configuration is correct. You should get an output similar to this: + +``` +pi@planktoscope:~ $ gpsmon +/dev/serial0 NMEA0183> +┌──────────────────────────────────────────────────────────────────────────────┐ +│Time: 2020-07-21T11:09:26.000Z Lat: 45 33' 28.08539" Non: 1 03' 44.02019" W│ +└───────────────────────────────── Cooked TPV ─────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────────────────────┐ +│ GPGGA GPGSA GPRMC GPZDA GPGSV │ +└───────────────────────────────── Sentences ──────────────────────────────────┘ +┌──────────────────┐┌────────────────────────────┐┌────────────────────────────┐ +│Ch PRN Az El S/N ││Time: 110926.000 ││Time: 110927.000 │ +│ 0 27 351 78 49 ││Latitude: 4533.4809 N ││Latitude: 4533.4809 │ +│ 1 21 51 69 47 ││Longitude: 00103.7367 W ││Longitude: 00103.7367 │ +│ 2 16 184 61 43 ││Speed: 0.00 ││Altitude: -0.1 │ +│ 3 10 116 51 50 ││Course: 201.75 ││Quality: 2 Sats: 11 │ +│ 4 8 299 47 49 ││Status: A FAA: D ││HDOP: 0.87 │ +│ 5 20 66 42 46 ││MagVar: ││Geoid: 49.3 │ +│ 6 123 138 28 43 │└─────────── RMC ────────────┘└─────────── GGA ────────────┘ +│ 7 26 165 25 30 │┌────────────────────────────┐┌────────────────────────────┐ +│ 8 11 264 23 48 ││Mode: A3 ...s: 27 21 16 10 ││UTC: RMS: │ +│ 9 7 303 15 38 ││DOP: H=0.87 V=1.13 P=1.42 ││MAJ: MIN: │ +│10 18 56 14 44 ││TOFF: 0.530187817 ││ORI: LAT: │ +│11 30 330 5 35 ││PPS: ││LON: ALT: │ +└────── GSV ───────┘└──────── GSA + PPS ─────────┘└─────────── GST ────────────┘ +(42) $GPGSV,4,4,14,15,03,035,36,01,02,238,*72 +(72) $GPRMC,110922.000,A,4533.4809,N,00103.7366,W,0.01,322.19,210720,,,D*7E +(35) $GPZDA,110922.000,21,07,2020,,*5B +(81) $GPGGA,110923.000,4533.4809,N,00103.7367,W,2,11,0.87,-0.1,M,49.3,M,0000,0000*5B +(64) $GPGSA,A,3,16,27,30,10,18,21,20,08,11,07,26,,1.43,0.87,1.13*0B +(72) $GPRMC,110923.000,A,4533.4809,N,00103.7367,W,0.01,188.90,210720,,,D*7D +(35) $GPZDA,110923.000,21,07,2020,,*5A +(81) $GPGGA,110924.000,4533.4809,N,00103.7367,W,2,11,0.87,-0.1,M,49.3,M,0000,0000*5C +(64) $GPGSA,A,3,16,27,30,10,18,21,20,08,11,07,26,,1.43,0.87,1.13*0B +(72) $GPRMC,110924.000,A,4533.4809,N,00103.7367,W,0.01,156.23,210720,,,D*71 +``` + +You can leave with `CTRL+C`. + +#### Bonus Configuration: Automatic time update from GPSD + +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`: + +``` +sudo nano /boot/config.txt +# Add the following line at the end of the line +dtoverlay=pps-gpio,gpiopin=4 +``` + +We also need to activate the pps module of the kernel, by editing `/etc/modules`: + +``` +sudo nano /etc/modules +# Add the following line at the end of the line +pps-gpio +``` + +Now install `pps-tools` so we can check that this is properly running. + +```sh +sudo apt install pps-tools +``` + +Finally, in the `/etc/default/gpsd` file, we need to add our pps device to the line `DEVICES`. Append `/dev/pps0`: + +```sh +DEVICES="/dev/serial0 /dev/pps0" +``` + +Reboot your PlanktoScope now and check that the PPS signal is properly parsed by the PlanktoScope. You can do this by running `sudo ppstest /dev/pps0`: + +``` +pi@planktoscope:~ $ sudo ppstest /dev/pps0 +trying PPS source "/dev/pps0" +found PPS source "/dev/pps0" +ok, found 1 source(s), now start fetching data... +source 0 - assert 1595329939.946478786, sequence: 4125 - clear 0.000000000, sequence: 0 +source 0 - assert 1595329940.946459463, sequence: 4126 - clear 0.000000000, sequence: 0 +``` + +`gpsmon` should also show a PPS signal in the `GSA + PPS` box. + +We now need to install the software that will act as timeserver, both locally and globally. Its name is Chrony. It's a more modern replacement for `ntp`, using the same underlying protocol. Let's go ahead and install it: + +```sh +sudo apt install chrony +``` + +We need to edit the configuration of chrony, to activate both the GPS time synchronization and to allow clients to request time updates directly from our microscope. + +Edit the file `/etc/chrony/chrony.conf` and replace its content with the following: + +``` +pool pool.ntp.org iburst maxsources 4 + +driftfile /var/lib/chrony/drift + +# allow to make big changes to clock if difference with ref clock is more than 1 seconds +makestep 1 5 + +refclock SHM 0 refid NMEA offset 0.006 +refclock SHM 1 pps refid NME+ +refclock SOCK /var/run/chrony.sock delay 0.0 refid SOCK +# noselect poll 8 filter 1000 +#refclock PPS /dev/pps0 precision 1e-7 noselect refid GPPS + +allow all + +rtcsync + +logdir /var/log/chrony +log rtc refclocks +``` + +Before restarting `chrony`, we need to make sure the timesync service from systemd is deactivated: + +```sh +sudo systemctl stop systemd-timesyncd.service +sudo systemctl disable systemd-timesyncd.service +``` + +Final step, let's start `chrony` with its new configuration and restart `gpsd`: + +```sh +sudo systemctl restart chrony +sudo systemctl restart gpsd +``` + +To check that everything is working as intended, wait a few minutes, and then type `chronyc sources -v`. This command will show the time sources `chrony` is using, and right at the top there should be our NMEA source. Make sure its line starts with `#*`, which means this source is selected: + +``` +pi@planktoscope:~ $ chronyc sources -v +210 Number of sources = 5 + + .-- Source mode '^' = server, '=' = peer, '#' = local clock. + / .- Source state '*' = current synced, '+' = combined , '-' = not combined, +| / '?' = unreachable, 'x' = time may be in error, '~' = time too variable. +|| .- xxxx [ yyyy ] +/- zzzz +|| Reachability register (octal) -. | xxxx = adjusted offset, +|| Log2(Polling interval) --. | | yyyy = measured offset, +|| \ | | zzzz = estimated error. +|| | | \ +MS Name/IP address Stratum Poll Reach LastRx Last sample +=============================================================================== +#* NMEA 0 4 377 13 -434ns[ -582ns] +/- 444ns +^- mail.raveland.org 3 7 377 215 -18ms[ -18ms] +/- 53ms +^- nio.nucli.net 2 6 377 19 -7340us[-7340us] +/- 63ms +^- ntp4.kashra-server.com 2 8 377 146 -11ms[ -11ms] +/- 50ms +^- pob01.aplu.fr 2 8 377 83 -15ms[ -15ms] +/- 66ms +``` + +The other servers are here just as fallback measures, in case the GPS is not working for an unknown reason. + +This part is now complete! Everytime you start your Planktoscope, it will set its own time after a few minutes (once a GPS signal is acquired). + +The ultimate step will have to be done on the other equipment on the network where you want to use this time source. You will need to add the line `server planktoscope.local` to your ntp configuration file either at `/etc/ntp.conf` or at `/etc/chrony/chrony.conf` and then restart your ntp service. + +You can find more information in this hardware module in Adafruit documentation at [Installing Adafruit GPS HAT](https://learn.adafruit.com/adafruit-ultimate-gps-hat-for-raspberry-pi/overview) or on this page to [use Python Thread with GPS HAT](http://www.danmandle.com/blog/getting-gpsd-to-work-with-python/) + +### Install RGB Cooling HAT + +To setup the RGB Cooling HAT, you just need to clone and build the WiringPi library: + +```sh +cd ~/libraries +git clone https://github.com/WiringPi/WiringPi.git +cd WiringPi +sudo ./build +gpio -v +``` + +The last command should output something similar to the following: + +``` +gpio version: 2.60 +Copyright (c) 2012-2018 Gordon Henderson +This is free software with ABSOLUTELY NO WARRANTY. +For details type: gpio -warranty + +Raspberry Pi Details: + Type: Pi 4B, Revision: 01, Memory: 4096MB, Maker: Sony + * Device tree is enabled. + *--> Raspberry Pi 4 Model B Rev 1.1 + * This Raspberry Pi supports user-level GPIO access. + +``` + +You will also need to install some python modules: + +```sh +sudo apt install i2c-tools +sudo pip3 install smbus2 +``` + +More information can be found on Yahboom website, on the page [Installing RGB Cooling HAT](https://www.yahboom.net/study/RGB_Cooling_HAT). + +### Install Mosquitto MQTT + +In order to send and receive data from Node-RED, you need to install this. Run the following: + +``` +sudo apt install mosquitto mosquitto-clients + +``` + +### Check OpenCV's installation + +We need to install the latest OpenCV version. Unfortunately, it is not available in the repositories. We are going to install it directly by using pip. + +First, we need to install the needed dependencies, then we will directly install opencv: + +```sh +sudo apt install libgtk-3-0 libavformat58 libavcodec58 libqt4-test libopenexr23 libilmbase23 libqtgui4 libavutil56 libjasper1 libqtcore4 libcairo-gobject2 libswscale5 libhdf5-dev libilmbase-dev libopenexr-dev libgstreamer1.0-dev libavcodec-dev libavformat-dev libswscale-dev libwebp-dev libatlas-base-dev +``` + +Install now openCV diretly with pip: + +```sh +pip install opencv-contrib-python +``` + +You can now check that opencv is properly installed by running a python interpreter and importing the cv2 module. + +```sh +pi@planktoscope:~ $ python3 +Python 3.7.3 (default, Jan 22 2021, 20:04:44) +[GCC 8.3.0] on linux +Type "help", "copyright", "credits" or "license" for more information. +>>> import cv2 +>>> cv2.__version__ +'4.4.0' +>>> quit() +``` + +If all goes well, the displayed version number should be `4.4.0`. + +More detailed information can be found on this [website](https://www.pyimagesearch.com/2019/09/16/install-opencv-4-on-raspberry-pi-4-and-raspbian-buster/). + +### Check MorphoCut's installation + +To test the installation, open up once again a python interpreter and import the morphocut module: + +```sh +pi@planktoscope:~ $ python3 +Python 3.7.3 (default, Dec 20 2019, 18:57:59) +[GCC 8.3.0] on linux +Type "help", "copyright", "credits" or "license" for more information. +>>> import morphocut +>>> morphocut.__version__ +'0.1.1+42.g01a051e' +>>> quit() +``` + +The MorphoCut documentation can be found [on this page](https://morphocut.readthedocs.io/en/stable/index.html). + +### Nginx Setup + +To display the gallery, we need to setup an nginx webserver. + +Type in the following commands: + +``` +sudo apt install nginx +sudo rm /etc/nginx/sites-enabled/default +sudo ln -s /home/pi/PlanktoScope/scripts/gallery/gallery.conf /etc/nginx/sites-enabled/gallery.conf +sudo nginx -t && sudo systemctl reload nginx +``` + +If you navigate to , you should see the library opened. + +### Install Node-RED + +#### Download and installation + +To install Node.js, npm and Node-RED onto a Raspberry Pi, you just need to run the following command. You can review the content of this script [here](https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered). + +```sh +bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered) +``` + +Type `y` at both prompts to accept the installation and its settings. + +### Override Node-RED default settings to make it start after Mosquitto + +We need to make sure nodered only starts after Mosquitto. And Mosquitto waits for a network connection to appear before starting. + +To change this behavior, we need to override Node-red default setting. We modify the default service unit file with the following: + +```sh +sudo mkdir -p /etc/systemd/system/nodered.service.d/ +sudo cp /home/pi/PlanktoScope/scripts/raspbian_configuration/etc/systemd/system/nodered.service.d/override.conf /etc/systemd/system/nodered.service.d/override.conf +sudo systemctl daemon-reload +``` + +#### Enable start on boot and launch Node-RED + +To run Node-RED when the Pi is turned on or restarted, you need to enable the systemd service by running this command: + +```sh +sudo systemctl enable nodered.service +``` + +You can now start Node-RED by running the following: + +```sh +sudo systemctl start nodered.service +``` + +#### Check the installation + +Make sure Node-RED is correctly installed by reaching the following page from the browser of your pi or from another computer on the same network. + +#### Install the necessary nodes and activate necessary features + +We are going to activate the Projects feature of Node-Red as this will help us manage and track changes to the flows. Open the file `settings.js` with an editor (for example with `nano ~/.node-red/settings.js`) so we can change the following lines (you can use `CTRL+_` to quickly navigate to the line indicated): + +- Line 75: uncomment the line (remove the //) that ends with flowFilePretty: true, +- Line 337: set enabled to true + +Restart Node-RED to take into account those changes: + +```sh +sudo systemctl restart nodered.service +``` + +We need to move the PlanktoScope folder in the right place, in the `projects` subfolder of Node-Red and link this new folder to our `/home/`. To do so, in the terminal type the following:: + +```sh +mv /home/pi/PlanktoScope /home/pi/.node-red/projects/ +ln -s ./.node-red/projects/PlanktoScope /home/pi/PlanktoScope +``` + +We will now install the missing nodes. These nodes will be used by the PlanktoScope software: + +```sh +cd /home/pi/.node-red/ +npm install copy-dependencies +node_modules/copy-dependencies/index.js projects/PlanktoScope ./ +npm update +``` + +Save you changes. + +The final step before restarting node-red is to link the projects directory from within node-red folder to our main home directory. To do so, just open a terminal and type the following: + +You can now restart the nodered service: + +``` +sudo systemctl restart nodered.service +``` + +#### Import the last GUI + +If you now open the Node-Red GUI in your browser, it will ask you to setup the project, an email and a username (so if you make changes to the flow and want to share them we can know who made them). + +Open your browser and navigate to . In the prompt, select `Open existing project` button at the bottom, choose the PlanktoScope project and click on `Open Project`. Eventually, merge the proposed changes. + +The latest flow version will be available immediately. + +#### More information + +[Installing Node-RED on Raspberry Pi](https://nodered.org/docs/getting-started/raspberrypi) + +## Finishing the install + +Make sure to update your Pi + +``` +sudo apt update -y +sudo apt full-upgrade -y +``` + +Reboot your Pi safely + +``` +sudo reboot now + +``` + +## Useful later maybe + +### Update the cloned repository + +Updates are published on Github regurlarly. Make sure to update once in a while by running this command: + +```sh +cd PlanktoScope +git pull +``` + +This will pull and merge all the changes made since your last update. + +### Share WiFi via Ethernet + +At this link : diff --git a/docs/software/update_devicetree.md b/docs/software/update_devicetree.md new file mode 100644 index 0000000..aaeb171 --- /dev/null +++ b/docs/software/update_devicetree.md @@ -0,0 +1,130 @@ + + +# 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: + +- one for connection to an LED based flash (xenon flashes won't work with the camera module due to it having a `rolling shutter`). This will fire before (`flash metering`) and during capture +- one for an optional privacy indicator (a requirement for cameras in some jurisdictions). This will fire after taking a picture to indicate that the + camera has been used + +These pins are configured by updating the `VideoCore device tree blob`. Firstly, install the device tree compiler, then grab a copy of the default +device tree source: + +```sh +sudo apt-get install device-tree-compiler +wget https://github.com/raspberrypi/firmware/raw/master/extra/dt-blob.dts +``` + +The device tree source contains a number of sections enclosed in curly braces, which form a hierarchy of definitions. The section to edit will depend on which revision of Raspberry Pi you have (check the silk-screen writing on the board for the revision number if you are unsure): + +| Model | Section | +| -------------------------------------- | :----------------------- | +| Raspberry Pi Model B rev 1 | `/videocore/pins_rev1` | +| Raspberry Pi Model A and Model B rev 2 | `/videocore/pins_rev2` | +| Raspberry Pi Model A+ | `/videocore/pins_aplus` | +| Raspberry Pi Model B+ rev 1.1 | `/videocore/pins_bplus1` | +| Raspberry Pi Model B+ rev 1.2 | `/videocore/pins_bplus2` | +| Raspberry Pi 2 Model B rev 1.0 | `/videocore/pins_2b1` | +| Raspberry Pi 2 Model B rev 1.1-1.2 | `/videocore/pins_2b2` | +| Raspberry Pi 3 Model B rev 1.0 | `/videocore/pins_3b1` | +| Raspberry Pi 3 Model B rev 1.2 | `/videocore/pins_3b2` | +| Raspberry Pi Zero rev 1.2-1.3 | `/videocore/pins_pi0` | + +Under the section for your particular model of Pi you will find `pin_config` and `pin_defines` sections. Under the `pin_config` section you need to configure the GPIO pins you want to use for the flash and privacy indicator as using pull down termination. Then, under the `pin_defines` section you need to associate those pins with the `FLASH_0_ENABLE` and `FLASH_0_INDICATOR` pins. + +For example, to configure GPIO 17 as the flash pin, leaving the privacy indicator pin absent, on a Raspberry Pi 2 Model B rev 1.1 you would add the following line under the `/videocore/pins_2b2/pin_config` section: + +```txt +pin@p17 { function = "output"; termination = "pull_down"; }; +``` + +Please note that GPIO pins will be numbered according to the `Broadcom pin numbers`(BCM mode in the RPi.GPIO library, _not_ BOARD mode). Then change the following section under `/videocore/pins_2b2/pin_defines`. Specifically, change the type from "absent" to "internal", and add a number property defining the flash pin as GPIO 17: + +```c +pin_define@FLASH_0_ENABLE { + type = "internal"; + number = <17>; +}; +``` + +With the device tree source updated, you now need to compile it into a binary blob for the firmware to read. This is done with the following command line: + +```sh +dtc -q -I dts -O dtb dt-blob.dts -o dt-blob.bin +``` + +Dissecting this command line, the following components are present: + +- `dtc` - Execute the device tree compiler +- `-I dts` - The input file is in device tree source format +- `-O dtb` - The output file should be produced in device tree binary format +- `dt-blob.dts` - The first anonymous parameter is the input filename +- `-o dt-blob.bin` - The output filename + +This should output nothing. If you get lots of warnings, you've forgotten the `-q` switch; you can ignore the warnings. If anything else is output, it will most likely be an error message indicating you have made a mistake in the device tree source. In this case, review your edits carefully (note that sections and properties _must_ be semi-colon terminated for example), and try again. + +Now the device tree binary blob has been produced, it needs to be placed on the first partition of the SD card. In the case of non-NOOBS Raspbian installs, this is generally the partition mounted as `/boot`: + +```sh +sudo cp dt-blob.bin /boot/ +``` + +However, in the case of NOOBS Raspbian installs, this is the recovery partition, which is not mounted by default: + +```sh +sudo mkdir /mnt/recovery +sudo mount /dev/mmcblk0p1 /mnt/recovery +sudo cp dt-blob.bin /mnt/recovery +sudo umount /mnt/recovery +sudo rmdir /mnt/recovery +``` + +Please note that the filename and location are important. The binary blob must be named `dt-blob.bin` (all lowercase), and it must be placed in the root +directory of the first partition on the SD card. Once you have rebooted the Pi (to activate the new device tree configuration) you can test the flash with the following simple script: + +```python +import picamera + +with picamera.PiCamera() as camera: + camera.flash_mode = 'on' + camera.capture('foo.jpg') +``` + +You should see your flash LED blink twice during the execution of the script. + +!!! warning +The GPIOs only have a limited current drive which is insufficient for powering the sort of LEDs typically used as flashes in mobile phones. You will require a suitable drive circuit to power such devices, or risk damaging your Pi. + +For reference, the flash driver chips we have used on mobile phones will often drive up to 500mA into the LED. If you're aiming for that, then please think about your power supply too. + +If you wish to experiment with the flash driver without attaching anything to the GPIO pins, you can also reconfigure the camera's own LED to act as the flash LED. Obviously this is no good for actual flash photography but it can demonstrate whether your configuration is good. In this case you need not add anything to the `pin_config` section (the camera's LED pin is already defined to use pull down termination), but you do need to set `CAMERA_0_LED` to absent, and `FLASH_0_ENABLE` to the old `CAMERA_0_LED` definition (this will be pin 5 in the case of `pins_rev1` and `pins_rev2``, and pin 32 in the case of everything else). + +For example, change: + +```c +pin_define@CAMERA_0_LED { + type = "internal"; + number = <5>; +}; +pin_define@FLASH_0_ENABLE { + type = "absent"; +}; +``` + +into this: + +```c +pin_define@CAMERA_0_LED { + type = "absent"; +}; +pin_define@FLASH_0_ENABLE { + type = "internal"; + number = <5>; +}; +``` + +After compiling and installing the device tree blob according to the instructions above, and rebooting the Pi, you should find the camera LED now +acts as a flash LED with the Python script above. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..9edc066 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,7 @@ +[data-md-color-primary=indigo] { + --md-accent-fg-color: #674ea7; + --md-primary-fg-color--dark: #674ea7; + --md-primary-fg-color--light: #674ea7; + --md-primary-fg-color: #674ea7; + --md-typeset-a-color: #674ea7; +} diff --git a/docs/usage/getting_started.md b/docs/usage/getting_started.md new file mode 100644 index 0000000..d7d055e --- /dev/null +++ b/docs/usage/getting_started.md @@ -0,0 +1,34 @@ + + +# Getting started with using the machine + +Congratulations! You have finished assembling your machine, now is the time to test it and learn how to use it! + +## How to connect to and control the machine + +On powering up, your PlanktoScope will create its own isolated WiFi network. It should appear on the list of available wifi networks about two minutes after the first startup. +![network list](../images/getting_started/wifi.webp) + +As you can see, its name will be similar to `PlanktoScope-Baba*****_*****`. This name is unique to your machine and is linked to the serial number of the Raspberry CPU. You can connect to this network now. + +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. + +From there, you can have a look at the [UI guide](ui_guide.md) to get a handle on how it works. + +## How to image plankton + +Before doing an acquisition, you will need to collect targets. There are several ways to do this, and you probably already have a source nearby (in a culture if you are working in a lab). + +However, if you have access to a body of water (even a tiny lake or river is enough), you can build yourself a plankton net to collect a sample. Once the sample is collected, either pump it with a syringe that you connect to the machine, or dip one of the silicone tube inside the sample tube you have. + +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. + + 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. diff --git a/docs/usage/mqtt_messages.md b/docs/usage/mqtt_messages.md new file mode 100644 index 0000000..01e8dc4 --- /dev/null +++ b/docs/usage/mqtt_messages.md @@ -0,0 +1,231 @@ + + +# 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) + +## Topic details + +### `actuator` + +#### `actuator/pump` + +Control the movement of the pump. The message is a JSON object: + +```json +{ + "action": "move", + "direction": "FORWARD", + "volume": 10, + "flowrate": 1 +} +``` + +This messages make the pump move 10mL forward at 1mL/min. + +Another supported message is: + +```json +{ + "action": "stop" +} +``` + +- Receive only + +#### `actuator/focus` + +Control of the focus stage. The message is a JSON object, speed is optional: + +```json +{ + "action": "move", + "direction": "UP", + "distance": 0.26, + "speed": 1 +} +``` + +This message makes the stage move up by 10mm. + +Another supported message is: + +```json +{ + "action": "stop" +} +``` + +- Receive only + +### `imager/image` + +This topic controls the camera and capture. The message allowed is a JSON message: + +```json +{ + "action": "image", + "pump_direction": "FORWARD", + "volume": 1, + "nb_frame": 200 +} +``` + +Volume is in mL. + +This topic can also receive a config update message: + +```json +{ + "action": "config", + "config": {...} +} +``` + +A camera settings message can also be received here. The fields `iso`, `shutter_speed`, `white_balance_gain`, `white_balance` and `image_gain` are optionals: + +```json +{ + "action": "settings", + "settings":{ + "iso": 100, + "shutter_speed": 40, + "white_balance_gain": {"red": 100, "blue": 100}, + "white_balance": "auto", + "image_gain": {"analog": 100, "digital": 100} + } +} +``` + +- Receive only + +### `segmenter/segment` + +This topic controls the segmentation process. The message is a JSON object: + +```json +{ + "action": "segment", + "path": "/path/to/segment", + "settings": { + "force": False, + "recursive": True, + "ecotaxa": True, + "keep": True + } +} +``` + +`action` can also be `stop`. +The `action` element is the only element required. If no `path` is supplied, the whole images repository is segmented recursively (this is very long!). + +`force` is going to overcome the presence of the file `done` that is here to prevent for resegmenting a folder already segmented. + +`recursive` will force parsing all folders below `path`. + +`ecotaxa` activates the export of an ecotaxa compatible archive. + +`keep` allows to remove or keep the roi (when you do an ecotaxa export, no effects otherwise, the roi are kept). + +- Receive only + +### `status` + +This high-level topic is used to send information to the Node-Red process. There is no publication or receive at this level. + +#### `status/pump` + +State of the pump. It's a JSON object with: + +```json +{ + "status": "Started", + "duration": 25 +} +``` + +Duration is a best guess estimate. It should not be used to control the other events. If you want to wait for a movement to finish, the best thing to do is to wait for the message `Done`. + +Status can be `Started`, `Ready`, `Done`, `Interrupted`, `Error`, `Dead`. + +- Publish only + +#### `status/focus` + +State of the focus stage. It's a JSON object with: + +```json +{ + "status": "Started", + "duration": 25 +} +``` + +Duration is a best guess estimate. It should not be used to control the other events. If you want to wait for a movement to finish, the best thing to do is to wait for the message `Done`. + +Status is one of `Started`, `Ready`, `Done`, `Interrupted`, `Error`, `Dead`. + +- Publish only + +#### `status/imager` + +State of the imager. It's a JSON object with: + +```json +{ + "status": "Started", + "time_left": 25 +} +``` + +Status is one of `Started`, `Ready`, `Completed` or `12_11_15_0.1.jpg has been imaged`. + +- Publish only + +#### `status/segmenter` + +Status of the segmentation. It's a JSON object with: + +```json +{ + "status": "Started", +} +``` + +`status` is one of `Started`, `Done`, `Interrupted`, `Busy`, `Ready` or `Dead`. + +- Publish only + +#### `status/segmenter/object_id` + +```json +{ + "object_id": "13449" +} +``` + +#### `status/segmenter/metric` + +```json +{ + "name": "01_13_28_232066_0", + "metadata": { + "label": 0, "width": 29, "height": 80, .... +} +``` diff --git a/docs/usage/remote_access.md b/docs/usage/remote_access.md new file mode 100644 index 0000000..58c1c80 --- /dev/null +++ b/docs/usage/remote_access.md @@ -0,0 +1,408 @@ + + +# 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). + +All the files modified in this document are also available in the repository, in the folder `scripts/raspbian_configuration`. The architecture of this folder shows where each file belong. + +In order to work as an access point, the Raspberry Pi will need to have access point software installed, along with DHCP server software to provide connecting devices with a network address. + +To create an access point, we'll need DNSMasq and HostAPD. Install all the required software in one go with this command:: + +```sh +sudo apt install dnsmasq hostapd +``` + +Since the configuration files are not ready yet, turn the new software off as follows:: + +```sh +sudo systemctl unmask hostapd +sudo systemctl disable dnsmasq +sudo systemctl disable hostapd +``` + +## Configuring HostAPD + +Using a text editor edit the hostapd configuration file. This file won't exist at this stage so will be blank: `sudo nano /etc/hostapd/hostapd.conf` + +```txt +#2.4GHz setup wifi 80211 b,g,n +interface=wlan0 +driver=nl80211 +ssid=PlanktoScope-Bababui_Tuogaore +hw_mode=g +channel=8 +wmm_enabled=0 +macaddr_acl=0 +auth_algs=1 +ignore_broadcast_ssid=0 +wpa=2 +wpa_passphrase=copepode +wpa_key_mgmt=WPA-PSK +wpa_pairwise=CCMP TKIP +rsn_pairwise=CCMP + +#80211n - Change GB to your WiFi country code +country_code=FR +ieee80211n=1 +ieee80211d=1 +``` + +The interface will be wlan0. The driver nl80211 works with the Raspberry RPi 4, RPi 3B+, RPi 3 & Pi Zero W onboard WiFi but you will need to check that your wifi dongle is compatable and can use Access Point mode. + +For more information on wifi dongles see elinux.org/RPi_USB_Wi-Fi_Adapters + +The SSID is the name of the WiFi signal broadcast from the RPi, which you will connect to with your Tablet or phones WiFi settings. +Channel can be set between 1 and 13. If you are having trouble connection because of to many wifi signals in your area are using channel 8 then try another channel. +Wpa_passphrase is the password you will need to enter when you first connect a device to your Raspberry Pi's hotspot. This should be at least 8 characters and a bit more difficult to guess than my example. +The country_code should be set to your country to comply with local RF laws. You may experience connection issues if this is not correct. Your country_code can be found in /etc/wpa_supplicant/wpa_supplicant.conf or in Raspberry Pi Configuration - Localisation settings + +To save the config file press `CTRL+O` and to exit press `CTRL+X`. + +We also use a special function to change the network name to the machine name. Add this to `/etc/rc.local` with `sudo nano /etc/rc.local`: + +```sh +# Replace wifi hostname +sed -i "s/^ssid.*/ssid=PlanktoScope-$(python3 -c "import planktoscope.uuidName as uuidName; print(uuidName.machineName(machine=uuidName.getSerial()).replace(' ','_'))")/" /etc/hostapd/hostapd.conf +``` + +Now the defaults file needs to be updated to point to where the config file is stored. +In terminal enter the command `sudo nano /etc/default/hostapd` + +Change `#DAEMON_CONF=""` to `DAEMON_CONF="/etc/hostapd/hostapd.conf"` + +Check the `DAEMON_OPTS=""` is preceded by a #, so is `#DAEMON_OPTS=""`. + +And save. + +## DNSmasq configuration + +Next dnsmasq needs to be configured to allow the Rpi to act as a router and issue ip addresses. Open the dnsmasq.conf file with `sudo nano /etc/dnsmasq.conf` + +Go to the bottom of the file and add the following lines: + +```txt +#AutoHotspot config +interface=wlan0 +bind-dynamic +server=1.1.1.1 +domain-needed +bogus-priv +dhcp-range=192.168.4.100,192.168.4.200,12h + +#AutoEthernet config +interface=eth0 +bind-dynamic +server=1.1.1.1 +domain-needed +bogus-priv +dhcp-range=192.168.5.100,192.168.5.200,12h +``` + +and then save `CTRL+O` and exit `CTRL+X`. + +Reload dnsmasq to use the updated configuration: + +```sh +sudo systemctl reload dnsmasq +``` + +## DHCPCD + +DHCPCD is the software that manages the network setup. The next step is to stop dhcpcd from starting the wifi network so the autohotspot script in the next step takes control of that. Ethernet will still be managed by dhcpcd. + +This will also create a fallback configuration to a static IP if no DHCP server is present on the Ethernet network. + +Just add this line to the end of /etc/dhcpcd.conf with `sudo nano /etc/dhcpcd.conf`: + +```txt +nohook wpa_supplicant + +# define static profile +profile static_eth0 +static ip_address=192.168.5.1/24 +static routers=192.168.5.1 +static domain_name_servers=192.168.5.1 + +# fallback to static profile on eth0 +interface eth0 +fallback static_eth0 +``` + +Save and exit. + +For the fallback Ethernet network to work, we also need to add a hook to DHCPCD so it starts up the local DHCP server (dnsmasq). Edit the file `/etc/dhcpcd.enter-hook` with `sudo nano /etc/dhcpcd.enter-hook`: + +```sh +if [ "$interface" = "eth0" ] && [ "$if_up" ]; then + systemctl start dnsmasq + if [ "$reason" = "STATIC" ] || [ "$reason" = "TIMEOUT" ] || [ "$reason" = "EXPIRE" ] || [ "$reason" = "NAK" ]; then + systemctl start dnsmasq + elif [ "$reason" = "NOCARRIER" ] || [ "$reason" = "INFORM" ] || [ "$reason" = "DEPARTED" ]; then + systemctl stop dnsmasq + fi +fi +``` + +## Autohotspot service file + +Next we have to create a service which will run the autohotspot script when the Raspberry Pi starts up. +Create a new file with the command `sudo nano /etc/systemd/system/autohotspot.service` + +Then enter the following text: + +```txt +[Unit] +Description=Automatically generates a Hotspot when a valid SSID is not in range +After=multi-user.target +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStart=/usr/bin/autohotspotN +[Install] +WantedBy=multi-user.target +``` + +Save and exit. + +For the service to work it has to be enabled. To do this enter the command `sudo systemctl enable autohotspot.service`. + +## Service Timer + +Create the timer with `sudo nano /etc/systemd/system/autohotspot.timer`: + +```txt +# /etc/systemd/system/autohotspot.timer +[Unit] +Description=Run autohotspot every 5 minutes, starting 10 seconds after system boot + +[Timer] +OnBootSec=5sec +OnUnitActivateSec=5min + +[Install] +WantedBy=timers.target +``` + +Save and exit. + +Activate with `sudo systemctl enable autohotspot.timer`. + +### AutoHotspot Script + +This is the main script that will manage your wifi connections between a wifi router and an Access Point. + +It will search for any wifi connection that is setup on you Raspberry Pi by using the details found in /etc/wpa_supplicant/wpa_supplicant.conf + +If no wifi signal is found for a known SSID then the script will shutdown the wifi network setup and create a Hotspot. If an ethernet cable that allows internet access is connect then the Hotspot will become a full internet access point. Allowing all connected devices to use the Internet. Without an ethernet connect the Raspberry Pi can be accessed from a wifi device using SSH or VNC. + +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 + + 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=() + ``` + + 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: + +```sh +#!/bin/bash +#version 0.961-N/HS-I-PlanktonPlanet + +#changes by PlanktonPlanet includes the following: +#- formatting and shellcheck validation +#- removal of ip forwarding setup + +#You may share this script on the condition a reference to RaspberryConnect.com +#must be included in copies or derivatives of this script. + +#Network Wifi & Hotspot with Internet +#A script to switch between a wifi network and an Internet routed Hotspot +#A Raspberry Pi with a network port required for Internet in hotspot mode. +#Works at startup or with a seperate timer or manually without a reboot +#Other setup required find out more at +#http://www.raspberryconnect.com + +wifidev="wlan0" #device name to use. Default is wlan0. +ethdev="eth0" #Ethernet port to use with IP tables +#use the command: iw dev ,to see wifi interface name + +#These two lines capture the wifi networks the RPi is setup to use +wpassid=$(awk '/ssid="/{ print $0 }' /etc/wpa_supplicant/wpa_supplicant.conf | awk -F'ssid=' '{ print $2 }' | sed 's/\r//g' | awk 'BEGIN{ORS=","} {print}' | sed 's/\"/''/g' | sed 's/,$//') +IFS="," read -r -a ssids <<<"$wpassid" + +#Note:If you only want to check for certain SSIDs +#Remove the # in in front of ssids=('mySSID1'.... below and put a # infront of all four lines above +# separated by a space, eg ('mySSID1' 'mySSID2') +#ssids=('mySSID1' 'mySSID2' 'mySSID3') + +#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=() + +ssidsmac=("${ssids[@]}" "${mac[@]}") #combines ssid and MAC for checking + +createAdHocNetwork() { + echo "Creating Hotspot" + ip link set dev "$wifidev" down + ip a add 192.168.4.1/24 brd + dev "$wifidev" + ip link set dev "$wifidev" up + dhcpcd -k "$wifidev" >/dev/null 2>&1 + systemctl start dnsmasq + systemctl start hostapd +} + +KillHotspot() { + echo "Shutting Down Hotspot" + ip link set dev "$wifidev" down + systemctl stop hostapd + systemctl stop dnsmasq + ip addr flush dev "$wifidev" + ip link set dev "$wifidev" up + dhcpcd -n "$wifidev" >/dev/null 2>&1 +} + +ChkWifiUp() { + echo "Checking WiFi connection ok" + sleep 20 #give time for connection to be completed to router + if ! wpa_cli -i "$wifidev" status | grep 'ip_address' >/dev/null 2>&1; then #Failed to connect to wifi (check your wifi settings, password etc) + echo 'Wifi failed to connect, falling back to Hotspot.' + wpa_cli terminate "$wifidev" >/dev/null 2>&1 + createAdHocNetwork + fi +} + +chksys() { + #After some system updates hostapd gets masked using Raspbian Buster, and above. This checks and fixes + #the issue and also checks dnsmasq is ok so the hotspot can be generated. + #Check Hostapd is unmasked and disabled + if systemctl -all list-unit-files hostapd.service | grep "hostapd.service masked" >/dev/null 2>&1; then + systemctl unmask hostapd.service >/dev/null 2>&1 + fi + if systemctl -all list-unit-files hostapd.service | grep "hostapd.service enabled" >/dev/null 2>&1; then + systemctl disable hostapd.service >/dev/null 2>&1 + systemctl stop hostapd >/dev/null 2>&1 + fi + #Check dnsmasq is disabled + if systemctl -all list-unit-files dnsmasq.service | grep "dnsmasq.service masked" >/dev/null 2>&1; then + systemctl unmask dnsmasq >/dev/null 2>&1 + fi + if systemctl -all list-unit-files dnsmasq.service | grep "dnsmasq.service enabled" >/dev/null 2>&1; then + systemctl disable dnsmasq >/dev/null 2>&1 + systemctl stop dnsmasq >/dev/null 2>&1 + fi +} + +FindSSID() { + #Check to see what SSID's and MAC addresses are in range + ssidChk='NoSSid' + i=0 + j=0 + until [ $i -eq 1 ]; do #wait for wifi if busy, usb wifi is slower. + ssidreply=$( (iw dev "$wifidev" scan ap-force | grep -E "^BSS|SSID:") 2>&1) >/dev/null 2>&1 + #echo "SSid's in range: " $ssidreply + printf '%s\n' "${ssidreply[@]}" + echo "Device Available Check try " $j + if ((j >= 5)); then #if busy 5 times goto hotspot + echo "Device busy or unavailable 5 times, going to Hotspot" + ssidreply="" + i=1 + elif echo "$ssidreply" | grep "No such device (-19)" >/dev/null 2>&1; then + echo "No Device Reported, try " $j + NoDevice + elif echo "$ssidreply" | grep "Network is down (-100)" >/dev/null 2>&1; then + echo "Network Not available, trying again" $j + j=$((j + 1)) + sleep 2 + elif echo "$ssidreply" | grep "Read-only file system (-30)" >/dev/null 2>&1; then + echo "Temporary Read only file system, trying again" + j=$((j + 1)) + sleep 2 + elif echo "$ssidreply" | grep "Invalid exchange (-52)" >/dev/null 2>&1; then + echo "Temporary unavailable, trying again" + j=$((j + 1)) + sleep 2 + elif echo "$ssidreply" | grep -v "resource busy (-16)" >/dev/null 2>&1; then + echo "Device Available, checking SSid Results" + i=1 + else #see if device not busy in 2 seconds + echo "Device unavailable checking again, try " $j + j=$((j + 1)) + sleep 2 + fi + done + + for ssid in "${ssidsmac[@]}"; do + if (echo "$ssidreply" | grep -F -- "$ssid") >/dev/null 2>&1; then + #Valid SSid found, passing to script + echo "Valid SSID Detected, assesing Wifi status" + ssidChk=$ssid + return 0 + else + #No Network found, NoSSid issued" + echo "No SSid found, assessing WiFi status" + ssidChk='NoSSid' + fi + done +} + +NoDevice() { + #if no wifi device,ie usb wifi removed, activate wifi so when it is + #reconnected wifi to a router will be available + echo "No wifi device connected" + wpa_supplicant -B -i "$wifidev" -c /etc/wpa_supplicant/wpa_supplicant.conf >/dev/null 2>&1 + exit 1 +} + +chksys +FindSSID + +#Create Hotspot or connect to valid wifi networks +if [ "$ssidChk" != "NoSSid" ]; then + if systemctl status hostapd | grep "(running)" >/dev/null 2>&1; then #hotspot running and ssid in range + KillHotspot + echo "Hotspot Deactivated, Bringing Wifi Up" + wpa_supplicant -B -i "$wifidev" -c /etc/wpa_supplicant/wpa_supplicant.conf >/dev/null 2>&1 + ChkWifiUp + elif { wpa_cli -i "$wifidev" status | grep 'ip_address'; } >/dev/null 2>&1; then #Already connected + echo "Wifi already connected to a network" + else #ssid exists and no hotspot running connect to wifi network + echo "Connecting to the WiFi Network" + wpa_supplicant -B -i "$wifidev" -c /etc/wpa_supplicant/wpa_supplicant.conf >/dev/null 2>&1 + ChkWifiUp + fi +else #ssid or MAC address not in range + if systemctl status hostapd | grep "(running)" >/dev/null 2>&1; then + echo "Hostspot already active" + elif { wpa_cli status | grep "$wifidev"; } >/dev/null 2>&1; then + echo "Cleaning wifi files and Activating Hotspot" + wpa_cli terminate >/dev/null 2>&1 + ip addr flush "$wifidev" + ip link set dev "$wifidev" down + # ip addr flush "$ethdev" + # ip link set dev "$ethdev" down + rm -r /var/run/wpa_supplicant >/dev/null 2>&1 + createAdHocNetwork + else #"No SSID, activating Hotspot" + createAdHocNetwork + fi +fi + +``` + +Save and exit. + +Make this script executable with `sudo chmod +x /usr/bin/autohotspotN`. + +You can now reboot your machine. If it doesn't find the a setup wifi network, it will generate its own. diff --git a/docs/usage/ui_guide.md b/docs/usage/ui_guide.md new file mode 100644 index 0000000..bf511c4 --- /dev/null +++ b/docs/usage/ui_guide.md @@ -0,0 +1,167 @@ + + +# User interface guide + +Starting with the release of v2.2, a new user interface brings a whole new user interface. This guide will help you get familiar with it. + +![Home](../images/ui_guide/home.webp) + +## Home + +As you can see above, when you first connect with your planktoscope at [http://planktoscope.local:1880/ui](http://planktoscope.local:1880/ui), you will reach this page. + +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 + +![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. + +## 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!** + +To shutdown the machine, first unlock the shutdown button by clicking on "Unlock Button". + +![Home Shutdown Unlocked](../images/ui_guide/home_unlocked.webp) + +You can then click on "Shutdown". The machine will ask for a final confirmation and will then shut itself down. + +![Home Shutdown](../images/ui_guide/home_shutdown.webp) + +## Sample Tab + +![Sample](../images/ui_guide/sample_pass.webp) + +In this page, you can enter all the information regarding the current sample you want to image. This includes the project name, the operator, but also the type of collection device you used. + +![Sample device selection](../images/ui_guide/sample_selection.webp) + +Depending on the device you choose, the page will change to reflect the needed information. + +There is a mechanism of validation of the submitted data. Please be careful to use the format given in example for each input field. + +![Sample validation](../images/ui_guide/sample_validation.webp) + +The GPS status block will give you the current information on the GPS fix and location, your direction and speed. This can be used to grab the location when in the field. + +![Sample net](../images/ui_guide/sample_net.webp) + +Once all the fields are completed, you can go to the next tab by clicking the -> arrow. This will make sure all the inserted data is valid. + +## Optic Configuration + +This page allows you to control the optical setup of the acquisition. + +![Optic configuration](../images/ui_guide/optic_configuration.webp) + +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). + +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. + +The Fluidic Manual Manipulation allows you to control the pump. You can change both the flowrate and the volume pumped. If you click on the rotating arrow, it will start the pump for the given volume at the chosen flowrate. + +The Focus Adjustment block allows you to control the focus stage. With the leftmost buttons, you can choose to move the stage quickly by one mm, either up or down. The rightmost buttons move the stage by the specified distance in the slider under. + +As with all the tabs, once you are satisfied with your focus and your image settings, you can click on "Continue". + +## Fluidic Acquisition + +Finally, this is where the magic happens! You will be able to chose the final parameters of your capture. + +![Fluidic Acquisition](../images/ui_guide/fluidic_acquisition.webp) + +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. + +## Gallery + +![Gallery](../images/ui_guide/gallery.webp) + +This simple page will allow you to navigate the local directory of the machine and visualize the captured data. + +## System Monitoring + +This tab allows you to monitor the physical characteristics of the machine and follow the processor load, CPU temperature, memory use and disk usage. + +![System Monitoring](../images/ui_guide/system_monitoring.webp) + +You also can find information about the software version you are using, the machine name and its camera. + +### USB Backup of the data + +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. + +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. + +## Wifi + +![Administration](../images/ui_guide/wifi.webp) + +This page will give you information about the network the PlanktoScope is connected to. It will also allows you to connect your machine to a new WiFi network. + +Start by doing a network scan by clicking on the `Scan` button. The list will be populated with detected networks after a few seconds. You can then choose one of them, enter its password and click on `Add the network` to connect to it. The wifi network of the PlanktoScope will disappear after a few seconds, so **you will need to connect back to the same network you just put the machine on**. + +Finally, if you are not located in France, please update the Country code in the field below. This will ensure the PlanktoScope complies with local Wifi regulations (such as maximum emitted power, duty cycle and such). + +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. + +!!! 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. + +## Administration + +![Administration](../images/ui_guide/administration.webp) + +On this page you can find the logs generated by the python script and also the [Danger Zone](https://www.youtube.com/watch?v=siwpn14IE7E). + +You should only touch here if you know what you are doing. The update process can be started from here. Also you can restart the python script if something becomes unresponsive (like the pump or the focus stage). You can also restart the machine or shut it down from this page. + +### Update process + +After clicking on the button to launch the update, the script will first check that there is an available update. + +![Administration](../images/ui_guide/update_start.webp) + +The script will then kill node-red, update its code and restart it. +![Administration](../images/ui_guide/update.webp) + +The python script will also restart the python script. +![Administration](../images/ui_guide/update_restarting.webp) + +Once the message displayed top right show "The segmenter is ready", you're good to go on the latest version! +![Administration](../images/ui_guide/update_ready.webp) + +## Hardware Configuration + +![Hardware Configuration](../images/ui_guide/hardware_config.webp) + +You can change the hardware settings of your machine here. If you use a Waveshare hat for the steppers, instead of the adafruit one, if you want to invert the stepper output (switch the stepper 1 with the stepper 2 for example) and the Steps per ml settings of the pump. diff --git a/mkdocs.yml b/mkdocs.yml index 851015d..b3e957f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,45 +10,46 @@ repo_url: https://code.curious.bio/curious.bio/planktoscope nav: - Introduction: - - General: 00_introduction/introduction.md - - Device Specification: 00_introduction/device_specification.md - - Research: 00_introduction/research.md + - General: introduction/introduction.md + - Device Specifications: introduction/device_specification.md + - Research: introduction/research.md - Hardware: - - Manufacturing: 01_hardware/manufacturing.md - - Supply Chain: 01_hardware/supply_chain.md - - Assembly Guide: 01_hardware/assembly_guide.md - - Maintenance and repair: 01_hardware/maintenance_repair.md - - Disposal and recycling: 01_hardware/disposal_recycling.md - - Planktoscope HAT: 01_hardware/hat_hardware.md - - Collection devices: 01_hardware/collection_devices.md + - Manufacturing: hardware/manufacturing.md + - Supply Chain: hardware/supply_chain.md + - Assembly Guide: hardware/assembly_guide.md + - Maintenance and repair: hardware/maintenance_repair.md + - Disposal and recycling: hardware/disposal_recycling.md + - Planktoscope HAT: hardware/hat_hardware.md + - Collection devices: hardware/collection_devices.md - Software: - - Basic Install: 02_software/easy_install.md - - Create the SD Card: 02_software/create_sd.md - - Expert Setup: 02_software/expert_setup.md - - Update Devicetree: 02_software/update_devicetree.md + - Basic Install: software/easy_install.md + - Create the SD Card: software/create_sd.md + - Expert Setup: software/expert_setup.md + - Update Devicetree: software/update_devicetree.md - Usage: - - Getting started: 03_usage/getting_started.md - - User Interface: 03_usage/ui_guide.md - - Remote Access: 03_usage/remote_access.md - - MQTT Messages: 03_usage/mqtt_messages.md + - Getting started: usage/getting_started.md + - User Interface: usage/ui_guide.md + - Remote Access: usage/remote_access.md + - MQTT Messages: usage/mqtt_messages.md - Protocols: - - Basic Primer: 04_protocols/basic_primer.md + - Basic Primer: protocols/basic_primer.md + - FAQ: faq.md - Contribute: - - Development Workflow: 05_contribute/contributions.md - - Hardware Development: 05_contribute/hardware_development.md - - Software Development: 05_contribute/software_development.md - - Software architecture: 05_contribute/software_architecture.md - - Writing Documentation: 05_contribute/writing_documentation.md + - Development Workflow: contribute/development_workflow.md + - Hardware Development: contribute/hardware_development.md + - Software Development: contribute/software_development.md + - Software architecture: contribute/software_architecture.md + - Writing Documentation: contribute/writing_documentation.md - Community: - - Getting in touch: 06_community/community.md - - Trainer: 06_community/trainer.md - - Code of Conduct: 06_community/code_of_conduct.md - - Changelog: changelog.md - - License: license.md + - Getting in touch: community/community.md + - Trainer: community/trainer.md + - Code of Conduct: community/code_of_conduct.md - Funding: funding.md + - License: license.md + - Changelog: changelog.md theme: - logo: images/logo-white.png + logo: images/logos/planktoscope_white.png locale: en name: material font: @@ -80,14 +81,7 @@ theme: plugins: - glightbox - charts - -extra_javascript: - - https://cdn.jsdelivr.net/npm/vega@5 - - https://cdn.jsdelivr.net/npm/vega-lite@5 - - https://cdn.jsdelivr.net/npm/vega-embed@6 - -extra: - generator: false + # - table-reader markdown_extensions: - admonition @@ -98,6 +92,7 @@ markdown_extensions: - tables - toc: permalink: true + - pymdownx.pathconverter - pymdownx.details - pymdownx.superfences: custom_fences: @@ -115,3 +110,14 @@ markdown_extensions: - overrides/.icons - pymdownx.tasklist: custom_checkbox: true + +extra: + generator: false + +extra_css: + - stylesheets/extra.css + +extra_javascript: + - https://cdn.jsdelivr.net/npm/vega@5 + - https://cdn.jsdelivr.net/npm/vega-lite@5 + - https://cdn.jsdelivr.net/npm/vega-embed@6