From e3c0484514bf2c0c1baff5e41eee8b06e14eaf6e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 26 Jun 2024 20:12:27 +0000 Subject: [PATCH] Deploy https://github.com/PlanktoScope/PlanktoScope/commit/18f07c91ab495a258e4a3ab75f1f10d90a35a00b --- .../social/reference/software/product-specs.png | Bin 0 -> 51084 bytes .../social/setup/hardware/index-noguides.png | Bin 0 -> 50720 bytes site/community/code-of-conduct/index.html | 2 +- .../contribute/documentation/index.html | 2 +- site/community/contribute/github/index.html | 2 +- site/community/contribute/hardware/index.html | 2 +- site/community/contribute/software/index.html | 2 +- site/community/index.html | 2 +- site/community/license/index.html | 2 +- site/community/trainings/index.html | 2 +- site/faq/index.html | 2 +- site/index.html | 2 +- site/operation/index.html | 2 +- site/operation/maintenance/index.html | 2 +- site/operation/sample-collection/index.html | 2 +- site/operation/user-interface/index.html | 2 +- site/reference/hardware/changelog/index.html | 2 +- site/reference/hardware/hat/index.html | 2 +- .../reference/hardware/product-specs/index.html | 2 +- site/reference/index.html | 2 +- .../software/architecture/os/index.html | 2 +- .../functionalities/camera-settings/index.html | 2 +- .../functionalities/sample-imaging/index.html | 2 +- .../functionalities/segmentation/index.html | 2 +- .../interfaces/exported-metadata/index.html | 2 +- .../software/interfaces/mqtt/index.html | 2 +- .../reference/software/product-specs/index.html | 2 +- .../software/release-process/index.html | 2 +- .../software/subsystems/installation/index.html | 2 +- .../software/subsystems/startup/index.html | 2 +- site/search/search_index.json | 2 +- site/setup/hardware/index-noguides/index.html | 2 +- site/setup/hardware/index.html | 2 +- site/setup/hardware/v2.1/index.html | 2 +- site/setup/hardware/v2.5/assembly/index.html | 2 +- site/setup/hardware/v2.5/index.html | 2 +- site/setup/hardware/v2.5/kit/index.html | 2 +- site/setup/index.html | 2 +- site/setup/software/config/index.html | 2 +- site/setup/software/create-sd/index.html | 2 +- site/setup/software/index.html | 2 +- .../software/nonstandard-install/index.html | 2 +- site/setup/software/standard-install/index.html | 2 +- site/sitemap.xml.gz | Bin 568 -> 568 bytes site/troubleshooting/index.html | 2 +- 45 files changed, 42 insertions(+), 42 deletions(-) diff --git a/site/assets/images/social/reference/software/product-specs.png b/site/assets/images/social/reference/software/product-specs.png index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..38c9bc1f43cea482ed671af01b588ad6774525cf 100644 GIT binary patch literal 51084 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 J372m^_z%fQ3FH6( literal 0 HcmV?d00001 diff --git a/site/assets/images/social/setup/hardware/index-noguides.png b/site/assets/images/social/setup/hardware/index-noguides.png index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..3114f9376fed5dbb9d1ab7ecdae78225c3e172e4 100644 GIT binary patch literal 50720 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

OLQo4@?SSdf3_n&- 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 KM!0(O@&5oPWVJ>B literal 0 HcmV?d00001 diff --git a/site/community/code-of-conduct/index.html b/site/community/code-of-conduct/index.html index 479f81c..8060178 100644 --- a/site/community/code-of-conduct/index.html +++ b/site/community/code-of-conduct/index.html @@ -7,7 +7,7 @@ .gdesc-inner { font-size: 0.75rem; } body[data-md-color-scheme="slate"] .gdesc-inner { background: var(--md-default-bg-color);} body[data-md-color-scheme="slate"] .gslide-title { color: var(--md-default-fg-color);} - body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);}

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 < thibaut at fairscope.com > . 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, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

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 < thibaut at fairscope.com > . 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, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Writing Documentation🔗

The source files are in the main github repository, in the docs folder.

They are simple Markdown files, that you can edit in any text editor of your choice.

The local development and test is made using mkdocs. This allows you to test your documentation changes for styling issues and see what it will look like once rendered.

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.

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: Converts ASCII dashes, quotes and ellipses to their HTML entity equivalents.
  • Sane Lists: Alters the behavior of the Markdown List syntax to be less surprising.
  • Admonition: Adds rST-style admonitions to Markdown documents.
  • Table of contents: Generates a Table of Contents from a Markdown document and adds it into the resulting HTML document.
  • Metadata: Adds a syntax for defining meta-data about a document.
  • Tables: Adds the ability to create tables in Markdown documents.
  • Fenced Code Blocks: Adds a secondary way to define code blocks.

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.

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 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.

Assumptions🔗

  1. You're familiar with git and the Merge Request(PR) workflow.
  2. **You've read the PlanktoScope documentation.
  3. You know about the PlanktoScope community on Slack. 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 or open a new one.
  2. Once done, fork the PlanktoScope repository 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.
  4. Review the 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 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.

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.

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.

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 ❤️

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.

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 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.

Assumptions🔗

  1. You're familiar with git and the Merge Request(PR) workflow.
  2. **You've read the PlanktoScope documentation.
  3. You know about the PlanktoScope community on Slack. 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 or open a new one.
  2. Once done, fork the PlanktoScope repository 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.
  4. Review the 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 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.

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.

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.

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 ❤️

Hardware Development🔗

planktoscope_hero

PlanktoScope Case🔗

autodesk_fusion_360

As a hardware engineer working on the PlanktoScope Case, you will be using Autodesk Fusion 360 for the development of the case design. Fusion 360 is a comprehensive computer-aided design (CAD) software that allows you to create and analyze complex 3D models, perform simulations and stress tests, and collaborate with team members in real-time.

To get started with the project, you will need to install a development environment on your computer. Here are the steps to follow:

  • Download and install Fusion 360 from the Autodesk website.
  • Create a free Autodesk account and log in to Fusion 360.
  • Join the PlanktoScope Case team in Fusion 360. This will give you access to all of the project files and allow you to collaborate with other team members.
  • Familiarize yourself with the Fusion 360 interface and tools. There are many resources available online, including tutorials and user guides, to help you get up to speed.
  • Start designing and testing your case components in Fusion 360. You can use the software to create 3D models, run simulations and stress tests, and collaborate with other team members in real-time.

By following these steps, you will be able to successfully install a development environment and participate in the PlanktoScope Case using Autodesk Fusion 360.

PlanktoScope Hat🔗

autodesk_eagle

As a hardware engineer working on the PlanktoScope Hat, you will be using Autodesk Eagle to design and develop the electronic components of the hat. Autodesk Eagle is a powerful and widely used software platform for designing and laying out printed circuit boards (PCBs).

To participate in the project, you will need to install a development environment on your computer that includes Autodesk Eagle and any other necessary tools and libraries. Here are the steps you can follow to set up your development environment:

  • Download and install Autodesk Eagle from the official website. Make sure to select the appropriate version for your operating system (Windows, Mac, or Linux).
  • Follow the instructions provided by Autodesk to complete the installation process. This may involve entering a license key or activating the software through your Autodesk account.
  • Once Autodesk Eagle is installed, you may need to install additional libraries or tools depending on the specific requirements of the PlanktoScope Hat. These may include libraries for communicating with specific hardware components, or tools for debugging and testing your designs.
  • Once you have installed all the necessary tools and libraries, you should be ready to start working on the PlanktoScope Hat using Autodesk Eagle. You can begin by opening the project files and familiarizing yourself with the existing design, or by creating new designs as needed.

By following these steps, you can set up a development environment that allows you to contribute to the PlanktoScope Hat using Autodesk Eagle.

Hardware Development🔗

planktoscope_hero

PlanktoScope Case🔗

autodesk_fusion_360

As a hardware engineer working on the PlanktoScope Case, you will be using Autodesk Fusion 360 for the development of the case design. Fusion 360 is a comprehensive computer-aided design (CAD) software that allows you to create and analyze complex 3D models, perform simulations and stress tests, and collaborate with team members in real-time.

To get started with the project, you will need to install a development environment on your computer. Here are the steps to follow:

  • Download and install Fusion 360 from the Autodesk website.
  • Create a free Autodesk account and log in to Fusion 360.
  • Join the PlanktoScope Case team in Fusion 360. This will give you access to all of the project files and allow you to collaborate with other team members.
  • Familiarize yourself with the Fusion 360 interface and tools. There are many resources available online, including tutorials and user guides, to help you get up to speed.
  • Start designing and testing your case components in Fusion 360. You can use the software to create 3D models, run simulations and stress tests, and collaborate with other team members in real-time.

By following these steps, you will be able to successfully install a development environment and participate in the PlanktoScope Case using Autodesk Fusion 360.

PlanktoScope Hat🔗

autodesk_eagle

As a hardware engineer working on the PlanktoScope Hat, you will be using Autodesk Eagle to design and develop the electronic components of the hat. Autodesk Eagle is a powerful and widely used software platform for designing and laying out printed circuit boards (PCBs).

To participate in the project, you will need to install a development environment on your computer that includes Autodesk Eagle and any other necessary tools and libraries. Here are the steps you can follow to set up your development environment:

  • Download and install Autodesk Eagle from the official website. Make sure to select the appropriate version for your operating system (Windows, Mac, or Linux).
  • Follow the instructions provided by Autodesk to complete the installation process. This may involve entering a license key or activating the software through your Autodesk account.
  • Once Autodesk Eagle is installed, you may need to install additional libraries or tools depending on the specific requirements of the PlanktoScope Hat. These may include libraries for communicating with specific hardware components, or tools for debugging and testing your designs.
  • Once you have installed all the necessary tools and libraries, you should be ready to start working on the PlanktoScope Hat using Autodesk Eagle. You can begin by opening the project files and familiarizing yourself with the existing design, or by creating new designs as needed.

By following these steps, you can set up a development environment that allows you to contribute to the PlanktoScope Hat using Autodesk Eagle.

How to help development for the PlanktoScope code🔗

We are using the Github Flow approach for our development efforts.

If you want to join us, have a look at the currently opened 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!)

Node-Red🔗

Node-Red is our main process. We use the flow to manage our user interface through a dashboard instance.

node-red

As a software engineer, you may need to set up a Node-RED development environment on a Debian operating system. Node-RED is an open-source programming tool for wiring together hardware devices, APIs, and online services in new and interesting ways. It provides a visual, drag-and-drop interface for building applications, and can be used to develop a wide range of IoT, automation, and data processing projects.

To set up a Node-RED development environment on a Debian operating system, you will need to follow these steps:

  1. Install Node.js: Node-RED requires Node.js to be installed on your system. You can install Node.js using the package manager by running the following command: sudo apt-get install nodejs
  2. Install npm (Node Package Manager): npm is a package manager for Node.js that is used to install and manage Node-RED and its dependencies. You can install npm by running the following command: sudo apt-get install npm
  3. Install Node-RED: Once Node.js and npm are installed, you can install Node-RED by running the following command: sudo npm install -g --unsafe-perm node-red
  4. Start the Node-RED server: You can start the Node-RED server by running the following command: node-red
  5. Access the Node-RED editor: You can access the Node-RED editor by opening a web browser and going to the URL http://localhost:1880.

By following these steps, you will be able to set up a Node-RED development environment on your Debian operating system and start building applications with the visual, drag-and-drop interface.

Python🔗

python

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.

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.

How to help development for the PlanktoScope code🔗

We are using the Github Flow approach for our development efforts.

If you want to join us, have a look at the currently opened 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!)

Node-Red🔗

Node-Red is our main process. We use the flow to manage our user interface through a dashboard instance.

node-red

As a software engineer, you may need to set up a Node-RED development environment on a Debian operating system. Node-RED is an open-source programming tool for wiring together hardware devices, APIs, and online services in new and interesting ways. It provides a visual, drag-and-drop interface for building applications, and can be used to develop a wide range of IoT, automation, and data processing projects.

To set up a Node-RED development environment on a Debian operating system, you will need to follow these steps:

  1. Install Node.js: Node-RED requires Node.js to be installed on your system. You can install Node.js using the package manager by running the following command: sudo apt-get install nodejs
  2. Install npm (Node Package Manager): npm is a package manager for Node.js that is used to install and manage Node-RED and its dependencies. You can install npm by running the following command: sudo apt-get install npm
  3. Install Node-RED: Once Node.js and npm are installed, you can install Node-RED by running the following command: sudo npm install -g --unsafe-perm node-red
  4. Start the Node-RED server: You can start the Node-RED server by running the following command: node-red
  5. Access the Node-RED editor: You can access the Node-RED editor by opening a web browser and going to the URL http://localhost:1880.

By following these steps, you will be able to set up a Node-RED development environment on your Debian operating system and start building applications with the visual, drag-and-drop interface.

Python🔗

python

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.

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.

The PlanktoScope Community🔗

PlanktoScope is a completely open platform. The core of the PlanktoScope project is a basis in an evolving network of designers and users collaborating to increase the impact and availability of the tools. Building a community of users will enable PlanktoScope to grow with capabilities not yet imagined.

For around $800, and with parts freely available in most parts of the globe, any person with the desire to engage can begin building a PlanktoScope. This website contains the information needed to assemble, test, and begin collecting data on your PlanktoScope.

Engage on GitHub🔗

Feel free to visit the GitHub and engage if you want.

GitHub

GitHub is a web-based platform that is widely used in the PlanktoScope Community for version control and collaboration. It allows members to easily share, track, and manage code and other project files. The platform is built around the Git version control system, which allows multiple contributors to work on the same codebase simultaneously while keeping a record of every change made.

In the PlanktoScope Community, members can use GitHub to collaborate on the development of the Planktoscope project. They created a central repository where they can share and track the code, documentation, and other project files.

Chat on Slack🔗

The community is using Slack to communicate.

Slack

Slack is a communication and collaboration tool that is widely used in the PlanktoScope Community. It allows members to communicate and work together in real-time, providing a central hub for all conversations related to Planktoscope project. The platform offers features such as direct messaging, group channels, video conferencing, and file sharing, making it easy for members to stay informed and on the same page.

The PlanktoScope community has created a dedicated Slack workspace for the community members to share their findings, ask for help, and discuss project-related topics.

Classify on EcoTaxa🔗

To join EcoTaxa, you just need to create an account.

EcoTaxa

EcoTaxa is a web-based platform that enables researchers, educators, and citizen scientists to identify, classify and share images of microorganisms. The platform is designed to support biodiversity research and education by providing a user-friendly interface for browsing and analyzing images of microorganisms, as well as a collaborative environment for sharing images and data. EcoTaxa allows users to upload their own images, and the platform's machine learning algorithms can automatically identify and classify the organisms in the images.

The platform also offers a variety of tools for analyzing and visualizing data, including image annotation, statistical analysis, and data export. Additionally, EcoTaxa has a community feature where researchers can share their findings, and have a discussion on the data, and contribute to the knowledge base. Overall, EcoTaxa is a valuable resource for anyone interested in microorganism biodiversity research and education.

The PlanktoScope Community🔗

PlanktoScope is a completely open platform. The core of the PlanktoScope project is a basis in an evolving network of designers and users collaborating to increase the impact and availability of the tools. Building a community of users will enable PlanktoScope to grow with capabilities not yet imagined.

For around $800, and with parts freely available in most parts of the globe, any person with the desire to engage can begin building a PlanktoScope. This website contains the information needed to assemble, test, and begin collecting data on your PlanktoScope.

Engage on GitHub🔗

Feel free to visit the GitHub and engage if you want.

GitHub

GitHub is a web-based platform that is widely used in the PlanktoScope Community for version control and collaboration. It allows members to easily share, track, and manage code and other project files. The platform is built around the Git version control system, which allows multiple contributors to work on the same codebase simultaneously while keeping a record of every change made.

In the PlanktoScope Community, members can use GitHub to collaborate on the development of the Planktoscope project. They created a central repository where they can share and track the code, documentation, and other project files.

Chat on Slack🔗

The community is using Slack to communicate.

Slack

Slack is a communication and collaboration tool that is widely used in the PlanktoScope Community. It allows members to communicate and work together in real-time, providing a central hub for all conversations related to Planktoscope project. The platform offers features such as direct messaging, group channels, video conferencing, and file sharing, making it easy for members to stay informed and on the same page.

The PlanktoScope community has created a dedicated Slack workspace for the community members to share their findings, ask for help, and discuss project-related topics.

Classify on EcoTaxa🔗

To join EcoTaxa, you just need to create an account.

EcoTaxa

EcoTaxa is a web-based platform that enables researchers, educators, and citizen scientists to identify, classify and share images of microorganisms. The platform is designed to support biodiversity research and education by providing a user-friendly interface for browsing and analyzing images of microorganisms, as well as a collaborative environment for sharing images and data. EcoTaxa allows users to upload their own images, and the platform's machine learning algorithms can automatically identify and classify the organisms in the images.

The platform also offers a variety of tools for analyzing and visualizing data, including image annotation, statistical analysis, and data export. Additionally, EcoTaxa has a community feature where researchers can share their findings, and have a discussion on the data, and contribute to the knowledge base. Overall, EcoTaxa is a valuable resource for anyone interested in microorganism biodiversity research and education.

Our work is fully open source🔗

That's the headline, yes.

Hardware files🔗

We released our hardware files (everything in the hardware directory) under a CERN OHL-S license.

Software source🔗

Our source code (everything in the directories flows and scripts) is released under a GPL-3.0 license.

Everything else (documentation, pictures, etc...)🔗

Everything else is released under a Creative Commons CC-BY-SA license.

Our work is fully open source🔗

That's the headline, yes.

Hardware files🔗

We released our hardware files (everything in the hardware directory) under a CERN OHL-S license.

Software source🔗

Our source code (everything in the directories flows and scripts) is released under a GPL-3.0 license.

Everything else (documentation, pictures, etc...)🔗

Everything else is released under a Creative Commons CC-BY-SA license.

Trainings🔗

The success of the PlanktoScope community depends on the people who generously share their knowledge and expertise about its production and use with others, helping to promote its widespread adoption and use. By actively participating in the community and sharing their insights and experiences, individuals can contribute to the growth and success of the PlanktoScope, ultimately benefiting not just the community but also the broader field of study.

The Train the trainer program🔗

The train the trainer program is a training program designed to equip individuals with the knowledge and skills needed to deliver training to others. The goal of a train the trainer program is to build capacity within the PlanktoScope community by volunteers to become trainers themselves.

This guide is intended to provide you with a solid foundation of knowledge and understanding about the PlanktoScope, enabling you to confidently develop and deliver your own training program for others. Whether you are an experienced user looking to share your expertise with others or a newcomer to the PlanktoScope looking to learn more about its capabilities and applications, this guide is designed to help you gain the necessary skills and knowledge to successfully teach others about this powerful tool.

Event types🔗

Build workshop🔗

Organizing a build workshop can be a challenging but rewarding experience. It requires careful planning and execution to ensure that the workshop is successful. This trainer manual is designed to guide you through the process of organizing a build workshop.

Selecting the production site🔗

Choosing the right production site for preparing and manufacturing the PlanktoScope Kits is an important step in the workshop planning process. The production site should have the necessary tools and equipment, as well as the knowledge and expertise to manufacture the PlanktoScope Kits. Here are a few things to consider when choosing a production site:

  1. Check the Manufacturing and Assembly Guides: Before choosing a production site, make sure to review the PlanktoScope Kit Manufacturing Guide and the Device Assembly Guide. These guides will provide detailed information on the necessary tools and equipment required for the production of the PlanktoScope Kits.
  2. Visit Fablab and Hackspaces: Consider visiting Fablabs or Hackspaces in your region. These organizations often have a culture of openness and may be willing to support you with your project. They may have the necessary tools and equipment to produce the PlanktoScope Kits, as well as the knowledge and expertise to guide you through the production process.
  3. Commercial Manufacturing: Look for a facility that has the capability to handle small scale production runs, a good quality control process and a logistic plan to ship the product to the final destination. Many

Tip

For the PlanktoScope case, for example, you can look for woodworking companies. They often have a CNC machine and are familiar with the process of ditigal production.

Material procurement🔗

Building a PlanktoScope requires a specific set of materials. In order to ensure that the workshop runs smoothly and that all attendees are able to successfully build their own PlanktoScope, it is important to properly plan and execute the procurement of materials. The following is a step-by-step guide on how to properly plan and execute the procurement of materials for a workshop:

  1. Prepare the order list: Use the bill of materials (BOM) as a starting point to create a comprehensive list of all materials needed for the workshop. Expand it with additional columns for suppliers, delivery dates, prices, shipping costs, and import taxes.
  2. Plan for packaging: Plan for extra packaging so you can assemble the parts as shown in the instructions. Try to minimize plastic as much as possible.
  3. Research suppliers: Research suppliers and see if there are local options, if you can consolidate orders to save costs and ensure timely delivery.
  4. Compare prices: Compare the prices of different suppliers to minimize the total cost.
  5. Plan for spare parts: Plan for spare parts in case something is broken or lost.
  6. Check your Budget: Check your budget and ensure that you have enough funds to cover the cost of all materials, shipping, and any additional expenses before placing your orders.
  7. Place orders: Once you have identified the best suppliers, place orders for all of the materials that you need. Be sure to factor in lead time when placing orders to ensure that the materials will arrive in time for the workshop.
  8. Track orders: Keep track of your orders and expected delivery dates, mark a component when it arrives. Contact suppliers if there are any delays or problems with delivery.
  9. Communicate: Communicate with participants if there are issues with timely delivery. It may make sense to postpone the workshop if there is not enough time to prepare and test everything. The participants will be grateful and will understand if it helps to ensure that everything runs smoothly.

By following this process, you can ensure that all materials are procured and organized well in advance of the workshop, to avoid any last-minute delays or complications.

Note

If you have difficulty finding the components you need, contact us and we will be happy to help you find the right alternative.

Warning

Have a backup plan and be prepared for unexpected events that may occur during the procurement process. Allow two months for delivery, as some specialty parts may travel a long way and require additional time for customs inspection.

Tip

Let us know your results, we would love to hear what solutions you found and how cost effective you were able to make the PlanktoScope.

Prepare the Kit🔗

Kit preparation for the workshop is an important step in the preparation process. This ensures that participants have the materials and equipment they need to complete the workshop and build their own PlanktoScope. Here are a few things to keep in mind when preparing the kits:

  1. Review the Bill of Materials (BOM): Review the Bill of Materials (BOM) for the PlanktoScope to ensure that you have all the necessary parts and materials for the workshop. The parts list can be found in the Device Assembly Guide and lists all components and quantities needed to build a microscope.
  2. Divide the kit components according to the BOM: Once the materials have been received, divide the kit components from the orders according to the Bill of Materials (BOM) of the PlanktoScope. This will ensure that each participant receives the correct components and that there are no missing parts.
  3. Have extra components: Have extra components on hand in case of any missing or damaged parts during the workshop.
  4. Package the kits: Package the kits in a way that makes it easy for the participants to find and use the components during the workshop.
  5. Label materials: Label the packages as described in Device Assembly Guide so that they are easy to find and distribute during the workshop.
  6. Preparation of the housing parts: Prepare the housing parts by applying the surface sealant and insert the nuts to screw the housing as described in the Kit Manufacturing Guide.
  7. Cutting and soldering of electronic cables: Cut and solder the electronic cables for the PlanktoScope. This will save time during the workshop and ensure that the participants have all the necessary cables to complete the assembly.
  8. Setting up the embedded development environment: Set up the embedded development environment and flash the eeprom of the PlanktoScope hat. This will ensure that the PlanktoScope hat is ready to be used during the workshop.
  9. Download the Raspberry Pi image: Download the Raspberry Pi image and flash it to the SD card. This will ensure that the participants have a ready to use image for the PlanktoScope.
  10. Test the kits: Test the kits before the workshop to ensure that all components are working correctly and that the instructions are clear and easy to follow. This will help to ensure that the participants have a positive and productive experience during the workshop.

Tip

Identify any items that are time consuming during the workshop and not particularly important or complex to explain. These tasks can be completed in advance to save time during the workshop. This will make it easier for the participants to assemble the PlanktoScope during the workshop.

Conducting the workshop🔗

It's finally here! After all the planning, preparation, and anticipation, the build workshop is about to begin. Take a deep breath and let's go!

  1. Prepare the presentation: Prepare the presentation device and start your slides.
  2. Check-In: Once the Participants arrive, complete the check-in, share the agenda and set expectations for the workshop.
  3. Venue: Provide information about the venue, including where to find restrooms and where to buy food.
  4. Digital tools: Provide information about the digital tools that will be used during the workshop, such as the platform for collaboration, the survey tool and the chat channel, and how to access them.
  5. Data privacy: Inform about the privacy policy and the forms that need to be signed by the participants if you want to take photos.
  6. Introduction round: Begin with a round of introductions and give everyone a chance to introduce themselves, their background, and their interest in the project.
  7. Provide an overview: Provide details about the project, including the general mode of operation, the working materials such as the kit, the documentation and the git repository.
  8. Provide the Kits and Tools: Provide the Kit and Tools to each participant with a kit and the necessary tools.
  9. Follow the build instructions: Depending on the format you have chosen, start implementing by following the Kit Manufacturing guide or Device Assembly guide
  10. Follow the operation instructions: Now that you have successfully assembled the PlanktoScope, you can proceed to operation of the PlanktoScope by following the Getting started and User interface instructions.
  11. Final Test: For a final test you can use for example pure cultures or a sample taken with a Plankton net from a surrounding waters.

Field trip🔗

Are you an expert in organizing field trips? Share your skills with the PlanktoScope community by documenting the process! By documenting how you organize a field trip, you can help others create successful events and bring more event options to the PlanktoScope community. Your documentation will be a valuable resource for anyone looking to plan a field trip, and it will also help to grow and strengthen the PlanktoScope community. Don't miss this opportunity to contribute to the community, start documenting your process today!

Hackathon🔗

Are you a master at organizing Hackathons? Share your knowledge with the PlanktoScope community by documenting the process! By documenting how you organize a Hackathon, you can help others create successful events and bring more event options to the PlanktoScope community. Your documentation will be a valuable resource for anyone looking to host a Hackathon, and it will also help to grow and strengthen the PlanktoScope community. Don't miss this opportunity to contribute to the community, start documenting your process today!

General planning methods🔗

Organizing a workshop can be a challenging but rewarding experience. It requires careful planning and execution to ensure that the workshop is successful. This trainer module is designed to guide you through the process of organizing any type of event.

By following the guidelines, you will be able to plan a workshop that is engaging, productive, and successful. It will also help you to create a sense of community among participants and will help them continue their learning after the workshop.

Building a team🔗

Every project needs a team to support it. The team should be composed of individuals with a diverse set of skills and experiences to ensure all aspects of the workshop are effectively covered.

  1. Identify the roles and responsibilities: Determine the key areas that need to be covered during the workshop and assign specific roles to team members. For example, one team member may be responsible for organizing logistics, while another may be responsible for creating the agenda.
  2. Assemble the team: Once the roles and responsibilities have been identified, begin assembling the team. Consider individuals with relevant skills and experiences, as well as those who have a passion for the topic of the workshop. It is also important to have a mix of team members from different departments or backgrounds to bring a variety of perspectives to the planning process.
  3. Communicate effectively: Establish clear lines of communication within the team to ensure that everyone is on the same page. This can be done through regular meetings, email, or a team collaboration platform.
  4. Encourage participation: Encourage team members to actively participate in the planning process by sharing their ideas and feedback. This will help to ensure that everyone feels invested in the success of the workshop.
  5. Appoint a leader: Appoint a leader for the team who will be responsible for coordinating the planning process and ensuring that the team stays on track. The leader should be someone who is organized, a good communicator, and able to delegate tasks effectively.

Communication channels🔗

Choosing the right communication channels is an important step in the planning process for a workshop, as it is crucial not only for the organizing team but also for the participants during and after the workshop. The right communication channels can help to build a fluent community, improve collaboration and keep everyone informed and on the same page.

  1. Choose the right channels: Once the needs have been identified, choose the communication channels that will best serve those needs. Email, chat, and video conferencing are all popular options. If the group is small, a group chat or email chain may be sufficient. If the group is larger or more dispersed, a video conferencing platform may be more appropriate.
  2. Make sure they are accessible: Ensure that the communication channels you choose are accessible to all participants. This may include providing training or support for those who are less familiar with the tools you are using.
  3. Communicate expectations: Clearly communicate the expectations for using the communication channels to the participants. This includes guidelines for how often and when to check the channels, as well as how to respond to messages.
  4. Continuity: Make sure that you have continuity in the communication channels after the workshop. This will help to build a fluent community and to keep the participants connected and engaged. Use the same channels to share updates and resources, or to organize follow-up events or activities.

Note

Email is a reliable and widely-used communication channel that can be used for sending out workshop updates, sending materials, and answering questions. It is also a good option for sending out reminders and follow-up information after the workshop.

Note

Chat networks, such as Matrix, are a great option for secure, real-time and decentralized communication during the workshop. They allow participants to ask questions, share resources and collaborate on projects in real-time. They can also be used for group discussions and as a platform for sharing feedback. Additionally, chat platforms can be used as a platform for post-workshop communication and to build a fluent community.

Tip

If you need assistance with creating a Chat for your workshop, please let us know. We can easily set up new subchannels within our PlanktoScope Slack channel to support communication and collaboration during your workshop. This will also help facilitate the exchange of information within the community.

Selecting digital tools🔗

The right tools can help to facilitate communication, collaboration, and organization, making the workshop experience more productive and enjoyable for everyone.

  1. Use web-based tools: Whenever possible, use web-based tools that can be accessed from any device with an internet connection. This will make it easier for participants to access and use the tools, regardless of their location or device.
  2. Use collaborative note-taking tools: You might use web-based tools like HedgeDoc that allow participants to collaboratively collect notes during the workshop. This can help to ensure that everyone has access to the same information, and can help to make the workshop experience more productive and enjoyable for everyone.
  3. Use survey tools: You might use survey tools like LimeSurvey to gather information about the participants' needs and expectations for the workshop. This can help to ensure that the workshop is relevant, valuable, and effective for them.
  4. Use ticketing tools: You might use tools like Pretix to manage ticketing for the workshop. This can help to simplify the registration process, and can also provide valuable information about the attendees.

Find your audience🔗

If you already have an audience for your workshop, that's fantastic. But it's also a good idea to let others know about your plans and potentially expand your audience. Contact nongovernmental organizations, universities, and research institutions in your area to see if they would be interested in participating in or even helping to organize the workshop.

Tip

One way to get in touch with others who are interested in PlanktoScope is to join our Slack Channel. We can support you by sharing contacts of individuals and organizations who have expressed an interest in PlanktoScope.

Determining the need🔗

Understanding the needs of the participants will help to ensure that the workshop is relevant, valuable, and effective for them. Here are a few things to consider when determining the needs of the participants:

  1. Surveys and questionnaires: Use surveys and questionnaires to gather information about the participants' needs and expectations for the workshop. This can include their level of experience and knowledge, their specific interests and goals, and any challenges or concerns they may have.
  2. Pre-workshop consultation: Schedule pre-workshop consultations with the participants to discuss their needs and expectations in more detail. This can help to identify any specific areas of interest or concern, and can also provide an opportunity to address any questions or concerns the participants may have.
  3. Audience analysis: Analyze the characteristics of the audience, such as their profession, level of education and experience, and any other relevant details. This will give you a better idea of the type of content that will be most relevant and useful for the participants.
  4. Feedback: Ask for feedback from participants after the workshop and take it into account when planning future workshops. This feedback can be used to improve the overall experience and to tailor the workshop to better meet the needs of the participants.

Defining the goals🔗

Defining the goals of a workshop is an essential step in the planning process. The goals will serve as the foundation for the workshop, guiding the content and activities that are included.

  1. Number of participants: The workshop should be designed for a specific number of participants. Depending on the available resources, the number of participants can range from small groups of 4-8 people to larger groups of 8-12 people.
  2. Number of microscopes: The goal of the workshop is to build a specific number of PlanktoScope Microscopes. It is important to have the necessary materials and tools for each participant to build their own microscope.
  3. Content: The workshop will include both theoretical and practical content. The theoretical content will cover the principles of open-source hardware and software and the specific design of the PlanktoScope Microscope. The practical content will focus on the assembly and usage of the microscope, including hands-on experience with soldering and other techniques.

Tip

Depending on the time, resources, and audience, it is important to carefully decide what activities and tasks should be done during the workshop and what should be prepared upfront. This will ensure that the workshop runs smoothly and efficiently, and that the participants are able to fully engage and participate in the activities. Additionally, by carefully planning and preparing upfront, you can minimize the chances of overwhelming attendees with problems or difficulties that may arise during the workshop.

Financial planning🔗

The cost of materials, equipment, and other expenses can add up quickly, so it is important to have a plan in place to secure funding. Here are a few things to consider when planning the finances for your workshop:

  1. Decide on the cost of the kits: One of the first things to consider is whether you want to offer the kits for sale to the participants or if you want them to purchase the kits themselves. If you choose to offer the kits for sale, you will need to factor in the cost of materials and other expenses, such as shipping and handling. If you choose to have the participants purchase the kits themselves, you will need to provide them with information on where to purchase the kits and the estimated cost.
  2. Check for funding opportunities: There may be organizations or foundations that would be willing to support your workshop financially. It's a good idea to research potential sources of funding such as grants, sponsorships, and crowdfunding campaigns. Additionally, look for local or regional organizations that are working in the same field as your workshop, they might be interested in supporting your initiative.
  3. Reach out to potential sponsors: Once you have identified potential sources of funding, reach out to them to inquire about their funding opportunities. Be prepared to provide them with information about the workshop, including the goals, objectives, and expected outcomes. Be sure to include information about the open-source nature of the project, as this may make it more attractive to organizations with an interest in open-source technology.
  4. Look for cost-saving options: In addition to securing funding, there are also ways to save money on expenses. Consider renting equipment or space rather than purchasing it. Reach out to local universities or community organizations to see if they have equipment or space that you can use for the workshop at a reduced cost or for free.

Tip

If you are organizing the workshop as an individual, consider running the project through a non-profit organization to facilitate the collection of donations. This will also help to ensure transparency and accountability for the funding received. Alternatively, you can choose a commercially active organization that can provide proper accounting and financial management for the workshop participants. This will provide a clear financial record and can help to ensure that the workshop is run in a professional and organized manner.

Creating a timetable🔗

Creating a schedule for a workshop is an important step in the planning process. A well-organized schedule will help to ensure that the workshop runs smoothly and that all the important topics are covered. Here are a few things to consider when creating a schedule for your workshop:

  1. Plan for more than just a day: A workshop may take more than one day to complete, so be sure to plan accordingly. Consider the amount of time required to cover all the topics, and allocate enough time for each one.
  2. Assign an expected duration to each item on the schedule: Assign an expected duration to each item on the schedule so that participants know how much time they should expect to spend on each topic. This will also help you to ensure that you have allocated enough time for each topic.
  3. Allocate time for breaks and activities: Make sure to allocate time for breaks, meals and other activities such as group discussions, teamwork, or hands-on activities. This will help to keep the participants engaged and energized throughout the workshop.
  4. Plan for contingencies: Include some flexibility in the schedule to allow for unexpected events or delays. This will help to ensure that the workshop stays on track even if things don't go exactly as planned.

Venue selection🔗

The location should be convenient and accessible for the participants, and should be equipped with the necessary resources to make the workshop a success. Here are a few things to consider when choosing a workshop location for a workshop on building an open-source PlanktoScope microscope:

  1. Reach out to Universities, research institutions, Fablabs, Hackspaces or non-profit organizations: Reach out to organizations that might have an interest in the PlanktoScope, and a community that might support you with free access to their location.
  2. Check the equipment: Make sure the location is equipped with the necessary resources such as a whiteboard, projector/TV, and other equipment that may be required for the workshop.
  3. Check the accessibility: Check the accessibility of the location with the public transport system and parking availability.
  4. Check for food provision: Consider if there is a possibility to go shopping or how to provide food for the course participants during the workshop.
  5. Check the environment: Consider the environment of the location, make sure it is comfortable, has enough space and is well-ventilated for the workshop.

Announcing the event🔗

When announcing the event, it is important to include the following information:

  1. Date: Provide a specific date, start and end time for the workshop, and ensure there is enough lead time for preparation, including ordering or manufacturing materials and coordinating with suppliers. Allow ample time between announcing the workshop and the actual event.
  2. Goal: Clearly communicate the specific goal of the workshop, such as to build a fully functional planktoscope and learn how to use it.
  3. What attendees will learn in the workshop: Clearly outline the specific skills or knowledge that will be covered in the workshop, such as how to assemble the kit, soldering the through-hole components of the controller, and working with the software.
  4. Instructor's background: Provide some notes about the instructor's qualifications or experience that make them well-suited to lead the workshop, such as experience working with planktoscope.
  5. Target audience: Clearly indicate the target group of the workshop, such as researchers, engineers or designers.
  6. Previous knowledge: Specify any previous knowledge required for the workshop, such as soldering skills or experience working with open-source hardware and software.
  7. Implementation method: Describe the form of the workshop, such as a step-by-step guide.
  8. Documentation: Consider sharing the documentation beforehand, so they can familiarize themselves with the process.
  9. Cost: Clearly communicate the cost of the workshop.
  10. Schedule: Provide a clear and detailed schedule of the workshop, including the duration of the workshop, for example, one day of building and one day of using the plankoscope.
  11. Location: Provide the location of the workshop, including information on how to get there with public transportation or Arrival by car and parking. Also, provide a link to a map service
  12. Registration: Details of the registration process, including information on where to obtain a ticket and any deadlines for registration.
  13. Contact details: Additionally, it may be helpful to include contact information for any questions.
  14. Images: Include some visually appealing images, such as from a previous workshop or field trip, to show what attendees can expect from the event. This can additionally be a great way to build anticipation and excitement, thus motivating more people to attend the workshop.
  15. Media: Post your offer on a website or social media platform that is relevant to the workshop topic and your target audience. This way you can increase visibility and reach a wider audience, which increases the chances of getting more attendees.

Tip

If you already have a group of interested people, send a link to the announcement via email or chat and invite them personally.

Preparing a presentation🔗

Preparing a presentation for a build workshop is an important step in the preparation process. It helps to ensure that the participants have the information they need to complete the workshop and understand the concepts behind building the Planktoscope.

  1. Gather resources: Gather resources such as images, videos, and diagrams that can be used to support the presentation. These resources can be found on the Planktoscope website or other sources.
  2. Outline the main topics: Outline the main topics that will be covered during the workshop, such as the components of the microscope, the assembly process, and the use of the microscope.
  3. Prepare a handout: Prepare a handout or a guide that the participants can use during the workshop to follow the steps, and have it ready to be printed or shared digitally
  4. Practice the presentation: Practice the presentation several times before the workshop to ensure that it runs smoothly and that you are comfortable with the material.
  5. Be ready to adapt: Be ready to adapt the presentation during the workshop to fit the needs of the participants.

Here are some topics that should be covered in a presentation:

  1. Event: Provide an overview of the event, including the goal of the workshop.
  2. Schedule: Provide an timetable for the event, including breaks, start and end times, and any planned activities for the next day.
  3. Venue: Provide information about the venue, including where to find restrooms and where to buy food.
  4. Instructor: Provide information about the instructor, including his or her background, and how to get in touch with him or her
  5. Digital tools: Provide information about the digital tools that will be used during the workshop, such as the platform for collaboration, the survey tool and the chat channel, and how to access them
  6. Data privacy: Provide information about the data privacy policy and the forms that need to be signed by the participants.
  7. Follow-ups: Point out follow-up actions such as the survey and that participation can be very helpful in improving the offer.
  8. Communication: Inform about the communication channels that will be used during the workshop and complete the onboarding.
  9. Introduction round: A round of introductions at the beginning of a workshop helps to create a sense of community and connection among the participants, allows the instructor to tailor the workshop to the group's needs, addresses potential language barriers, creates a sense of accountability, and helps participants to be more focused and relaxed.
  10. About the project: Provide details about the project, including the working materials such as the kit, the documentation, and the git repository.

Send an final Reminder🔗

Make sure participants are well informed and can find their way to you by sending a final reminder before the start so everything is well prepared.

  1. Schedule for the event: Include a detailed schedule for the event, including breaks, start and end times, and any planned activities for the next day. This will help participants to plan their time and make the most of the workshop.
  2. About the venue: Provide detailed information about the venue, including the address, public transportation options, and parking situation. Make sure to include any specific instructions or requirements for accessing the venue.
  3. About the documentation: Provide a link to the documentation, such as the assembly and manufacturing guide, that the participants can familiarize themselves with before the workshop. This will help them to be better prepared and make the most of the workshop.
  4. Cancellation policy: Remind the participants that now is the last opportunity to cancel their registration. This will allow other individuals on the waiting list to attend the workshop.
  5. Final Instructions: Provide any final instructions or important information that the participants should be aware of before the workshop.

Documenting the event🔗

Documenting a PlanktoScope workshop through photography is essential for several reasons. Photos can be used to showcase the workshop activities and the learning process of the participants. This can be useful for sharing information about the workshop with others, and for promoting future workshops.

  1. Equipment: Make sure you have the necessary equipment to document the event, including a camera (DSLR or mirrorless camera), lenses, memory cards, and batteries.
  2. Backup: Always make sure to have a backup plan for your equipment and photos, such as bringing extra memory cards and batteries.
  3. Lighting: Take into account the lighting conditions and make sure to have the right settings for your camera to capture the best possible images.
  4. Planning: Plan out the photos you want to take, taking into account the theme, location and schedule of the event.
  5. Composition: Pay attention to the composition of your photos and make sure to use techniques such as the rule of thirds and leading lines to create visually appealing images.
  6. Capturing candid moments: In addition to capturing posed shots, make sure to capture candid moments that capture the atmosphere and emotions of the event.
  7. Post-processing: Once the event is over, review and edit your photos to make them look their best.
  8. Data Privacy and Opt-Out: Pay attention to the privacy policy and get participants' consent before taking photos of them. Offer an opt-out option for participants who do not want to have photos taken. Clearly communicate what the photos will be used for and by whom, for example, to enhance this documentation.
  9. License: If your participants have agreed to share and use the photos, choose an appropriate license under which to license the photos. We recommend the Creative Commons license. For more information, see the project's license terms page.
  10. Sharing on Social Media: Share the photos on social media platforms to create a visual memory of the event and increase the visibility of the event.

By preparing and taking care of these things, you can ensure that you are able to document the event effectively and create a visual record of the event that can be shared and enjoyed for years to come.

Follow-up🔗

Follow-up activities are an essential part of the workshop planning process. They help to ensure that the workshop's objectives are met and that the participants leave the workshop with a sense of accomplishment. Here are a few things to consider when planning follow-up activities after an event like a workshop:

  1. Follow-up with participants: Send out a survey or contact participants individually to gather feedback on their experience during the workshop. This feedback can be used to improve future workshops and address any issues that may have arisen.
  2. Share resources and information: Share any relevant resources such as presentations, handouts, or any other materials that will help the participants continue their learning after the workshop.
  3. Build a community: Encourage participants to connect and share their experiences with each other. This can be done through online forums, social media groups, or other platforms. Building a community of enthusiasts and collaborators will help to ensure that the workshop's goals and objectives are met and that the participants leave the workshop with a sense of accomplishment.
  4. Continual learning: Provide additional training opportunities or resources for participants to continue their learning after the workshop. This could be through follow-up workshops, webinars, or online tutorials.
  5. Track progress: Keep track of the progress of the participants, check if they are applying what they learned during the workshop and give feedback to help them improve.

Improve this training program🔗

As with any training program, there is always room for improvement. To ensure that this program continues to meet the needs of its attendees, it is important to actively seek feedback and make changes as necessary.

Here are a few ways to improve this training program:

  1. Gather feedback: Regularly gather feedback from attendees, instructors and other stakeholders to understand how the program is being received and identify areas for improvement.
  2. Review and revise content: Review the content of the program and make changes as necessary to ensure that it is up-to-date, accurate, and relevant to the attendees.
  3. Continuously update the material: Continuously update the material, adding new information and best practices as it becomes available.
  4. Use different learning methods: Use different learning methods to accommodate different learning styles, such as hands-on activities, group discussions, and online resources.
  5. Encourage participation: Encourage participation and collaboration among attendees, creating an interactive and dynamic learning experience.
  6. Use modern technologies: Use modern technologies to enhance the learning experience, such as virtual reality, gamification, and AI-based learning.
  7. Assess the impact: Assess the impact of the program on the attendees and make changes as necessary to ensure that the program is achieving its intended goals.

For more information on how to contribute to this document and improve this training program, please see the contribute section on Writing Documentation.

Trainings🔗

The success of the PlanktoScope community depends on the people who generously share their knowledge and expertise about its production and use with others, helping to promote its widespread adoption and use. By actively participating in the community and sharing their insights and experiences, individuals can contribute to the growth and success of the PlanktoScope, ultimately benefiting not just the community but also the broader field of study.

The Train the trainer program🔗

The train the trainer program is a training program designed to equip individuals with the knowledge and skills needed to deliver training to others. The goal of a train the trainer program is to build capacity within the PlanktoScope community by volunteers to become trainers themselves.

This guide is intended to provide you with a solid foundation of knowledge and understanding about the PlanktoScope, enabling you to confidently develop and deliver your own training program for others. Whether you are an experienced user looking to share your expertise with others or a newcomer to the PlanktoScope looking to learn more about its capabilities and applications, this guide is designed to help you gain the necessary skills and knowledge to successfully teach others about this powerful tool.

Event types🔗

Build workshop🔗

Organizing a build workshop can be a challenging but rewarding experience. It requires careful planning and execution to ensure that the workshop is successful. This trainer manual is designed to guide you through the process of organizing a build workshop.

Selecting the production site🔗

Choosing the right production site for preparing and manufacturing the PlanktoScope Kits is an important step in the workshop planning process. The production site should have the necessary tools and equipment, as well as the knowledge and expertise to manufacture the PlanktoScope Kits. Here are a few things to consider when choosing a production site:

  1. Check the Manufacturing and Assembly Guides: Before choosing a production site, make sure to review the PlanktoScope Kit Manufacturing Guide and the Device Assembly Guide. These guides will provide detailed information on the necessary tools and equipment required for the production of the PlanktoScope Kits.
  2. Visit Fablab and Hackspaces: Consider visiting Fablabs or Hackspaces in your region. These organizations often have a culture of openness and may be willing to support you with your project. They may have the necessary tools and equipment to produce the PlanktoScope Kits, as well as the knowledge and expertise to guide you through the production process.
  3. Commercial Manufacturing: Look for a facility that has the capability to handle small scale production runs, a good quality control process and a logistic plan to ship the product to the final destination. Many

Tip

For the PlanktoScope case, for example, you can look for woodworking companies. They often have a CNC machine and are familiar with the process of ditigal production.

Material procurement🔗

Building a PlanktoScope requires a specific set of materials. In order to ensure that the workshop runs smoothly and that all attendees are able to successfully build their own PlanktoScope, it is important to properly plan and execute the procurement of materials. The following is a step-by-step guide on how to properly plan and execute the procurement of materials for a workshop:

  1. Prepare the order list: Use the bill of materials (BOM) as a starting point to create a comprehensive list of all materials needed for the workshop. Expand it with additional columns for suppliers, delivery dates, prices, shipping costs, and import taxes.
  2. Plan for packaging: Plan for extra packaging so you can assemble the parts as shown in the instructions. Try to minimize plastic as much as possible.
  3. Research suppliers: Research suppliers and see if there are local options, if you can consolidate orders to save costs and ensure timely delivery.
  4. Compare prices: Compare the prices of different suppliers to minimize the total cost.
  5. Plan for spare parts: Plan for spare parts in case something is broken or lost.
  6. Check your Budget: Check your budget and ensure that you have enough funds to cover the cost of all materials, shipping, and any additional expenses before placing your orders.
  7. Place orders: Once you have identified the best suppliers, place orders for all of the materials that you need. Be sure to factor in lead time when placing orders to ensure that the materials will arrive in time for the workshop.
  8. Track orders: Keep track of your orders and expected delivery dates, mark a component when it arrives. Contact suppliers if there are any delays or problems with delivery.
  9. Communicate: Communicate with participants if there are issues with timely delivery. It may make sense to postpone the workshop if there is not enough time to prepare and test everything. The participants will be grateful and will understand if it helps to ensure that everything runs smoothly.

By following this process, you can ensure that all materials are procured and organized well in advance of the workshop, to avoid any last-minute delays or complications.

Note

If you have difficulty finding the components you need, contact us and we will be happy to help you find the right alternative.

Warning

Have a backup plan and be prepared for unexpected events that may occur during the procurement process. Allow two months for delivery, as some specialty parts may travel a long way and require additional time for customs inspection.

Tip

Let us know your results, we would love to hear what solutions you found and how cost effective you were able to make the PlanktoScope.

Prepare the Kit🔗

Kit preparation for the workshop is an important step in the preparation process. This ensures that participants have the materials and equipment they need to complete the workshop and build their own PlanktoScope. Here are a few things to keep in mind when preparing the kits:

  1. Review the Bill of Materials (BOM): Review the Bill of Materials (BOM) for the PlanktoScope to ensure that you have all the necessary parts and materials for the workshop. The parts list can be found in the Device Assembly Guide and lists all components and quantities needed to build a microscope.
  2. Divide the kit components according to the BOM: Once the materials have been received, divide the kit components from the orders according to the Bill of Materials (BOM) of the PlanktoScope. This will ensure that each participant receives the correct components and that there are no missing parts.
  3. Have extra components: Have extra components on hand in case of any missing or damaged parts during the workshop.
  4. Package the kits: Package the kits in a way that makes it easy for the participants to find and use the components during the workshop.
  5. Label materials: Label the packages as described in Device Assembly Guide so that they are easy to find and distribute during the workshop.
  6. Preparation of the housing parts: Prepare the housing parts by applying the surface sealant and insert the nuts to screw the housing as described in the Kit Manufacturing Guide.
  7. Cutting and soldering of electronic cables: Cut and solder the electronic cables for the PlanktoScope. This will save time during the workshop and ensure that the participants have all the necessary cables to complete the assembly.
  8. Setting up the embedded development environment: Set up the embedded development environment and flash the eeprom of the PlanktoScope hat. This will ensure that the PlanktoScope hat is ready to be used during the workshop.
  9. Download the Raspberry Pi image: Download the Raspberry Pi image and flash it to the SD card. This will ensure that the participants have a ready to use image for the PlanktoScope.
  10. Test the kits: Test the kits before the workshop to ensure that all components are working correctly and that the instructions are clear and easy to follow. This will help to ensure that the participants have a positive and productive experience during the workshop.

Tip

Identify any items that are time consuming during the workshop and not particularly important or complex to explain. These tasks can be completed in advance to save time during the workshop. This will make it easier for the participants to assemble the PlanktoScope during the workshop.

Conducting the workshop🔗

It's finally here! After all the planning, preparation, and anticipation, the build workshop is about to begin. Take a deep breath and let's go!

  1. Prepare the presentation: Prepare the presentation device and start your slides.
  2. Check-In: Once the Participants arrive, complete the check-in, share the agenda and set expectations for the workshop.
  3. Venue: Provide information about the venue, including where to find restrooms and where to buy food.
  4. Digital tools: Provide information about the digital tools that will be used during the workshop, such as the platform for collaboration, the survey tool and the chat channel, and how to access them.
  5. Data privacy: Inform about the privacy policy and the forms that need to be signed by the participants if you want to take photos.
  6. Introduction round: Begin with a round of introductions and give everyone a chance to introduce themselves, their background, and their interest in the project.
  7. Provide an overview: Provide details about the project, including the general mode of operation, the working materials such as the kit, the documentation and the git repository.
  8. Provide the Kits and Tools: Provide the Kit and Tools to each participant with a kit and the necessary tools.
  9. Follow the build instructions: Depending on the format you have chosen, start implementing by following the Kit Manufacturing guide or Device Assembly guide
  10. Follow the operation instructions: Now that you have successfully assembled the PlanktoScope, you can proceed to operation of the PlanktoScope by following the Getting started and User interface instructions.
  11. Final Test: For a final test you can use for example pure cultures or a sample taken with a Plankton net from a surrounding waters.

Field trip🔗

Are you an expert in organizing field trips? Share your skills with the PlanktoScope community by documenting the process! By documenting how you organize a field trip, you can help others create successful events and bring more event options to the PlanktoScope community. Your documentation will be a valuable resource for anyone looking to plan a field trip, and it will also help to grow and strengthen the PlanktoScope community. Don't miss this opportunity to contribute to the community, start documenting your process today!

Hackathon🔗

Are you a master at organizing Hackathons? Share your knowledge with the PlanktoScope community by documenting the process! By documenting how you organize a Hackathon, you can help others create successful events and bring more event options to the PlanktoScope community. Your documentation will be a valuable resource for anyone looking to host a Hackathon, and it will also help to grow and strengthen the PlanktoScope community. Don't miss this opportunity to contribute to the community, start documenting your process today!

General planning methods🔗

Organizing a workshop can be a challenging but rewarding experience. It requires careful planning and execution to ensure that the workshop is successful. This trainer module is designed to guide you through the process of organizing any type of event.

By following the guidelines, you will be able to plan a workshop that is engaging, productive, and successful. It will also help you to create a sense of community among participants and will help them continue their learning after the workshop.

Building a team🔗

Every project needs a team to support it. The team should be composed of individuals with a diverse set of skills and experiences to ensure all aspects of the workshop are effectively covered.

  1. Identify the roles and responsibilities: Determine the key areas that need to be covered during the workshop and assign specific roles to team members. For example, one team member may be responsible for organizing logistics, while another may be responsible for creating the agenda.
  2. Assemble the team: Once the roles and responsibilities have been identified, begin assembling the team. Consider individuals with relevant skills and experiences, as well as those who have a passion for the topic of the workshop. It is also important to have a mix of team members from different departments or backgrounds to bring a variety of perspectives to the planning process.
  3. Communicate effectively: Establish clear lines of communication within the team to ensure that everyone is on the same page. This can be done through regular meetings, email, or a team collaboration platform.
  4. Encourage participation: Encourage team members to actively participate in the planning process by sharing their ideas and feedback. This will help to ensure that everyone feels invested in the success of the workshop.
  5. Appoint a leader: Appoint a leader for the team who will be responsible for coordinating the planning process and ensuring that the team stays on track. The leader should be someone who is organized, a good communicator, and able to delegate tasks effectively.

Communication channels🔗

Choosing the right communication channels is an important step in the planning process for a workshop, as it is crucial not only for the organizing team but also for the participants during and after the workshop. The right communication channels can help to build a fluent community, improve collaboration and keep everyone informed and on the same page.

  1. Choose the right channels: Once the needs have been identified, choose the communication channels that will best serve those needs. Email, chat, and video conferencing are all popular options. If the group is small, a group chat or email chain may be sufficient. If the group is larger or more dispersed, a video conferencing platform may be more appropriate.
  2. Make sure they are accessible: Ensure that the communication channels you choose are accessible to all participants. This may include providing training or support for those who are less familiar with the tools you are using.
  3. Communicate expectations: Clearly communicate the expectations for using the communication channels to the participants. This includes guidelines for how often and when to check the channels, as well as how to respond to messages.
  4. Continuity: Make sure that you have continuity in the communication channels after the workshop. This will help to build a fluent community and to keep the participants connected and engaged. Use the same channels to share updates and resources, or to organize follow-up events or activities.

Note

Email is a reliable and widely-used communication channel that can be used for sending out workshop updates, sending materials, and answering questions. It is also a good option for sending out reminders and follow-up information after the workshop.

Note

Chat networks, such as Matrix, are a great option for secure, real-time and decentralized communication during the workshop. They allow participants to ask questions, share resources and collaborate on projects in real-time. They can also be used for group discussions and as a platform for sharing feedback. Additionally, chat platforms can be used as a platform for post-workshop communication and to build a fluent community.

Tip

If you need assistance with creating a Chat for your workshop, please let us know. We can easily set up new subchannels within our PlanktoScope Slack channel to support communication and collaboration during your workshop. This will also help facilitate the exchange of information within the community.

Selecting digital tools🔗

The right tools can help to facilitate communication, collaboration, and organization, making the workshop experience more productive and enjoyable for everyone.

  1. Use web-based tools: Whenever possible, use web-based tools that can be accessed from any device with an internet connection. This will make it easier for participants to access and use the tools, regardless of their location or device.
  2. Use collaborative note-taking tools: You might use web-based tools like HedgeDoc that allow participants to collaboratively collect notes during the workshop. This can help to ensure that everyone has access to the same information, and can help to make the workshop experience more productive and enjoyable for everyone.
  3. Use survey tools: You might use survey tools like LimeSurvey to gather information about the participants' needs and expectations for the workshop. This can help to ensure that the workshop is relevant, valuable, and effective for them.
  4. Use ticketing tools: You might use tools like Pretix to manage ticketing for the workshop. This can help to simplify the registration process, and can also provide valuable information about the attendees.

Find your audience🔗

If you already have an audience for your workshop, that's fantastic. But it's also a good idea to let others know about your plans and potentially expand your audience. Contact nongovernmental organizations, universities, and research institutions in your area to see if they would be interested in participating in or even helping to organize the workshop.

Tip

One way to get in touch with others who are interested in PlanktoScope is to join our Slack Channel. We can support you by sharing contacts of individuals and organizations who have expressed an interest in PlanktoScope.

Determining the need🔗

Understanding the needs of the participants will help to ensure that the workshop is relevant, valuable, and effective for them. Here are a few things to consider when determining the needs of the participants:

  1. Surveys and questionnaires: Use surveys and questionnaires to gather information about the participants' needs and expectations for the workshop. This can include their level of experience and knowledge, their specific interests and goals, and any challenges or concerns they may have.
  2. Pre-workshop consultation: Schedule pre-workshop consultations with the participants to discuss their needs and expectations in more detail. This can help to identify any specific areas of interest or concern, and can also provide an opportunity to address any questions or concerns the participants may have.
  3. Audience analysis: Analyze the characteristics of the audience, such as their profession, level of education and experience, and any other relevant details. This will give you a better idea of the type of content that will be most relevant and useful for the participants.
  4. Feedback: Ask for feedback from participants after the workshop and take it into account when planning future workshops. This feedback can be used to improve the overall experience and to tailor the workshop to better meet the needs of the participants.

Defining the goals🔗

Defining the goals of a workshop is an essential step in the planning process. The goals will serve as the foundation for the workshop, guiding the content and activities that are included.

  1. Number of participants: The workshop should be designed for a specific number of participants. Depending on the available resources, the number of participants can range from small groups of 4-8 people to larger groups of 8-12 people.
  2. Number of microscopes: The goal of the workshop is to build a specific number of PlanktoScope Microscopes. It is important to have the necessary materials and tools for each participant to build their own microscope.
  3. Content: The workshop will include both theoretical and practical content. The theoretical content will cover the principles of open-source hardware and software and the specific design of the PlanktoScope Microscope. The practical content will focus on the assembly and usage of the microscope, including hands-on experience with soldering and other techniques.

Tip

Depending on the time, resources, and audience, it is important to carefully decide what activities and tasks should be done during the workshop and what should be prepared upfront. This will ensure that the workshop runs smoothly and efficiently, and that the participants are able to fully engage and participate in the activities. Additionally, by carefully planning and preparing upfront, you can minimize the chances of overwhelming attendees with problems or difficulties that may arise during the workshop.

Financial planning🔗

The cost of materials, equipment, and other expenses can add up quickly, so it is important to have a plan in place to secure funding. Here are a few things to consider when planning the finances for your workshop:

  1. Decide on the cost of the kits: One of the first things to consider is whether you want to offer the kits for sale to the participants or if you want them to purchase the kits themselves. If you choose to offer the kits for sale, you will need to factor in the cost of materials and other expenses, such as shipping and handling. If you choose to have the participants purchase the kits themselves, you will need to provide them with information on where to purchase the kits and the estimated cost.
  2. Check for funding opportunities: There may be organizations or foundations that would be willing to support your workshop financially. It's a good idea to research potential sources of funding such as grants, sponsorships, and crowdfunding campaigns. Additionally, look for local or regional organizations that are working in the same field as your workshop, they might be interested in supporting your initiative.
  3. Reach out to potential sponsors: Once you have identified potential sources of funding, reach out to them to inquire about their funding opportunities. Be prepared to provide them with information about the workshop, including the goals, objectives, and expected outcomes. Be sure to include information about the open-source nature of the project, as this may make it more attractive to organizations with an interest in open-source technology.
  4. Look for cost-saving options: In addition to securing funding, there are also ways to save money on expenses. Consider renting equipment or space rather than purchasing it. Reach out to local universities or community organizations to see if they have equipment or space that you can use for the workshop at a reduced cost or for free.

Tip

If you are organizing the workshop as an individual, consider running the project through a non-profit organization to facilitate the collection of donations. This will also help to ensure transparency and accountability for the funding received. Alternatively, you can choose a commercially active organization that can provide proper accounting and financial management for the workshop participants. This will provide a clear financial record and can help to ensure that the workshop is run in a professional and organized manner.

Creating a timetable🔗

Creating a schedule for a workshop is an important step in the planning process. A well-organized schedule will help to ensure that the workshop runs smoothly and that all the important topics are covered. Here are a few things to consider when creating a schedule for your workshop:

  1. Plan for more than just a day: A workshop may take more than one day to complete, so be sure to plan accordingly. Consider the amount of time required to cover all the topics, and allocate enough time for each one.
  2. Assign an expected duration to each item on the schedule: Assign an expected duration to each item on the schedule so that participants know how much time they should expect to spend on each topic. This will also help you to ensure that you have allocated enough time for each topic.
  3. Allocate time for breaks and activities: Make sure to allocate time for breaks, meals and other activities such as group discussions, teamwork, or hands-on activities. This will help to keep the participants engaged and energized throughout the workshop.
  4. Plan for contingencies: Include some flexibility in the schedule to allow for unexpected events or delays. This will help to ensure that the workshop stays on track even if things don't go exactly as planned.

Venue selection🔗

The location should be convenient and accessible for the participants, and should be equipped with the necessary resources to make the workshop a success. Here are a few things to consider when choosing a workshop location for a workshop on building an open-source PlanktoScope microscope:

  1. Reach out to Universities, research institutions, Fablabs, Hackspaces or non-profit organizations: Reach out to organizations that might have an interest in the PlanktoScope, and a community that might support you with free access to their location.
  2. Check the equipment: Make sure the location is equipped with the necessary resources such as a whiteboard, projector/TV, and other equipment that may be required for the workshop.
  3. Check the accessibility: Check the accessibility of the location with the public transport system and parking availability.
  4. Check for food provision: Consider if there is a possibility to go shopping or how to provide food for the course participants during the workshop.
  5. Check the environment: Consider the environment of the location, make sure it is comfortable, has enough space and is well-ventilated for the workshop.

Announcing the event🔗

When announcing the event, it is important to include the following information:

  1. Date: Provide a specific date, start and end time for the workshop, and ensure there is enough lead time for preparation, including ordering or manufacturing materials and coordinating with suppliers. Allow ample time between announcing the workshop and the actual event.
  2. Goal: Clearly communicate the specific goal of the workshop, such as to build a fully functional planktoscope and learn how to use it.
  3. What attendees will learn in the workshop: Clearly outline the specific skills or knowledge that will be covered in the workshop, such as how to assemble the kit, soldering the through-hole components of the controller, and working with the software.
  4. Instructor's background: Provide some notes about the instructor's qualifications or experience that make them well-suited to lead the workshop, such as experience working with planktoscope.
  5. Target audience: Clearly indicate the target group of the workshop, such as researchers, engineers or designers.
  6. Previous knowledge: Specify any previous knowledge required for the workshop, such as soldering skills or experience working with open-source hardware and software.
  7. Implementation method: Describe the form of the workshop, such as a step-by-step guide.
  8. Documentation: Consider sharing the documentation beforehand, so they can familiarize themselves with the process.
  9. Cost: Clearly communicate the cost of the workshop.
  10. Schedule: Provide a clear and detailed schedule of the workshop, including the duration of the workshop, for example, one day of building and one day of using the plankoscope.
  11. Location: Provide the location of the workshop, including information on how to get there with public transportation or Arrival by car and parking. Also, provide a link to a map service
  12. Registration: Details of the registration process, including information on where to obtain a ticket and any deadlines for registration.
  13. Contact details: Additionally, it may be helpful to include contact information for any questions.
  14. Images: Include some visually appealing images, such as from a previous workshop or field trip, to show what attendees can expect from the event. This can additionally be a great way to build anticipation and excitement, thus motivating more people to attend the workshop.
  15. Media: Post your offer on a website or social media platform that is relevant to the workshop topic and your target audience. This way you can increase visibility and reach a wider audience, which increases the chances of getting more attendees.

Tip

If you already have a group of interested people, send a link to the announcement via email or chat and invite them personally.

Preparing a presentation🔗

Preparing a presentation for a build workshop is an important step in the preparation process. It helps to ensure that the participants have the information they need to complete the workshop and understand the concepts behind building the Planktoscope.

  1. Gather resources: Gather resources such as images, videos, and diagrams that can be used to support the presentation. These resources can be found on the Planktoscope website or other sources.
  2. Outline the main topics: Outline the main topics that will be covered during the workshop, such as the components of the microscope, the assembly process, and the use of the microscope.
  3. Prepare a handout: Prepare a handout or a guide that the participants can use during the workshop to follow the steps, and have it ready to be printed or shared digitally
  4. Practice the presentation: Practice the presentation several times before the workshop to ensure that it runs smoothly and that you are comfortable with the material.
  5. Be ready to adapt: Be ready to adapt the presentation during the workshop to fit the needs of the participants.

Here are some topics that should be covered in a presentation:

  1. Event: Provide an overview of the event, including the goal of the workshop.
  2. Schedule: Provide an timetable for the event, including breaks, start and end times, and any planned activities for the next day.
  3. Venue: Provide information about the venue, including where to find restrooms and where to buy food.
  4. Instructor: Provide information about the instructor, including his or her background, and how to get in touch with him or her
  5. Digital tools: Provide information about the digital tools that will be used during the workshop, such as the platform for collaboration, the survey tool and the chat channel, and how to access them
  6. Data privacy: Provide information about the data privacy policy and the forms that need to be signed by the participants.
  7. Follow-ups: Point out follow-up actions such as the survey and that participation can be very helpful in improving the offer.
  8. Communication: Inform about the communication channels that will be used during the workshop and complete the onboarding.
  9. Introduction round: A round of introductions at the beginning of a workshop helps to create a sense of community and connection among the participants, allows the instructor to tailor the workshop to the group's needs, addresses potential language barriers, creates a sense of accountability, and helps participants to be more focused and relaxed.
  10. About the project: Provide details about the project, including the working materials such as the kit, the documentation, and the git repository.

Send an final Reminder🔗

Make sure participants are well informed and can find their way to you by sending a final reminder before the start so everything is well prepared.

  1. Schedule for the event: Include a detailed schedule for the event, including breaks, start and end times, and any planned activities for the next day. This will help participants to plan their time and make the most of the workshop.
  2. About the venue: Provide detailed information about the venue, including the address, public transportation options, and parking situation. Make sure to include any specific instructions or requirements for accessing the venue.
  3. About the documentation: Provide a link to the documentation, such as the assembly and manufacturing guide, that the participants can familiarize themselves with before the workshop. This will help them to be better prepared and make the most of the workshop.
  4. Cancellation policy: Remind the participants that now is the last opportunity to cancel their registration. This will allow other individuals on the waiting list to attend the workshop.
  5. Final Instructions: Provide any final instructions or important information that the participants should be aware of before the workshop.

Documenting the event🔗

Documenting a PlanktoScope workshop through photography is essential for several reasons. Photos can be used to showcase the workshop activities and the learning process of the participants. This can be useful for sharing information about the workshop with others, and for promoting future workshops.

  1. Equipment: Make sure you have the necessary equipment to document the event, including a camera (DSLR or mirrorless camera), lenses, memory cards, and batteries.
  2. Backup: Always make sure to have a backup plan for your equipment and photos, such as bringing extra memory cards and batteries.
  3. Lighting: Take into account the lighting conditions and make sure to have the right settings for your camera to capture the best possible images.
  4. Planning: Plan out the photos you want to take, taking into account the theme, location and schedule of the event.
  5. Composition: Pay attention to the composition of your photos and make sure to use techniques such as the rule of thirds and leading lines to create visually appealing images.
  6. Capturing candid moments: In addition to capturing posed shots, make sure to capture candid moments that capture the atmosphere and emotions of the event.
  7. Post-processing: Once the event is over, review and edit your photos to make them look their best.
  8. Data Privacy and Opt-Out: Pay attention to the privacy policy and get participants' consent before taking photos of them. Offer an opt-out option for participants who do not want to have photos taken. Clearly communicate what the photos will be used for and by whom, for example, to enhance this documentation.
  9. License: If your participants have agreed to share and use the photos, choose an appropriate license under which to license the photos. We recommend the Creative Commons license. For more information, see the project's license terms page.
  10. Sharing on Social Media: Share the photos on social media platforms to create a visual memory of the event and increase the visibility of the event.

By preparing and taking care of these things, you can ensure that you are able to document the event effectively and create a visual record of the event that can be shared and enjoyed for years to come.

Follow-up🔗

Follow-up activities are an essential part of the workshop planning process. They help to ensure that the workshop's objectives are met and that the participants leave the workshop with a sense of accomplishment. Here are a few things to consider when planning follow-up activities after an event like a workshop:

  1. Follow-up with participants: Send out a survey or contact participants individually to gather feedback on their experience during the workshop. This feedback can be used to improve future workshops and address any issues that may have arisen.
  2. Share resources and information: Share any relevant resources such as presentations, handouts, or any other materials that will help the participants continue their learning after the workshop.
  3. Build a community: Encourage participants to connect and share their experiences with each other. This can be done through online forums, social media groups, or other platforms. Building a community of enthusiasts and collaborators will help to ensure that the workshop's goals and objectives are met and that the participants leave the workshop with a sense of accomplishment.
  4. Continual learning: Provide additional training opportunities or resources for participants to continue their learning after the workshop. This could be through follow-up workshops, webinars, or online tutorials.
  5. Track progress: Keep track of the progress of the participants, check if they are applying what they learned during the workshop and give feedback to help them improve.

Improve this training program🔗

As with any training program, there is always room for improvement. To ensure that this program continues to meet the needs of its attendees, it is important to actively seek feedback and make changes as necessary.

Here are a few ways to improve this training program:

  1. Gather feedback: Regularly gather feedback from attendees, instructors and other stakeholders to understand how the program is being received and identify areas for improvement.
  2. Review and revise content: Review the content of the program and make changes as necessary to ensure that it is up-to-date, accurate, and relevant to the attendees.
  3. Continuously update the material: Continuously update the material, adding new information and best practices as it becomes available.
  4. Use different learning methods: Use different learning methods to accommodate different learning styles, such as hands-on activities, group discussions, and online resources.
  5. Encourage participation: Encourage participation and collaboration among attendees, creating an interactive and dynamic learning experience.
  6. Use modern technologies: Use modern technologies to enhance the learning experience, such as virtual reality, gamification, and AI-based learning.
  7. Assess the impact: Assess the impact of the program on the attendees and make changes as necessary to ensure that the program is achieving its intended goals.

For more information on how to contribute to this document and improve this training program, please see the contribute section on Writing Documentation.

Frequently Asked Questions🔗

This FAQ has been compiled to answer common questions about the PlanktoScope project and how you can get involved. We hope you find it useful and we look forward to working with you to advance our knowledge of the oceans!

Can I purchase a PlanktoScope?🔗

You can purchase a PlanktoScope - either as a kit of parts to assemble yourself or as a fully preassembled device - from a small business called FairScope, which was started by the inventor of the PlanktoScope in order to make PlanktoScopes easier to obtain. For more information, please refer to our page on how to obtain a PlanktoScope.

Where do I get support or find the necessary tools to build PlanktoScope?🔗

To find the necessary tools and knowledge to produce the PlanktoScope, consider visiting a Fablab or Hackspaces in your region. These organizations often have a culture of openness and may be willing to support you with your project.

And if you have specific questions or problems, you can always report them in the Slack Channel and in the best case you will find someone there who can support you.

Frequently Asked Questions🔗

This FAQ has been compiled to answer common questions about the PlanktoScope project and how you can get involved. We hope you find it useful and we look forward to working with you to advance our knowledge of the oceans!

Can I purchase a PlanktoScope?🔗

You can purchase a PlanktoScope - either as a kit of parts to assemble yourself or as a fully preassembled device - from a small business called FairScope, which was started by the inventor of the PlanktoScope in order to make PlanktoScopes easier to obtain. For more information, please refer to our page on how to obtain a PlanktoScope.

Where do I get support or find the necessary tools to build PlanktoScope?🔗

To find the necessary tools and knowledge to produce the PlanktoScope, consider visiting a Fablab or Hackspaces in your region. These organizations often have a culture of openness and may be willing to support you with your project.

And if you have specific questions or problems, you can always report them in the Slack Channel and in the best case you will find someone there who can support you.

PlanktoScope Documentation🔗

planktoscope_hero

Welcome to the documentation for the PlanktoScope project! Here are some quick links to help you navigate the documentation depending on what you what you want to do:

  1. "I want to get a PlanktoScope!"
  2. "I want to learn how to operate a PlanktoScope!"
  3. "I want to fix something which isn't working on my PlanktoScope!"
  4. "I want to get involved in the PlanktoScope community!"
  5. "I want to study the design of the PlanktoScope!"

What is PlanktoScope?🔗

Plankton are living things which drift with the water currents in our world's oceans, rivers, and lakes. Lots of plankton are very small - so small that we need tools called microscopes in order for us to see them. One type of plankton is phytoplankton: plant-like plankton which take a huge amount of carbon dioxide from the air and become the food for all other life in the water - like the grasses of the sea. Because of this, plankton are very important to the health of our planet.

But there’s still a lot we don’t know about what’s happening with groups of plankton and how they’re changing: most tools would be too hard and expensive for us to use to get much detail about how every group of plankton is changing across an entire ocean. If we can make tools which give detailed information and which everyone can use - everywhere, all the time - then we can learn more about how the oceans will change because of things people and companies are doing.

The PlanktoScope is a low-cost, open-source, and portable microscope designed to take detailed photos of tiny plankton from lots of water, so that we can count the different kinds of plankton in the water.

The PlanktoScope at tfom23 Expo

What is the PlanktoScope project?🔗

The PlanktoScope project is a community project to develop the PlanktoScope as a tool and to help people use it for a variety of purposes around the world. It is part of a broader movement toward making scientific tools more accessible and affordable, while also empowering citizen scientists, educators, and researchers to study and monitor aquatic ecosystems.

Who are PlanktoScopes for?🔗

We want the PlanktoScope to be a tool which is easy to use for anyone who's interested in the tiny things which live in our oceans, and for anyone who cares about the health of our oceans - not just scientists, but also sailors, marine farmers, makers, fishing communities, and students. However, we still need to make many improvements to the PlanktoScope in order to reach this goal. Most of the people who currently enjoy using PlanktoScopes have some experience with using microscopes, a tolerance for handling software problems, and a sense of adventure for trying out new technologies which are still in development.

We also want PlanktoScopes to be easy to use for people around the world. Currently, the PlanktoScope software's user interface and documentation are all in English; we will need software and translation help to support other languages. The PlanktoScope community mainly works in English, though we also have active community members whose primary languages are French and Japanese.

We are excited about the possibility of using PlanktoScopes for measuring things besides plankton - for example, counting and identifying microplastics, or monitoring suspended cell cultures, or even detecting parasites in certain diseases. However, we have not yet developed or assessed the PlanktoScope as a tool which people could use for these other purposes.

If you want to help to improve the PlanktoScope, to build a PlanktoScope community in a non-English language, or to explore new uses for PlanktoScopes, please get involved in our global community!

PlanktoScope Documentation🔗

planktoscope_hero

Welcome to the documentation for the PlanktoScope project! Here are some quick links to help you navigate the documentation depending on what you what you want to do:

  1. "I want to get a PlanktoScope!"
  2. "I want to learn how to operate a PlanktoScope!"
  3. "I want to fix something which isn't working on my PlanktoScope!"
  4. "I want to get involved in the PlanktoScope community!"
  5. "I want to study the design of the PlanktoScope!"

What is PlanktoScope?🔗

Plankton are living things which drift with the water currents in our world's oceans, rivers, and lakes. Lots of plankton are very small - so small that we need tools called microscopes in order for us to see them. One type of plankton is phytoplankton: plant-like plankton which take a huge amount of carbon dioxide from the air and become the food for all other life in the water - like the grasses of the sea. Because of this, plankton are very important to the health of our planet.

But there’s still a lot we don’t know about what’s happening with groups of plankton and how they’re changing: most tools would be too hard and expensive for us to use to get much detail about how every group of plankton is changing across an entire ocean. If we can make tools which give detailed information and which everyone can use - everywhere, all the time - then we can learn more about how the oceans will change because of things people and companies are doing.

The PlanktoScope is a low-cost, open-source, and portable microscope designed to take detailed photos of tiny plankton from lots of water, so that we can count the different kinds of plankton in the water.

The PlanktoScope at tfom23 Expo

What is the PlanktoScope project?🔗

The PlanktoScope project is a community project to develop the PlanktoScope as a tool and to help people use it for a variety of purposes around the world. It is part of a broader movement toward making scientific tools more accessible and affordable, while also empowering citizen scientists, educators, and researchers to study and monitor aquatic ecosystems.

Who are PlanktoScopes for?🔗

We want the PlanktoScope to be a tool which is easy to use for anyone who's interested in the tiny things which live in our oceans, and for anyone who cares about the health of our oceans - not just scientists, but also sailors, marine farmers, makers, fishing communities, and students. However, we still need to make many improvements to the PlanktoScope in order to reach this goal. Most of the people who currently enjoy using PlanktoScopes have some experience with using microscopes, a tolerance for handling software problems, and a sense of adventure for trying out new technologies which are still in development.

We also want PlanktoScopes to be easy to use for people around the world. Currently, the PlanktoScope software's user interface and documentation are all in English; we will need software and translation help to support other languages. The PlanktoScope community mainly works in English, though we also have active community members whose primary languages are French and Japanese.

We are excited about the possibility of using PlanktoScopes for measuring things besides plankton - for example, counting and identifying microplastics, or monitoring suspended cell cultures, or even detecting parasites in certain diseases. However, we have not yet developed or assessed the PlanktoScope as a tool which people could use for these other purposes.

If you want to help to improve the PlanktoScope, to build a PlanktoScope community in a non-English language, or to explore new uses for PlanktoScopes, please get involved in our global community!

Operation🔗

This page provides basic instructions for operating your PlanktoScope.

getting started

Connect directly to your PlanktoScope🔗

In order to operate your PlanktoScope, you will need to connect to your PlanktoScope from a separate device (a computer, tablet, or phone) with a web browser. If this is your first time setting up or connecting to your PlanktoScope, you will need to set up a direct network connection between your computer and your PlanktoScope.

Connect with an Ethernet cable🔗

You can connect your computer to the PlanktoScope by plugging an Ethernet cable between your computer and your PlanktoScope's Raspberry Pi.

Connect with the PlanktoScope's isolated Wi-Fi network🔗

Unless you have already configured your PlanktoScope to connect to an existing Wi-Fi network, your PlanktoScope will create its own isolated Wi-Fi network (like a Wi-Fi hotspot, but without internet access). The Wi-Fi network created by your PlanktoScope should appear on your computer's list of available Wi-Fi networks a few minutes after you turn on power to your PlanktoScope.

wifi-network.png

As you can see, the name of your PlanktoScope's Wi-Fi network will be of the format pkscope-{random word}-{random word}-{random number}. This name corresponds exactly to the serial number of the Raspberry Pi computer in your PlanktoScope, so it is a unique Wi-Fi network name; and the unique name of your machine has format {random-word}-{random-word}-{random number}, which is just the name of the Wi-Fi network but without the pkscope- prefix (e.g. chain-list-27764). You should connect to the Wi-Fi network specific to your PlanktoScope.

Access your PlanktoScope's software🔗

Once you connect your computer to your PlanktoScope, you will need to access your PlanktoScope's software from a web browser on your computer. You should try opening the following URLs in your web browser (try opening them in the following order, and just use the first one which works):

Tip

If you know the machine name of your PlanktoScope (which has format {random-word}-{random-word}-{random number}, e.g. chain-list-27764, you can also try the following URLs after replacing {machine-name} with the actual machine name of your PlanktoScope:

http://pkscope-{machine-name}.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)

http://{machine-name}.pkscope (this should work unless your web browser is configured to use a Private DNS provider)

You will need to use a URL with your PlanktoScope's machine name if your computer has network connections to multiple PlanktoScopes, e.g. via multiple Ethernet cables. In such a situation, using http://home.pkscope or http://pkscope.local may cause you to access the software for a different PlanktoScope connected to your computer than the one you had intended to access.

Warning

You may encounter older documents which ask you to connect to http://planktoscope.local:1880/ui, which is the URL to use for software version 2.3 and even older versions. That link does not work on software versions newer than v2.3; instead, you should use the links listed above.

One of the above URLs should work, and your web browser should show a landing page with a list of links:

landing-page.png

You should click on the "Node-RED dashboard" link; this will open a new tab with the primary interface for operating your PlanktoScope. Once you have opened the Node-RED dashboard, you should proceed to our User interface guide to understand how to use it.

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.

For quantitative imaging of water samples, refer to the following protocols published by members of the PlanktoScope community:

Operation🔗

This page provides basic instructions for operating your PlanktoScope.

getting started

Connect directly to your PlanktoScope🔗

In order to operate your PlanktoScope, you will need to connect to your PlanktoScope from a separate device (a computer, tablet, or phone) with a web browser. If this is your first time setting up or connecting to your PlanktoScope, you will need to set up a direct network connection between your computer and your PlanktoScope.

Connect with an Ethernet cable🔗

You can connect your computer to the PlanktoScope by plugging an Ethernet cable between your computer and your PlanktoScope's Raspberry Pi.

Connect with the PlanktoScope's isolated Wi-Fi network🔗

Unless you have already configured your PlanktoScope to connect to an existing Wi-Fi network, your PlanktoScope will create its own isolated Wi-Fi network (like a Wi-Fi hotspot, but without internet access). The Wi-Fi network created by your PlanktoScope should appear on your computer's list of available Wi-Fi networks a few minutes after you turn on power to your PlanktoScope.

wifi-network.png

As you can see, the name of your PlanktoScope's Wi-Fi network will be of the format pkscope-{random word}-{random word}-{random number}. This name corresponds exactly to the serial number of the Raspberry Pi computer in your PlanktoScope, so it is a unique Wi-Fi network name; and the unique name of your machine has format {random-word}-{random-word}-{random number}, which is just the name of the Wi-Fi network but without the pkscope- prefix (e.g. chain-list-27764). You should connect to the Wi-Fi network specific to your PlanktoScope.

Access your PlanktoScope's software🔗

Once you connect your computer to your PlanktoScope, you will need to access your PlanktoScope's software from a web browser on your computer. You should try opening the following URLs in your web browser (try opening them in the following order, and just use the first one which works):

Tip

If you know the machine name of your PlanktoScope (which has format {random-word}-{random-word}-{random number}, e.g. chain-list-27764, you can also try the following URLs after replacing {machine-name} with the actual machine name of your PlanktoScope:

http://pkscope-{machine-name}.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)

http://{machine-name}.pkscope (this should work unless your web browser is configured to use a Private DNS provider)

You will need to use a URL with your PlanktoScope's machine name if your computer has network connections to multiple PlanktoScopes, e.g. via multiple Ethernet cables. In such a situation, using http://home.pkscope or http://pkscope.local may cause you to access the software for a different PlanktoScope connected to your computer than the one you had intended to access.

Warning

You may encounter older documents which ask you to connect to http://planktoscope.local:1880/ui, which is the URL to use for software version 2.3 and even older versions. That link does not work on software versions newer than v2.3; instead, you should use the links listed above.

One of the above URLs should work, and your web browser should show a landing page with a list of links:

landing-page.png

You should click on the "Node-RED dashboard" link; this will open a new tab with the primary interface for operating your PlanktoScope. Once you have opened the Node-RED dashboard, you should proceed to our User interface guide to understand how to use it.

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.

For quantitative imaging of water samples, refer to the following protocols published by members of the PlanktoScope community:

Maintenance and Repair🔗

Instructions for maintaining and repairing the PlanktoScope.

Cleaning the optics🔗

  • Begin by turning off the microscope and unplugging it from any power source. Gently remove any dust or debris using a soft, dry cloth.
  • To clean the lenses and other optics, use a lens cleaning solution and a lens cleaning tissue or cloth. Gently wipe the optics in a circular motion, starting from the center and working outward. Avoid applying too much pressure or using a rough cloth, as this can scratch or damage the optics.
  • Once you have finished cleaning the optics, use a dry cloth to remove any excess moisture or cleaning solution.

Software updates🔗

The PlanktoScope project aims to keep improving the PlanktoScope software by fixing problems and making the software simpler and easier to use, releasing a new version of the software a few times each year. At the same time, we aim to keep the software compatible with all previous officially-released versions of the PlanktoScope hardware. For this reason, we strongly recommend everyone to keep their PlanktoScopes updated to run the latest stable release of the PlanktoScope software, and the PlanktoScope documentation will only support the latest stable release. You can always find the latest stable release at https://github.com/PlanktoScope/PlanktoScope/releases/latest, which will redirect you to a web page for the latest stable release.

Currently, you will need to re-flash the SD card of your PlanktoScope's embedded Raspberry Pi in order to update the PlanktoScope software to the latest version, and then you will need to reapply any custom software configurations you had set (e.g. hardware settings). We are also developing an easier and less disruptive way to update the PlanktoScope software, but it is not yet ready for use.

Maintenance and Repair🔗

Instructions for maintaining and repairing the PlanktoScope.

Cleaning the optics🔗

  • Begin by turning off the microscope and unplugging it from any power source. Gently remove any dust or debris using a soft, dry cloth.
  • To clean the lenses and other optics, use a lens cleaning solution and a lens cleaning tissue or cloth. Gently wipe the optics in a circular motion, starting from the center and working outward. Avoid applying too much pressure or using a rough cloth, as this can scratch or damage the optics.
  • Once you have finished cleaning the optics, use a dry cloth to remove any excess moisture or cleaning solution.

Software updates🔗

The PlanktoScope project aims to keep improving the PlanktoScope software by fixing problems and making the software simpler and easier to use, releasing a new version of the software a few times each year. At the same time, we aim to keep the software compatible with all previous officially-released versions of the PlanktoScope hardware. For this reason, we strongly recommend everyone to keep their PlanktoScopes updated to run the latest stable release of the PlanktoScope software, and the PlanktoScope documentation will only support the latest stable release. You can always find the latest stable release at https://github.com/PlanktoScope/PlanktoScope/releases/latest, which will redirect you to a web page for the latest stable release.

Currently, you will need to re-flash the SD card of your PlanktoScope's embedded Raspberry Pi in order to update the PlanktoScope software to the latest version, and then you will need to reapply any custom software configurations you had set (e.g. hardware settings). We are also developing an easier and less disruptive way to update the PlanktoScope software, but it is not yet ready for use.

Sample collection🔗

The most common way to collect samples for the PlanktoScope is to use a plankton net.

Plankton Net🔗

A plankton net is a scientific tool used to collect plankton samples from aquatic environments. Plankton are small, drifting organisms that play a vital role in marine ecosystems. They include a diverse range of species, including bacteria, algae, protozoa, and small animals such as crustaceans and mollusks. Plankton nets are designed to capture these tiny organisms as they drift through the water column.

Plankton nets typically consist of a fine mesh net attached to a long, narrow handle. The net is usually cone- or cylinder-shaped, with a small opening at the base and a wider opening at the top. The net is lowered into the water and dragged through the water column, collecting plankton as it goes. The collected plankton is then collected in a sample bottle or container for further study.

Plankton nets can be used in a variety of aquatic environments, including oceans, lakes, and rivers. They are commonly used in scientific research to study the diversity and abundance of plankton in different ecosystems, as well as their role in the food web and the broader ecosystem. Plankton nets are also used in environmental monitoring programs to track changes in plankton populations over time.

network list

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.

Sample collection🔗

The most common way to collect samples for the PlanktoScope is to use a plankton net.

Plankton Net🔗

A plankton net is a scientific tool used to collect plankton samples from aquatic environments. Plankton are small, drifting organisms that play a vital role in marine ecosystems. They include a diverse range of species, including bacteria, algae, protozoa, and small animals such as crustaceans and mollusks. Plankton nets are designed to capture these tiny organisms as they drift through the water column.

Plankton nets typically consist of a fine mesh net attached to a long, narrow handle. The net is usually cone- or cylinder-shaped, with a small opening at the base and a wider opening at the top. The net is lowered into the water and dragged through the water column, collecting plankton as it goes. The collected plankton is then collected in a sample bottle or container for further study.

Plankton nets can be used in a variety of aquatic environments, including oceans, lakes, and rivers. They are commonly used in scientific research to study the diversity and abundance of plankton in different ecosystems, as well as their role in the food web and the broader ecosystem. Plankton nets are also used in environmental monitoring programs to track changes in plankton populations over time.

network list

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.

User interface guide🔗

This guide will help you understand how to use the Node-RED dashboard, which is the primary user interface for operating the PlanktoScope.

Home

Home🔗

When you open the "Node-RED dashboard link" from the PlanktoScope's landing page, you will reach a page like what is shown in the screenshot above.

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

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

You can then click on "Shutdown". The machine will ask for a final confirmation and will then shut itself down.

Home Shutdown

Sample Tab🔗

Sample

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

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

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

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

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

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

This simple page will allow you to preview and download 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

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

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 the US, 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

On this page you can find links to view the logs generated by the Python backend, and buttons to restart the Python backend's hardware controller or segmenter, as well as buttons to restart or shut down your PlanktoScope's Raspberry Pi computer.

Hardware Settings🔗

Hardware Settings

You should not touch anything here unless you have received specific instructions to do so, e.g. as part of our post-installation configuration guide, or as part of a guide for calibrating your PlanktoScope.

User interface guide🔗

This guide will help you understand how to use the Node-RED dashboard, which is the primary user interface for operating the PlanktoScope.

Home

Home🔗

When you open the "Node-RED dashboard link" from the PlanktoScope's landing page, you will reach a page like what is shown in the screenshot above.

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

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

You can then click on "Shutdown". The machine will ask for a final confirmation and will then shut itself down.

Home Shutdown

Sample Tab🔗

Sample

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

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

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

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

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

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

This simple page will allow you to preview and download 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

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

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 the US, 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

On this page you can find links to view the logs generated by the Python backend, and buttons to restart the Python backend's hardware controller or segmenter, as well as buttons to restart or shut down your PlanktoScope's Raspberry Pi computer.

Hardware Settings🔗

Hardware Settings

You should not touch anything here unless you have received specific instructions to do so, e.g. as part of our post-installation configuration guide, or as part of a guide for calibrating your PlanktoScope.

Changelog🔗

The design of the PlanktoScope's hardware has been evolving to fix usability issues and improve the quality of images captured by the PlanktoScope. Thus, multiple versions of the hardware have been developed:

v2.6🔗

This is the latest version of the PlanktoScope hardware, and it is the version currently sold by FairScope. It replaced the optical components so that the PlanktoScope produces higher-quality images.

v2.5🔗

This was the first version of the PlanktoScope hardware made commercially available by FairScope, a small business started by the inventor of the PlanktoScope in order to make it easier for people to obtain PlanktoScopes. It is a minor variation of the v2.4 hardware design and includes all of the changes made in previous hardware versions - including a custom-designed PCB HAT, a glass capillary flowcell. The mechanical structure of this design uses CNC-milled parts rather than laser-cut parts.

v2.4🔗

This was a prototype which replaced the ibidi u-Slide flowcell with a simpler flowcell design based on rectangular glass capillaries, in order to fix various issues with the ibidi flowcells and to make it possible for people to make their own flowcells.

This version was only an internal prototype for the PlanktoScope development team.

v2.3🔗

This was a prototype version of the hardware which replaced the Adafruit Stepper Motor HAT and the Yahboom RGB Cooling HAT with a custom-designed PCB HAT, in order to simplify overall assembly and provide additional features which solved problems with the v2.1 hardware design. As a result, a different configuration of the PlanktoScope software is required to control this version of the PlanktoScope hardware, as well as subsequent hardware versions. This version also significantly changed the physical dimensions of the PlanktoScope's mechanical structure, in order to solve some problems with the v2.1 design.

This version was only an internal prototype for the PlanktoScope development team.

v2.2🔗

This was a prototype version of the hardware which replaced the Adafruit Stepper Motor HAT with a Waveshare Stepper Motor HAT.

This version was only an internal prototype for the PlanktoScope development team.

v2.1🔗

This is the first version of the PlanktoScope hardware which was publicly released, and it is one of the two hardware designs described in the initial paper introducing the PlanktoScope. It simplified the hardware's robustness and mechanical assembly by integrating most subsystems into a monolithic architecture whose structure uses laser-cut parts. The electronic hardware components of this design are all available off-the-shelf, using an Adafruit Stepper Motor HAT to control various actuators and a Yahboom RGB Cooling HAT to cool the PlanktoScope's embedded Raspberry Pi computer. The mechanical structure was designed for fabrication using a laser cutter. This hardware version included some design flaws, such as providing no way to replace the Raspberry Pi's micro-SD card without partially disassembling the PlanktoScope.

v1.0🔗

This was the first prototype of the PlanktoScope, and it is one of the two hardware designs described in the initial paper introducing the PlanktoScope. Its mechanical structure featured a fully modular, stackable architecture consisting of triangular layers which coupled together with magnets.

This design was complicated to assemble, and it suffered from unreliable electronic communication between the modules, so it was never publicly released.

Changelog🔗

The design of the PlanktoScope's hardware has been evolving to fix usability issues and improve the quality of images captured by the PlanktoScope. Thus, multiple versions of the hardware have been developed:

v2.6🔗

This is the latest version of the PlanktoScope hardware, and it is the version currently sold by FairScope. It replaced the optical components so that the PlanktoScope produces higher-quality images.

v2.5🔗

This was the first version of the PlanktoScope hardware made commercially available by FairScope, a small business started by the inventor of the PlanktoScope in order to make it easier for people to obtain PlanktoScopes. It is a minor variation of the v2.4 hardware design and includes all of the changes made in previous hardware versions - including a custom-designed PCB HAT, a glass capillary flowcell. The mechanical structure of this design uses CNC-milled parts rather than laser-cut parts.

v2.4🔗

This was a prototype which replaced the ibidi u-Slide flowcell with a simpler flowcell design based on rectangular glass capillaries, in order to fix various issues with the ibidi flowcells and to make it possible for people to make their own flowcells.

This version was only an internal prototype for the PlanktoScope development team.

v2.3🔗

This was a prototype version of the hardware which replaced the Adafruit Stepper Motor HAT and the Yahboom RGB Cooling HAT with a custom-designed PCB HAT, in order to simplify overall assembly and provide additional features which solved problems with the v2.1 hardware design. As a result, a different configuration of the PlanktoScope software is required to control this version of the PlanktoScope hardware, as well as subsequent hardware versions. This version also significantly changed the physical dimensions of the PlanktoScope's mechanical structure, in order to solve some problems with the v2.1 design.

This version was only an internal prototype for the PlanktoScope development team.

v2.2🔗

This was a prototype version of the hardware which replaced the Adafruit Stepper Motor HAT with a Waveshare Stepper Motor HAT.

This version was only an internal prototype for the PlanktoScope development team.

v2.1🔗

This is the first version of the PlanktoScope hardware which was publicly released, and it is one of the two hardware designs described in the initial paper introducing the PlanktoScope. It simplified the hardware's robustness and mechanical assembly by integrating most subsystems into a monolithic architecture whose structure uses laser-cut parts. The electronic hardware components of this design are all available off-the-shelf, using an Adafruit Stepper Motor HAT to control various actuators and a Yahboom RGB Cooling HAT to cool the PlanktoScope's embedded Raspberry Pi computer. The mechanical structure was designed for fabrication using a laser cutter. This hardware version included some design flaws, such as providing no way to replace the Raspberry Pi's micro-SD card without partially disassembling the PlanktoScope.

v1.0🔗

This was the first prototype of the PlanktoScope, and it is one of the two hardware designs described in the initial paper introducing the PlanktoScope. Its mechanical structure featured a fully modular, stackable architecture consisting of triangular layers which coupled together with magnets.

This design was complicated to assemble, and it suffered from unreliable electronic communication between the modules, so it was never publicly released.

PlanktoScope Hat Hardware🔗

planktoscope_hero

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.

PlanktoScope Hat Hardware🔗

planktoscope_hero

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.

Product Specifications🔗

Product specifications for the PlanktoScope hardware are listed below for each hardwaare version. For more information on each hardware version, refer to the hardware changelog.

v2.6🔗

Overview:

  • Weight: 3.5 kg

  • Enclosure:

    • Dimensions: 27.5 cm (length) x 12.5 cm (width) x 10.5 cm (height)
    • Material: bamboo plywood
    • Fabrication process: CNC milling

Functionalities🔗

  • Automated image acquisition, with a motorized pump and an embedded computer
  • Precise focus adjustment, with motorized linear actuators
  • Continuous mixing of input sample to prevent sedimentation of heavier particles, with a USB-powered bubbler
  • On-board image processing, with the embedded computer
  • Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer
  • Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer

Subsystems🔗

planktoscope_hero

Optics:

  • Imaging characteristics:

    • Optical magnification: 1.33
    • Field of view: 3062 µm x 2295 µm
    • Optical pixel size: 0.75 µm
    • Depth of field: 95 µm

  • Internal camera: Raspberry Pi High Quality Camera

    • Sensor: Sony IMX477R
    • Resolution: 12.3 Megapixels (4056 x 3040 pixels)

  • Lenses:

    • Objective lens: 12 mm focal length, M12
    • Tube lens: 25 mm focal length, M12
    • Lens mount: M12x0.5

  • Illumination: white LED

Fluidics:

  • Flow cell: capillary with rectangular cross-section

    • Thickness: 300 µm
    • Material: glass

  • Internal tubing:

    • Material: Tygon S3 (contains no BPA or phthalates)
    • Dimensions: 1.6 mm (1/16") inner diameter, 3.2 mm (1/8") outer diameter
    • Connectors: Luer lock

  • Peristaltic pump

  • Sample intake capacity: 20 mL

Other internal electronics:

  • Embedded computer: Raspberry Pi 4 Model B

    • Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz
    • Memory: 4 GB RAM
    • Storage: 128 GB capacity (micro-SD card, UHS speed class 3)

  • Control board: PlanktoScope HAT v1.2

External interfaces & connectivity:

  • Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports
  • Wired networking: Gigabit Ethernet
  • Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi
  • Power input: 12 V DC, up to 4 A of current draw (5.1 x 2.2 mm DC barrel jack, center positive)
  • Latching push-button switch to toggle power

External AC-to-DC power adapter:

  • Input: 100-240 V AC, 50-60 Hz (IEC 60320 C8 socket)
  • Output: 12 V DC, up to 4 A of current output (5.1 x 2.2 mm DC barrel jack, center positive)
  • Dimensions: 126 mm (length) x 52 mm (width) x 35.5 mm (height)
  • Weight: 0.25 kg

System performance🔗

Image acquisition throughput:

  • Volume of sample measured: 2.1 µL per acquired image
  • Volume of sample pumped: ~15 µL per acquired image
  • Maximum image acquisition rate: ~60 images/min

Samples:

  • Object size range:

    • Minimum for taxonomy: ~20 µm diameter for round objects
    • Maximum: ~200 µm diameter for round objects (larger objects will clog the flow cell)

v2.5🔗

Overview:

  • Enclosure:

    • Dimensions: 27.5 cm (length) x 12.5 cm (width) x 10.5 cm (height)
    • Material: bamboo plywood
    • Fabrication process: CNC milling

Functionalities🔗

  • Automated image acquisition, with a motorized pump and an embedded computer
  • Precise focus adjustment, with motorized linear actuators
  • Continuous mixing of input sample to prevent sedimentation of heavier particles, with a USB-powered bubbler
  • On-board image processing, with the embedded computer
  • Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer
  • Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer

Subsystems🔗

planktoscope_hero

Optics:

  • Imaging characteristics:

    • Field of view: 3670 µm x 2675 µm
    • Optical pixel size: 0.88 µm

  • Internal camera: Raspberry Pi High Quality Camera

    • Sensor: Sony IMX477R
    • Resolution: 12.3 Megapixels (4056 x 3040 pixels)

  • Lenses:

    • Objective lens: 16 mm focal length, M12
    • Tube lens: 25 mm focal length, M12
    • Lens mount: M12x0.5

  • Illumination: white LED

Fluidics:

  • Flow cell: capillary with rectangular cross-section

    • Thickness: 300 µm
    • Material: glass

  • Internal tubing:

    • Material: Tygon S3 (contains no BPA or phthalates)
    • Dimensions: 1.6 mm (1/16") inner diameter, 3.2 mm (1/8") outer diameter
    • Connectors: Luer lock

  • Peristaltic pump

  • Sample intake capacity: 20 mL

Other internal electronics:

  • Embedded computer: Raspberry Pi 4 Model B

    • Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz
    • Memory: 4 GB RAM
    • Storage: 128 GB capacity (micro-SD card, UHS speed class 3)

  • Control board: PlanktoScope HAT v1.2

External interfaces & connectivity:

  • Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports
  • Wired networking: Gigabit Ethernet
  • Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi
  • Power input: 12 V DC, up to 4 A of current draw (5.1 x 2.2 mm DC barrel jack, center positive)
  • Latching push-button switch to toggle power

External AC-to-DC power adapter:

  • Input: 100-240 V AC, 50-60 Hz (IEC 60320 C8 socket)
  • Output: 12 V DC, up to 4 A of current output (5.1 x 2.2 mm DC barrel jack, center positive)
  • Dimensions: 126 mm (length) x 52 mm (width) x 35.5 mm (height)
  • Weight: 0.25 kg

System performance🔗

Image acquisition throughput:

  • Volume of sample pumped: ~15 µL per acquired image
  • Maximum image acquisition rate: ~60 images/min

Samples:

  • Object size range:

    • Maximum: ~200 µm diameter for round objects (larger objects will clog the flow cell)

v2.1🔗

Overview:

  • Enclosure:

    • Dimensions: ~32 cm (length) x ~5.5 cm (width) x ~15 cm (height)
    • Material: acrylic, plywood, or fiberboard
    • Fabrication process: laser cutting

Functionalities🔗

  • Automated image acquisition, with a motorized pump and an embedded computer
  • Precise focus adjustment, with motorized linear actuators
  • On-board image processing, with the embedded computer
  • Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer
  • Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer

Subsystems🔗

Optics:

  • Imaging characteristics:

    • Field of view: 2300 µm x 1730 µm
    • Optical pixel size: 0.75 µm

  • Internal camera: Raspberry Pi Camera Module 2

    • Sensor: Sony IMX219
    • Resolution: 8 Megapixels (3280 x 2464 pixels)

  • Lenses:

    • Objective lens: 12 mm focal length, M12
    • Tube lens: 25 mm focal length, M12
    • Lens mount: M12x0.5

  • Illumination: white LED

Fluidics:

  • Flow cell: ibidi µ-Slide I Luer channel slide

    • Thickness: 200 µm, 400 µm, 600 µm, or 800 µm
    • Material: Plastic (no surface modification)

  • Internal tubing:

    • Material: Tygon S3 (contains no BPA or phthalates)
    • Dimensions: 1.6 mm (1/16") inner diameter, 3.2 mm (1/8") outer diameter
    • Connectors: Luer lock

  • Peristaltic pump

  • Sample intake capacity: 20 mL

Other internal electronics:

External interfaces & connectivity:

  • Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports, 2 micro-HDMI ports
  • Wired networking: Gigabit Ethernet
  • Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi
  • Power input for embedded computer: 5 V DC, up to 3 A of current draw (USB-C)
  • Power input for motors: 5 - 12 V DC, depending on pump motor (5.1 x 2.2 mm DC barrel jack, center positive)

Product Specifications🔗

Product specifications for the PlanktoScope hardware are listed below for each hardwaare version. For more information on each hardware version, refer to the hardware changelog.

v2.6🔗

Overview:

  • Weight: 3.5 kg

  • Enclosure:

    • Dimensions: 27.5 cm (length) x 12.5 cm (width) x 10.5 cm (height)
    • Material: bamboo plywood
    • Fabrication process: CNC milling

Functionalities🔗

  • Automated image acquisition, with a motorized pump and an embedded computer
  • Precise focus adjustment, with motorized linear actuators
  • Continuous mixing of input sample to prevent sedimentation of heavier particles, with a USB-powered bubbler
  • On-board image processing, with the embedded computer
  • Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer
  • Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer

Subsystems🔗

planktoscope_hero

Optics:

  • Imaging characteristics:

    • Optical magnification: 1.33
    • Field of view: 3062 µm x 2295 µm
    • Optical pixel size: 0.75 µm
    • Depth of field: 95 µm

  • Internal camera: Raspberry Pi High Quality Camera

    • Sensor: Sony IMX477R
    • Resolution: 12.3 Megapixels (4056 x 3040 pixels)

  • Lenses:

    • Objective lens: 12 mm focal length, M12
    • Tube lens: 25 mm focal length, M12
    • Lens mount: M12x0.5

  • Illumination: white LED

Fluidics:

  • Flow cell: capillary with rectangular cross-section

    • Thickness: 300 µm
    • Material: glass

  • Internal tubing:

    • Material: Tygon S3 (contains no BPA or phthalates)
    • Dimensions: 1.6 mm (1/16") inner diameter, 3.2 mm (1/8") outer diameter
    • Connectors: Luer lock

  • Peristaltic pump

  • Sample intake capacity: 20 mL

Other internal electronics:

  • Embedded computer: Raspberry Pi 4 Model B

    • Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz
    • Memory: 4 GB RAM
    • Storage: 128 GB capacity (micro-SD card, UHS speed class 3)

  • Control board: PlanktoScope HAT v1.2

External interfaces & connectivity:

  • Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports
  • Wired networking: Gigabit Ethernet
  • Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi
  • Power input: 12 V DC, up to 4 A of current draw (5.1 x 2.2 mm DC barrel jack, center positive)
  • Latching push-button switch to toggle power

External AC-to-DC power adapter:

  • Input: 100-240 V AC, 50-60 Hz (IEC 60320 C8 socket)
  • Output: 12 V DC, up to 4 A of current output (5.1 x 2.2 mm DC barrel jack, center positive)
  • Dimensions: 126 mm (length) x 52 mm (width) x 35.5 mm (height)
  • Weight: 0.25 kg

System performance🔗

Image acquisition throughput:

  • Volume of sample measured: 2.1 µL per acquired image
  • Volume of sample pumped: ~15 µL per acquired image
  • Maximum image acquisition rate: ~60 images/min

Samples:

  • Object size range:

    • Minimum for taxonomy: ~20 µm diameter for round objects
    • Maximum: ~200 µm diameter for round objects (larger objects will clog the flow cell)

v2.5🔗

Overview:

  • Enclosure:

    • Dimensions: 27.5 cm (length) x 12.5 cm (width) x 10.5 cm (height)
    • Material: bamboo plywood
    • Fabrication process: CNC milling

Functionalities🔗

  • Automated image acquisition, with a motorized pump and an embedded computer
  • Precise focus adjustment, with motorized linear actuators
  • Continuous mixing of input sample to prevent sedimentation of heavier particles, with a USB-powered bubbler
  • On-board image processing, with the embedded computer
  • Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer
  • Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer

Subsystems🔗

planktoscope_hero

Optics:

  • Imaging characteristics:

    • Field of view: 3670 µm x 2675 µm
    • Optical pixel size: 0.88 µm

  • Internal camera: Raspberry Pi High Quality Camera

    • Sensor: Sony IMX477R
    • Resolution: 12.3 Megapixels (4056 x 3040 pixels)

  • Lenses:

    • Objective lens: 16 mm focal length, M12
    • Tube lens: 25 mm focal length, M12
    • Lens mount: M12x0.5

  • Illumination: white LED

Fluidics:

  • Flow cell: capillary with rectangular cross-section

    • Thickness: 300 µm
    • Material: glass

  • Internal tubing:

    • Material: Tygon S3 (contains no BPA or phthalates)
    • Dimensions: 1.6 mm (1/16") inner diameter, 3.2 mm (1/8") outer diameter
    • Connectors: Luer lock

  • Peristaltic pump

  • Sample intake capacity: 20 mL

Other internal electronics:

  • Embedded computer: Raspberry Pi 4 Model B

    • Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz
    • Memory: 4 GB RAM
    • Storage: 128 GB capacity (micro-SD card, UHS speed class 3)

  • Control board: PlanktoScope HAT v1.2

External interfaces & connectivity:

  • Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports
  • Wired networking: Gigabit Ethernet
  • Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi
  • Power input: 12 V DC, up to 4 A of current draw (5.1 x 2.2 mm DC barrel jack, center positive)
  • Latching push-button switch to toggle power

External AC-to-DC power adapter:

  • Input: 100-240 V AC, 50-60 Hz (IEC 60320 C8 socket)
  • Output: 12 V DC, up to 4 A of current output (5.1 x 2.2 mm DC barrel jack, center positive)
  • Dimensions: 126 mm (length) x 52 mm (width) x 35.5 mm (height)
  • Weight: 0.25 kg

System performance🔗

Image acquisition throughput:

  • Volume of sample pumped: ~15 µL per acquired image
  • Maximum image acquisition rate: ~60 images/min

Samples:

  • Object size range:

    • Maximum: ~200 µm diameter for round objects (larger objects will clog the flow cell)

v2.1🔗

Overview:

  • Enclosure:

    • Dimensions: ~32 cm (length) x ~5.5 cm (width) x ~15 cm (height)
    • Material: acrylic, plywood, or fiberboard
    • Fabrication process: laser cutting

Functionalities🔗

  • Automated image acquisition, with a motorized pump and an embedded computer
  • Precise focus adjustment, with motorized linear actuators
  • On-board image processing, with the embedded computer
  • Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer
  • Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer

Subsystems🔗

Optics:

  • Imaging characteristics:

    • Field of view: 2300 µm x 1730 µm
    • Optical pixel size: 0.75 µm

  • Internal camera: Raspberry Pi Camera Module 2

    • Sensor: Sony IMX219
    • Resolution: 8 Megapixels (3280 x 2464 pixels)

  • Lenses:

    • Objective lens: 12 mm focal length, M12
    • Tube lens: 25 mm focal length, M12
    • Lens mount: M12x0.5

  • Illumination: white LED

Fluidics:

  • Flow cell: ibidi µ-Slide I Luer channel slide

    • Thickness: 200 µm, 400 µm, 600 µm, or 800 µm
    • Material: Plastic (no surface modification)

  • Internal tubing:

    • Material: Tygon S3 (contains no BPA or phthalates)
    • Dimensions: 1.6 mm (1/16") inner diameter, 3.2 mm (1/8") outer diameter
    • Connectors: Luer lock

  • Peristaltic pump

  • Sample intake capacity: 20 mL

Other internal electronics:

External interfaces & connectivity:

  • Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports, 2 micro-HDMI ports
  • Wired networking: Gigabit Ethernet
  • Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi
  • Power input for embedded computer: 5 V DC, up to 3 A of current draw (USB-C)
  • Power input for motors: 5 - 12 V DC, depending on pump motor (5.1 x 2.2 mm DC barrel jack, center positive)

Technical Reference🔗

The PlanktoScope is a modular, open-source platform for high-throughput quantitative imaging of plankton samples. Its small size, ease of use, and low cost make it suitable for a variety of applications, including the monitoring of laboratory cultures or natural micro-plankton communities. It can be controlled from any WiFi-enabled device and can be easily reconfigured to meet the changing needs of the user.

Key Features🔗

Here are some key features of the PlanktoScope:

  1. Low cost: The PlanktoScope is designed to be affordable, with parts costing under $1000.
  2. Modular: The PlanktoScope is modular, meaning it can be easily reconfigured to meet the changing needs of users.
  3. Open-source: The PlanktoScope is based on open-source hardware and software, making it accessible to a wide community of engineers, researchers, and citizens.
  4. Versatility: The PlanktoScope is versatile, and can be used to study a variety of plankton types, including laboratory cultures and natural micro-plankton communities.
  5. High-throughput: The PlanktoScope is capable of high-throughput quantitative imaging, allowing users to analyze large numbers of samples quickly and efficiently.
  6. WiFi-enabled: The PlanktoScope can be controlled from any WiFi-enabled device, making it easy to use and deploy in a variety of settings.
  7. Portable: The PlanktoScope is small and portable, making it easy to transport and use in the field.
  8. Ease of use: The PlanktoScope is designed to be easy to use, with instructions for assembly and use available on the PlanktoScope website.

Technical Reference🔗

The PlanktoScope is a modular, open-source platform for high-throughput quantitative imaging of plankton samples. Its small size, ease of use, and low cost make it suitable for a variety of applications, including the monitoring of laboratory cultures or natural micro-plankton communities. It can be controlled from any WiFi-enabled device and can be easily reconfigured to meet the changing needs of the user.

Key Features🔗

Here are some key features of the PlanktoScope:

  1. Low cost: The PlanktoScope is designed to be affordable, with parts costing under $1000.
  2. Modular: The PlanktoScope is modular, meaning it can be easily reconfigured to meet the changing needs of users.
  3. Open-source: The PlanktoScope is based on open-source hardware and software, making it accessible to a wide community of engineers, researchers, and citizens.
  4. Versatility: The PlanktoScope is versatile, and can be used to study a variety of plankton types, including laboratory cultures and natural micro-plankton communities.
  5. High-throughput: The PlanktoScope is capable of high-throughput quantitative imaging, allowing users to analyze large numbers of samples quickly and efficiently.
  6. WiFi-enabled: The PlanktoScope can be controlled from any WiFi-enabled device, making it easy to use and deploy in a variety of settings.
  7. Portable: The PlanktoScope is small and portable, making it easy to transport and use in the field.
  8. Ease of use: The PlanktoScope is designed to be easy to use, with instructions for assembly and use available on the PlanktoScope website.

Operating System🔗

When you flash an SD card image with the PlanktoScope software as part of PlanktoScope's software setup process, that SD card image consists of the PlanktoScope OS. This document describes the architecture of the PlanktoScope OS as an operating system, in order to explain:

  • How the PlanktoScope software abstracts over the PlanktoScope hardware.

  • How the PlanktoScope manages the execution of software programs intended to run on the PlanktoScope.

This information is intended to help you understand:

  • The overall design of the PlanktoScope OS, including what functionalities it provides and what software it includes, and why we made certain design decisions.

  • How various software functionalities and responsibilities in the PlanktoScope are divided among the various programs in the PlanktoScope OS.

  • How various programs in the PlanktoScope OS support other programs which provide the PlanktoScope's high-level/end-user functionalities.

  • What tools you can use to perform software troubleshooting and system administration tasks with the PlanktoScope.

  • What kinds of new software you can develop and deploy to run on a PlanktoScope.

Each SD card image of the PlanktoScope's software consists of an operating system for the PlanktoScope; the definition of the term "operating system" can be tricky to demarcate, but for practical purposes this document follows Bryan Cantrill's characterization of the operating system as the special program that:

  • "Abstracts hardware to allow execution of other programs."
  • "Defines the liveness of the machine: without it, no program can run."
  • Provides some important components including the operating system kernel, libraries, commands, daemons, and other facilities.

This definition is a reasonable description of the PlanktoScope OS, because it's a program which abstracts the following hardware subsystems in a way that enables you to run other programs on the PlanktoScope which need to control or otherwise interact with the PlanktoScope's hardware:

  • A Raspberry Pi computer.

  • Various input/output devices such as actuators (e.g. the pump, the sample focus-adjustment actuators, and the illumination LED), sensors (e.g. the camera and the GPS module), and information storage devices (e.g. the real-time clock and the EEPROM).

Software deployment & execution🔗

In order to abstract the Raspberry Pi computer hardware to enable execution of other programs, the PlanktoScope OS merely uses software provided by other open-source projects:

  • The PlanktoScope OS is based on - and includes everything from the "Lite" image of - the Raspberry Pi OS (which in turn is based on Debian Linux), which provides abstractions for the Raspberry Pi's computer hardware via its custom Linux kernel and its included libraries. We use the Raspberry Pi OS because it provides Raspberry Pi-specific hardware support which we need and which is not easy to achieve with other Linux distros; and because it is the Linux distro with the best combination of familiarity, optimization, and maturity for the Raspberry Pi.

  • Lower-level system services - including services which we've added on top of the default Raspberry Pi OS - are launched and supervised by systemd, which provides a system and service manager. We use systemd because the Raspberry Pi OS provides it and relies on it.

  • Most of the PlanktoScope's software is (or eventually will be) executed as Docker containers by the dockerd daemon (which in turn is run by the docker.service systemd service). In the PlanktoScope OS, all Docker containers are declaratively specified, configured, and integrated together as Docker Compose applications. We use Docker because it enables us to isolate programs from each other so that they interact only in specifically-defined ways; this makes it easier for us to configure, integrate, distribute, and deploy the various programs running on the PlanktoScope.

The PlanktoScope OS is a 64-bit operating system.

Boot sequence🔗

Because the PlanktoScope OS is a systemd-based Linux system running on the Raspberry Pi, the PlanktoScope's initial boot sequence is described by external documentation of:

The systemd system manager starts a variety of services added by the PlanktoScope OS which do not exist in the default installation of the Raspberry Pi OS, such as docker.service. The startup ordering relationships between those services are listed in our reference document about services in the startup process.

System upgrades🔗

Traditional Linux distros such as the Raspberry Pi OS are designed to run software directly on the host OS using a shared collection of programs and system libraries provided by the Linux distro, and with programs and libraries installed and upgraded in-place directly on the host OS via the package managers provided by the distro, such as APT and pip. This causes the following challenges for system administration on the PlanktoScope:

  • These packages are not atomic in how they perform system upgrades of installed libraries and programs, so they can fail during the upgrade process (e.g. due to loss of power) in a way that leaves the system in an unknown and un-reproducible state. Such a state can be hard to revert or recover from, short of wiping and re-flashing the Raspberry Pi's SD card with a new OS installation; this would cause the loss of any OS customizations (e.g. installation of additional software) made by the user.

  • If an upgrade of all installed programs and libraries results in a system with problems (e.g. bugs in the new version of an installed program), it is hard to completely revert the system to the previous state. Thus, software upgrades involve a trade-off between extra work (e.g. to backup the SD card image before any upgrade) and extra risk (e.g. of software breakage which is hard to revert due to lack of backups).

  • Making certain customizations to the OS, such as adding additional programs/libraries or modifying system configuration files, increases the risk of configuration drift in which the system's actual state increasingly diverges over time from the state expected by the PlanktoScope's software maintainers, and thus becomes harder to understand, troubleshoot, or replace. User customizations to the OS cannot be easily separated from the default configuration of the OS, so it is complicated to copy only those customizations in order to drop them onto a fresh installation of the OS from a newer release - especially if the updated OS includes changes to default configurations which conflict with the user customizations.

  • Some Python packages required by PlanktoScope-specific programs (namely the PlanktoScope hardware controller and the PlanktoScope segmenter, which are both described in later sections of this document), such as picamera2 and opencv-python-headless, can only be installed as pre-built wheels from piwheels (which is used instead of PyPi because the PlanktoScope OS is not yet able to run as a 64-bit operating system) when certain versions of system libraries are installed, or else they must be re-compiled from source (which is prohitively slow on the Raspberry Pi for the affected Python packages). This makes dependencies more complicated to manage in maintenance of the PlanktoScope OS for creating and releasing new SD card images with updated software. The reliance on system libraries also increases the risk that a user-initiated upgrade or removal of some of the system's installed APT packages could cause breakage of some pip-managed Python packages which had been installed before the change.

All of the factors listed above increase the perceived risk (and/or the required effort for sufficient mitigation of that risk) of accidentally degrading system integrity by keeping all software on the OS up-to-date, which makes it harder for users to receive bugfixes, security patches, and new features in a timely manner. Indeed, outside of systems like phones and Chromebooks (whose operating systems automatically update themselves), it is common for users of operating systems to avoid installing security updates or OS upgrades out of a fear of breaking their installed software; this is especially common for users who rely on software to operate other scientific instruments, and for good reasons! But the PlanktoScope project currently does not have enough resources to be able to support users stuck on old versions of the PlanktoScope OS; instead, we want to make it easy and safe for all users to always keep their PlanktoScopes - even with customizations to the OS - automatically updated to the latest version of the PlanktoScope OS. We intend to achieve this by:

  • Running all PlanktoScope-specific programs which require system libraries (e.g. the PlanktoScope's Python-based programs) in Docker containers - with the required versions of the required system libraries bundled inside those containers - to isolate them from the host OS's libraries installed via APT. This way, APT packages will always be safe to add, upgrade, and remove on the host OS with negligible risk of interfering with PlanktoScope-specific software.

  • Enabling (almost) all software not provided by the default installation of the Raspberry Pi OS to be upgraded and downgraded in-place - either as container images or as replacements of files on the filesystem - with just a reboot. This way, software upgrades can be reverted in-place in case new bugs are introduced, and SD cards will only need to be re-flashed with new images once every few years (i.e. after a new major version of the Raspberry Pi OS is released).

  • Enabling most types of user-initiated OS customizations to be version-controlled (in a Git repository) and applied (as a system upgrade/downgrade) together with most of the default configurations added by the PlanktoScope OS over what is already present from the default installation of the Raspberry Pi OS. This way, user-initiated OS customizations can be easy to re-apply automatically even after an SD card is re-flashed with a fresh SD card image of the PlanktoScope OS.

Currently, we have partially implemented the systems necessary for these goals. Much of the PlanktoScope's software is not installed or upgraded directly on the host OS via APT or pip; instead, we use a (partially-implemented) tool called forklift which we're developing specifically to support the goals listed above, and which provides a robust way for us to fully manage deployment, configuration, and upgrading of:

  • All software which we run using Docker.
  • PlanktoScope-specific systemd services.
  • PlanktoScope-specific OS configuration files.

Everything managed by forklift is version-controlled in a Git repository, enabling easy backup and restoration of forklift-managed configurations even if the PlanktoScope's SD card is wiped and re-flashed.

Package management with forklift🔗

When you're just experimenting and you can tolerate the challenges mentioned above, it's fine to customize the PlanktoScope OS by installing software packages using pip directly on the OS and/or by making extensive changes to OS configuration files. However, once you actually care about keeping your customizations around - and especially if/when you want to share your customizations with other people - we recommend migrating those customizations into Forklift packages, which are just files and configuration files stored in a specially-structured Git repository which is also published online (e.g. on GitHub, GitLab, Gitea, etc.). forklift provides an easy way to package, publish, combine, and apply customizations via YAML configuration files in Git repositories; this enables easy sharing, configuration, (re-)composition, and downloading of Docker Compose applications, systemd services, and OS configuration files. Configurations of all deployments of Forklift packages on a computer running the PlanktoScope OS are specified and integrated in a single Git repository, a Forklift pallet. At any given time, each PlanktoScope has exactly one Forklift pallet deployed; switching between Forklift pallets (whether to try out a different set of customizations or to upgrade/downgrade all programs and OS configurations managed by Forklift) is easy and can be done by running just one command (forklift pallet switch, described below in the Applying published customizations subsection).

forklift is used very differently compared to traditional Linux system package managers like APT, for which you must run step-by-step commands in order to modify the state of your system (e.g. to install some package or install some other package). When using forklift, you instead edit configuration files which declare the desired state of your system (though some step-by-step commands are also provided by forklift to make editing of files easier), and then you ask forklift to try to reconcile the actual state of your system with the desired state. If you've worked with Hashicorp Terraform/OpenTofu before, this may sound very familiar to you - in fact, several aspects of forklift's design were inspired by Terraform.

Dependency management🔗

forklift is simpler than traditional package managers in some notable ways, including in the concept of dependencies between packages. For example, Forklift packages cannot specify dependencies on other Forklift packages; instead, they may declare that they depend on certain resources - and you must declare a deployment of some other package which provides those resources. And although forklift checks whether resource dependencies between package deployments are satisfied, it does not attempt to solve unmet dependencies. If you've worked with the Go programming language before, resource dependency relationships among Forklift packages are analogous to the relationships between functions which require arguments with particular interfaces and the types which implement those interfaces, with Forklift resources being analogous to Go interfaces.

This design is intended to facilitate replacement of particular programs with modified or customized versions of those programs. For example, a Forklift package could be declared as providing the same API on the same network port as some other package, so that one package can be substituted for the other while still maintaining compatibility with some other program which relies on the existence of that API. forklift also checks these resource declarations to ensure that any two packages which would conflict with each other (e.g. by trying to listen on the same network port) will be prevented from being deployed together.

Making & publishing customizations🔗

The workflow with forklift for developing/testing OS customizations, such as new package deployments or non-standard configurations of existing package deployments or substitutions of existing package deployments, is as follows:

  • Initialize a custom pallet based on (i.e. layered over) an existing pallet, using the forklift pallet init command (e.g. forklift pallet init --from github.com/PlanktoScope/pallet-standard@stable --as github.com/ethanjli/custom-pallet to make a starter which will be a customization of the latest stable version of the github.com/PlanktoScope/pallet-standard pallet, and which can be published to github.com/ethanjli/custom-pallet). (Note: the forklift pallet init command is not yet implemented, and pallet layering is not yet implemented; currently, pallets can only be created manually via the filesystem by cloning from an existing Git repository.)

  • Optionally, create new Forklift packages with definitions of Docker Compose applications and/or systemd services and/or OS configuration files, and configure the deployment of those packages by creating particular files in the pallet.

  • Optionally, add published Forklift repositories to the pallet with the forklift pallet add-repo command (e.g. forklift pallet add-repo github.com/ethanjli/pallet-example-minimal@main), so that one or more packages provided by those repositories can be deployed with the pallet by creating one or more package deployment configuration files for each package. The forklift pallet add-repo command is also used to upgrade or downgrade the version of the Forklift repository used by the pallet.

  • Optionally, add one or more files which override files from the existing pallet, in order to override the configurations specified by those files. (Note: file overrides are not yet implemented, because they are part of pallet layering functionality which is not yet implemented.)

  • Stage the pallet to be applied on the next boot of the PlanktoScope OS, with the forklift pallet stage command; when Forklift applies a pallet, it makes the PlanktoScope OS match the configuration of Forklift package deployments specified by the pallet.

  • Use git to commit changes and (ideally) push them to GitHub, in order to publish your customizations for other people to try out.

(TODO: create a "tutorial"-style page elsewhere in this docs site, and link to it from here; it could be as simple as creating a new pallet which adds a new helloworld-style Node-RED dashboard)

Applying published customizations🔗

The envisioned workflow for applying published customizations (which you or someone else already developed and pushed to a Git repository served by an online host such as GitHub) is only partially implemented so far, but it already works well for basic use-cases - and it is already used as part of the PlanktoScope OS's installation process for setting up the PlanktoScope OS over a Raspberry Pi OS image:

  • Stage the customized pallet to be applied on the next boot of the PlanktoScope OS, using the forklift pallet switch command (e.g. forklift pallet switch github.com/PlanktoScope/pallet-segmenter@edge to use the latest development/unstable version of the github.com/PlanktoScope/pallet-segmenter pallet).

  • Reboot the Raspberry Pi computer to apply the staged pallet. If the staged pallet cannot be successfully applied during boot, on subsequent boots forklift will instead apply the last staged pallet which was successfully applied. (Note: only a failure to update the Docker containers running on the OS is detected as a failed attempt to apply the staged pallet; if you cause problems with the systemd services or other OS configurations provided by your pallet but the Docker containers are all correctly updated, the pallet will still be considered to have been successfully applied.)

(TODO: create a "tutorial"-style page elsewhere in this docs site, and link to it from here; it could just be a pallet which reconfigures the docs-site deployment to serve the full site with hardware instructions, and which includes https://hub.docker.com/r/linuxserver/firefox or https://github.com/linuxserver/docker-chromium and/or https://github.com/linuxserver/docker-webtop and/or ZeroTier and/or an ML classifier GUI and/or Jupyter Tensorflow)

Note: currently all of forklift's functionality is only exposed through a command-line interface, but after the forklift tool stabilizes we plan to add a web browser-based graphical interface for use by a general audience.

PlanktoScope-specific hardware abstraction🔗

PlanktoScope-specific hardware modules are abstracted by PlanktoScope-specific programs which expose high-level network APIs (typically using MQTT and/or HTTP); other programs should use these APIs in order to interact with the PlanktoScope-specific hardware modules. To provide these APIs, the PlanktoScope OS adds the following services (beyond what is already provided by the default installation of the Raspberry Pi OS):

  • gpsd: for providing an abstraction for the PlanktoScope's GPS receiver.

  • chronyd: for managing synchronization of the Raspberry Pi's system clock with the PlanktoScope's GPS receiver and with any time sources available over the Internet.

  • The PlanktoScope hardware controller: for controlling PlanktoScope-specific hardware modules and abstracting them into high-level network APIs for other programs to interact with.

User interface🔗

Traditional operating systems provide a desktop environment with a graphical user interface for operating the computer. By contrast, the PlanktoScope OS provides a set of web browser-based graphical user interfaces for operating the PlanktoScope. This approach was chosen for the following reasons:

  • Most people already have a personal computing device (e.g. a phone or laptop). By relying on the user's personal computing device as the graphical interface for the PlanktoScope's software, the PlanktoScope project can reduce hardware costs by omitting a display from the PlanktoScope hardware.

  • The PlanktoScope's computational resources are limited and may often need to be fully used for data processing tasks. By offloading real-time interaction (such as rendering of the graphical display, and handling of mouse and keyboard events) to a separate device, we can ensure a smooth user experience even when the PlanktoScope's Raspberry Pi computer is busy with other work.

  • When the PlanktoScope is connected to the internet, its web browser-based graphical interfaces can be accessed remotely over the internet from other web browsers. This can be easier to set up - and have lower bandwidth requirements and higher responsiveness - compared to a remote-desktop system for remotely accessing a Raspberry Pi's graphical desktop. This is especially relevant when the PlanktoScope is deployed in a setting where it only has a relatively low-bandwidth internet connection.

The PlanktoScope OS adds the following network services which provide web browser-based graphical user interfaces to help users operate the PlanktoScope:

  • A Node-RED server which serves over HTTP the PlanktoScope Node-RED dashboard, a graphical interface for end-users to operate the PlanktoScope for image acquisition and image processing.

  • A datasets file browser for viewing, managing, uploading, and downloading image dataset files on the PlanktoScope. These files are generated and used by the PlanktoScope hardware controller and the PlanktoScope segmenter.

  • device-portal: a landing page with links for end-users to quickly access the various web browser-based interfaces mentioned above.

Note: we will probably simplify things by consolidating some of these components together into the PlanktoScope's Node-RED dashboard.

The PlanktoScope OS also provides various tools with web browser-based interfaces to aid with system administration and troubleshooting:

  • Cockpit: for performing system-administration tasks such as monitoring system resources, managing system services, viewing system logs, and executing commands in a terminal.

  • A system file browser for viewing, managing, editing, uploading, and downloading any file on the PlanktoScope.

  • A log file browser for viewing, downloading, and deleting log files files generated by the PlanktoScope hardware controller.

  • Dozzle: for viewing and monitoring logs of Docker containers.

  • Grafana: for monitoring and exploring metrics stored in Prometheus.

Finally, the PlanktoScope OS adds some command-line tools (beyond what is already provided by the default installation of the Raspberry Pi OS) for administrative tasks which system administrators, software developers, and advanced users may need to use:

  • vim: for editing text files.

  • byobu: for running processes persistently across ephemeral terminal sessions.

  • git: for interacting with Git repositories.

  • w3m and lynx: for interacting with web pages (such as Wi-Fi network captive portals) from the PlanktoScope.

  • docker: for managing and inspecting Docker containers.

Networking🔗

The PlanktoScope is often deployed in settings with limited or unstable internet access, and also in settings with no internet access at all. The PlanktoScope also needs to be deployable in remote settings where the user needs to control the PlanktoScope without being physically present. In both types of situations, the PlanktoScope's web browser-based interfaces need to remain accessible.

We solve this problem by allowing the PlanktoScope to connect to the internet over a known Wi-Fi network, and/or over Ethernet, so that the PlanktoScope's web browser-based interfaces can be accessed over the internet; and by making the PlanktoScope bring up a Wi-Fi hotspot (more formally, a wireless access point) using the Raspberry Pi's integrated Wi-Fi module in the absence of any known Wi-Fi network, so that the web browser-based interfaces can be accessed over the Wi-Fi hotspot.

When a device connects directly to the PlanktoScope (e.g. via the PlanktoScope's Wi-Fi hotspot, or via an Ethernet cable), the PlanktoScope acts as a DHCP server to assign itself certain static IP addresses (e.g. 192.168.4.1) and as a DNS server to assign itself certain domain names (e.g. home.pkscope), so that user can locate and open the PlanktoScope's web browser-based interfaces via those domain names. The PlanktoScope also announces itself under certain mDNS names (e.g. pkscope.local) which may work on networks where the PlanktoScope does not have a static IP address (e.g. because the PlanktoScope is connected to an existing Wi-Fi network).

When the PlanktoScope both has internet access and has devices connected to it (e.g. over a Wi-Fi hotspot or over Ethernet), the PlanktoScope shares its internet access with all connected devices, to enable the user to access web pages even when connected to the PlanktoScope. This is implemented in the PlanktoScope OS with network configurations for the PlanktoScope to act as a network router using Network Address Translation when it has internet access.

The standard PlanktoScope OS adds the following systemd services (beyond what is already provided by the default installation of the Raspberry Pi OS) for managing the PlanktoScope's network connectivity:

  • autohotspot (which in turn launches hostapd): a PlanktoScope-specific daemon for automatically checking the presence of known Wi-Fi networks, automatically connecting to any known Wi-Fi networks, and falling back to creating a Wi-Fi hotspot when no known Wi-Fi networks are present.

  • enable-interface-forwarding: configures the Linux kernel firewall's IP packet filter rules to forward packets between the Raspberry Pi's network interfaces, to allow the Raspberry Pi to act as a network router.

  • dnsmasq: for allowing computers connected to the PlanktoScope over a network to access the PlanktoScope using domain names defined on the PlanktoScope.

  • firewalld: a network firewall (currently disabled by default).

The standard PlanktoScope OS also adds the following systemd services for dynamically updating the system's network configuration during boot:

  • generate-machine-name: generates a human-readable machine name at /run/machine-name from the Raspberry Pi's serial number (or, if that's missing, from /etc/machine-d).

  • generate-hostname-templated: generates a temporary hostname file (which is used by a symlink at /etc/hostname) from /etc/hostname-template, which can include the machine name from /run/machine-name.

  • update-hostname: updates systemd-hostnamed so that the hostname matches what is specified by /etc/hostname.

  • assemble-dnsmasq-config-templated: generates a temporary dnsmasq drop-in config file (which is used by a symlink at /etc/dnsmasq.d/40-generated-templated-config) from drop-in config file templates at /etc/dnsmasq-templates.d.

  • assemble-hostapd-config-templated: generates a temporary hostapd drop-in config file (which is used by a symlink at /etc/hostapd/hostapd.conf.d/60-generated-templated.conf) from drop-in config file templates at /etc/hostapd/hostapd.conf-templates.d.

  • assemble-hostapd-config: generates a temporary hostapd config file (which is used by a symlink at /etc/hostapd/hostapd.conf) from drop-in config files at /etc/hostapd/hostapd.conf.d.

  • assemble-hosts-templated: generates a temporary hosts drop-in snippet (which is used by a symlink at /etc/hosts.d/50-generated-templated) from drop-in hosts snippet templates at /etc/hosts-templates.d.

  • assemble-hosts generates a temporary hosts file (which is used by a symlink at /etc/hosts) from drop-in snippets at /etc/hosts-templates.d.

The PlanktoScope OS also adds the following common services for integrating network APIs provided by various programs, and to facilitate communication among programs running on the PlanktoScope OS:

  • Mosquitto: a server which acts as an MQTT broker. This is used by the PlanktoScope hardware controller and segmenter (described below) to receive commands and broadcast notifications. This is also used by the PlanktoScope's Node-RED dashboard (described below) to send commands and receive notifications.

  • Caddy with the caddy-docker-proxy plugin: an HTTP server which acts as a reverse proxy to route all HTTP requests on port 80 from HTTP clients (e.g. web browsers) to the appropriate HTTP servers (e.g. the Node-RED server, Prometheus, and the PlanktoScope hardware controller's HTTP-MJPEG camera preview stream) running on the PlanktoScope.

Filesystem🔗

The PlanktoScope OS's filesystem makes some changes from the default Debian/Raspberry Pi OS filesystem structure so that /etc and /usr can be managed by Forklift while still being directly customizable by the system administrator. Specifically, a number of systemd services in the PlanktoScope OS run during early boot to:

  • Make a read-only mount (via the overlay-sysroot systemd service) of the initial root filesystem, at /sysroot.

  • Make a read-only mount of the next Forklift pallet to be applied (via the bindro-run-forklift-stages-current.service) from a subdirectory within /var/lib/forklift/stages to /run/forklift/stages/current.

  • Remount /usr (via the overlay-usr systemd service) as a writable overlay with a Forklift-managed intermediate layer (in a subdirectory within /var/lib/forklift/stages which can also be accessed at /run/forklift/stages/current/exports/overlays/usr) and /sysroot/usr as a base layer; any changes made by the system administrator to files in /usr will be transparently stored by the overlay in /var/lib/overlays/overrides/usr. This allows Forklift to provide extra files in /usr in an atomic way, while overrides made by the system administrator are stored separately.

  • Remount /etc (via the overlay-etc systemd service) as a writable overlay with a Forklift-managed intermediate layer (in a subdirectory within /var/lib/forklift/stages which can also be accessed at /run/forklift/stages/current/exports/overlays/etc) and /sysroot/etc as a base layer; any changes made by the system administrator to files in /etc will be transparently stored by the overlay in /var/lib/overlays/overrides/etc. This allows Forklift to provide extra files in /etc in an atomic way, while overrides made by the system administrator are stored separately.

  • Make a writable mount of /var/lib/forklift/stages to /home/pi/.local/share/forklift/stages (via the bind-.local-share-forklift-stages@home-pi systemd service) so that, when the pi user runs forklift commands like forklift pallet switch, those commands will update /var/lib/forklift/stages - and without requiring the use of sudo.

  • Update systemd (via the start-overlaid-units systemd service) with any new systemd units provided via Forklift, so that they will run during boot.

Beyond what is required by the Linux Filesystem Hierarchy Standard, the PlanktoScope OS sets the following conventions related to filesystem paths:

  • Scripts which are provided by Forklift and only used as part of systemd services should be provided in /usr/libexec, Forklift packages should export those scripts to overlays/usr/libexec (so, for example, they will be accessible in /run/forklift/stages/current/exports/overlays/usr/libexec).

  • Systemd units provided by Forklift should be provided in /usr/lib/systemd/system, and Forklift packages should export those units to overlays/usr/lib/systemd/system. Symlinks to enable those units should be provided in /etc/systemd/system, and Forklift packages should export those scripts to overlays/etc/systemd/system.

  • Forklift-provided systemd services which dynamically generate temporary files meant to be used in /etc should generate those temporary files at stable paths in /run/overlays/generated/etc. Forklift packages which provide such systemd services should also provide relative symlinks into those temporary files in /run/overlays/generated/etc to be exported into overlays/etc as overlays for the corresponding paths in /etc. For example, if a package provides a service to dynamically generate a hosts file meant to be used as /etc/hosts, that service should generate the file in /run/overlays/generated/etc/hosts and the package should export a symlink at overlays/etc/hosts which points to ../../run/overlays/generated/etc/hosts, so that /etc/hosts will be a symlink pointing to /run/overlays/generated/etc/hosts.

Observability & telemetry🔗

Although it is not a high priority yet, we would like to enable operators of large (>10) collections of PlanktoScopes to easily log and monitor the health and utilization of each PlanktoScope and to investigate issues with their PlanktoScopes, regardless of whether each PlanktoScope is deployed locally or remotely. The PlanktoScope OS currently includes the following common services to support system observability and telemetry both for the PlanktoScope OS as a system and for programs running on the PlanktoScope OS:

  • Prometheus: a server for collecting and storing metrics and for exposing metrics over an HTTP API.

  • Prometheus node exporter: for measuring computer hardware and OS monitoring metrics and exposing them over a Prometheus-compatible HTTP API.

In the future, we will instrument other PlanktoScope-specific programs (especially the PlanktoScope hardware controller) to export various metrics for Prometheus to collect and expose.

Data processing🔗

Because the PlanktoScope collects raw image datasets which are often too large to transfer efficiently over low-bandwidth or intermittent internet connections, the PlanktoScope needs to be able to process raw image data into lower-bandwidth data (e.g. cropped and segmented images of particles in the raw images, or even just counts of different classes of particles) without internet access. In other words, the PlanktoScope must support on-board data processing at the edge. The PlanktoScope OS adds the following services for on-board processing of data generated by the PlanktoScope:

  • The PlanktoScope segmenter: for processing raw image datasets acquired by the PlanktoScope hardware controller to detect and extract particles from raw images.

Note: in the future, the PlanktoScope OS will add more on-board services for processing the outputs of the PlanktoScope segmenter, and the PlanktoScope OS may also provide hardware abstractions (such as for AI accelerator modules) to support the deployment of neural-network models for data processing.

Security🔗

Currently, the PlanktoScope OS lacks basic security measures to make it safe for them to be connected to the internet; currently it is the responsibility of system administrators to add extremely basic risk mitigations, for example by:

  • Changing the password of the pi user away from the default of copepode.

  • Password-protecting the Node-RED dashboard editor, which can be used to execute arbitrary commands with root permissions.

  • Setting firewall rules.

  • Changing the password of the Wi-Fi hotspot away from the default of copepode, or disabling Wi-Fi hotspot functionality.

Other risk mitigations will require deeper changes to the PlanktoScope OS, such as:

  • Limiting the permissions and capabilities made available to various system services which currently run with root permissions

  • Password-protecting web browser-based user interfaces

  • Password-protecting network APIs.

We would like to start taking even just the very basic steps listed above to improve security, but security is not yet a high-enough priority for us to work on it with the limited resources available to us 🙃 - if you're interested in computer/network security and you'd like to help us as a volunteer on this project, please contact us!

Operating System🔗

When you flash an SD card image with the PlanktoScope software as part of PlanktoScope's software setup process, that SD card image consists of the PlanktoScope OS. This document describes the architecture of the PlanktoScope OS as an operating system, in order to explain:

  • How the PlanktoScope software abstracts over the PlanktoScope hardware.

  • How the PlanktoScope manages the execution of software programs intended to run on the PlanktoScope.

This information is intended to help you understand:

  • The overall design of the PlanktoScope OS, including what functionalities it provides and what software it includes, and why we made certain design decisions.

  • How various software functionalities and responsibilities in the PlanktoScope are divided among the various programs in the PlanktoScope OS.

  • How various programs in the PlanktoScope OS support other programs which provide the PlanktoScope's high-level/end-user functionalities.

  • What tools you can use to perform software troubleshooting and system administration tasks with the PlanktoScope.

  • What kinds of new software you can develop and deploy to run on a PlanktoScope.

Each SD card image of the PlanktoScope's software consists of an operating system for the PlanktoScope; the definition of the term "operating system" can be tricky to demarcate, but for practical purposes this document follows Bryan Cantrill's characterization of the operating system as the special program that:

  • "Abstracts hardware to allow execution of other programs."
  • "Defines the liveness of the machine: without it, no program can run."
  • Provides some important components including the operating system kernel, libraries, commands, daemons, and other facilities.

This definition is a reasonable description of the PlanktoScope OS, because it's a program which abstracts the following hardware subsystems in a way that enables you to run other programs on the PlanktoScope which need to control or otherwise interact with the PlanktoScope's hardware:

  • A Raspberry Pi computer.

  • Various input/output devices such as actuators (e.g. the pump, the sample focus-adjustment actuators, and the illumination LED), sensors (e.g. the camera and the GPS module), and information storage devices (e.g. the real-time clock and the EEPROM).

Software deployment & execution🔗

In order to abstract the Raspberry Pi computer hardware to enable execution of other programs, the PlanktoScope OS merely uses software provided by other open-source projects:

  • The PlanktoScope OS is based on - and includes everything from the "Lite" image of - the Raspberry Pi OS (which in turn is based on Debian Linux), which provides abstractions for the Raspberry Pi's computer hardware via its custom Linux kernel and its included libraries. We use the Raspberry Pi OS because it provides Raspberry Pi-specific hardware support which we need and which is not easy to achieve with other Linux distros; and because it is the Linux distro with the best combination of familiarity, optimization, and maturity for the Raspberry Pi.

  • Lower-level system services - including services which we've added on top of the default Raspberry Pi OS - are launched and supervised by systemd, which provides a system and service manager. We use systemd because the Raspberry Pi OS provides it and relies on it.

  • Most of the PlanktoScope's software is (or eventually will be) executed as Docker containers by the dockerd daemon (which in turn is run by the docker.service systemd service). In the PlanktoScope OS, all Docker containers are declaratively specified, configured, and integrated together as Docker Compose applications. We use Docker because it enables us to isolate programs from each other so that they interact only in specifically-defined ways; this makes it easier for us to configure, integrate, distribute, and deploy the various programs running on the PlanktoScope.

The PlanktoScope OS is a 64-bit operating system.

Boot sequence🔗

Because the PlanktoScope OS is a systemd-based Linux system running on the Raspberry Pi, the PlanktoScope's initial boot sequence is described by external documentation of:

The systemd system manager starts a variety of services added by the PlanktoScope OS which do not exist in the default installation of the Raspberry Pi OS, such as docker.service. The startup ordering relationships between those services are listed in our reference document about services in the startup process.

System upgrades🔗

Traditional Linux distros such as the Raspberry Pi OS are designed to run software directly on the host OS using a shared collection of programs and system libraries provided by the Linux distro, and with programs and libraries installed and upgraded in-place directly on the host OS via the package managers provided by the distro, such as APT and pip. This causes the following challenges for system administration on the PlanktoScope:

  • These packages are not atomic in how they perform system upgrades of installed libraries and programs, so they can fail during the upgrade process (e.g. due to loss of power) in a way that leaves the system in an unknown and un-reproducible state. Such a state can be hard to revert or recover from, short of wiping and re-flashing the Raspberry Pi's SD card with a new OS installation; this would cause the loss of any OS customizations (e.g. installation of additional software) made by the user.

  • If an upgrade of all installed programs and libraries results in a system with problems (e.g. bugs in the new version of an installed program), it is hard to completely revert the system to the previous state. Thus, software upgrades involve a trade-off between extra work (e.g. to backup the SD card image before any upgrade) and extra risk (e.g. of software breakage which is hard to revert due to lack of backups).

  • Making certain customizations to the OS, such as adding additional programs/libraries or modifying system configuration files, increases the risk of configuration drift in which the system's actual state increasingly diverges over time from the state expected by the PlanktoScope's software maintainers, and thus becomes harder to understand, troubleshoot, or replace. User customizations to the OS cannot be easily separated from the default configuration of the OS, so it is complicated to copy only those customizations in order to drop them onto a fresh installation of the OS from a newer release - especially if the updated OS includes changes to default configurations which conflict with the user customizations.

  • Some Python packages required by PlanktoScope-specific programs (namely the PlanktoScope hardware controller and the PlanktoScope segmenter, which are both described in later sections of this document), such as picamera2 and opencv-python-headless, can only be installed as pre-built wheels from piwheels (which is used instead of PyPi because the PlanktoScope OS is not yet able to run as a 64-bit operating system) when certain versions of system libraries are installed, or else they must be re-compiled from source (which is prohitively slow on the Raspberry Pi for the affected Python packages). This makes dependencies more complicated to manage in maintenance of the PlanktoScope OS for creating and releasing new SD card images with updated software. The reliance on system libraries also increases the risk that a user-initiated upgrade or removal of some of the system's installed APT packages could cause breakage of some pip-managed Python packages which had been installed before the change.

All of the factors listed above increase the perceived risk (and/or the required effort for sufficient mitigation of that risk) of accidentally degrading system integrity by keeping all software on the OS up-to-date, which makes it harder for users to receive bugfixes, security patches, and new features in a timely manner. Indeed, outside of systems like phones and Chromebooks (whose operating systems automatically update themselves), it is common for users of operating systems to avoid installing security updates or OS upgrades out of a fear of breaking their installed software; this is especially common for users who rely on software to operate other scientific instruments, and for good reasons! But the PlanktoScope project currently does not have enough resources to be able to support users stuck on old versions of the PlanktoScope OS; instead, we want to make it easy and safe for all users to always keep their PlanktoScopes - even with customizations to the OS - automatically updated to the latest version of the PlanktoScope OS. We intend to achieve this by:

  • Running all PlanktoScope-specific programs which require system libraries (e.g. the PlanktoScope's Python-based programs) in Docker containers - with the required versions of the required system libraries bundled inside those containers - to isolate them from the host OS's libraries installed via APT. This way, APT packages will always be safe to add, upgrade, and remove on the host OS with negligible risk of interfering with PlanktoScope-specific software.

  • Enabling (almost) all software not provided by the default installation of the Raspberry Pi OS to be upgraded and downgraded in-place - either as container images or as replacements of files on the filesystem - with just a reboot. This way, software upgrades can be reverted in-place in case new bugs are introduced, and SD cards will only need to be re-flashed with new images once every few years (i.e. after a new major version of the Raspberry Pi OS is released).

  • Enabling most types of user-initiated OS customizations to be version-controlled (in a Git repository) and applied (as a system upgrade/downgrade) together with most of the default configurations added by the PlanktoScope OS over what is already present from the default installation of the Raspberry Pi OS. This way, user-initiated OS customizations can be easy to re-apply automatically even after an SD card is re-flashed with a fresh SD card image of the PlanktoScope OS.

Currently, we have partially implemented the systems necessary for these goals. Much of the PlanktoScope's software is not installed or upgraded directly on the host OS via APT or pip; instead, we use a (partially-implemented) tool called forklift which we're developing specifically to support the goals listed above, and which provides a robust way for us to fully manage deployment, configuration, and upgrading of:

  • All software which we run using Docker.
  • PlanktoScope-specific systemd services.
  • PlanktoScope-specific OS configuration files.

Everything managed by forklift is version-controlled in a Git repository, enabling easy backup and restoration of forklift-managed configurations even if the PlanktoScope's SD card is wiped and re-flashed.

Package management with forklift🔗

When you're just experimenting and you can tolerate the challenges mentioned above, it's fine to customize the PlanktoScope OS by installing software packages using pip directly on the OS and/or by making extensive changes to OS configuration files. However, once you actually care about keeping your customizations around - and especially if/when you want to share your customizations with other people - we recommend migrating those customizations into Forklift packages, which are just files and configuration files stored in a specially-structured Git repository which is also published online (e.g. on GitHub, GitLab, Gitea, etc.). forklift provides an easy way to package, publish, combine, and apply customizations via YAML configuration files in Git repositories; this enables easy sharing, configuration, (re-)composition, and downloading of Docker Compose applications, systemd services, and OS configuration files. Configurations of all deployments of Forklift packages on a computer running the PlanktoScope OS are specified and integrated in a single Git repository, a Forklift pallet. At any given time, each PlanktoScope has exactly one Forklift pallet deployed; switching between Forklift pallets (whether to try out a different set of customizations or to upgrade/downgrade all programs and OS configurations managed by Forklift) is easy and can be done by running just one command (forklift pallet switch, described below in the Applying published customizations subsection).

forklift is used very differently compared to traditional Linux system package managers like APT, for which you must run step-by-step commands in order to modify the state of your system (e.g. to install some package or install some other package). When using forklift, you instead edit configuration files which declare the desired state of your system (though some step-by-step commands are also provided by forklift to make editing of files easier), and then you ask forklift to try to reconcile the actual state of your system with the desired state. If you've worked with Hashicorp Terraform/OpenTofu before, this may sound very familiar to you - in fact, several aspects of forklift's design were inspired by Terraform.

Dependency management🔗

forklift is simpler than traditional package managers in some notable ways, including in the concept of dependencies between packages. For example, Forklift packages cannot specify dependencies on other Forklift packages; instead, they may declare that they depend on certain resources - and you must declare a deployment of some other package which provides those resources. And although forklift checks whether resource dependencies between package deployments are satisfied, it does not attempt to solve unmet dependencies. If you've worked with the Go programming language before, resource dependency relationships among Forklift packages are analogous to the relationships between functions which require arguments with particular interfaces and the types which implement those interfaces, with Forklift resources being analogous to Go interfaces.

This design is intended to facilitate replacement of particular programs with modified or customized versions of those programs. For example, a Forklift package could be declared as providing the same API on the same network port as some other package, so that one package can be substituted for the other while still maintaining compatibility with some other program which relies on the existence of that API. forklift also checks these resource declarations to ensure that any two packages which would conflict with each other (e.g. by trying to listen on the same network port) will be prevented from being deployed together.

Making & publishing customizations🔗

The workflow with forklift for developing/testing OS customizations, such as new package deployments or non-standard configurations of existing package deployments or substitutions of existing package deployments, is as follows:

  • Initialize a custom pallet based on (i.e. layered over) an existing pallet, using the forklift pallet init command (e.g. forklift pallet init --from github.com/PlanktoScope/pallet-standard@stable --as github.com/ethanjli/custom-pallet to make a starter which will be a customization of the latest stable version of the github.com/PlanktoScope/pallet-standard pallet, and which can be published to github.com/ethanjli/custom-pallet). (Note: the forklift pallet init command is not yet implemented, and pallet layering is not yet implemented; currently, pallets can only be created manually via the filesystem by cloning from an existing Git repository.)

  • Optionally, create new Forklift packages with definitions of Docker Compose applications and/or systemd services and/or OS configuration files, and configure the deployment of those packages by creating particular files in the pallet.

  • Optionally, add published Forklift repositories to the pallet with the forklift pallet add-repo command (e.g. forklift pallet add-repo github.com/ethanjli/pallet-example-minimal@main), so that one or more packages provided by those repositories can be deployed with the pallet by creating one or more package deployment configuration files for each package. The forklift pallet add-repo command is also used to upgrade or downgrade the version of the Forklift repository used by the pallet.

  • Optionally, add one or more files which override files from the existing pallet, in order to override the configurations specified by those files. (Note: file overrides are not yet implemented, because they are part of pallet layering functionality which is not yet implemented.)

  • Stage the pallet to be applied on the next boot of the PlanktoScope OS, with the forklift pallet stage command; when Forklift applies a pallet, it makes the PlanktoScope OS match the configuration of Forklift package deployments specified by the pallet.

  • Use git to commit changes and (ideally) push them to GitHub, in order to publish your customizations for other people to try out.

(TODO: create a "tutorial"-style page elsewhere in this docs site, and link to it from here; it could be as simple as creating a new pallet which adds a new helloworld-style Node-RED dashboard)

Applying published customizations🔗

The envisioned workflow for applying published customizations (which you or someone else already developed and pushed to a Git repository served by an online host such as GitHub) is only partially implemented so far, but it already works well for basic use-cases - and it is already used as part of the PlanktoScope OS's installation process for setting up the PlanktoScope OS over a Raspberry Pi OS image:

  • Stage the customized pallet to be applied on the next boot of the PlanktoScope OS, using the forklift pallet switch command (e.g. forklift pallet switch github.com/PlanktoScope/pallet-segmenter@edge to use the latest development/unstable version of the github.com/PlanktoScope/pallet-segmenter pallet).

  • Reboot the Raspberry Pi computer to apply the staged pallet. If the staged pallet cannot be successfully applied during boot, on subsequent boots forklift will instead apply the last staged pallet which was successfully applied. (Note: only a failure to update the Docker containers running on the OS is detected as a failed attempt to apply the staged pallet; if you cause problems with the systemd services or other OS configurations provided by your pallet but the Docker containers are all correctly updated, the pallet will still be considered to have been successfully applied.)

(TODO: create a "tutorial"-style page elsewhere in this docs site, and link to it from here; it could just be a pallet which reconfigures the docs-site deployment to serve the full site with hardware instructions, and which includes https://hub.docker.com/r/linuxserver/firefox or https://github.com/linuxserver/docker-chromium and/or https://github.com/linuxserver/docker-webtop and/or ZeroTier and/or an ML classifier GUI and/or Jupyter Tensorflow)

Note: currently all of forklift's functionality is only exposed through a command-line interface, but after the forklift tool stabilizes we plan to add a web browser-based graphical interface for use by a general audience.

PlanktoScope-specific hardware abstraction🔗

PlanktoScope-specific hardware modules are abstracted by PlanktoScope-specific programs which expose high-level network APIs (typically using MQTT and/or HTTP); other programs should use these APIs in order to interact with the PlanktoScope-specific hardware modules. To provide these APIs, the PlanktoScope OS adds the following services (beyond what is already provided by the default installation of the Raspberry Pi OS):

  • gpsd: for providing an abstraction for the PlanktoScope's GPS receiver.

  • chronyd: for managing synchronization of the Raspberry Pi's system clock with the PlanktoScope's GPS receiver and with any time sources available over the Internet.

  • The PlanktoScope hardware controller: for controlling PlanktoScope-specific hardware modules and abstracting them into high-level network APIs for other programs to interact with.

User interface🔗

Traditional operating systems provide a desktop environment with a graphical user interface for operating the computer. By contrast, the PlanktoScope OS provides a set of web browser-based graphical user interfaces for operating the PlanktoScope. This approach was chosen for the following reasons:

  • Most people already have a personal computing device (e.g. a phone or laptop). By relying on the user's personal computing device as the graphical interface for the PlanktoScope's software, the PlanktoScope project can reduce hardware costs by omitting a display from the PlanktoScope hardware.

  • The PlanktoScope's computational resources are limited and may often need to be fully used for data processing tasks. By offloading real-time interaction (such as rendering of the graphical display, and handling of mouse and keyboard events) to a separate device, we can ensure a smooth user experience even when the PlanktoScope's Raspberry Pi computer is busy with other work.

  • When the PlanktoScope is connected to the internet, its web browser-based graphical interfaces can be accessed remotely over the internet from other web browsers. This can be easier to set up - and have lower bandwidth requirements and higher responsiveness - compared to a remote-desktop system for remotely accessing a Raspberry Pi's graphical desktop. This is especially relevant when the PlanktoScope is deployed in a setting where it only has a relatively low-bandwidth internet connection.

The PlanktoScope OS adds the following network services which provide web browser-based graphical user interfaces to help users operate the PlanktoScope:

  • A Node-RED server which serves over HTTP the PlanktoScope Node-RED dashboard, a graphical interface for end-users to operate the PlanktoScope for image acquisition and image processing.

  • A datasets file browser for viewing, managing, uploading, and downloading image dataset files on the PlanktoScope. These files are generated and used by the PlanktoScope hardware controller and the PlanktoScope segmenter.

  • device-portal: a landing page with links for end-users to quickly access the various web browser-based interfaces mentioned above.

Note: we will probably simplify things by consolidating some of these components together into the PlanktoScope's Node-RED dashboard.

The PlanktoScope OS also provides various tools with web browser-based interfaces to aid with system administration and troubleshooting:

  • Cockpit: for performing system-administration tasks such as monitoring system resources, managing system services, viewing system logs, and executing commands in a terminal.

  • A system file browser for viewing, managing, editing, uploading, and downloading any file on the PlanktoScope.

  • A log file browser for viewing, downloading, and deleting log files files generated by the PlanktoScope hardware controller.

  • Dozzle: for viewing and monitoring logs of Docker containers.

  • Grafana: for monitoring and exploring metrics stored in Prometheus.

Finally, the PlanktoScope OS adds some command-line tools (beyond what is already provided by the default installation of the Raspberry Pi OS) for administrative tasks which system administrators, software developers, and advanced users may need to use:

  • vim: for editing text files.

  • byobu: for running processes persistently across ephemeral terminal sessions.

  • git: for interacting with Git repositories.

  • w3m and lynx: for interacting with web pages (such as Wi-Fi network captive portals) from the PlanktoScope.

  • docker: for managing and inspecting Docker containers.

Networking🔗

The PlanktoScope is often deployed in settings with limited or unstable internet access, and also in settings with no internet access at all. The PlanktoScope also needs to be deployable in remote settings where the user needs to control the PlanktoScope without being physically present. In both types of situations, the PlanktoScope's web browser-based interfaces need to remain accessible.

We solve this problem by allowing the PlanktoScope to connect to the internet over a known Wi-Fi network, and/or over Ethernet, so that the PlanktoScope's web browser-based interfaces can be accessed over the internet; and by making the PlanktoScope bring up a Wi-Fi hotspot (more formally, a wireless access point) using the Raspberry Pi's integrated Wi-Fi module in the absence of any known Wi-Fi network, so that the web browser-based interfaces can be accessed over the Wi-Fi hotspot.

When a device connects directly to the PlanktoScope (e.g. via the PlanktoScope's Wi-Fi hotspot, or via an Ethernet cable), the PlanktoScope acts as a DHCP server to assign itself certain static IP addresses (e.g. 192.168.4.1) and as a DNS server to assign itself certain domain names (e.g. home.pkscope), so that user can locate and open the PlanktoScope's web browser-based interfaces via those domain names. The PlanktoScope also announces itself under certain mDNS names (e.g. pkscope.local) which may work on networks where the PlanktoScope does not have a static IP address (e.g. because the PlanktoScope is connected to an existing Wi-Fi network).

When the PlanktoScope both has internet access and has devices connected to it (e.g. over a Wi-Fi hotspot or over Ethernet), the PlanktoScope shares its internet access with all connected devices, to enable the user to access web pages even when connected to the PlanktoScope. This is implemented in the PlanktoScope OS with network configurations for the PlanktoScope to act as a network router using Network Address Translation when it has internet access.

The standard PlanktoScope OS adds the following systemd services (beyond what is already provided by the default installation of the Raspberry Pi OS) for managing the PlanktoScope's network connectivity:

  • autohotspot (which in turn launches hostapd): a PlanktoScope-specific daemon for automatically checking the presence of known Wi-Fi networks, automatically connecting to any known Wi-Fi networks, and falling back to creating a Wi-Fi hotspot when no known Wi-Fi networks are present.

  • enable-interface-forwarding: configures the Linux kernel firewall's IP packet filter rules to forward packets between the Raspberry Pi's network interfaces, to allow the Raspberry Pi to act as a network router.

  • dnsmasq: for allowing computers connected to the PlanktoScope over a network to access the PlanktoScope using domain names defined on the PlanktoScope.

  • firewalld: a network firewall (currently disabled by default).

The standard PlanktoScope OS also adds the following systemd services for dynamically updating the system's network configuration during boot:

  • generate-machine-name: generates a human-readable machine name at /run/machine-name from the Raspberry Pi's serial number (or, if that's missing, from /etc/machine-d).

  • generate-hostname-templated: generates a temporary hostname file (which is used by a symlink at /etc/hostname) from /etc/hostname-template, which can include the machine name from /run/machine-name.

  • update-hostname: updates systemd-hostnamed so that the hostname matches what is specified by /etc/hostname.

  • assemble-dnsmasq-config-templated: generates a temporary dnsmasq drop-in config file (which is used by a symlink at /etc/dnsmasq.d/40-generated-templated-config) from drop-in config file templates at /etc/dnsmasq-templates.d.

  • assemble-hostapd-config-templated: generates a temporary hostapd drop-in config file (which is used by a symlink at /etc/hostapd/hostapd.conf.d/60-generated-templated.conf) from drop-in config file templates at /etc/hostapd/hostapd.conf-templates.d.

  • assemble-hostapd-config: generates a temporary hostapd config file (which is used by a symlink at /etc/hostapd/hostapd.conf) from drop-in config files at /etc/hostapd/hostapd.conf.d.

  • assemble-hosts-templated: generates a temporary hosts drop-in snippet (which is used by a symlink at /etc/hosts.d/50-generated-templated) from drop-in hosts snippet templates at /etc/hosts-templates.d.

  • assemble-hosts generates a temporary hosts file (which is used by a symlink at /etc/hosts) from drop-in snippets at /etc/hosts-templates.d.

The PlanktoScope OS also adds the following common services for integrating network APIs provided by various programs, and to facilitate communication among programs running on the PlanktoScope OS:

  • Mosquitto: a server which acts as an MQTT broker. This is used by the PlanktoScope hardware controller and segmenter (described below) to receive commands and broadcast notifications. This is also used by the PlanktoScope's Node-RED dashboard (described below) to send commands and receive notifications.

  • Caddy with the caddy-docker-proxy plugin: an HTTP server which acts as a reverse proxy to route all HTTP requests on port 80 from HTTP clients (e.g. web browsers) to the appropriate HTTP servers (e.g. the Node-RED server, Prometheus, and the PlanktoScope hardware controller's HTTP-MJPEG camera preview stream) running on the PlanktoScope.

Filesystem🔗

The PlanktoScope OS's filesystem makes some changes from the default Debian/Raspberry Pi OS filesystem structure so that /etc and /usr can be managed by Forklift while still being directly customizable by the system administrator. Specifically, a number of systemd services in the PlanktoScope OS run during early boot to:

  • Make a read-only mount (via the overlay-sysroot systemd service) of the initial root filesystem, at /sysroot.

  • Make a read-only mount of the next Forklift pallet to be applied (via the bindro-run-forklift-stages-current.service) from a subdirectory within /var/lib/forklift/stages to /run/forklift/stages/current.

  • Remount /usr (via the overlay-usr systemd service) as a writable overlay with a Forklift-managed intermediate layer (in a subdirectory within /var/lib/forklift/stages which can also be accessed at /run/forklift/stages/current/exports/overlays/usr) and /sysroot/usr as a base layer; any changes made by the system administrator to files in /usr will be transparently stored by the overlay in /var/lib/overlays/overrides/usr. This allows Forklift to provide extra files in /usr in an atomic way, while overrides made by the system administrator are stored separately.

  • Remount /etc (via the overlay-etc systemd service) as a writable overlay with a Forklift-managed intermediate layer (in a subdirectory within /var/lib/forklift/stages which can also be accessed at /run/forklift/stages/current/exports/overlays/etc) and /sysroot/etc as a base layer; any changes made by the system administrator to files in /etc will be transparently stored by the overlay in /var/lib/overlays/overrides/etc. This allows Forklift to provide extra files in /etc in an atomic way, while overrides made by the system administrator are stored separately.

  • Make a writable mount of /var/lib/forklift/stages to /home/pi/.local/share/forklift/stages (via the bind-.local-share-forklift-stages@home-pi systemd service) so that, when the pi user runs forklift commands like forklift pallet switch, those commands will update /var/lib/forklift/stages - and without requiring the use of sudo.

  • Update systemd (via the start-overlaid-units systemd service) with any new systemd units provided via Forklift, so that they will run during boot.

Beyond what is required by the Linux Filesystem Hierarchy Standard, the PlanktoScope OS sets the following conventions related to filesystem paths:

  • Scripts which are provided by Forklift and only used as part of systemd services should be provided in /usr/libexec, Forklift packages should export those scripts to overlays/usr/libexec (so, for example, they will be accessible in /run/forklift/stages/current/exports/overlays/usr/libexec).

  • Systemd units provided by Forklift should be provided in /usr/lib/systemd/system, and Forklift packages should export those units to overlays/usr/lib/systemd/system. Symlinks to enable those units should be provided in /etc/systemd/system, and Forklift packages should export those scripts to overlays/etc/systemd/system.

  • Forklift-provided systemd services which dynamically generate temporary files meant to be used in /etc should generate those temporary files at stable paths in /run/overlays/generated/etc. Forklift packages which provide such systemd services should also provide relative symlinks into those temporary files in /run/overlays/generated/etc to be exported into overlays/etc as overlays for the corresponding paths in /etc. For example, if a package provides a service to dynamically generate a hosts file meant to be used as /etc/hosts, that service should generate the file in /run/overlays/generated/etc/hosts and the package should export a symlink at overlays/etc/hosts which points to ../../run/overlays/generated/etc/hosts, so that /etc/hosts will be a symlink pointing to /run/overlays/generated/etc/hosts.

Observability & telemetry🔗

Although it is not a high priority yet, we would like to enable operators of large (>10) collections of PlanktoScopes to easily log and monitor the health and utilization of each PlanktoScope and to investigate issues with their PlanktoScopes, regardless of whether each PlanktoScope is deployed locally or remotely. The PlanktoScope OS currently includes the following common services to support system observability and telemetry both for the PlanktoScope OS as a system and for programs running on the PlanktoScope OS:

  • Prometheus: a server for collecting and storing metrics and for exposing metrics over an HTTP API.

  • Prometheus node exporter: for measuring computer hardware and OS monitoring metrics and exposing them over a Prometheus-compatible HTTP API.

In the future, we will instrument other PlanktoScope-specific programs (especially the PlanktoScope hardware controller) to export various metrics for Prometheus to collect and expose.

Data processing🔗

Because the PlanktoScope collects raw image datasets which are often too large to transfer efficiently over low-bandwidth or intermittent internet connections, the PlanktoScope needs to be able to process raw image data into lower-bandwidth data (e.g. cropped and segmented images of particles in the raw images, or even just counts of different classes of particles) without internet access. In other words, the PlanktoScope must support on-board data processing at the edge. The PlanktoScope OS adds the following services for on-board processing of data generated by the PlanktoScope:

  • The PlanktoScope segmenter: for processing raw image datasets acquired by the PlanktoScope hardware controller to detect and extract particles from raw images.

Note: in the future, the PlanktoScope OS will add more on-board services for processing the outputs of the PlanktoScope segmenter, and the PlanktoScope OS may also provide hardware abstractions (such as for AI accelerator modules) to support the deployment of neural-network models for data processing.

Security🔗

Currently, the PlanktoScope OS lacks basic security measures to make it safe for them to be connected to the internet; currently it is the responsibility of system administrators to add extremely basic risk mitigations, for example by:

  • Changing the password of the pi user away from the default of copepode.

  • Password-protecting the Node-RED dashboard editor, which can be used to execute arbitrary commands with root permissions.

  • Setting firewall rules.

  • Changing the password of the Wi-Fi hotspot away from the default of copepode, or disabling Wi-Fi hotspot functionality.

Other risk mitigations will require deeper changes to the PlanktoScope OS, such as:

  • Limiting the permissions and capabilities made available to various system services which currently run with root permissions

  • Password-protecting web browser-based user interfaces

  • Password-protecting network APIs.

We would like to start taking even just the very basic steps listed above to improve security, but security is not yet a high-enough priority for us to work on it with the limited resources available to us 🙃 - if you're interested in computer/network security and you'd like to help us as a volunteer on this project, please contact us!

Camera Settings🔗

This document explains how the PlanktoScope software controls the PlanktoScope's camera using the camera settings exposed by the "Optic Configuration" page of the PlanktoScope's Node-RED dashboard.

The following camera settings can be adjusted via the Node-RED dashboard:

  • "ISO" & "Shutter Speed" control the brightness of images captured by the camera.

  • "Auto White Balance", "WB: Red", and "WB: Blue" control the color balance of images captured by the camera.

Image brightness🔗

The Node-RED dashboard's "Shutter Speed" setting, which is specified in units of microseconds (μs), is used to set the ExposureTime control with the picamera2 library; a higher value for this setting will make captured images brighter and - when objects are moving - blurrier. To prevent the camera from capturing blurry images of moving objects, the value of this setting should be minimized; usually the default value of 125 μs is appropriate. For a detailed explanation of the exposure time of the camera sensor, refer to the picamera library's discussion of "exposure time".

The Node-RED dashboard's "ISO" setting is divided by 100 and used to set the AnalogueGain control with the picamera2 library; a higher value for this setting will make the camera sensor more sensitive to light, and thus make captured images brighter and noisier. To prevent the camera from capturing excessively dark images - which will prevent the PlanktoScope's segmenter from correctly detecting objects - the value of this setting should not be too low. To prevent the camera from "washing out" images by making everything excessively bright - which will destroy visual detail in the images - the value of this setting should not be too high, either. For a detailed explanation of the analog gain of the camera sensor, refer to the picamera library's discussion of "sensor gain" and the picamera2 library's discussion of the AnalogueGain control and the DigitalGain property.

Image color balance🔗

The PlanktoScope's camera can operate with "Automatic White Balance" mode either enabled or disabled. In "Automatic White Balance" mode, the camera ignores any manually-set white-balance settings and instead applies an adaptive algorithm to automatically (and gradually) correct the color balance of the images to prevent them from appearing more red or more blue than we would expect the images to be. However, "Automatic White Balance" mode prevents images from having consistent calibrations, so we recommend always disabling "Automatic White Balance" mode when collecting data with the PlanktoScope, and instead manually calibrating the camera's white-balance settings.

The camera's manual white-balance settings consist of two normalized color values, which are the red gain ("WB: Red" in the Node-RED dashboard) and the blue gain ("WB: Blue" in the Node-RED dashboard). The red gain can be understood as a multiplier applied to the image to achieve the desired ratio between the redness of the image and the greenness of the image, so a higher value will make the image appear redder. Similarly, the blue gain can be understood as a multiplier applied to the image to achieve the desired ratio between the blueness of the image and the greenness of the image, so a higher value will make the image appear bluer. For a deeper conceptual explanation of white balance, refer to the first two pages of Freescale Semiconductor's application note on white balance and color correction in digital cameras.

Camera Settings🔗

This document explains how the PlanktoScope software controls the PlanktoScope's camera using the camera settings exposed by the "Optic Configuration" page of the PlanktoScope's Node-RED dashboard.

The following camera settings can be adjusted via the Node-RED dashboard:

  • "ISO" & "Shutter Speed" control the brightness of images captured by the camera.

  • "Auto White Balance", "WB: Red", and "WB: Blue" control the color balance of images captured by the camera.

Image brightness🔗

The Node-RED dashboard's "Shutter Speed" setting, which is specified in units of microseconds (μs), is used to set the ExposureTime control with the picamera2 library; a higher value for this setting will make captured images brighter and - when objects are moving - blurrier. To prevent the camera from capturing blurry images of moving objects, the value of this setting should be minimized; usually the default value of 125 μs is appropriate. For a detailed explanation of the exposure time of the camera sensor, refer to the picamera library's discussion of "exposure time".

The Node-RED dashboard's "ISO" setting is divided by 100 and used to set the AnalogueGain control with the picamera2 library; a higher value for this setting will make the camera sensor more sensitive to light, and thus make captured images brighter and noisier. To prevent the camera from capturing excessively dark images - which will prevent the PlanktoScope's segmenter from correctly detecting objects - the value of this setting should not be too low. To prevent the camera from "washing out" images by making everything excessively bright - which will destroy visual detail in the images - the value of this setting should not be too high, either. For a detailed explanation of the analog gain of the camera sensor, refer to the picamera library's discussion of "sensor gain" and the picamera2 library's discussion of the AnalogueGain control and the DigitalGain property.

Image color balance🔗

The PlanktoScope's camera can operate with "Automatic White Balance" mode either enabled or disabled. In "Automatic White Balance" mode, the camera ignores any manually-set white-balance settings and instead applies an adaptive algorithm to automatically (and gradually) correct the color balance of the images to prevent them from appearing more red or more blue than we would expect the images to be. However, "Automatic White Balance" mode prevents images from having consistent calibrations, so we recommend always disabling "Automatic White Balance" mode when collecting data with the PlanktoScope, and instead manually calibrating the camera's white-balance settings.

The camera's manual white-balance settings consist of two normalized color values, which are the red gain ("WB: Red" in the Node-RED dashboard) and the blue gain ("WB: Blue" in the Node-RED dashboard). The red gain can be understood as a multiplier applied to the image to achieve the desired ratio between the redness of the image and the greenness of the image, so a higher value will make the image appear redder. Similarly, the blue gain can be understood as a multiplier applied to the image to achieve the desired ratio between the blueness of the image and the greenness of the image, so a higher value will make the image appear bluer. For a deeper conceptual explanation of white balance, refer to the first two pages of Freescale Semiconductor's application note on white balance and color correction in digital cameras.

Sample Imaging🔗

This document explains how the PlanktoScope software captures images of samples and how it uses the image-acquisition settings exposed by the "Fluidic Acquisition" page of the PlanktoScope's Node-RED dashboard.

Currently, the PlanktoScope software only has one sample-imaging mode, which we call "stop-flow imaging":

Stop-flow imaging🔗

This imaging mode is optimized to allow capture of high-quality images using low-cost, high-resolution camera modules such as the Raspberry Pi Camera Module 2 and the Raspberry Pi High Quality Camera (refer to the hardware product specifications to see which camera modules are used in each version of the PlanktoScope hardware), whose rolling-shutter designs can introduce artifacts around moving objects while the camera is capturing an image.

When this imaging mode is started, the PlanktoScope will repeatedly perform the following sequence of actions until a desired number of images ("Number of images to acquire" in the Node-RED dashboard) is captured:

  1. The PlanktoScope's pump will pull some fixed volume of sample ("Pumped volume" in the Node-RED dashboard, in units of mL) from the sample intake and move the same volume of sample down through the PlanktoScope's flowcell.

  2. After the PlanktoScope's pump finishes pumping the specified volume, the pump will stop and the PlanktoScope will wait for some short fixed duration of time ("Delay to stabilize image" in the Node-RED dashboard, in units of seconds). This waiting period is intended to allow the sample in the PlanktoScope's flowcell to stop flowing, so that all objects in the camera's field-of-view will (hopefully) stop moving - because moving objects will cause distortion effects to appear in images captured with rolling-shutter cameras such as those used in the PlanktoScope.

  3. The PlanktoScope will capture and save an image of its entire field-of-view.

Sample Imaging🔗

This document explains how the PlanktoScope software captures images of samples and how it uses the image-acquisition settings exposed by the "Fluidic Acquisition" page of the PlanktoScope's Node-RED dashboard.

Currently, the PlanktoScope software only has one sample-imaging mode, which we call "stop-flow imaging":

Stop-flow imaging🔗

This imaging mode is optimized to allow capture of high-quality images using low-cost, high-resolution camera modules such as the Raspberry Pi Camera Module 2 and the Raspberry Pi High Quality Camera (refer to the hardware product specifications to see which camera modules are used in each version of the PlanktoScope hardware), whose rolling-shutter designs can introduce artifacts around moving objects while the camera is capturing an image.

When this imaging mode is started, the PlanktoScope will repeatedly perform the following sequence of actions until a desired number of images ("Number of images to acquire" in the Node-RED dashboard) is captured:

  1. The PlanktoScope's pump will pull some fixed volume of sample ("Pumped volume" in the Node-RED dashboard, in units of mL) from the sample intake and move the same volume of sample down through the PlanktoScope's flowcell.

  2. After the PlanktoScope's pump finishes pumping the specified volume, the pump will stop and the PlanktoScope will wait for some short fixed duration of time ("Delay to stabilize image" in the Node-RED dashboard, in units of seconds). This waiting period is intended to allow the sample in the PlanktoScope's flowcell to stop flowing, so that all objects in the camera's field-of-view will (hopefully) stop moving - because moving objects will cause distortion effects to appear in images captured with rolling-shutter cameras such as those used in the PlanktoScope.

  3. The PlanktoScope will capture and save an image of its entire field-of-view.

Image Segmentation🔗

This document explains how the PlanktoScope software's segmenter program processes raw images (captured by the PlanktoScope's sample-imaging functionality) in order to detect objects - such as plankton, microplastics, and other particles - and to extract each object into its own segmented image for downstream use, such as for uploading to EcoTaxa. This document also lists and explains the metadata fields added by the PlanktoScope segmenter for uploading to EcoTaxa.

Currently, the segmenter only operates in batch-processing mode: the segmenter takes as input a complete raw image dataset, and it produces as output a complete segmented object dataset as well as an export archive of segmented objects which can be uploaded to EcoTaxa.

When the segmenter starts, it will perform a median-calculation step on the first ten images of the dataset of raw images. The median-calculation step outputs a median image which is then used as an input for an image-correction step on each raw image; the median image will occasionally be recalculated (conditions triggering a recalculation are described below). Each image-cleaning step outputs a median-corrected image is then used as the input for a mask-calculation step. Each mask-calculation step outputs a segmentation mask which is then used as an input for an object-extraction step.

For each raw image from the input dataset, after the object-extraction step outputs a set of objects, the number of extracted objects is accumulated into a cumulative moving average of the number of objects extracted per raw image. However, before the cumulative moving average is updated, the number of extracted objects is compared against the previous value of the cumulative moving average (calculated after the previous raw image was processed): if the number of extracted objects is greater than the previous value of the cumulative moving average by more than 20, then the median image will be recalculated for the next raw image. The input for the next median-calculation step will usually be the next 10 consecutive raw images, unless the next raw image is one of the last 10 raw images - in which case the previous ten images will instead be used as the input for the next median-calculation step. Yes, this logic is complicated, and yes, for some reason we don't center the sequence of raw images around the next raw image as our input to the median-calculation step.

Median-calculation step🔗

The median-calculation step takes as input a sequence of consecutive raw images, but if the image sequence consists of an even number of images then the last image is excluded from the calculation. The median-calculation step uses the raw images to calculate a median image, in which the color of each pixel of the output is calculated as the median of the colors of the corresponding pixels in the input images.

The output of this step is supposed to be an estimate of what the the "background" of the image would be if there were no objects within the field-of-view. However, this step is not robust to sample density: if a sample is dense enough that certain pixel locations overlap with objects in more than half of any consecutive sequence of ten images, the color of the "background" in those pixel locations will be estimated as the color of an object in one of those images.

Image-correction step🔗

The image-correction step takes as input a median image and a raw image. First, the image-correction step divides the color of each pixel of the raw image by the color of the corresponding pixel of the median image; this is probably intended to correct for inhomogeneous illumination in the raw image, and to remove any objects which had been stuck to the flow cell (and thus were included in the median image) from the raw image. Next, the image-correction step slightly rescales the intensity range of the resulting image (TODO: determine what the effect of this intensity-rescaling operation is - does it make the image brighter or dimmer? Does it increase or decrease the contrast? Does it clip the white value? Why is this step performed???). The final result is a median-corrected image.

Mask-calculation step🔗

The mask-calculation step takes as input a median-corrected image and the result from the previous mask-calculation step. It consists of the following operations:

  1. "Simple threshold": this operation applies a global threshold to the input corrected image, using the triangle algorithm to calculate an optimal threshold value for the image; the output is a mask in which each pixel is set to 0 if the corresponding pixel of the input image is greater than the threshold, and to 255 otherwise. The resulting mask should select for objects which appear darker than the background of the image.

  2. "Remove previous mask": this operation combines the result of the previous mask-calculation step with the mask created by the previous "simple threshold" operation, by subtracting the intersection of the two masks from the mask created by the previous "simple threshold" operation. This operation is probably intended to remove objects which had been stuck to the PlanktoScope's flowcell during imaging and thus might appear in many consecutive input corrected images. However, this operation is not robust in dense samples where two different objects might appear in overlapping locations across two consecutive raw images.

  3. "Erode": this operation erodes the mask with a 2-pixel-by-2-pixel square kernel. In the resulting mask, small regions (such as thresholded noise) are eliminated.

  4. "Dilate": this operation dilates the mask with an 8-pixel-diameter circular kernel. In the resulting mask, regions remaining after the previous "erode" operation are padded with a margin.

  5. "Close": this operation dilates and then erodes the mask with an 8-pixel-diameter circular kernel. In the resulting mask, small holes in regions remaining after the previous "dilate" operation are eliminated.

  6. "Erode2": this operation erodes the mask with an 8-pixel-diameter circular kernel, inverting the effect of the previous "dilate" operation.

The final result these operations is a spatially-filtered segmentation mask where the value of each pixel represents whether that pixel is part of an object or part of the background of the input corrected image.

Object-extraction step🔗

The object-extraction step takes the following inputs:

  • A median-corrected image

  • A segmentation mask

  • The following sample metadata fields:

  • acq_minimum_mesh: the diameter of the smallest spherical object which is expected to be in the sample, usually 20 µm. This value is set on the "Fluidic Acquisition" page of the PlanktoScope's Node-RED dashboard as the "Min fraction size".

  • process_pixel: the pixel size calibration of the PlanktoScope, in units of µm per pixel; then the area (in units of µm2) per pixel is process_pixel * process_pixel. This value is set on the "Hardware Settings" page of the PlanktoScope's Node-RED dashboard as the "Pixel size calibration: um per pixel".

First, the object-extraction step calculates a minimum-area threshold for objects to extract using the input segmentation mask: the threshold (in units of pixel2) is calculated as (2 * acq_minimum_mesh / process_pixel) ^ 2.

Next, the object-extraction step identifies all connected regions of the input segmentation mask and measures properties of those regions. The object-extraction step then discards any region whose bounding-box area (area_bbox in scikit-image) is less than the minimum-area threshold.

Metadata calculation🔗

For each resulting region after the minimum-area threshold is applied, that region will be used to extract a segmented and cropped image of the object (including pixels in any holes in the object) from the input median-corrected image. This cropped image is used to calculate some metadata fields about the distribution of colors in the object's segmented image:

  • MeanHue: the mean of the hue channel of the image in a hue-saturation-value (HSV) representation of the image

  • StdHue: the standard deviation of the hue channel of the image in an HSV representation of the image

  • MeanSaturation: the standard deviation of the saturation channel of the image in an HSV representation of the image

  • StdSaturation: the standard deviation of the saturation channel of the image in an HSV representation of the image

  • MeanValue: the standard deviation of the value channel of the image in an HSV representation of the image

  • StdValue: the standard deviation of the value channel of the image in an HSV representation of the image

Additionally, some metadata for the object is calculated from the region properties calculated by scikit-image for that object's region:

  • label: The identifier of the object's region, as assigned by scikit-image. This corresponds to the label region property in scikit-image.

  • Basic area properties:

  • area_exc: Number of pixels in the region (excluding pixels in any holes). This corresponds to the area region property in scikit-image.

  • area: Number of pixels of the region with all holes filled in (i.e. including pixels in any holes). This corresponds to the area_filled region property in scikit-image. Yes, it's somewhat confusing that the PlanktoScope segmenter renames scikit-image's area region property to area_exc and renames scikit-image's area_filled region property to area.

  • %area: Ratio between the number of pixels in any holes in the region and the total number of pixels of the region with all holes filled in; calculated as 1 - area_exc / area. In other words, this represents the proportion of the region which consists of holes. Yes, %area is a misleading name both because of the % in the name and because of the area in the name.

  • Equivalent-circle properties:

  • equivalent_diameter: The diameter (in pixels) of a circle with the same number of pixels in its area as the number of pixels in the region (excluding pixels in any holes). This corresponds to the equivalent_diameter_area property in scikit-image.

  • Equivalent-ellipse properties:

  • eccentricity: Eccentricity of the ellipse that has the same second-moments as the region; eccentricity is the ratio of the focal distance (distance between focal points) over the major axis length. The value is in the interval [0, 1), where a value of 0 represents a circle. This corresponds to the eccentricity property in scikit-image.

  • major: The length (in pixels) of the major axis of region's equivalent ellipse. This corresponds to the axis_major_length property in scikit-image.

  • minor: The length (in pixels) of the minor axis of the region's equivalent ellipse. This corresponds to the axis_minor_length property in scikit-image.

  • elongation: The ratio between major and minor.

  • angle: Angle (in degrees) between the x-axis of the input median-corrected image and the major axis of the region's equivalent ellipse. Values range from 0 deg to 180 deg counter-clockwise. This is calculated from the orientation property in scikit-image.

  • Equivalent-object perimeter properties:

  • perim.: Perimeter (in pixels) of an object which approximates the region's contour as a line through the centers of border pixels using a 4-connectivity. This corresponds to the perimeter property in scikit-image.

  • perimareaexc: Ratio between the perimeter and the number of pixels in the region (excluding pixels in any holes). Calculated as perim. / area_exc.

  • perimmajor: Ratio between the perimeter and the length of the major axis of the region's equivalent ellipse. Calculated as perim. / major.

  • circ.: The roundness of the region's equivalent object, including pixels in any holes. Calculated as 4 * π * area / (perim. * perim.). Ranges from 1 for a perfect circle to 0 for highly non-circular shapes.

  • circex: The roundness of the region's equivalent object, excluding pixels in any holes. Calculated as 4 * π * area_exc / (perim. * perim.). Ranges from 1 for a perfect circle to 0 for highly non-circular shapes or shapes with many large holes.

  • Bounding box (the smallest rectangle which includes all pixels of the region, under the constraint that the edges of the box are parallel to the x- and y-axes of the input median-corrected image) properties:

  • bx: x-position (in pixels) of the top-left corner of the region's bounding box, relative to the top-left corner of the input median-corrected image. This corresponds to the second element of the bbox property in scikit-image.

  • by: y-position (in pixels) of the top-left corner of the region's bounding box, relative to the top-left corner of the input median-corrected image. This corresponds to the first element of the bbox property in scikit-image.

  • width: Width (in number of pixels) of the region's bounding box. This is calculated from the elements of the bbox property in scikit-image.

  • height: Height (in number of pixels) of the region's bounding box. This is calculated from the elements of the bbox property in scikit-image.

  • bounding_box_area: Number of pixels in the region's bounding box; equivalent to width * height. This corresponds to the area_bbox region property in scikit-image.

  • extent: Ratio between the number of pixels in the region (excluding pixels in any holes) and the number of pixels in the region's bounding box; equivalent to area_exc / bounding_box_area. This corresponds to the extent region property in scikit-image.

  • Convex hull (the smallest convex polygon which encloses the region) properties:

  • convex_area: Number of pixels in the convex hull of the region. This corresponds to the area_convex region property in scikit-image.

  • solidity: Ratio between the number of pixels in the region (excluding pixels in any holes) and the number of pixels in the convex hull of the region. Equivalent to area_exc / convex_area. This corresponds to the solidity region property in scikit-image.

  • Unweighted centroid properties:

  • x: x-position (in pixels) of the centroid of the object, relative to the top-left corner of the input median-corrected image. This corresponds to the second element of the centroid region property in scikit-image.

  • y: y-position (in pixels) of the centroid of the object, relative to the top-left corner of the input median-corrected image. This corresponds to the first element of the centroid region property in scikit-image.

  • local_centroid_col: x-position (in pixels) of the centroid of the object, relative to the top-left corner of the region's bounding box; equivalent to x - bx. This corresponds to the second element of the centroid_local region property in scikit-image.

  • local_centroid_row: y-position (in pixels) of the centroid of the object, relative to the top-left corner of the region's bounding box; equivalent to y - by. This corresponds to the first element of the centroid_local region property in scikit-image.

  • Topological properties:

  • euler_number: The Euler characteristic of the set of non-zero pixels. Computed as the number of connected components subtracted by the number of holes (with 2-connectivity). This corresponds to the euler_number property in scikit-image.

Output image cropping🔗

Finally, a segmented and cropped image of the object (including pixels in any holes in the object) is saved from the input median-corrected image, but with the crop expanded by up to 10 pixels in each direction (TODO: check whether this description is accurate - the corresponding code is extremely unreadable).

Thus, the output of the output-extraction step is a set of objects, each with a corresponding cropped image saved to file and with a corresponding list of metadata values.

Image Segmentation🔗

This document explains how the PlanktoScope software's segmenter program processes raw images (captured by the PlanktoScope's sample-imaging functionality) in order to detect objects - such as plankton, microplastics, and other particles - and to extract each object into its own segmented image for downstream use, such as for uploading to EcoTaxa. This document also lists and explains the metadata fields added by the PlanktoScope segmenter for uploading to EcoTaxa.

Currently, the segmenter only operates in batch-processing mode: the segmenter takes as input a complete raw image dataset, and it produces as output a complete segmented object dataset as well as an export archive of segmented objects which can be uploaded to EcoTaxa.

When the segmenter starts, it will perform a median-calculation step on the first ten images of the dataset of raw images. The median-calculation step outputs a median image which is then used as an input for an image-correction step on each raw image; the median image will occasionally be recalculated (conditions triggering a recalculation are described below). Each image-cleaning step outputs a median-corrected image is then used as the input for a mask-calculation step. Each mask-calculation step outputs a segmentation mask which is then used as an input for an object-extraction step.

For each raw image from the input dataset, after the object-extraction step outputs a set of objects, the number of extracted objects is accumulated into a cumulative moving average of the number of objects extracted per raw image. However, before the cumulative moving average is updated, the number of extracted objects is compared against the previous value of the cumulative moving average (calculated after the previous raw image was processed): if the number of extracted objects is greater than the previous value of the cumulative moving average by more than 20, then the median image will be recalculated for the next raw image. The input for the next median-calculation step will usually be the next 10 consecutive raw images, unless the next raw image is one of the last 10 raw images - in which case the previous ten images will instead be used as the input for the next median-calculation step. Yes, this logic is complicated, and yes, for some reason we don't center the sequence of raw images around the next raw image as our input to the median-calculation step.

Median-calculation step🔗

The median-calculation step takes as input a sequence of consecutive raw images, but if the image sequence consists of an even number of images then the last image is excluded from the calculation. The median-calculation step uses the raw images to calculate a median image, in which the color of each pixel of the output is calculated as the median of the colors of the corresponding pixels in the input images.

The output of this step is supposed to be an estimate of what the the "background" of the image would be if there were no objects within the field-of-view. However, this step is not robust to sample density: if a sample is dense enough that certain pixel locations overlap with objects in more than half of any consecutive sequence of ten images, the color of the "background" in those pixel locations will be estimated as the color of an object in one of those images.

Image-correction step🔗

The image-correction step takes as input a median image and a raw image. First, the image-correction step divides the color of each pixel of the raw image by the color of the corresponding pixel of the median image; this is probably intended to correct for inhomogeneous illumination in the raw image, and to remove any objects which had been stuck to the flow cell (and thus were included in the median image) from the raw image. Next, the image-correction step slightly rescales the intensity range of the resulting image (TODO: determine what the effect of this intensity-rescaling operation is - does it make the image brighter or dimmer? Does it increase or decrease the contrast? Does it clip the white value? Why is this step performed???). The final result is a median-corrected image.

Mask-calculation step🔗

The mask-calculation step takes as input a median-corrected image and the result from the previous mask-calculation step. It consists of the following operations:

  1. "Simple threshold": this operation applies a global threshold to the input corrected image, using the triangle algorithm to calculate an optimal threshold value for the image; the output is a mask in which each pixel is set to 0 if the corresponding pixel of the input image is greater than the threshold, and to 255 otherwise. The resulting mask should select for objects which appear darker than the background of the image.

  2. "Remove previous mask": this operation combines the result of the previous mask-calculation step with the mask created by the previous "simple threshold" operation, by subtracting the intersection of the two masks from the mask created by the previous "simple threshold" operation. This operation is probably intended to remove objects which had been stuck to the PlanktoScope's flowcell during imaging and thus might appear in many consecutive input corrected images. However, this operation is not robust in dense samples where two different objects might appear in overlapping locations across two consecutive raw images.

  3. "Erode": this operation erodes the mask with a 2-pixel-by-2-pixel square kernel. In the resulting mask, small regions (such as thresholded noise) are eliminated.

  4. "Dilate": this operation dilates the mask with an 8-pixel-diameter circular kernel. In the resulting mask, regions remaining after the previous "erode" operation are padded with a margin.

  5. "Close": this operation dilates and then erodes the mask with an 8-pixel-diameter circular kernel. In the resulting mask, small holes in regions remaining after the previous "dilate" operation are eliminated.

  6. "Erode2": this operation erodes the mask with an 8-pixel-diameter circular kernel, inverting the effect of the previous "dilate" operation.

The final result these operations is a spatially-filtered segmentation mask where the value of each pixel represents whether that pixel is part of an object or part of the background of the input corrected image.

Object-extraction step🔗

The object-extraction step takes the following inputs:

  • A median-corrected image

  • A segmentation mask

  • The following sample metadata fields:

  • acq_minimum_mesh: the diameter of the smallest spherical object which is expected to be in the sample, usually 20 µm. This value is set on the "Fluidic Acquisition" page of the PlanktoScope's Node-RED dashboard as the "Min fraction size".

  • process_pixel: the pixel size calibration of the PlanktoScope, in units of µm per pixel; then the area (in units of µm2) per pixel is process_pixel * process_pixel. This value is set on the "Hardware Settings" page of the PlanktoScope's Node-RED dashboard as the "Pixel size calibration: um per pixel".

First, the object-extraction step calculates a minimum-area threshold for objects to extract using the input segmentation mask: the threshold (in units of pixel2) is calculated as (2 * acq_minimum_mesh / process_pixel) ^ 2.

Next, the object-extraction step identifies all connected regions of the input segmentation mask and measures properties of those regions. The object-extraction step then discards any region whose bounding-box area (area_bbox in scikit-image) is less than the minimum-area threshold.

Metadata calculation🔗

For each resulting region after the minimum-area threshold is applied, that region will be used to extract a segmented and cropped image of the object (including pixels in any holes in the object) from the input median-corrected image. This cropped image is used to calculate some metadata fields about the distribution of colors in the object's segmented image:

  • MeanHue: the mean of the hue channel of the image in a hue-saturation-value (HSV) representation of the image

  • StdHue: the standard deviation of the hue channel of the image in an HSV representation of the image

  • MeanSaturation: the standard deviation of the saturation channel of the image in an HSV representation of the image

  • StdSaturation: the standard deviation of the saturation channel of the image in an HSV representation of the image

  • MeanValue: the standard deviation of the value channel of the image in an HSV representation of the image

  • StdValue: the standard deviation of the value channel of the image in an HSV representation of the image

Additionally, some metadata for the object is calculated from the region properties calculated by scikit-image for that object's region:

  • label: The identifier of the object's region, as assigned by scikit-image. This corresponds to the label region property in scikit-image.

  • Basic area properties:

  • area_exc: Number of pixels in the region (excluding pixels in any holes). This corresponds to the area region property in scikit-image.

  • area: Number of pixels of the region with all holes filled in (i.e. including pixels in any holes). This corresponds to the area_filled region property in scikit-image. Yes, it's somewhat confusing that the PlanktoScope segmenter renames scikit-image's area region property to area_exc and renames scikit-image's area_filled region property to area.

  • %area: Ratio between the number of pixels in any holes in the region and the total number of pixels of the region with all holes filled in; calculated as 1 - area_exc / area. In other words, this represents the proportion of the region which consists of holes. Yes, %area is a misleading name both because of the % in the name and because of the area in the name.

  • Equivalent-circle properties:

  • equivalent_diameter: The diameter (in pixels) of a circle with the same number of pixels in its area as the number of pixels in the region (excluding pixels in any holes). This corresponds to the equivalent_diameter_area property in scikit-image.

  • Equivalent-ellipse properties:

  • eccentricity: Eccentricity of the ellipse that has the same second-moments as the region; eccentricity is the ratio of the focal distance (distance between focal points) over the major axis length. The value is in the interval [0, 1), where a value of 0 represents a circle. This corresponds to the eccentricity property in scikit-image.

  • major: The length (in pixels) of the major axis of region's equivalent ellipse. This corresponds to the axis_major_length property in scikit-image.

  • minor: The length (in pixels) of the minor axis of the region's equivalent ellipse. This corresponds to the axis_minor_length property in scikit-image.

  • elongation: The ratio between major and minor.

  • angle: Angle (in degrees) between the x-axis of the input median-corrected image and the major axis of the region's equivalent ellipse. Values range from 0 deg to 180 deg counter-clockwise. This is calculated from the orientation property in scikit-image.

  • Equivalent-object perimeter properties:

  • perim.: Perimeter (in pixels) of an object which approximates the region's contour as a line through the centers of border pixels using a 4-connectivity. This corresponds to the perimeter property in scikit-image.

  • perimareaexc: Ratio between the perimeter and the number of pixels in the region (excluding pixels in any holes). Calculated as perim. / area_exc.

  • perimmajor: Ratio between the perimeter and the length of the major axis of the region's equivalent ellipse. Calculated as perim. / major.

  • circ.: The roundness of the region's equivalent object, including pixels in any holes. Calculated as 4 * π * area / (perim. * perim.). Ranges from 1 for a perfect circle to 0 for highly non-circular shapes.

  • circex: The roundness of the region's equivalent object, excluding pixels in any holes. Calculated as 4 * π * area_exc / (perim. * perim.). Ranges from 1 for a perfect circle to 0 for highly non-circular shapes or shapes with many large holes.

  • Bounding box (the smallest rectangle which includes all pixels of the region, under the constraint that the edges of the box are parallel to the x- and y-axes of the input median-corrected image) properties:

  • bx: x-position (in pixels) of the top-left corner of the region's bounding box, relative to the top-left corner of the input median-corrected image. This corresponds to the second element of the bbox property in scikit-image.

  • by: y-position (in pixels) of the top-left corner of the region's bounding box, relative to the top-left corner of the input median-corrected image. This corresponds to the first element of the bbox property in scikit-image.

  • width: Width (in number of pixels) of the region's bounding box. This is calculated from the elements of the bbox property in scikit-image.

  • height: Height (in number of pixels) of the region's bounding box. This is calculated from the elements of the bbox property in scikit-image.

  • bounding_box_area: Number of pixels in the region's bounding box; equivalent to width * height. This corresponds to the area_bbox region property in scikit-image.

  • extent: Ratio between the number of pixels in the region (excluding pixels in any holes) and the number of pixels in the region's bounding box; equivalent to area_exc / bounding_box_area. This corresponds to the extent region property in scikit-image.

  • Convex hull (the smallest convex polygon which encloses the region) properties:

  • convex_area: Number of pixels in the convex hull of the region. This corresponds to the area_convex region property in scikit-image.

  • solidity: Ratio between the number of pixels in the region (excluding pixels in any holes) and the number of pixels in the convex hull of the region. Equivalent to area_exc / convex_area. This corresponds to the solidity region property in scikit-image.

  • Unweighted centroid properties:

  • x: x-position (in pixels) of the centroid of the object, relative to the top-left corner of the input median-corrected image. This corresponds to the second element of the centroid region property in scikit-image.

  • y: y-position (in pixels) of the centroid of the object, relative to the top-left corner of the input median-corrected image. This corresponds to the first element of the centroid region property in scikit-image.

  • local_centroid_col: x-position (in pixels) of the centroid of the object, relative to the top-left corner of the region's bounding box; equivalent to x - bx. This corresponds to the second element of the centroid_local region property in scikit-image.

  • local_centroid_row: y-position (in pixels) of the centroid of the object, relative to the top-left corner of the region's bounding box; equivalent to y - by. This corresponds to the first element of the centroid_local region property in scikit-image.

  • Topological properties:

  • euler_number: The Euler characteristic of the set of non-zero pixels. Computed as the number of connected components subtracted by the number of holes (with 2-connectivity). This corresponds to the euler_number property in scikit-image.

Output image cropping🔗

Finally, a segmented and cropped image of the object (including pixels in any holes in the object) is saved from the input median-corrected image, but with the crop expanded by up to 10 pixels in each direction (TODO: check whether this description is accurate - the corresponding code is extremely unreadable).

Thus, the output of the output-extraction step is a set of objects, each with a corresponding cropped image saved to file and with a corresponding list of metadata values.

Exported Metadata🔗

TODO

Exported Metadata🔗

TODO

Product Specifications🔗

The PlanktoScope OS includes all software which needs to run on the PlanktoScope's hardware to provide the overall functionality of a PlanktoScope. Product specifications for the PlanktoScope OS are listed below for ranges of software version numbers. To see software versions listed individually in chronological order, refer to the project release notes or the software changelog. To understand how to interpret software version numbers, refer to our description of the PlanktoScope OS's version numbering system.

v2024.0.0🔗

Specs for v2024.0.0 are the same as in v2023.9.0, except for the following sections:

  • Base operating system: the binary target architecture has changed from 32-bit to 64-bit.
  • System performance: on-board image processing speeds have improved (processing speeds have nearly doubled).

Functionalities🔗

Regular operation:

  • Image acquisition: stop-flow imaging (JPEG image output)
  • On-board image processing: detection and segmentation of objects (batch-processing only)
  • User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer
  • Export of data for uploading to EcoTaxa

Advanced operations:

  • User interfacing: web browser interfaces for system administration, system monitoring, and troubleshooting
  • Automation: MQTT-based API
  • Application deployment: ability to add software as OCI containers using Docker, optionally via Forklift
  • System configuration: ability to reversibly add, remove, replace, or override OS configuration files via Forklift

Base operating system🔗

  • Distro: Raspberry Pi OS 11 (bullseye)
  • Binary target architecture: 64-bit (aarch64, also known as arm64)

Supported hardware🔗

Minimum for image acquisition (but not sufficient for on-board image processing):

  • PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer
  • Memory: 1 GB RAM
  • Storage: 8 GB capacity

Minimum for full functionality, including on-board image processing:

  • Memory: 4 GB RAM

Recommended:

  • PlanktoScope: hardware v2.5 or v2.6 with Raspberry Pi 4 Model B computer
  • Storage: 32 GB capacity

Forwards-incompatibilities:

  • Unable to run on the Raspberry Pi 5 computer.

Backwards-incompatibilities:

  • Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.

System performance🔗

With minimum supported hardware for full functionality:

  • On-board image processing: a dataset of 400 raw images is processed in approximately 1 hour

v2023.9.0🔗

Functionalities🔗

Regular operation:

  • Image acquisition: stop-flow imaging (JPEG image output)
  • On-board image processing: detection and segmentation of objects (batch-processing only)
  • User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer
  • Export of data for uploading to EcoTaxa

Advanced operations:

  • User interfacing: web browser interfaces for system administration, system monitoring, and troubleshooting
  • Automation: MQTT-based API
  • Application deployment: ability to add software as OCI containers using Docker, optionally via Forklift

Base operating system🔗

  • Distro: Raspberry Pi OS 11 (bullseye)
  • Binary target architecture: 32-bit only (armhf, also known as armv7)

Supported hardware🔗

Minimum for image acquisition (but not sufficient for on-board image processing):

  • PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer
  • Memory: 1 GB RAM
  • Storage: 8 GB capacity

Minimum for full functionality, including on-board image processing:

  • Memory: 4 GB RAM

Recommended:

  • PlanktoScope: hardware v2.5 or v2.6 with Raspberry Pi 4 Model B computer
  • Storage: 32 GB capacity

Forwards-incompatibilities:

  • Unable to run on the Raspberry Pi 5 computer.

Backwards-incompatibilities:

  • Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.

System performance🔗

With minimum supported hardware for full functionality:

  • On-board image processing: a dataset of 400 raw images is processed in approximately 1.5 to 2 hours

v2.3🔗

Functionalities🔗

Regular operation:

  • Image acquisition: stop-flow imaging (JPEG image output)
  • On-board image processing: detection and segmentation of objects (batch-processing only)
  • User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer
  • Export of data for uploading to EcoTaxa

Advanced operations:

  • Automation: MQTT-based API

Base operating system🔗

  • Distro: Raspberry Pi OS 11 (bullseye)
  • Binary target architecture: 32-bit only (armhf, also known as armv7)

Supported hardware🔗

Minimum for image acquisition (but not sufficient for on-board image processing):

  • PlanktoScope: hardware v2.1 with Raspberry Pi 3 Model B+ computer
  • Memory: 1 GB RAM
  • Storage: 8 GB capacity

Minimum for full functionality, including on-board image processing:

  • PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer
  • Memory: 4 GB RAM

Recommended for full functionality:

  • PlanktoScope: hardware v2.5 or v2.6
  • Storage: 32 GB capacity

Forwards-incompatibilities:

  • Unable to run on the Raspberry Pi 5 computer.
  • Incompatible with Adafruit Stepper Motor HATs (used in PlanktoScope hardware v2.1) manufactured after mid-2022.

System performance🔗

With minimum supported hardware for full functionality:

  • On-board image processing: a dataset of 400 raw images is processed in approximately 1.5 to 2 hours

Product Specifications🔗

The PlanktoScope OS includes all software which needs to run on the PlanktoScope's hardware to provide the overall functionality of a PlanktoScope. Product specifications for the PlanktoScope OS are listed below for ranges of software version numbers. To see software versions listed individually in chronological order, refer to the project release notes or the software changelog. To understand how to interpret software version numbers, refer to our description of the PlanktoScope OS's version numbering system.

v2024.0.0🔗

Specs for v2024.0.0 are the same as in v2023.9.0, except for the following sections:

  • Base operating system: the binary target architecture has changed from 32-bit to 64-bit.
  • System performance: on-board image processing speeds have improved (processing speeds have nearly doubled).

Functionalities🔗

Regular operation:

  • Image acquisition: stop-flow imaging (JPEG image output)
  • On-board image processing: detection and segmentation of objects (batch-processing only)
  • User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer
  • Export of data for uploading to EcoTaxa

Advanced operations:

  • User interfacing: web browser interfaces for system administration, system monitoring, and troubleshooting
  • Automation: MQTT-based API
  • Application deployment: ability to add software as OCI containers using Docker, optionally via Forklift
  • System configuration: ability to reversibly add, remove, replace, or override OS configuration files via Forklift

Base operating system🔗

  • Distro: Raspberry Pi OS 11 (bullseye)
  • Binary target architecture: 64-bit (aarch64, also known as arm64)

Supported hardware🔗

Minimum for image acquisition (but not sufficient for on-board image processing):

  • PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer
  • Memory: 1 GB RAM
  • Storage: 8 GB capacity

Minimum for full functionality, including on-board image processing:

  • Memory: 4 GB RAM

Recommended:

  • PlanktoScope: hardware v2.5 or v2.6 with Raspberry Pi 4 Model B computer
  • Storage: 32 GB capacity

Forwards-incompatibilities:

  • Unable to run on the Raspberry Pi 5 computer.

Backwards-incompatibilities:

  • Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.

System performance🔗

With minimum supported hardware for full functionality:

  • On-board image processing: a dataset of 400 raw images is processed in approximately 1 hour

v2023.9.0🔗

Functionalities🔗

Regular operation:

  • Image acquisition: stop-flow imaging (JPEG image output)
  • On-board image processing: detection and segmentation of objects (batch-processing only)
  • User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer
  • Export of data for uploading to EcoTaxa

Advanced operations:

  • User interfacing: web browser interfaces for system administration, system monitoring, and troubleshooting
  • Automation: MQTT-based API
  • Application deployment: ability to add software as OCI containers using Docker, optionally via Forklift

Base operating system🔗

  • Distro: Raspberry Pi OS 11 (bullseye)
  • Binary target architecture: 32-bit only (armhf, also known as armv7)

Supported hardware🔗

Minimum for image acquisition (but not sufficient for on-board image processing):

  • PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer
  • Memory: 1 GB RAM
  • Storage: 8 GB capacity

Minimum for full functionality, including on-board image processing:

  • Memory: 4 GB RAM

Recommended:

  • PlanktoScope: hardware v2.5 or v2.6 with Raspberry Pi 4 Model B computer
  • Storage: 32 GB capacity

Forwards-incompatibilities:

  • Unable to run on the Raspberry Pi 5 computer.

Backwards-incompatibilities:

  • Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.

System performance🔗

With minimum supported hardware for full functionality:

  • On-board image processing: a dataset of 400 raw images is processed in approximately 1.5 to 2 hours

v2.3🔗

Functionalities🔗

Regular operation:

  • Image acquisition: stop-flow imaging (JPEG image output)
  • On-board image processing: detection and segmentation of objects (batch-processing only)
  • User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer
  • Export of data for uploading to EcoTaxa

Advanced operations:

  • Automation: MQTT-based API

Base operating system🔗

  • Distro: Raspberry Pi OS 11 (bullseye)
  • Binary target architecture: 32-bit only (armhf, also known as armv7)

Supported hardware🔗

Minimum for image acquisition (but not sufficient for on-board image processing):

  • PlanktoScope: hardware v2.1 with Raspberry Pi 3 Model B+ computer
  • Memory: 1 GB RAM
  • Storage: 8 GB capacity

Minimum for full functionality, including on-board image processing:

  • PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer
  • Memory: 4 GB RAM

Recommended for full functionality:

  • PlanktoScope: hardware v2.5 or v2.6
  • Storage: 32 GB capacity

Forwards-incompatibilities:

  • Unable to run on the Raspberry Pi 5 computer.
  • Incompatible with Adafruit Stepper Motor HATs (used in PlanktoScope hardware v2.1) manufactured after mid-2022.

System performance🔗

With minimum supported hardware for full functionality:

  • On-board image processing: a dataset of 400 raw images is processed in approximately 1.5 to 2 hours

Release Process🔗

The PlanktoScope's software is released independently of the PlanktoScope's hardware; this document explains how we manage releases of the PlanktoScope OS (which contains the software which runs on a PlanktoScope, and which you can download as an SD card image), to help you to:

Version numbering🔗

The PlanktoScope OS is a combination of many individual software components; some components (such as most parts of the PlanktoScope's graphical user interface, and some of its hardware drivers) are written, maintained, and distributed by the PlanktoScope project, while other components (such as the Cockpit administration dashboard and the file browser) are written, maintained, and distributed by other open-source software projects. Each component has its own release schedule and version numbering system; the specific combination of releases and versions of all these components will change over time as these components change, and we represent each total combination of all software components by a version number assigned to a particular release of the PlanktoScope OS. For example, the v2023.9.0 release of the PlanktoScope OS included various software programs at one specific combination of versions, while the v2024.0.0 release upgraded some of those programs to newer versions.

We use a calendar-based version numbering system for the PlanktoScope OS, where each version number has the format v(year).(minor).(patch) for stable releases of the software or v(year).(minor).(patch)-(modifier) for testing pre-releases of the software:

  • year is a 4-digit number representing the year (in the Gregorian calendar) in which the stable release is (or will be) published. For example, version v2024.0.0 was published in 2024, while version v2025.0.0 will be published in 2025.

  • minor is a number which starts at 0 for the first release in each year, and increments by 1 for each release which adds new features or includes notable changes to existing features. Usually minor will be incremented one or two times each year. For example, version v2024.0.0 was the first version published in 2024, while version v2024.1.0 will be the second version with notable changes to be published in 2024.

  • patch is a number which starts at 0 for each (year).(minor) combination, and increments by 1 for each release which consists only of small bug fixes. For example, if there were some small bugs in v2024.0.0 which we wanted to patch before a v2024.1.0 release, we could add those patches as part of a (hypothetical) v2024.0.1 release. If the bugs are not very severe, we might not publish a patch release and we could instead just include those bug fixes together with other new features, in which case we would increment minor with the next release. For example, we might not publish a v2024.0.1 release, and instead just publish a v2024.1.0 release.

  • modifier is an additional string included to identify "alpha" or "beta" pre-releases published for testing before the stable release. We typically publish multiple "alpha" and "beta" pre-releases with additional improvements before a stable release, so modifier has the format of either alpha.(index) or beta.(index), where index is a number which starts at 0 for each (year).(minor).(patch)-alpha or (year).(minor).(patch)-beta combination. For example, the first "alpha" pre-release for v2024.0.0 was v2024.0.0-alpha.0, the second "alpha" pre-release was v2024.0.0-alpha.1, and the first "beta" pre-release was v2024.0.0-beta.0.

Release channels🔗

The PlanktoScope project uses a concept called "release channels" to structure our process for stabilizing and testing our software before we publish a new release of the PlanktoScope OS for everyone to use. There are three channels for PlanktoScope software releases and pre-releases, each corresponding to a particular branch of the PlanktoScope repository on GitHub:

  • Edge: On the "Edge" channel, the PlanktoScope OS is built from the setup scripts on the latest commit of the master branch of the PlanktoScope repository on GitHub - so the "Edge" channel is essentially the current unstable development version of the PlanktoScope OS, and is often likely to be broken or buggy in various ways. Occasionally, specific commits on the master branch are tagged as "alpha" pre-releases; "alpha" pre-releases should be treated as snapshots of PlanktoScope software development for testing by PlanktoScope software developers and advanced users.
  • Beta: Once an "alpha" pre-release has received sufficient testing for the PlanktoScope software developers to consider it stable enough for all PlanktoScope users to test it out, it will be promoted to a "beta" pre-release, and the software/beta branch of the PlanktoScope repository on GitHub will be advanced to the Git commit of the "beta" pre-release. At that point, the software/beta branch will only receive patches to fix serious errors. As bugs are fixed on the software/beta branch, more "beta" pre-releases may be created on that branch for users to test.
  • Stable: After the latest "beta" pre-release has received sufficient testing for the PlanktoScope software developers to consider it stable enough for most (or, ideally, all) PlanktoScope users to rely on it for production use and scientific operations, that "beta" pre-release will be promoted to a "stable" release, and the software/stable branch of the PlanktoScope repository on GitHub will be advanced to the git commit of the "stable" release.

Release schedules🔗

We try to publish a few stable releases every year. Some stable releases may consist of small bugfixes, while other stable releases may add new functionalities or change existing functionalities. Thus, each release involves changes with different sizes of potential impact on software stability and different levels of risks for introducing new bugs. Because of this, we usually cannot make confident predictions about how long we will need to wait before we can promote an "alpha" pre-release to a "beta" pre-release. And because we rely on volunteers to test our "beta" pre-releases and the availability of volunteers for testing each "beta" pre-release often varies a lot, we cannot make confident predictions about how long we will need to wait before we can promote a "beta" pre-release to a "stable" release.

Although the unpredictability of "alpha" and "beta" pre-release testing timelines prevents us from being able to set realistic expectations about specific software release timelines, you can generally expect at least one stable release in the first half of each year, and at least one stable release in the second half of each year.

Choosing a release channel🔗

Unless you have a specific reason, you probably should follow the stable release channel. "Stable" releases are intended for a general audience to rely on.

However, we encourage all PlanktoScope users who use the stable release channel to also test beta pre-releases once those pre-releases are published. This will help us to discover and understand bugs which we may need to fix before promoting the PlanktoScope software from the "Beta"" channel to the "Stable" channel.

Upgrading to a new release or pre-release🔗

In order to use a new release or pre-release of the PlanktoScope OS, you will need to do one of the following:

Then you will need to re-flash your PlanktoScope's SD card (or flash a new SD card for your PlanktoScope) with the resulting SD card image for the new release/pre-release of the PlanktoScope OS.

Release Process🔗

The PlanktoScope's software is released independently of the PlanktoScope's hardware; this document explains how we manage releases of the PlanktoScope OS (which contains the software which runs on a PlanktoScope, and which you can download as an SD card image), to help you to:

Version numbering🔗

The PlanktoScope OS is a combination of many individual software components; some components (such as most parts of the PlanktoScope's graphical user interface, and some of its hardware drivers) are written, maintained, and distributed by the PlanktoScope project, while other components (such as the Cockpit administration dashboard and the file browser) are written, maintained, and distributed by other open-source software projects. Each component has its own release schedule and version numbering system; the specific combination of releases and versions of all these components will change over time as these components change, and we represent each total combination of all software components by a version number assigned to a particular release of the PlanktoScope OS. For example, the v2023.9.0 release of the PlanktoScope OS included various software programs at one specific combination of versions, while the v2024.0.0 release upgraded some of those programs to newer versions.

We use a calendar-based version numbering system for the PlanktoScope OS, where each version number has the format v(year).(minor).(patch) for stable releases of the software or v(year).(minor).(patch)-(modifier) for testing pre-releases of the software:

  • year is a 4-digit number representing the year (in the Gregorian calendar) in which the stable release is (or will be) published. For example, version v2024.0.0 was published in 2024, while version v2025.0.0 will be published in 2025.

  • minor is a number which starts at 0 for the first release in each year, and increments by 1 for each release which adds new features or includes notable changes to existing features. Usually minor will be incremented one or two times each year. For example, version v2024.0.0 was the first version published in 2024, while version v2024.1.0 will be the second version with notable changes to be published in 2024.

  • patch is a number which starts at 0 for each (year).(minor) combination, and increments by 1 for each release which consists only of small bug fixes. For example, if there were some small bugs in v2024.0.0 which we wanted to patch before a v2024.1.0 release, we could add those patches as part of a (hypothetical) v2024.0.1 release. If the bugs are not very severe, we might not publish a patch release and we could instead just include those bug fixes together with other new features, in which case we would increment minor with the next release. For example, we might not publish a v2024.0.1 release, and instead just publish a v2024.1.0 release.

  • modifier is an additional string included to identify "alpha" or "beta" pre-releases published for testing before the stable release. We typically publish multiple "alpha" and "beta" pre-releases with additional improvements before a stable release, so modifier has the format of either alpha.(index) or beta.(index), where index is a number which starts at 0 for each (year).(minor).(patch)-alpha or (year).(minor).(patch)-beta combination. For example, the first "alpha" pre-release for v2024.0.0 was v2024.0.0-alpha.0, the second "alpha" pre-release was v2024.0.0-alpha.1, and the first "beta" pre-release was v2024.0.0-beta.0.

Release channels🔗

The PlanktoScope project uses a concept called "release channels" to structure our process for stabilizing and testing our software before we publish a new release of the PlanktoScope OS for everyone to use. There are three channels for PlanktoScope software releases and pre-releases, each corresponding to a particular branch of the PlanktoScope repository on GitHub:

  • Edge: On the "Edge" channel, the PlanktoScope OS is built from the setup scripts on the latest commit of the master branch of the PlanktoScope repository on GitHub - so the "Edge" channel is essentially the current unstable development version of the PlanktoScope OS, and is often likely to be broken or buggy in various ways. Occasionally, specific commits on the master branch are tagged as "alpha" pre-releases; "alpha" pre-releases should be treated as snapshots of PlanktoScope software development for testing by PlanktoScope software developers and advanced users.
  • Beta: Once an "alpha" pre-release has received sufficient testing for the PlanktoScope software developers to consider it stable enough for all PlanktoScope users to test it out, it will be promoted to a "beta" pre-release, and the software/beta branch of the PlanktoScope repository on GitHub will be advanced to the Git commit of the "beta" pre-release. At that point, the software/beta branch will only receive patches to fix serious errors. As bugs are fixed on the software/beta branch, more "beta" pre-releases may be created on that branch for users to test.
  • Stable: After the latest "beta" pre-release has received sufficient testing for the PlanktoScope software developers to consider it stable enough for most (or, ideally, all) PlanktoScope users to rely on it for production use and scientific operations, that "beta" pre-release will be promoted to a "stable" release, and the software/stable branch of the PlanktoScope repository on GitHub will be advanced to the git commit of the "stable" release.

Release schedules🔗

We try to publish a few stable releases every year. Some stable releases may consist of small bugfixes, while other stable releases may add new functionalities or change existing functionalities. Thus, each release involves changes with different sizes of potential impact on software stability and different levels of risks for introducing new bugs. Because of this, we usually cannot make confident predictions about how long we will need to wait before we can promote an "alpha" pre-release to a "beta" pre-release. And because we rely on volunteers to test our "beta" pre-releases and the availability of volunteers for testing each "beta" pre-release often varies a lot, we cannot make confident predictions about how long we will need to wait before we can promote a "beta" pre-release to a "stable" release.

Although the unpredictability of "alpha" and "beta" pre-release testing timelines prevents us from being able to set realistic expectations about specific software release timelines, you can generally expect at least one stable release in the first half of each year, and at least one stable release in the second half of each year.

Choosing a release channel🔗

Unless you have a specific reason, you probably should follow the stable release channel. "Stable" releases are intended for a general audience to rely on.

However, we encourage all PlanktoScope users who use the stable release channel to also test beta pre-releases once those pre-releases are published. This will help us to discover and understand bugs which we may need to fix before promoting the PlanktoScope software from the "Beta"" channel to the "Stable" channel.

Upgrading to a new release or pre-release🔗

In order to use a new release or pre-release of the PlanktoScope OS, you will need to do one of the following:

Then you will need to re-flash your PlanktoScope's SD card (or flash a new SD card for your PlanktoScope) with the resulting SD card image for the new release/pre-release of the PlanktoScope OS.

Installation🔗

This document explains how the PlanktoScope OS's installation process works, as a companion to our non-standard installation guide which carries out the process explained below.

The installation process is initiated by booting into an appropriate installation of the Raspberry Pi OS and then downloading and running the installation bootstrap script, which in turn downloads and runs the appropriate distro setup scripts according to the installation parameters provided to the installation bootstrap script.

Installation bootstrap script🔗

The installation bootstrap script is provided so that a one-line command can be executed to automatically perform the entire process of installing the PlanktoScope OS on top of the Raspberry Pi OS. The GitHub repository which contains that script always publishes the latest version on its stable branch to install.planktoscope.community/distro.sh via GitHub Pages; other versions can be downloaded from GitHub via the corresponding permalinks for those versions of the file (e.g. https://github.com/PlanktoScope/install.planktoscope.community/raw/v2023.9.0/distro.sh for the version from the v2023.9.0 tag in the repository). The installation bootstrap script performs the following steps:

  1. The script loads some parameters (set by environment variables and/or corresponding command-line arguments) which set the behavior of the script.

  2. The script installs git, if it was not already installed (as is the case on the "Lite" image of the Raspberry Pi OS); if the yes parameter was not set and git was not already installed, the script will first ask the user to confirm that they wish to install git before the script continues. git is required to resolve version query parameters provided to the script, so that the script can determine how to download the requested version of the PlanktoScope OS's distro setup scripts.

  3. The script clones a minimal "mirror" copy of the specified repository (set by the repo parameter) of distro setup scripts to a temporary directory (i.e. a directory created in /tmp). This "mirror" copy is used to:

    • Resolve the version query parameters (version-query, query-type, and - when query-type is tag - tag-prefix) into a specific commit hash for the repository.

    • Determine a (pseudo-)version string for the resolved commit based on the last release tag (whose name is prefixed with the tag-prefix parameter) ancestral to that commit.

  4. The script clones a copy of the specified repository (set by the repo parameter) to a temporary directory and checks out the specific commit which was resolved by the previous step; if the yes parameter was not set, the script will first ask the user to confirm that they wish to download the resolved commit of the distro setup scripts before the script continues. Because the repository containing the distro setup scripts may have many large files (e.g. image files for documentation) which are unrelated to the distro setup scripts, this step only downloads files in the specific commit needed for the distro setup scripts.

  5. The script records versioning information for the downloaded installation scripts, saving that information in two YAML files in a particular directory; if that directory already exists and the yes parameter was not set, the script will first ask the user to confirm that they wish to delete and re-create that directory before the script continues. Installed programs can read these files in order to determine the installed version of the PlanktoScope OS.

  6. The script runs the specified script (set by the setup-entrypoint parameter) within the downloaded copy of the specified repository; if the yes parameter was not set, the script will first ask the user to confirm that they wish to run the downloaded distro scripts before the script continues.

Script parameters🔗

Command-Line Flags Environment Variable Name Description
-r
--repo		 REPO URL of the Git repository used for downloading the distro setup scripts. If a protocol is not specified, the URL will be assumed to use HTTPS.
Default value: github.com/PlanktoScope/PlanktoScope
-v
--version-query		 VERSION_QUERY The version of the repository to download. The version query is interpreted differently depending on the query type set by the query-type parameter:
  • Query type  branch: query should be a branch name (e.g. software/beta).
  • Query type tag: query should be a Git tag name, excluding the tag prefix specified by the tag-prefix parameter (e.g. v2024.0.0 if tag-prefix is software and the Git tag is software/v2024.0.0).
  • Query type hash: query should be a commit hash and may be abbreviated (e.g. 2d6928e).
Default value: software/stable
-t
--query-type		 QUERY_TYPE The type of version query set by the version-query parameter.
Allowed values: branch, tag, hash.
Default value: branch
-H
--hardware		 HARDWARE The hardware configuration, passed as the first argument to the entrypoint of the distro setup scripts. The distro setup scripts in the github.com/PlanktoScope/PlanktoScope repo currently expect either adafruithat or planktoscopehat.
Default value: planktoscopehat
--tag-prefix TAG_PREFIX The prefix for Git version tags when resolving the version query (with query type tag) and when resolving tags (for pseudoversion strings). 
Default value: software/
--setup-entrypoint SETUP_ENTRYPOINT The entrypoint of the distro setup scripts, which will be executed in order to run the downloaded distro setup scripts. This should be a subdirectory path within the repository (set by the repo parameter) which will be downloaded at the specified commit (set by the version-query and query-type parameters and - when query-type is tag - by the tag-prefix parameter) to obtain the distro setup scripts.
Default value: software/distro/setup/setup.sh
-y
-f
--yes
--force		 FORCE Whether to automatically confirm all user confirmation prompts:
  • FORCE=1 (or including the command-line flag) automatically confirms all prompts.
  • Not setting FORCE (or not including the command-line flag) requires user input for confirmation on all prompts.
Default: User input required
-V
--verbose		 VERBOSE Whether to display additional (verbose) output:
  • VERBOSE=1 (or including the command-line flag) enables verbose output.
  • Not setting VERBOSE (or not including the command-line flag) disables verbose output.
Default: Don't display verbose output
-h
--help		 Whether to display a help message (which includes this parameter reference table and a list of example commands using this script) and quit without doing any work.

Example combinations of command-line arguments using the above parameters:

  • -v software/stable -H planktoscopehat or -H planktoscopehat: install the latest stable release of the standard PlanktoScope OS (i.e. from the software/stable branch) for a PlanktoScope with the PlanktoScope HAT.

  • -v software/beta -H adafruithat: install the latest beta pre-release or stable release of the standard PlanktoScope OS (i.e. from the software/beta branch) for a PlanktoScope with the Adafruit HAT.

  • -v master -H planktoscopehat: install the latest development version of the standard PlanktoScope OS (i.e. from the master branch) for a PlanktoScope with the PlanktoScope HAT.

  • -t tag -v v2024.0.0-alpha.1 -H adafruithat: install the v2024.0.0-alpha.1 pre-release of the standard PlanktoScope OS (i.e. from the software/v2024.0.0-alpha.1 tag) for a PlanktoScope with the Adafruit HAT.

  • -t hash -v 2d6928e -H planktoscopehat: install 2d6928e commit of the standard PlanktoScope OS for a PlanktoScope with the PlanktoScope HAT.

  • -v master -r github.com/LaurentPV/PlanktoScope -H adafruithat: install the latest development commit of master branch of the github.com/LaurentPV/PlanktoScope fork of the PlanktoScope OS for a PlanktoScope with the Adafruit HAT.

Recorded versioning information🔗

Currently the installer script creates two YAML files, both in the /home/pi/.local/etc/pkscope-distro directory. (Note: this directory may change in the future.)

/home/pi/.local/etc/pkscope-distro/installer-config.yml records the values of the parameters with which the installer script was invoked:

YAML Field Name Corresponding Script Parameter Example Value
repo repo "github.com/PlanktoScope/PlanktoScope"
version-query version-query "v2024.0.0-alpha.1"
query-type query-type "tag"
hardware hardware "adafruithat"
tag-prefix tag-prefix "software/"
setup-entrypoint setup-entrypoint "software/distro/setup/setup.sh"

/home/pi/.local/etc/pkscope-distro/installer-versioning.yml records information about the version of the PlanktoScope OS's distro setup scripts which was used to install the PlanktoScope OS:

Field Name Description
repo The path of the Git repository which provided the distro setup scripts, with any leading protocol string (e.g. https://) removed.
Example Values:
  1. "github.com/PlanktoScope/PlanktoScope"
  2. "github.com/PlanktoScope/PlanktoScope"
commit The full hash of the exact commit which provided the distro setup scripts.
Example Values:
  1. "2d6928e596b28f0c4c268fecb588c85215b1027e" (for commit 2d6928e)
  2. "4d8b882616a8374918730bc1c6d300edfd7a523a" (for commit 4d8b882)
tag The full name of the Git tag (whose name starts with the prefix set by the tag-prefix script parameter) at the exact commit which provided the distro setup scripts, if such a tag exists; otherwise, the empty string ("").
Example Values:
  1. "software/v2024.0.0-alpha.1" (so commit 2d6928e has Git tag software/v2024.0.0-alpha.1)
  2. "" (so commit 4d8b882 has no Git tag)
version A version string or pseudo-version string describing the exact commit which provided the distro setup scripts. If a Git tag (with a name starting with the prefix set by the tag-prefix script parameter) exists at that commit, this is a version string which just the name of that tag, but with the tag-prefix stripped from the name. Otherwise, this is a pseudo-version string with format "{tag}-{distance}-g{commit}", where:
  • {tag} is the name of the most recent ancestral tag (with a name starting with the prefix set by the tag-prefix script parameter) reachable from the commit, but with the tag-prefix stripped from the name.
  • {distance} distance (in number of commits) between the commit and the most recent ancestral tag.
  • {commit} consists of the first seven characters of the hash of the commit.

Example Values:
  1. "v2024.0.0-alpha.1" (so commit 2d6928e has Git tag software/v2024.0.0-alpha.1)
  2. "v2024.0.0-alpha.1-4-g4d8b882" (so commit 4d8b882 is 4 commits above the commit with Git tag software/v2024.0.0-alpha.1, which was the last tag in the ancestry of the commit)

Distro setup scripts🔗

Currently, the entrypoint of the distro setup scripts, at software/distro/setup/setup.sh, takes exactly one command-line argument which must be one of the following values:

  • adafruithat: this will cause the distro setup scripts to install a version of the PlanktoScope hardware controller and the PlanktoScope Node-RED dashboard specific to PlanktoScopes using the Adafruit HAT, and to set the default hardware configuration files accordingly.

  • planktoscopehat: this will cause the distro setup scripts to install a version of the PlanktoScope hardware controller and the PlanktoScope Node-RED dashboard specific to PlanktoScopes using the PlanktoScope HAT, and to set the default hardware configuration files accordingly.

Currently, the distro setup scripts must be run by a user named pi. The scripts should not be run with sudo!

Currently, the distro setup scripts are split into two phases: setup of the base operating system, and setup of the PlanktoScope application environment. In the future, as we remove various setup steps from these scripts (and instead manage those steps using forklift), we may consolidate these two phases into a single phase.

Base system setup🔗

This phase performs steps which might (in theory) be useful for other projects which don't use the PlanktoScope hardware but would still benefit from many of the functionalities provided by the PlanktoScope OS. This phase consists of the following steps:

  • Installation of base tools: Docker, Cockpit, and various command-line tools are installed.

  • Installation of forklift and a Forklift pallet: a hard-coded version of forklift is downloaded to /usr/bin/forklift , a hard-coded version of a hard-coded pallet (namely, github.com/PlanktoScope/pallet-standard) is downloaded and prepared for deployment, and the forklift-apply.service systemd service is created and enabled. (Note: in the future, it will be possible to specify the pallet to be installed as a command-line argument.)

  • Partial configuration of Raspberry Pi-specific hardware: the SPI and I2C hardware interfaces are enabled, and the serial port and serial port console are enabled (note: the serial port console will be disabled by the PlanktoScope application environment setup phase so that the serial port can be used for the PlanktoScope's GPS receiver instead), and legacy camera support is disabled.

  • Configuration of the system locale: the system's language is changed to en_US.UTF-8, but the time and measurement formats are changed to en_DK.UTF-8 so that the date format is yyyy-mm-dd and units are metric. The system timezone is set to UTC.

  • Partial configuration of networking: various system services are installed and configured, namely dhcpcd, dnsmasq, hostapd, and firewalld. The enable-interface-forwarding.service and autohotspot.service systemd services are created and enabled. The Raspberry Pi's Wi-Fi country is set to the US.

  • Cleanup: SSH keys are reset to be regenerated on the next boot, unnecessary APT files are removed, and the OS machine ID is reset to be regenerated on the next boot.

PlanktoScope application environment setup🔗

This phase performs steps specific to the PlanktoScope's hardware:

  • Remaining configuration of networking: a hard-coded version of machine-name is downloaded to /usr/bin/machine-name, avahi-utils is installed using APT, and various systemd services are created and enabled to update the PlanktoScope OS's networking configurations based on a machine name which will be determined by machine-name from the Raspberry Pi's serial number at every boot. Additional systemd services are created and enabled so that the PlanktoScope will be accessible over some additional mDNS names (namely, pkscope.local and planktoscope.local).

  • Setup of the PlanktoScope hardware controller: various Python tools (pip, venv, and poetry) are installed using APT, a hard-coded version of a hard-coded Git repository (namely github.com/PlanktoScope/device-backend) is cloned, and various dependencies (both system libraries and Python packages) of the hardware controller are installed. The planktoscope-org.device-backend.controller-adafruithat.service and planktoscope-org.device-backend.controller-planktoscopehat.service systemd services are created, and the appropriate one is enabled depending on which HAT the PlanktoScope OS is being installed for. The appropriate hardware configuration file will also be copied into the location expected by the hardware controller. (Note: once the PlanktoScope hardware controller is containerized and managed in Forklift, this step will be eliminated.)

  • Setup of GPIO stepper initialization at boot: a systemd service is created to release the stepper motors at startup. (Note: this service currently doesn't work and will eventually be deleted or replaced.)

  • Setup of the PlanktoScope Node-RED dashboard: Node-RED is installed, as well as a Python package required by the adafruithat version of the PlanktoScope Node-RED dashboard (Note: the dependency on that package will eventually be removed.). The appropriate version of the PlanktoScope Node-RED dashboard and will be copied to the location expected by Node-RED depending on which HAT the PlanktoScope OS is being installed for, along with the appropriate configuration file. Finally, npm packages required by the Node-RED dashboard are installed. (Note: once the Node-RED dashboard is containerized and managed in Forklift, this step will be eliminated.)

  • Setup of hardware support for the PlanktoScope's real-time clock module: A kernel devicetree overlay is enabled. (Note: this currently enables support for the wrong hardware real-time clock chip, so it doesn't work yet.)

  • Setup of hardware support for the PlanktoScope's GPS receiver: gpsd and chrony are installed and configured. (Note: currently the configurations may be incorrect.)

  • Configuration of CPU overclocking: the CPU is overclocked so that the PlanktoScope segmenter will run more quickly. (Note: in the future, this will be removed.)

  • Cleanup: unnecessary APT and pip files are removed.

Installation🔗

This document explains how the PlanktoScope OS's installation process works, as a companion to our non-standard installation guide which carries out the process explained below.

The installation process is initiated by booting into an appropriate installation of the Raspberry Pi OS and then downloading and running the installation bootstrap script, which in turn downloads and runs the appropriate distro setup scripts according to the installation parameters provided to the installation bootstrap script.

Installation bootstrap script🔗

The installation bootstrap script is provided so that a one-line command can be executed to automatically perform the entire process of installing the PlanktoScope OS on top of the Raspberry Pi OS. The GitHub repository which contains that script always publishes the latest version on its stable branch to install.planktoscope.community/distro.sh via GitHub Pages; other versions can be downloaded from GitHub via the corresponding permalinks for those versions of the file (e.g. https://github.com/PlanktoScope/install.planktoscope.community/raw/v2023.9.0/distro.sh for the version from the v2023.9.0 tag in the repository). The installation bootstrap script performs the following steps:

  1. The script loads some parameters (set by environment variables and/or corresponding command-line arguments) which set the behavior of the script.

  2. The script installs git, if it was not already installed (as is the case on the "Lite" image of the Raspberry Pi OS); if the yes parameter was not set and git was not already installed, the script will first ask the user to confirm that they wish to install git before the script continues. git is required to resolve version query parameters provided to the script, so that the script can determine how to download the requested version of the PlanktoScope OS's distro setup scripts.

  3. The script clones a minimal "mirror" copy of the specified repository (set by the repo parameter) of distro setup scripts to a temporary directory (i.e. a directory created in /tmp). This "mirror" copy is used to:

    • Resolve the version query parameters (version-query, query-type, and - when query-type is tag - tag-prefix) into a specific commit hash for the repository.

    • Determine a (pseudo-)version string for the resolved commit based on the last release tag (whose name is prefixed with the tag-prefix parameter) ancestral to that commit.

  4. The script clones a copy of the specified repository (set by the repo parameter) to a temporary directory and checks out the specific commit which was resolved by the previous step; if the yes parameter was not set, the script will first ask the user to confirm that they wish to download the resolved commit of the distro setup scripts before the script continues. Because the repository containing the distro setup scripts may have many large files (e.g. image files for documentation) which are unrelated to the distro setup scripts, this step only downloads files in the specific commit needed for the distro setup scripts.

  5. The script records versioning information for the downloaded installation scripts, saving that information in two YAML files in a particular directory; if that directory already exists and the yes parameter was not set, the script will first ask the user to confirm that they wish to delete and re-create that directory before the script continues. Installed programs can read these files in order to determine the installed version of the PlanktoScope OS.

  6. The script runs the specified script (set by the setup-entrypoint parameter) within the downloaded copy of the specified repository; if the yes parameter was not set, the script will first ask the user to confirm that they wish to run the downloaded distro scripts before the script continues.

Script parameters🔗

Command-Line Flags Environment Variable Name Description
-r
--repo		 REPO URL of the Git repository used for downloading the distro setup scripts. If a protocol is not specified, the URL will be assumed to use HTTPS.
Default value: github.com/PlanktoScope/PlanktoScope
-v
--version-query		 VERSION_QUERY The version of the repository to download. The version query is interpreted differently depending on the query type set by the query-type parameter:
  • Query type  branch: query should be a branch name (e.g. software/beta).
  • Query type tag: query should be a Git tag name, excluding the tag prefix specified by the tag-prefix parameter (e.g. v2024.0.0 if tag-prefix is software and the Git tag is software/v2024.0.0).
  • Query type hash: query should be a commit hash and may be abbreviated (e.g. 2d6928e).
Default value: software/stable
-t
--query-type		 QUERY_TYPE The type of version query set by the version-query parameter.
Allowed values: branch, tag, hash.
Default value: branch
-H
--hardware		 HARDWARE The hardware configuration, passed as the first argument to the entrypoint of the distro setup scripts. The distro setup scripts in the github.com/PlanktoScope/PlanktoScope repo currently expect either adafruithat or planktoscopehat.
Default value: planktoscopehat
--tag-prefix TAG_PREFIX The prefix for Git version tags when resolving the version query (with query type tag) and when resolving tags (for pseudoversion strings). 
Default value: software/
--setup-entrypoint SETUP_ENTRYPOINT The entrypoint of the distro setup scripts, which will be executed in order to run the downloaded distro setup scripts. This should be a subdirectory path within the repository (set by the repo parameter) which will be downloaded at the specified commit (set by the version-query and query-type parameters and - when query-type is tag - by the tag-prefix parameter) to obtain the distro setup scripts.
Default value: software/distro/setup/setup.sh
-y
-f
--yes
--force		 FORCE Whether to automatically confirm all user confirmation prompts:
  • FORCE=1 (or including the command-line flag) automatically confirms all prompts.
  • Not setting FORCE (or not including the command-line flag) requires user input for confirmation on all prompts.
Default: User input required
-V
--verbose		 VERBOSE Whether to display additional (verbose) output:
  • VERBOSE=1 (or including the command-line flag) enables verbose output.
  • Not setting VERBOSE (or not including the command-line flag) disables verbose output.
Default: Don't display verbose output
-h
--help		 Whether to display a help message (which includes this parameter reference table and a list of example commands using this script) and quit without doing any work.

Example combinations of command-line arguments using the above parameters:

  • -v software/stable -H planktoscopehat or -H planktoscopehat: install the latest stable release of the standard PlanktoScope OS (i.e. from the software/stable branch) for a PlanktoScope with the PlanktoScope HAT.

  • -v software/beta -H adafruithat: install the latest beta pre-release or stable release of the standard PlanktoScope OS (i.e. from the software/beta branch) for a PlanktoScope with the Adafruit HAT.

  • -v master -H planktoscopehat: install the latest development version of the standard PlanktoScope OS (i.e. from the master branch) for a PlanktoScope with the PlanktoScope HAT.

  • -t tag -v v2024.0.0-alpha.1 -H adafruithat: install the v2024.0.0-alpha.1 pre-release of the standard PlanktoScope OS (i.e. from the software/v2024.0.0-alpha.1 tag) for a PlanktoScope with the Adafruit HAT.

  • -t hash -v 2d6928e -H planktoscopehat: install 2d6928e commit of the standard PlanktoScope OS for a PlanktoScope with the PlanktoScope HAT.

  • -v master -r github.com/LaurentPV/PlanktoScope -H adafruithat: install the latest development commit of master branch of the github.com/LaurentPV/PlanktoScope fork of the PlanktoScope OS for a PlanktoScope with the Adafruit HAT.

Recorded versioning information🔗

Currently the installer script creates two YAML files, both in the /home/pi/.local/etc/pkscope-distro directory. (Note: this directory may change in the future.)

/home/pi/.local/etc/pkscope-distro/installer-config.yml records the values of the parameters with which the installer script was invoked:

YAML Field Name Corresponding Script Parameter Example Value
repo repo "github.com/PlanktoScope/PlanktoScope"
version-query version-query "v2024.0.0-alpha.1"
query-type query-type "tag"
hardware hardware "adafruithat"
tag-prefix tag-prefix "software/"
setup-entrypoint setup-entrypoint "software/distro/setup/setup.sh"

/home/pi/.local/etc/pkscope-distro/installer-versioning.yml records information about the version of the PlanktoScope OS's distro setup scripts which was used to install the PlanktoScope OS:

Field Name Description
repo The path of the Git repository which provided the distro setup scripts, with any leading protocol string (e.g. https://) removed.
Example Values:
  1. "github.com/PlanktoScope/PlanktoScope"
  2. "github.com/PlanktoScope/PlanktoScope"
commit The full hash of the exact commit which provided the distro setup scripts.
Example Values:
  1. "2d6928e596b28f0c4c268fecb588c85215b1027e" (for commit 2d6928e)
  2. "4d8b882616a8374918730bc1c6d300edfd7a523a" (for commit 4d8b882)
tag The full name of the Git tag (whose name starts with the prefix set by the tag-prefix script parameter) at the exact commit which provided the distro setup scripts, if such a tag exists; otherwise, the empty string ("").
Example Values:
  1. "software/v2024.0.0-alpha.1" (so commit 2d6928e has Git tag software/v2024.0.0-alpha.1)
  2. "" (so commit 4d8b882 has no Git tag)
version A version string or pseudo-version string describing the exact commit which provided the distro setup scripts. If a Git tag (with a name starting with the prefix set by the tag-prefix script parameter) exists at that commit, this is a version string which just the name of that tag, but with the tag-prefix stripped from the name. Otherwise, this is a pseudo-version string with format "{tag}-{distance}-g{commit}", where:
  • {tag} is the name of the most recent ancestral tag (with a name starting with the prefix set by the tag-prefix script parameter) reachable from the commit, but with the tag-prefix stripped from the name.
  • {distance} distance (in number of commits) between the commit and the most recent ancestral tag.
  • {commit} consists of the first seven characters of the hash of the commit.

Example Values:
  1. "v2024.0.0-alpha.1" (so commit 2d6928e has Git tag software/v2024.0.0-alpha.1)
  2. "v2024.0.0-alpha.1-4-g4d8b882" (so commit 4d8b882 is 4 commits above the commit with Git tag software/v2024.0.0-alpha.1, which was the last tag in the ancestry of the commit)

Distro setup scripts🔗

Currently, the entrypoint of the distro setup scripts, at software/distro/setup/setup.sh, takes exactly one command-line argument which must be one of the following values:

  • adafruithat: this will cause the distro setup scripts to install a version of the PlanktoScope hardware controller and the PlanktoScope Node-RED dashboard specific to PlanktoScopes using the Adafruit HAT, and to set the default hardware configuration files accordingly.

  • planktoscopehat: this will cause the distro setup scripts to install a version of the PlanktoScope hardware controller and the PlanktoScope Node-RED dashboard specific to PlanktoScopes using the PlanktoScope HAT, and to set the default hardware configuration files accordingly.

Currently, the distro setup scripts must be run by a user named pi. The scripts should not be run with sudo!

Currently, the distro setup scripts are split into two phases: setup of the base operating system, and setup of the PlanktoScope application environment. In the future, as we remove various setup steps from these scripts (and instead manage those steps using forklift), we may consolidate these two phases into a single phase.

Base system setup🔗

This phase performs steps which might (in theory) be useful for other projects which don't use the PlanktoScope hardware but would still benefit from many of the functionalities provided by the PlanktoScope OS. This phase consists of the following steps:

  • Installation of base tools: Docker, Cockpit, and various command-line tools are installed.

  • Installation of forklift and a Forklift pallet: a hard-coded version of forklift is downloaded to /usr/bin/forklift , a hard-coded version of a hard-coded pallet (namely, github.com/PlanktoScope/pallet-standard) is downloaded and prepared for deployment, and the forklift-apply.service systemd service is created and enabled. (Note: in the future, it will be possible to specify the pallet to be installed as a command-line argument.)

  • Partial configuration of Raspberry Pi-specific hardware: the SPI and I2C hardware interfaces are enabled, and the serial port and serial port console are enabled (note: the serial port console will be disabled by the PlanktoScope application environment setup phase so that the serial port can be used for the PlanktoScope's GPS receiver instead), and legacy camera support is disabled.

  • Configuration of the system locale: the system's language is changed to en_US.UTF-8, but the time and measurement formats are changed to en_DK.UTF-8 so that the date format is yyyy-mm-dd and units are metric. The system timezone is set to UTC.

  • Partial configuration of networking: various system services are installed and configured, namely dhcpcd, dnsmasq, hostapd, and firewalld. The enable-interface-forwarding.service and autohotspot.service systemd services are created and enabled. The Raspberry Pi's Wi-Fi country is set to the US.

  • Cleanup: SSH keys are reset to be regenerated on the next boot, unnecessary APT files are removed, and the OS machine ID is reset to be regenerated on the next boot.

PlanktoScope application environment setup🔗

This phase performs steps specific to the PlanktoScope's hardware:

  • Remaining configuration of networking: a hard-coded version of machine-name is downloaded to /usr/bin/machine-name, avahi-utils is installed using APT, and various systemd services are created and enabled to update the PlanktoScope OS's networking configurations based on a machine name which will be determined by machine-name from the Raspberry Pi's serial number at every boot. Additional systemd services are created and enabled so that the PlanktoScope will be accessible over some additional mDNS names (namely, pkscope.local and planktoscope.local).

  • Setup of the PlanktoScope hardware controller: various Python tools (pip, venv, and poetry) are installed using APT, a hard-coded version of a hard-coded Git repository (namely github.com/PlanktoScope/device-backend) is cloned, and various dependencies (both system libraries and Python packages) of the hardware controller are installed. The planktoscope-org.device-backend.controller-adafruithat.service and planktoscope-org.device-backend.controller-planktoscopehat.service systemd services are created, and the appropriate one is enabled depending on which HAT the PlanktoScope OS is being installed for. The appropriate hardware configuration file will also be copied into the location expected by the hardware controller. (Note: once the PlanktoScope hardware controller is containerized and managed in Forklift, this step will be eliminated.)

  • Setup of GPIO stepper initialization at boot: a systemd service is created to release the stepper motors at startup. (Note: this service currently doesn't work and will eventually be deleted or replaced.)

  • Setup of the PlanktoScope Node-RED dashboard: Node-RED is installed, as well as a Python package required by the adafruithat version of the PlanktoScope Node-RED dashboard (Note: the dependency on that package will eventually be removed.). The appropriate version of the PlanktoScope Node-RED dashboard and will be copied to the location expected by Node-RED depending on which HAT the PlanktoScope OS is being installed for, along with the appropriate configuration file. Finally, npm packages required by the Node-RED dashboard are installed. (Note: once the Node-RED dashboard is containerized and managed in Forklift, this step will be eliminated.)

  • Setup of hardware support for the PlanktoScope's real-time clock module: A kernel devicetree overlay is enabled. (Note: this currently enables support for the wrong hardware real-time clock chip, so it doesn't work yet.)

  • Setup of hardware support for the PlanktoScope's GPS receiver: gpsd and chrony are installed and configured. (Note: currently the configurations may be incorrect.)

  • Configuration of CPU overclocking: the CPU is overclocked so that the PlanktoScope segmenter will run more quickly. (Note: in the future, this will be removed.)

  • Cleanup: unnecessary APT and pip files are removed.

Startup🔗

This reference document is a companion to our explanation about the PlanktoScope software as an operating system, particularly its discussion of the operating system's boot sequence and its explanation of the various system services provided with the operating system. Specifically, this document lists information about what happens when the PlanktoScope is powered on.

Services🔗

The PlanktoScope OS's daemons and system services (beyond what is already provided by the default installation of the Raspberry Pi OS) are defined with the following boot sequencing relationships:

Software deployment & execution🔗

In general:

  • dockerd (managed by docker.service) can start before network connectivity has been established; this is not the default behavior for dockerd.

  • All daemons & background processes not described in the rest of this page are sequenced by systemd according to the systemd unit dependency relationships specified by the default systemd service files installed with the APT packages which provide those programs.

The PlanktoScope OS's setup scripts provide some system services which are not managed by Forklift, because they are used to integrate Forklift into the OS in order to bootstrap the system services and config files provided by Forklift:

  • overlay-sysroot.service runs after -.mount and systemd-remount-fs.service.

  • bindro-run-forklift-stages-current.service runs after -mount and systemd-remount-fs.service and before overlay-fs.target.

  • overlay-usr.service runs after overlay-sysroot.service and before overlay-fs.target.

  • overlay-etc.service runs after overlay-sysroot.service and systemd-machine-id-commit.service , and before systemd-sysctl.service and overlay-fs.target.

  • start-overlaid-units.service runs after overlay-fs.target and basic.target.

  • bind-.local-share-forklift-stages@home-pi.service runs after -.mount, home.mount, and basic.target.

  • forklift-apply.service, which uses the forklift tool to start all Docker Compose applications, runs after docker.service has started. Docker Compose applications managed with forklift are sequenced by forklift-apply.service according to the resource dependency relationships declared by the Forklift packages which provide those applications.

Networking🔗

For descriptions of the various targets (e.g. sysinit.target, network-pre.target) referred to below, see systemd's bootup process and systemd's special targets:

  • generate-machine-name.service and generate-hostname-templated.service runs before sysinit.target.

  • update-hostname.service runs after generate-hostname-templated.service and systemd-hostnamed.service but before network-pre.target.

  • assemble-dnsmasq-config-templated.service runs after generate-machine-name.service and generate-hostname-templated.service but before dnsmasq.service.

  • assemble-hosts-templated.service and assemble-hosts.service run after generate-machine-name.service and generate-hostname-templated.service but before dnsmasq.service and network-pre.target.

  • enable-interface-forwarding.service runs before network-online.target.

  • assemble-hostapd-config-templated.service and assemble-hostapd-config.service run after generate-machine-name.service and generate-hostname-templated.service but before hostapd.service.

  • The hostapd daemon is manually started and stopped by autohotspot.service.

  • autohotspot.service runs after forklift-apply.service and enable-interface-forwarding.service have started (so that the PlanktoScope's web browser-based user interfaces are ready for connections before the PlanktoScope's Wi-Fi hotspot is started) and before network connectivity is considered to have been established. It is re-run every one or two minutes by autohotspot.timer.

  • planktoscope-mdns-alias@pkscope.service and planktoscopemdns-alias@planktoscope.service configure the Avahi daemon (provided by the Raspberry Pi OS) to also resolve mDNS names pkscope.local and planktoscope.local, respectively, to an IP address (192.168.4.1) which is usable by devices connected to the PlanktoScope by a direct connection between their respective network interfaces.

User interface🔗

  • assemble-cockpit-config.service, assemble-cockpit-origins.service, and assemble-cockpit-origins-templated.service update Cockpit's configuration file from drop-in config file fragments in /etc/cockpit/cockpit.conf.d, /etc/cockpit/origins.d, and /etc/cockpit/origins-templates.d, respectively. They run after generate-machine-name.service and generate-hostname-templated.service and before cockpit.service.

  • ensure-ssh-host-keys.service regenerates the SSH server's host keys if the keys are missing, and runs before ssh.service.

  • The PlanktoScope Node-RED dashboard (managed by nodered.service) starts after planktoscope-org.update-machine-name.service has started, to ensure that the Node-RED dashboard has the correct machine name. (In the future the PlanktoScope Node-RED dashboard will instead be run as a Docker container and will be managed by forklift.)

PlanktoScope-specific hardware abstraction🔗

  • The PlanktoScope hardware controller (managed by planktoscope-org.device-backend.controller-{adafruithat or planktoscopehat}.service) starts after forklift-apply.service (which manages Mosquitto) and nodered.service have started, to ensure that the PlanktoScope hardware controller broadcasts the detected camera model name only after the PlanktoScope Node-RED dashboard is ready to receive that broadcast. (In the future the PlanktoScope hardware controller will instead be run as a Docker container and will be managed by forklift.)

Startup🔗

This reference document is a companion to our explanation about the PlanktoScope software as an operating system, particularly its discussion of the operating system's boot sequence and its explanation of the various system services provided with the operating system. Specifically, this document lists information about what happens when the PlanktoScope is powered on.

Services🔗

The PlanktoScope OS's daemons and system services (beyond what is already provided by the default installation of the Raspberry Pi OS) are defined with the following boot sequencing relationships:

Software deployment & execution🔗

In general:

  • dockerd (managed by docker.service) can start before network connectivity has been established; this is not the default behavior for dockerd.

  • All daemons & background processes not described in the rest of this page are sequenced by systemd according to the systemd unit dependency relationships specified by the default systemd service files installed with the APT packages which provide those programs.

The PlanktoScope OS's setup scripts provide some system services which are not managed by Forklift, because they are used to integrate Forklift into the OS in order to bootstrap the system services and config files provided by Forklift:

  • overlay-sysroot.service runs after -.mount and systemd-remount-fs.service.

  • bindro-run-forklift-stages-current.service runs after -mount and systemd-remount-fs.service and before overlay-fs.target.

  • overlay-usr.service runs after overlay-sysroot.service and before overlay-fs.target.

  • overlay-etc.service runs after overlay-sysroot.service and systemd-machine-id-commit.service , and before systemd-sysctl.service and overlay-fs.target.

  • start-overlaid-units.service runs after overlay-fs.target and basic.target.

  • bind-.local-share-forklift-stages@home-pi.service runs after -.mount, home.mount, and basic.target.

  • forklift-apply.service, which uses the forklift tool to start all Docker Compose applications, runs after docker.service has started. Docker Compose applications managed with forklift are sequenced by forklift-apply.service according to the resource dependency relationships declared by the Forklift packages which provide those applications.

Networking🔗

For descriptions of the various targets (e.g. sysinit.target, network-pre.target) referred to below, see systemd's bootup process and systemd's special targets:

  • generate-machine-name.service and generate-hostname-templated.service runs before sysinit.target.

  • update-hostname.service runs after generate-hostname-templated.service and systemd-hostnamed.service but before network-pre.target.

  • assemble-dnsmasq-config-templated.service runs after generate-machine-name.service and generate-hostname-templated.service but before dnsmasq.service.

  • assemble-hosts-templated.service and assemble-hosts.service run after generate-machine-name.service and generate-hostname-templated.service but before dnsmasq.service and network-pre.target.

  • enable-interface-forwarding.service runs before network-online.target.

  • assemble-hostapd-config-templated.service and assemble-hostapd-config.service run after generate-machine-name.service and generate-hostname-templated.service but before hostapd.service.

  • The hostapd daemon is manually started and stopped by autohotspot.service.

  • autohotspot.service runs after forklift-apply.service and enable-interface-forwarding.service have started (so that the PlanktoScope's web browser-based user interfaces are ready for connections before the PlanktoScope's Wi-Fi hotspot is started) and before network connectivity is considered to have been established. It is re-run every one or two minutes by autohotspot.timer.

  • planktoscope-mdns-alias@pkscope.service and planktoscopemdns-alias@planktoscope.service configure the Avahi daemon (provided by the Raspberry Pi OS) to also resolve mDNS names pkscope.local and planktoscope.local, respectively, to an IP address (192.168.4.1) which is usable by devices connected to the PlanktoScope by a direct connection between their respective network interfaces.

User interface🔗

  • assemble-cockpit-config.service, assemble-cockpit-origins.service, and assemble-cockpit-origins-templated.service update Cockpit's configuration file from drop-in config file fragments in /etc/cockpit/cockpit.conf.d, /etc/cockpit/origins.d, and /etc/cockpit/origins-templates.d, respectively. They run after generate-machine-name.service and generate-hostname-templated.service and before cockpit.service.

  • ensure-ssh-host-keys.service regenerates the SSH server's host keys if the keys are missing, and runs before ssh.service.

  • The PlanktoScope Node-RED dashboard (managed by nodered.service) starts after planktoscope-org.update-machine-name.service has started, to ensure that the Node-RED dashboard has the correct machine name. (In the future the PlanktoScope Node-RED dashboard will instead be run as a Docker container and will be managed by forklift.)

PlanktoScope-specific hardware abstraction🔗

  • The PlanktoScope hardware controller (managed by planktoscope-org.device-backend.controller-{adafruithat or planktoscopehat}.service) starts after forklift-apply.service (which manages Mosquitto) and nodered.service have started, to ensure that the PlanktoScope hardware controller broadcasts the detected camera model name only after the PlanktoScope Node-RED dashboard is ready to receive that broadcast. (In the future the PlanktoScope hardware controller will instead be run as a Docker container and will be managed by forklift.)

PlanktoScope Hardware🔗

You are viewing a copy of the PlanktoScope project documentation without the hardware setup guides, probably because you're viewing an offline, reduced-size copy of the PlanktoScope documentation served by your PlanktoScope. You should go to an online copy of the PlanktoScope documentation to find the hardware setup guides.

PlanktoScope Hardware🔗

You are viewing a copy of the PlanktoScope project documentation without the hardware setup guides, probably because you're viewing an offline, reduced-size copy of the PlanktoScope documentation served by your PlanktoScope. You should go to an online copy of the PlanktoScope documentation to find the hardware setup guides.

PlanktoScope Hardware🔗

This section of the PlanktoScope documentation will help you to build the hardware of a PlanktoScope. Our documentation splits this PlanktoScope production process into two phases: making a kit of parts, and assembling a PlanktoScope from that kit of parts.

If you do not already have a kit of parts, you will need to either purchase a kit or make a kit yourself. You will need to choose a PlanktoScope hardware version and obtain the hardware components necessary for that hardware version; your assembly kit will consist of those components. You can purchase a kit from FairScope, a small business started by the inventor of the PlanktoScope in order to make it easier for people to obtain PlanktoScopes. Once you have selected a hardware version, you can proceed to our instructions for making your kit.

If you do already have a kit of parts, you can proceed to our instructions for assembling your kit into a PlanktoScope. However, you will first need to determine the PlanktoScope hardware version which your kit is made for, so that you can choose the correct assembly guide for your kit.

Hardware versions🔗

The design of the PlanktoScope's hardware has been evolving to fix usability issues and improve the quality of images captured by the PlanktoScope. Thus, multiple versions of the hardware have been developed. This page only describes hardware versions for which documentation has been published for anyone to manufacture the hardware, and here we only describe aspects of each hardware version relevant to choosing a version to manufacture. Due to a lack of time by the people developing the PlanktoScope hardware, documentation for other versions of the PlanktoScope hardware has not yet been created; for information on these other versions of the PlanktoScope hardware, please refer to the technical reference section of our documentation site.

Hardware v2.1🔗

This was the first publicly released version of the PlanktoScope hardware. The electronic components of this design are all available from commercial off-the-shelf sources, using an Adafruit Stepper Motor HAT to control various actuators and a Yahboom RGB Cooling HAT to cool the PlanktoScope's embedded Raspberry Pi 4 computer. The mechanical structure was designed for fabrication using a laser cutter. This hardware version has some design flaws, such as providing no way to replace the Raspberry Pi's micro-SD card without partially disassembling the PlanktoScope; these problems have been fixed in later versions of the PlanktoScope hardware.

This version of the PlanktoScope hardware is the only version which has been widely replicated by independent makers so far. Currently, its manufacturing documentation is provided by an older documentation site which is no longer maintained, and it has not yet been migrated into our current documentation site. Additionally, this hardware design uses a peristaltic pump which is no longer commercially available, so anyone making an assembly kit for this version will have to identify a different pump to use as a substitute.

Hardware v2.5🔗

This was the first version of the PlanktoScope hardware made commercially available by FairScope. It has made various design changes to solve various problems with the v2.1 hardware design, including:

  • Replacing the Adafruit Stepper Motor HAT with a custom-designed HAT.

  • Replacing the ibidi flowcell with a simpler glass capillary flowcell.

  • Replacing the linear actuators for sample focusing with a more mechanically robust pair of linear actuators.

  • Replacing the peristaltic pump with a more accurate pump which is commercially available.

The mechanical structure of this design uses CNC-milled parts rather than laser-cut parts.

Our documentation site provides manufacturing documentation to make assembly kits for this hardware version, and to assemble kits for this version into PlanktoScopes.

Choosing a version🔗

We recommend building a PlanktoScope of the latest available hardware version (currently v2.5). However, if you are making your own assembly kit and the following limitations apply to you, you may need to choose an older hardware version such as v2.1:

  • You do not have access to a CNC mill, or to a commercial fabrication service with a CNC mill.

  • You do not have access to manufacturing capabilities for assembling a custom printed circuit board, and you cannot buy a pre-assembled HAT from FairScope.

Building a PlanktoScope🔗

If you received a PlanktoScope hardware assembly kit from someone but you are not sure what hardware version the kit is for, you should check with the person who gave the kit to you.

Once you have figured out what hardware version of the PlanktoScope you will build, you can proceed to our version-specific hardware setup guides:

  • If you are building a PlanktoScope with the v2.5 hardware, please proceed to our page for Hardware v2.5 to find instructions for making an assembly kit, as well as instructions for building a PlanktoScope from an assembly kit for v2.5 of the hardware.

  • If you are building a PlanktoScope with the v2.1 hardware, please proceed to our page for Hardware v2.1 to find instructions for making an assembly kit, as well as instructions for building a PlanktoScope from an assembly kit for v2.1 of the hardware.

Next steps🔗

After making an assembly kit (if necessary) and building a PlanktoScope from your assembly kit, you should proceed to our software setup guide.

PlanktoScope Hardware🔗

This section of the PlanktoScope documentation will help you to build the hardware of a PlanktoScope. Our documentation splits this PlanktoScope production process into two phases: making a kit of parts, and assembling a PlanktoScope from that kit of parts.

If you do not already have a kit of parts, you will need to either purchase a kit or make a kit yourself. You will need to choose a PlanktoScope hardware version and obtain the hardware components necessary for that hardware version; your assembly kit will consist of those components. You can purchase a kit from FairScope, a small business started by the inventor of the PlanktoScope in order to make it easier for people to obtain PlanktoScopes. Once you have selected a hardware version, you can proceed to our instructions for making your kit.

If you do already have a kit of parts, you can proceed to our instructions for assembling your kit into a PlanktoScope. However, you will first need to determine the PlanktoScope hardware version which your kit is made for, so that you can choose the correct assembly guide for your kit.

Hardware versions🔗

The design of the PlanktoScope's hardware has been evolving to fix usability issues and improve the quality of images captured by the PlanktoScope. Thus, multiple versions of the hardware have been developed. This page only describes hardware versions for which documentation has been published for anyone to manufacture the hardware, and here we only describe aspects of each hardware version relevant to choosing a version to manufacture. Due to a lack of time by the people developing the PlanktoScope hardware, documentation for other versions of the PlanktoScope hardware has not yet been created; for information on these other versions of the PlanktoScope hardware, please refer to the technical reference section of our documentation site.

Hardware v2.1🔗

This was the first publicly released version of the PlanktoScope hardware. The electronic components of this design are all available from commercial off-the-shelf sources, using an Adafruit Stepper Motor HAT to control various actuators and a Yahboom RGB Cooling HAT to cool the PlanktoScope's embedded Raspberry Pi 4 computer. The mechanical structure was designed for fabrication using a laser cutter. This hardware version has some design flaws, such as providing no way to replace the Raspberry Pi's micro-SD card without partially disassembling the PlanktoScope; these problems have been fixed in later versions of the PlanktoScope hardware.

This version of the PlanktoScope hardware is the only version which has been widely replicated by independent makers so far. Currently, its manufacturing documentation is provided by an older documentation site which is no longer maintained, and it has not yet been migrated into our current documentation site. Additionally, this hardware design uses a peristaltic pump which is no longer commercially available, so anyone making an assembly kit for this version will have to identify a different pump to use as a substitute.

Hardware v2.5🔗

This was the first version of the PlanktoScope hardware made commercially available by FairScope. It has made various design changes to solve various problems with the v2.1 hardware design, including:

  • Replacing the Adafruit Stepper Motor HAT with a custom-designed HAT.

  • Replacing the ibidi flowcell with a simpler glass capillary flowcell.

  • Replacing the linear actuators for sample focusing with a more mechanically robust pair of linear actuators.

  • Replacing the peristaltic pump with a more accurate pump which is commercially available.

The mechanical structure of this design uses CNC-milled parts rather than laser-cut parts.

Our documentation site provides manufacturing documentation to make assembly kits for this hardware version, and to assemble kits for this version into PlanktoScopes.

Choosing a version🔗

We recommend building a PlanktoScope of the latest available hardware version (currently v2.5). However, if you are making your own assembly kit and the following limitations apply to you, you may need to choose an older hardware version such as v2.1:

  • You do not have access to a CNC mill, or to a commercial fabrication service with a CNC mill.

  • You do not have access to manufacturing capabilities for assembling a custom printed circuit board, and you cannot buy a pre-assembled HAT from FairScope.

Building a PlanktoScope🔗

If you received a PlanktoScope hardware assembly kit from someone but you are not sure what hardware version the kit is for, you should check with the person who gave the kit to you.

Once you have figured out what hardware version of the PlanktoScope you will build, you can proceed to our version-specific hardware setup guides:

  • If you are building a PlanktoScope with the v2.5 hardware, please proceed to our page for Hardware v2.5 to find instructions for making an assembly kit, as well as instructions for building a PlanktoScope from an assembly kit for v2.5 of the hardware.

  • If you are building a PlanktoScope with the v2.1 hardware, please proceed to our page for Hardware v2.1 to find instructions for making an assembly kit, as well as instructions for building a PlanktoScope from an assembly kit for v2.1 of the hardware.

Next steps🔗

After making an assembly kit (if necessary) and building a PlanktoScope from your assembly kit, you should proceed to our software setup guide.

Hardware v2.1🔗

This page will help you to build the v2.1 hardware for a PlanktoScope.

Make an assembly kit🔗

Currently, you can find the instructions for making an assembly kit at the PlanktoScope website.

You should be aware that some of the parts required for the kit, especially the peristaltic pump, are no longer commercially available; you will have to identify alternatives to substitute for those parts.

Assemble a PlanktoScope from a kit🔗

Currently, you can find step-by-step instructions for assembling a PlanktoScope from a kit at the old documentation site for PlanktoScope.

Next steps🔗

After assembling your PlanktoScope hardware, you will need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi. Then you can proceed to our operation guide to learn how to operate your PlanktoScope.

Hardware v2.1🔗

This page will help you to build the v2.1 hardware for a PlanktoScope.

Make an assembly kit🔗

Currently, you can find the instructions for making an assembly kit at the PlanktoScope website.

You should be aware that some of the parts required for the kit, especially the peristaltic pump, are no longer commercially available; you will have to identify alternatives to substitute for those parts.

Assemble a PlanktoScope from a kit🔗

Currently, you can find step-by-step instructions for assembling a PlanktoScope from a kit at the old documentation site for PlanktoScope.

Next steps🔗

After assembling your PlanktoScope hardware, you will need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi. Then you can proceed to our operation guide to learn how to operate your PlanktoScope.

Assembly🔗

planktoscope-assembly-workshop.jpg

Content of the Kit🔗

It is important to ensure that you have all of the necessary components before beginning the assembly of your PlanktoScope. To do so, please check that all bags are present as part of the kit.

planktoscope-assembly-002.jpg

Bag Content
A Scews
B Tools
C Adhesive Pads
D Tubing, Glass Cuvettes
E Bubbler Pump
F Peristaltic Pump
G Linear Stepper Motor
H Raspberry PI Chip cooler
I Raspberry HAT
J Camera Lens
K MicroSD Card, DC Power Jack Socket
L DC Power Supply and Cable
M Syringe and Falcon Tube
X1 Raspberry PI 4
X2 Pipet
X3 Cable ties
X4 Raspberry PI HQ Camera Modul
X5 Sandpaper

If any bags are missing, please go back to the BOM (Bill of Materials) and reorder the required components.

About this document🔗

To read this document, follow these guidelines:

Color codes🔗

  • 🔴 Look to the color red
  • 🟠 Look to the color orange
  • 🟡 Look to the color yellow
  • 🟢 Look to the color green
  • 🔵 Look to the color blue
  • 🟣 Look to the color purple

Icons🔗

  • 👁 Pay attention to this
  • ⚠ Be careful with this
  • 📜 The book says
  • 🎬 Action !
  • ❌ Don't focus on that location

As you read through the document, be sure to pay attention to these visual cues to guide you through the build process.

Requirements🔗

Tools🔗

planktoscope-assembly-254.jpg

Content of Bag B:

  • 🔴 B1. Small flat screwdriver 2mm
  • 🟠 B2. Razor blade
  • 🟡 B3. Allen key 2mm
  • 🟢 B4. Wrenches for standoffs

Components🔗

planktoscope-assembly-253.jpg

Content of Bag A:

  • 🟢 A1. Standoff M2.5 - 6mm - Brass
  • 🔵 A2. Standoff M2.5 - 15mm -  Brass
  • 🟣 A3. Standoff M2.5 - 16mm - SS
  • 🟠 A4. Screw M2.5x5mm CHC - SS
  • 🟡 A5. Screw M2.5x10mm CHC - SS
  • 🔴 A6. Screw M3x12mm BHC - SS

Chapter 1: Detach the Parts from panels by cutting the tabs🔗

planktoscope-assembly-004.jpg 👁 Locate the panel S1 and discover the 5 differents Parts F, P, K, J and I.

planktoscope-assembly-005.jpg 🎬 Flip your panel S1.

planktoscope-assembly-006.jpg 🔴 Locate the outer tabs on the edges of the different Parts. These are typically small projections of material that are used to secure the case parts to the panels.

planktoscope-assembly-007.jpg Gather all the necessary tools. You will need the B2 🟠 Razor blade to cut the tabs.

planktoscope-assembly-008.jpg

  • 🟣 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.

planktoscope-assembly-009.jpg

  • 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 all of the tabs are cut, gently lift the case parts away from the panels. If the case parts are stuck or difficult to remove, you may need to gently wiggle or pry them loose using a flat tool such as a screwdriver.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-011.jpg

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.

planktoscope-assembly-012.jpg

🟣 Place your razor blade flat on the edge of your piece being very careful with your fingers and cut the residual tab.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-013.jpg

Repeat the cutting of the tabs on all the Parts F, P, K, J and I present on the panel S1.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-014.jpg

🔴 Locate the inner tabs on the edges of the different Parts.

planktoscope-assembly-015.jpg

Cut out the tabs inside of all the Parts F, P, K, J and I detached from the panel S1.

Dispose of the cut tabs and any other debris that may have been created during the detachment process.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-016.jpg

  • ✅ Good way of cutting inner tabs
  • ❌ Wrong way of cutting inner tabs

planktoscope-assembly-018.jpg

Repeat the process on the panel S2.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-019.jpg

Discover the 11 differents Parts.

planktoscope-assembly-020.jpg

Dispose of the cut tabs and any other debris that may have been created during the detachment process. Inspect the case parts and panels for any damage or imperfections that may have occurred during the detachment process. If any damage is found, it may be necessary to repair or replace the affected parts.

Chapter 2: Place the 4 Adhesive Pads under the Part I🔗

planktoscope-assembly-023.jpg To secure the PlanktoScope on slippery grounds using the adhesive pads, follow these steps. Gather all the necessary materials. You will need:

  • Time: 1 min
  • 👁 and 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.

planktoscope-assembly-024.jpg

  • Clean the bottom of the case part I. Make sure the surface is free of dirt, debris, and any other substances that may prevent the adhesive pads from sticking properly.
  • Remove the paper and place the four adhesive pads in the pockets by pressing firmly on them, sticky-side down.
  • Test the stability of the PlanktoScope by gently shaking or tilting it. If it feels secure and does not slip or slide, the adhesive pads have been successfully installed.

Note

🎬 Store this assembly for later.

Chapter 3: Screw the four Standoffs into Part A🔗

planktoscope-assembly-026.jpg

Now it's time to assemble the ground plate for the Raspberry Pi as the PlanktoScope main processing unit.

  • Time: 5 min

planktoscope-assembly-027.jpg

  • 👁 Grab the Part A.
  • 🟣 Locate the four holes on Part A.

planktoscope-assembly-028.jpg

🟢 A1. Standoff M2.5 - 6mm- Brass

planktoscope-assembly-029.jpg

🟢 B4. Wrenches for standoffs

planktoscope-assembly-030.jpg

  • 🟣 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.

planktoscope-assembly-031.jpg

  • Place the standoff in the hole and start rotating by hand in a clockwise direction until secure.
  • Then tighten with the wrench.

planktoscope-assembly-032.jpg

  • ✅ Make sure to screw until the standoff is properly inserted in the hole.
  • ❌ Do not stop screwing before.

planktoscope-assembly-033.jpg

Keep going for each of the four holes.

Chapter 4: Mount the Heat Sinks on the Raspberry Pi🔗

planktoscope-assembly-035.jpg

  • Time: 2 min

Locate the Raspberry Pi 4 Model B packaging.

Warning

Be careful removing it from its packaging.

planktoscope-assembly-036.jpg

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

planktoscope-assembly-037.jpg

Remove the protective labels under a Heat Sink and place the Heat Sink on the slot of the Raspberry Pi.

planktoscope-assembly-038.jpg

Remove the protective labels under all the Heat Sinks and place all the Heat Sinks on the slots of the Raspberry Pi.

Chapter 5: Insert the micro SD card in the Raspberry Pi🔗

planktoscope-assembly-040.jpg

  • 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.

planktoscope-assembly-041.jpg

  • Flip your Raspberry Pi.
  • 🟠 Locate the micro SD port.
  • 🟣 Insert the micro SD card in the Raspberry Pi.

planktoscope-assembly-042.jpg

Push the micro SD card in the Raspberry Pi port to a point of resistance.

Note

If you notice that the micro SD card protrudes about 2mm from its slot, this is normal.

Chapter 6: Mount the Raspberry Pi on the Part A🔗

  • Time: 1 min

planktoscope-assembly-044.jpg

  • ✅ 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.

planktoscope-assembly-045.jpg

🟣 A3. Standoff M2.5 - 16mm - SS

planktoscope-assembly-046.jpg

Screw by hand a Standoff M2.5 - 16mm on the Raspberry Pi.

planktoscope-assembly-047.jpg

  • Screw by hand all Standoffs M2.5 - 16mm on the Raspberry Pi.
  • Make sure you insert all four standoffs by hand and tighten slightly.

planktoscope-assembly-048.jpg

🟢 B4. Wrenches for standoffs

planktoscope-assembly-049.jpg

  • 🟠 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.

Chapter 7: Attach the Ribbon Cable to the Raspberry Pi🔗

  • Time: 2 min

planktoscope-assembly-051.jpg

Locate the Raspberry Pi Camera HQ packaging.

Warning

Be careful removing it from its packaging.

planktoscope-assembly-052.jpg

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

planktoscope-assembly-053.jpg

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.

planktoscope-assembly-054.jpg

🔴 Locate the black connector present on the Raspberry Pi.

planktoscope-assembly-055.jpg

🔴 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.

planktoscope-assembly-056.jpg

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.

planktoscope-assembly-057.jpg

🔴 Secure the Ribbon Cable in the Raspberry Pi by pressing firmly on the black connector.

Chapter 8: Mount the PlanktoScope HAT on the Raspberry Pi🔗

planktoscope-assembly-059.jpg

  • Time: 2 min

Locate the PlanktoScope HAT present in bag I.

planktoscope-assembly-060.jpg

🔴 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.

planktoscope-assembly-061.jpg

🔴 Plug the PlanktoScope HAT into the Raspberry Pi.

Warning

Make sure the two black connectors are aligned before attaching them together.

planktoscope-assembly-062.jpg

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.

planktoscope-assembly-063.jpg

🟠 A4. Screw M2.5X5mm CHC - SS

planktoscope-assembly-064.jpg

🟣 Locate the 4 holes on the top of the PlanktoScope HAT and insert the four M2.5X5mm

planktoscope-assembly-065.jpg

🟡 B3. Allen key 2mm

planktoscope-assembly-066.jpg

Screw the four A4 screws through the PlanktoScope HAT onto the Standoff M2.5 - 16mm.

Note

🎬 Store this assembly for later.

Chapter 9: Place the Power Socket on Part M🔗

planktoscope-assembly-068.jpg

  • Time: 2 min
  • Locate the DC Power Jack from the Bag K.
  • Remove the Lock Ring from the DC Power Jack

planktoscope-assembly-069.jpg

planktoscope-assembly-070.jpg

  • 🔴 Lay the Part M down and make sure the pockets in these holes are facing upwards.
  • 🟣 Locate the Power Socket hole on Part M.

planktoscope-assembly-071.jpg

🔴 Insert the cable inside of the hole by being sure of the orientation of the Part M.

planktoscope-assembly-072.jpg

🟣 Flip the Part M and secure the DC Power Jack by hand on the Part M by screwing the Lock Ring.

Warning

Make sure the Lock Ring doesn’t spin on itself.

Note

🎬 Store this assembly for later.

Chapter 10: Mount the Raspberry Pi Camera HQ on Part B🔗

planktoscope-assembly-074.jpg

  • Time: 2 min

planktoscope-assembly-075.jpg

🟣 Locate the 4 holes on the top of the Part B.

planktoscope-assembly-076.jpg

🔵 A2. Standoff M2.5 - 15mm - Brass

planktoscope-assembly-077.jpg

Insert the four Standoff M2.5 - 15mm.

planktoscope-assembly-078.jpg

The result should be similar to the picture.

planktoscope-assembly-079.jpg

🟢 B4. Wrenches for standoffs

planktoscope-assembly-080.jpg

Using the small side of the Standoff Wrench, secure the 4 M2.5 - 15mm Standoffs

planktoscope-assembly-081.jpg

  • ✅ Make sure to screw until the Standoff is properly tightened into the hole.
  • ❌ Do not stop screwing before.

planktoscope-assembly-082.jpg

Locate the Raspberry Pi Camera HQ

planktoscope-assembly-083.jpg

Remove the lens cap Raspberry Pi Camera HQ.

planktoscope-assembly-084.jpg

Warning

Make sure your camera lens is clean. If it is not, gently wipe using cotton swab for this task.

planktoscope-assembly-085.jpg

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

planktoscope-assembly-086.jpg

🟠 A4. Screw M2.5X5mm CHC - SS

planktoscope-assembly-087.jpg

🟡 B3. Allen key 2mm

planktoscope-assembly-088.jpg

Use the allen key and tighten the Raspberry Pi Camera to the Standoffs.

planktoscope-assembly-089.jpg

The result should be similar to the picture.

Note

🎬 Store this assembly for later.

Chapter 11: Mount the Linear Stepper Motor on Part E🔗

planktoscope-assembly-091.jpg

Locate the Stepper Motors

Warning

Avoid touching the metal rods on the Stepper Motors

Info

You can touch the 🟣 gold stands

planktoscope-assembly-092.jpg

planktoscope-assembly-093.jpg

🟡 A5. Screw M2.5X10mm CHC - SS

planktoscope-assembly-094.jpg

🟡 B3. Allen key 2mm

planktoscope-assembly-095.jpg

  • 🔴 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.

planktoscope-assembly-096.jpg

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.

planktoscope-assembly-097.jpg

Use the 2mm allen key to fix the Stepper Motors.

The result should be similar to that picture.

planktoscope-assembly-098.jpg

The result should be similar to the picture.

planktoscope-assembly-099.jpg

Repeat the process on the other side with the other Stepper Motor.

planktoscope-assembly-100.jpg

Repeat the process on the other side with the other Stepper Motor.

planktoscope-assembly-101.jpg

The result should be similar to the picture.

Note

🎬 Store this assembly for later.

Chapter 12: Mount the LED on Part G🔗

planktoscope-assembly-103.jpg

  • Locate the LED and LED cable in Bag K.
  • 🟣 The LED will go on the end where the white plastic connector is smallest.

planktoscope-assembly-104.jpg

Insert the LED into the LED cable.

planktoscope-assembly-105.jpg

The result should be similar to the picture.

planktoscope-assembly-106.jpg

planktoscope-assembly-107.jpg

Locate part G.

planktoscope-assembly-108.jpg

🟣 Locate the LED hole on Part G.

planktoscope-assembly-109.jpg

We will now place the LED into the slot on part G.

planktoscope-assembly-110.jpg

Warning

Gently push the LED into the LED hole located on Part G. It should be a snug fit.

planktoscope-assembly-111.jpg

The result should be similar to the picture.

Info

🎬 Store this assembly for later.

Chapter 13: Mount the Peristaltic Pump on Part O and Part L🔗

planktoscope-assembly-113.jpg

  • Locate the Kamoer Peristaltic pump from the Bag F.
  • 🟣 Put aside the tubing contained in the little bag.

planktoscope-assembly-114.jpg

planktoscope-assembly-115.jpg

🟢 Insert the cable of the Peristaltic Pump into the hole on Part O and then insert the motor block assembly of the pump into it.

Warning

👁 Ensure the correct orientation of Part O and the Peristaltic Pump

planktoscope-assembly-116.jpg

🟡 A5. Screw M2.5X10mm CHC - SS

planktoscope-assembly-117.jpg

🟡 B3. Allen key 2mm B3

planktoscope-assembly-118.jpg

🟢 Insert the two M2.5X10mm in the two holes.

planktoscope-assembly-119.jpg

Screw the two M2.5X10mm into the two holes.

planktoscope-assembly-120.jpg

planktoscope-assembly-121.jpg

🔴 Lay the Part L down and make sure the pockets in these holes are facing upwards.

planktoscope-assembly-122.jpg

  • Place the Peristaltic Pump underneath part L, ensuring the correct orientation of these two parts.
  • 🔴 Insert the Peristaltic Pump into the allocated slot in Part L.

planktoscope-assembly-123.jpg

Insert the Peristaltic Pump into the allocated slot in Part L.

planktoscope-assembly-124.jpg

Insert the Peristaltic Pump into the allocated slot in Part L.

planktoscope-assembly-125.jpg

  • Lay the assembly down.
  • 🔴 Locate the four different holes.

planktoscope-assembly-126.jpg

🟡 A5.Screw M2.5X10mm CHC - SS

planktoscope-assembly-127.jpg

🟡 B3.Allen key 2mm

planktoscope-assembly-128.jpg

Screw the four M2.5X10mm in the located holes attaching the Part O to the Part L Peristaltic Pump.

planktoscope-assembly-129.jpg The result should be similar to the picture.

Info

We will use this part in the next step.

Chapter 14: Spiral wrap the LED and Peristaltic Pump cabling🔗

planktoscope-assembly-131.jpg

  • Locate the LED and housing, along with the pump and housing.
  • 🟣 Locate the spiral wrap from bag K.

planktoscope-assembly-132.jpg

  • Spiral wrap both sets of cables together.
  • There should be 4 cm (1.5 inches) between the connectors and the start of the spiral wrap.

planktoscope-assembly-133.jpg

Continue wrapping around the cables until you have used all of the spiral wrap, leaving small or no gaps.

Info

The result should look the same as the picture.

planktoscope-assembly-134.jpg

Info

The result should look the same as the picture.

Note

🎬 Store this assembly for later.

Chapter 15: Attaching the Stepper Motors to the Raspberry Pi Camera🔗

planktoscope-assembly-136.jpg

Locate the Stepper Motors with mount, and the Raspberry Pi Camera.

planktoscope-assembly-137.jpg Feed the Stepper Motor cables into the slots either side of the Raspberry Pi Camera.

Warning

Make sure the orientation is correct and matches the picture.

planktoscope-assembly-138.jpg Feed the Stepper Motor cables into the slots either side of the Raspberry Pi Camera.

Warning

Make sure the orientation is correct and matches the picture.

Then insert the cylindrical parts of the Stepper Motor into the slots.

planktoscope-assembly-139.jpg

Feed the Stepper Motor cables into the slots either side of the Raspberry Pi Camera.

Warning

Make sure the orientation is correct and matches the picture.

Then insert the cylindrical parts of the Stepper Motor into the slots.

Note

The result should be the same as the picture.

Chapter 16: Connecting the Raspberry Pi Camera to the Raspberry Pi HAT🔗

planktoscope-assembly-141.jpg

  • We will need the Raspberry Pi HAT with housing and Ribbon Cable along \ with the Raspberry Pi Camera with Stepper Motors and housing.
  • We will be connecting the 🟢Ribbon Cableto the 🟡black Raspberry Pi Camera connector that we removed it from earlier.

planktoscope-assembly-142.jpg

Gently feed the Ribbon Cable into the port of the Camera.

Warning

👁 Ensure the correct orientation of the Ribbon Cable with the blue end facing upwards.

planktoscope-assembly-143.jpg 🔴 Press down on the black connector on the Raspberry Pi camera board once the Ribbon Cable is in position.

planktoscope-assembly-144.jpg 🔴 B1.Small flat screwdriver 2mm

planktoscope-assembly-145.jpg

  • Now we will plug in the Stepper Mounts to the HAT.
  • 🔴The cables for the Stepper Mounts will be plugged into the HAT 🟣here.

Warning

Hold tight, a specific order is required.

planktoscope-assembly-146.jpg

Starting with the red cable, insert the cable in the far left port and tighten the screw situated above the port.

Note

The result should look the same as the picture.

planktoscope-assembly-147.jpg

Repeat this process with the order pictured here from left to right: 🔴 Red 🟡 Yellow 🔵 Blue ⚫ Black.

Chapter 17: Connect the LED and Peristaltic Pump to the Raspberry Pi🔗

planktoscope-assembly-149.jpg

We will now be connecting the LED and Peristaltic Pump with the Raspberry Pi HAT and Camera.

planktoscope-assembly-150.jpg

Place the LED housing onto the Stepper Mounts.

Warning

👁 Ensure correct orientation of both 🟣 parts by looking at the precut holes.

planktoscope-assembly-151.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-152.jpg

Now we will plug in the LED and Stepper Mount cables to the Raspberry Pi.

planktoscope-assembly-153.jpg

Feed the area of cabling that is not covered by the spiral wrap through the two holes to start. Then thread through to the spiral wrap so that it matches the picture.

planktoscope-assembly-154.jpg

We will now plug the cables into the correct ports.

planktoscope-assembly-155.jpg

🟣 The four wires (🔴 Red 🔵 Blue 🟢 Green ⚫ Black) enter the side port on the Raspberry Pi HAT.

planktoscope-assembly-156.jpg

🔴 The two wires (LED) enter on the port on top of the Raspberry Pi HAT.

planktoscope-assembly-157.jpg

The result should be similar to the picture.

Note

We will use this assembly in the next step.

Chapter 18: Connect the DC Power Jack to the Raspberry Pi🔗

planktoscope-assembly-159.jpg

  • 🟢 Locate the DC Power Jack
  • We will plug the DC Power Jack into the Raspberry Pi via the 🔵 blue port.

planktoscope-assembly-160.jpg

🔴 B1.Small flat screwdriver 2mm

planktoscope-assembly-161.jpg

  • Insert the 🔴 red cable of the DC Power Jack into the left side of the blue port.
  • Tighten the screw above.

planktoscope-assembly-162.jpg

  • Insert the ⚫ black cable of the DC Power Jack into the right side of the blue port.
  • Tighten the screw above.

planktoscope-assembly-163.jpg

Info

The result should be similar to the picture.

Note

We will use this assembly in the next step.

Chapter 19: Your PlanktoScope starts to take shape🔗

planktoscope-assembly-165.jpg

planktoscope-assembly-166.jpg

Locate Part I and Part H.

planktoscope-assembly-167.jpg

  • Slot Part H into Part I.
  • 🟣 Note the orientation. Part H goes into Part Iat the end with the rectangular slot (as opposed to the rectangle with bulbous hole).
  • 🟡 Also, the deeper slots on part H should be on the upper side.

planktoscope-assembly-168.jpg

🔴 Slot the Peristaltic Pump above the LED.

planktoscope-assembly-169.jpg

Note

The result should be the same as the picture.

planktoscope-assembly-170.jpg

Warning

👁 Ensure the correct orientation of the housing and the Peristaltic Pump.

planktoscope-assembly-171.jpg

At the other end, slot the DC Power Jack housing adjacent to the Raspberry Pi.

planktoscope-assembly-172-00.jpg planktoscope-assembly-172-00.jpg

Rotate so that the DC Power Jack is facing upwards. We will now slot the Raspberry Pi onto the rest of the housing.

planktoscope-assembly-173.jpg

Info

The result should be similar to that picture.

Note

🎬 Store this assembly for later.

Chapter 20: Inserting screws🔗

planktoscope-assembly-175.jpg

🟣 We will now insert eight M3 screws to fasten the housing together.

Note

🎬 Store this assembly for later.

planktoscope-assembly-176.jpg

🔴 A6. Screw M3X12mm BHC - SS

planktoscope-assembly-177.jpg

🟡 B3. Allen key 2mm

planktoscope-assembly-178.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-179.jpg

We will now turn over the PlanktoScope and repeat the process for the underside.

planktoscope-assembly-180.jpg

🟣 Insert eight more M3 screws on the underside.

planktoscope-assembly-181.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-182.jpg

Now turn the PlanktoScope on its side.

planktoscope-assembly-183.jpg

planktoscope-assembly-184.jpg

Warning

👁 Ensure the orientation of your PlanktoScope and Part K matches the picture.

planktoscope-assembly-185.jpg

Slot Part K onto the rest of the PlanktoScope.

Warning

🟢 Ensure the correct orientation. The result should look the same at the picture.

planktoscope-assembly-186.jpg

Content of Bag A: 🔴 A6. Screw M3X12mm BHC - SS

planktoscope-assembly-187.jpg

Content of Bag B: 🟡 B3. Allen key 2mm

planktoscope-assembly-188.jpg

🟣 Insert eight more M3 screws on the side to hold Part K in place.

planktoscope-assembly-189.jpg

planktoscope-assembly-190.jpg

We will now place Part J into position as the housing for the side.

Warning

👁 Ensure your PlanktoScope matches the orientation in the picture.

planktoscope-assembly-191.jpg

🟢 Place Part K onto the rest of the PlanktoScope and note the position of the cutout.

planktoscope-assembly-192.jpg

Content of Bag A: 🔴 A6. Screw M3X12mm BHC - SS

planktoscope-assembly-193.jpg

Content of Bag B: 🟡 B3. Allen key 2mm

planktoscope-assembly-194.jpg

🟣 Insert eight more M3 screws on the underside

planktoscope-assembly-195.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-196.jpg

planktoscope-assembly-197.jpg

Content of Bag A: 🟡 A5. Screw M2.5X10mm CHC - SS

planktoscope-assembly-198.jpg

Place the M2.5 screw through Part N. It will act as a cover for the electrical inputs.

planktoscope-assembly-199.jpg

  • Place the cover over the electrical inputs on the PlanktoScope.
  • 🟣 The screw will enter the hole located here.

planktoscope-assembly-200.jpg

Using the allen key, tighten the screw so that it is possible to move the cover with light force.

planktoscope-assembly-201.jpg

Info

The result should be the same as the picture.

Chapter 21: Insert the tubing in the Peristaltic Pump🔗

planktoscope-assembly-203.jpg

  • Orientate your PlanktoScope so that it matches the picture.
  • Twist off the orange top of the Peristaltic pump in an anti-clockwise direction.

planktoscope-assembly-205.jpg

You can now remove the Peristaltic Pump housing and 🟢 Rotor.

planktoscope-assembly-206.jpg

You can now remove the Peristaltic Pump housing and 🟢 Rotor.

planktoscope-assembly-207.jpg

🔴 Locate the Tube for the Peristaltic Pump in Bag F and remove it from the bag.

Warning

The tips of the Tubing that are covered by black rubber are very delicate and easily broken.

planktoscope-assembly-208.jpg

Insert the first plastic arch of the Tube into the slot on the Peristaltic Pump \ housing.

Info

The result should be similar to the picture.

planktoscope-assembly-209-00.jpg planktoscope-assembly-209-01.jpg

Insert the Rotor into the housing ensuring the correct orientation. The hole in the centre should be visible on the underside.

Info

The result should be similar to the picture.

planktoscope-assembly-210.jpg

Insert the Rotor into the housing. Then, thread the Tube around the Rotor and insert the other plastic arch into the second slot.

Info

The result should be similar to the picture.

planktoscope-assembly-211.jpg

  • Thread the Tube around around the Rotor and insert the other plastic arch into the second slot.
  • This will require stretching the Tube slightly.

planktoscope-assembly-212.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-213.jpg

Place the Peristaltic Pump housing back onto the PlanktoScope.

planktoscope-assembly-214.jpg

Achieve the angle shown in the picture between the Peristaltic Pump housing and PlanktoScope main body. Then, press and twist in a clockwise direction.

planktoscope-assembly-215.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-216.jpg

  • 🟣 Gently remove the black rubber covers for the Peristaltic Pump connectors by pinching the very tip and pulling away.
  • Once complete, locate Bag D which contains tubing.

planktoscope-assembly-217.jpg

Push the small piece of tubing from Bag D over the left-side connector of the Peristaltic Pump.

planktoscope-assembly-218.jpg

Place the long piece of tubing from Bag D over the right-side connector of the Peristaltic Pump.

planktoscope-assembly-219.jpg

Insert the connector from Bag D into the other end of the small piece of tubing.

planktoscope-assembly-220.jpg

planktoscope-assembly-221.jpg

Orientate Part P so that the magnets are face-down on the left-hand side.

planktoscope-assembly-222.jpg

Place Part P over the magnets adjacent to the Peristaltic Pump.

Info

The result should be similar to the picture.

planktoscope-assembly-223.jpg

🔴 From Bag M, Place the light blue Test Tube in the hole adjacent to the Peristaltic Pump.

planktoscope-assembly-224.jpg

Place the 🔵 dark blue Test Tube into the hole situated outside of the PlanktoScope.

planktoscope-assembly-225.jpg

🟢 Insert the other end of the long piece of tubing into the 🔵 dark blue Test Tube. This will serve as the waste container. The result should look the same as the picture.

planktoscope-assembly-226.jpg

planktoscope-assembly-227-00.jpg planktoscope-assembly-227-01.jpg planktoscope-assembly-227-02.jpg

  • Locate Part C
  • Locate 25 mm camera lens and Lock Ring from Bag J.
  • 25MM is printed on the lens.

planktoscope-assembly-228-00.jpg planktoscope-assembly-228-01.jpg

  • Remove the plastic lens cap.
  • Slot the 25 mm camera lens into Part C.

Info

The magnets are raised on the side where the lens lays flat.

Warning

Try not to touch the lens

Screw the Lock Ring onto the lens, flat-side down.

planktoscope-assembly-229-00.jpg planktoscope-assembly-229-01.jpg planktoscope-assembly-227-02.jpg

  • Locate Part D.
  • Locate 16 mm camera lens and Lock Ring from Bag J.
  • 16MM is printed on the lens.

planktoscope-assembly-230-00.jpg planktoscope-assembly-230-01.jpg

  • Remove the plastic lens cap.
  • Slot the 16 mm camera lens into Part D.

Info

The magnets are indented on the side that the lens lays flat.

Warning

Try not to touch the lens

Screw the Lock Ring onto the lens, flat-side down.

The result should be similar to that picture.

planktoscope-assembly-231-00.jpg planktoscope-assembly-231-01.jpg

Place both Lenses (C and D) together so that they flat together and both lenses are facing each other.

Info

The result should be similar to the picture.

planktoscope-assembly-232-01.jpg planktoscope-assembly-232-00.jpg planktoscope-assembly-232-02.jpg

Place the Lenses (both C and D) into position, adjacent to the camera.

The orientation of your PlanktoScope and Lenses should match the pictures.

planktoscope-assembly-233.jpg

  • Once together, place the lenses (both C and D) into position, adjacent to the camera.
  • Part C / 25mm lens should be furthest from the pump (orange piece).

Info

The result should be similar to the picture.

planktoscope-assembly-234.jpg

planktoscope-assembly-235.jpg

Info

The Fluidic Path will have a cardboard protector.

Please take extra precaution while handling this part and avoid touching the glass element of the piece.

Warning

The Fluidic Path is very delicate.

planktoscope-assembly-236.jpg

Place the Tube Clamp over the long piece of tube at the end of the Fluidic Path.

planktoscope-assembly-237.jpg

Place the white clamp over the long piece of tube at the end of the Fluidic Path.

Info

The result should look the same as the picture.

planktoscope-assembly-238.jpg

Press down on the Tube Clamp so that it clicks into place with just one click.

Info

The result should look the same as the picture.

planktoscope-assembly-239.jpg

Insert a small plastic Connector into the end of the tubing, below the Tube Clamp.

planktoscope-assembly-240.jpg

Make sure the tubing is over the Connector.

Info

The result should look the same as the picture.

planktoscope-assembly-241.jpg

Remove the cardboard protector from the Fluidic Path.

planktoscope-assembly-242.jpg

Warning

A reminder, the glass part of the Fluidic Path is very delicate. Please try not to touch it.

planktoscope-assembly-243.jpg

Place another Connector at the end of the tubing.

planktoscope-assembly-244.jpg

The result should be the same as the picture.

planktoscope-assembly-245.jpg

⚠ Gently place the Fluidic Path in the designated indentation on Part F.

Warning

Do not touch the glass. 

  • You may have to slightly stretch the tubing to get the Fluidic Path into position.
  • The result should be the same as the picture.

planktoscope-assembly-246.jpg

If you have tape available, place a small piece at the the bottom of Part F so that the tubing remains fixed in its position.

Avoid placing tape over the glass.

Info

The result should be similar to the picture.

planktoscope-assembly-247-01.jpg planktoscope-assembly-247-00.jpg

To insert the syringe, place finger and thumb either side of part F where green circle is located. This ensures the tubing does not rotate while you twist the syringe into position in a clockwise direction.

planktoscope-assembly-248.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-249-00.jpg planktoscope-assembly-249-01.jpg

  • Place the Fluidic Path into position between the mount and the Peristaltic Pump.
  • Connect the magnets to face each other.

planktoscope-assembly-250.jpg

The result should look the same as the pictures.

planktoscope-assembly-251-00.jpg planktoscope-assembly-251-01.jpg

  • 🟢 Connect the Fluidic Path to the Peristaltic Pump by twisting the two connectors together.
  • The result should be the same as the picture.

Build complete! 💯 💫🔗

planktoscope-assembly-251-01.jpg

The next stage is to plug in our PlanktoScope and connect it to the computer.

Assembly🔗

planktoscope-assembly-workshop.jpg

Content of the Kit🔗

It is important to ensure that you have all of the necessary components before beginning the assembly of your PlanktoScope. To do so, please check that all bags are present as part of the kit.

planktoscope-assembly-002.jpg

Bag Content
A Scews
B Tools
C Adhesive Pads
D Tubing, Glass Cuvettes
E Bubbler Pump
F Peristaltic Pump
G Linear Stepper Motor
H Raspberry PI Chip cooler
I Raspberry HAT
J Camera Lens
K MicroSD Card, DC Power Jack Socket
L DC Power Supply and Cable
M Syringe and Falcon Tube
X1 Raspberry PI 4
X2 Pipet
X3 Cable ties
X4 Raspberry PI HQ Camera Modul
X5 Sandpaper

If any bags are missing, please go back to the BOM (Bill of Materials) and reorder the required components.

About this document🔗

To read this document, follow these guidelines:

Color codes🔗

  • 🔴 Look to the color red
  • 🟠 Look to the color orange
  • 🟡 Look to the color yellow
  • 🟢 Look to the color green
  • 🔵 Look to the color blue
  • 🟣 Look to the color purple

Icons🔗

  • 👁 Pay attention to this
  • ⚠ Be careful with this
  • 📜 The book says
  • 🎬 Action !
  • ❌ Don't focus on that location

As you read through the document, be sure to pay attention to these visual cues to guide you through the build process.

Requirements🔗

Tools🔗

planktoscope-assembly-254.jpg

Content of Bag B:

  • 🔴 B1. Small flat screwdriver 2mm
  • 🟠 B2. Razor blade
  • 🟡 B3. Allen key 2mm
  • 🟢 B4. Wrenches for standoffs

Components🔗

planktoscope-assembly-253.jpg

Content of Bag A:

  • 🟢 A1. Standoff M2.5 - 6mm - Brass
  • 🔵 A2. Standoff M2.5 - 15mm -  Brass
  • 🟣 A3. Standoff M2.5 - 16mm - SS
  • 🟠 A4. Screw M2.5x5mm CHC - SS
  • 🟡 A5. Screw M2.5x10mm CHC - SS
  • 🔴 A6. Screw M3x12mm BHC - SS

Chapter 1: Detach the Parts from panels by cutting the tabs🔗

planktoscope-assembly-004.jpg 👁 Locate the panel S1 and discover the 5 differents Parts F, P, K, J and I.

planktoscope-assembly-005.jpg 🎬 Flip your panel S1.

planktoscope-assembly-006.jpg 🔴 Locate the outer tabs on the edges of the different Parts. These are typically small projections of material that are used to secure the case parts to the panels.

planktoscope-assembly-007.jpg Gather all the necessary tools. You will need the B2 🟠 Razor blade to cut the tabs.

planktoscope-assembly-008.jpg

  • 🟣 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.

planktoscope-assembly-009.jpg

  • 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 all of the tabs are cut, gently lift the case parts away from the panels. If the case parts are stuck or difficult to remove, you may need to gently wiggle or pry them loose using a flat tool such as a screwdriver.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-011.jpg

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.

planktoscope-assembly-012.jpg

🟣 Place your razor blade flat on the edge of your piece being very careful with your fingers and cut the residual tab.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-013.jpg

Repeat the cutting of the tabs on all the Parts F, P, K, J and I present on the panel S1.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-014.jpg

🔴 Locate the inner tabs on the edges of the different Parts.

planktoscope-assembly-015.jpg

Cut out the tabs inside of all the Parts F, P, K, J and I detached from the panel S1.

Dispose of the cut tabs and any other debris that may have been created during the detachment process.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-016.jpg

  • ✅ Good way of cutting inner tabs
  • ❌ Wrong way of cutting inner tabs

planktoscope-assembly-018.jpg

Repeat the process on the panel S2.

Warning

Be extremely careful because this is very sharp.

planktoscope-assembly-019.jpg

Discover the 11 differents Parts.

planktoscope-assembly-020.jpg

Dispose of the cut tabs and any other debris that may have been created during the detachment process. Inspect the case parts and panels for any damage or imperfections that may have occurred during the detachment process. If any damage is found, it may be necessary to repair or replace the affected parts.

Chapter 2: Place the 4 Adhesive Pads under the Part I🔗

planktoscope-assembly-023.jpg To secure the PlanktoScope on slippery grounds using the adhesive pads, follow these steps. Gather all the necessary materials. You will need:

  • Time: 1 min
  • 👁 and 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.

planktoscope-assembly-024.jpg

  • Clean the bottom of the case part I. Make sure the surface is free of dirt, debris, and any other substances that may prevent the adhesive pads from sticking properly.
  • Remove the paper and place the four adhesive pads in the pockets by pressing firmly on them, sticky-side down.
  • Test the stability of the PlanktoScope by gently shaking or tilting it. If it feels secure and does not slip or slide, the adhesive pads have been successfully installed.

Note

🎬 Store this assembly for later.

Chapter 3: Screw the four Standoffs into Part A🔗

planktoscope-assembly-026.jpg

Now it's time to assemble the ground plate for the Raspberry Pi as the PlanktoScope main processing unit.

  • Time: 5 min

planktoscope-assembly-027.jpg

  • 👁 Grab the Part A.
  • 🟣 Locate the four holes on Part A.

planktoscope-assembly-028.jpg

🟢 A1. Standoff M2.5 - 6mm- Brass

planktoscope-assembly-029.jpg

🟢 B4. Wrenches for standoffs

planktoscope-assembly-030.jpg

  • 🟣 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.

planktoscope-assembly-031.jpg

  • Place the standoff in the hole and start rotating by hand in a clockwise direction until secure.
  • Then tighten with the wrench.

planktoscope-assembly-032.jpg

  • ✅ Make sure to screw until the standoff is properly inserted in the hole.
  • ❌ Do not stop screwing before.

planktoscope-assembly-033.jpg

Keep going for each of the four holes.

Chapter 4: Mount the Heat Sinks on the Raspberry Pi🔗

planktoscope-assembly-035.jpg

  • Time: 2 min

Locate the Raspberry Pi 4 Model B packaging.

Warning

Be careful removing it from its packaging.

planktoscope-assembly-036.jpg

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

planktoscope-assembly-037.jpg

Remove the protective labels under a Heat Sink and place the Heat Sink on the slot of the Raspberry Pi.

planktoscope-assembly-038.jpg

Remove the protective labels under all the Heat Sinks and place all the Heat Sinks on the slots of the Raspberry Pi.

Chapter 5: Insert the micro SD card in the Raspberry Pi🔗

planktoscope-assembly-040.jpg

  • 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.

planktoscope-assembly-041.jpg

  • Flip your Raspberry Pi.
  • 🟠 Locate the micro SD port.
  • 🟣 Insert the micro SD card in the Raspberry Pi.

planktoscope-assembly-042.jpg

Push the micro SD card in the Raspberry Pi port to a point of resistance.

Note

If you notice that the micro SD card protrudes about 2mm from its slot, this is normal.

Chapter 6: Mount the Raspberry Pi on the Part A🔗

  • Time: 1 min

planktoscope-assembly-044.jpg

  • ✅ 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.

planktoscope-assembly-045.jpg

🟣 A3. Standoff M2.5 - 16mm - SS

planktoscope-assembly-046.jpg

Screw by hand a Standoff M2.5 - 16mm on the Raspberry Pi.

planktoscope-assembly-047.jpg

  • Screw by hand all Standoffs M2.5 - 16mm on the Raspberry Pi.
  • Make sure you insert all four standoffs by hand and tighten slightly.

planktoscope-assembly-048.jpg

🟢 B4. Wrenches for standoffs

planktoscope-assembly-049.jpg

  • 🟠 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.

Chapter 7: Attach the Ribbon Cable to the Raspberry Pi🔗

  • Time: 2 min

planktoscope-assembly-051.jpg

Locate the Raspberry Pi Camera HQ packaging.

Warning

Be careful removing it from its packaging.

planktoscope-assembly-052.jpg

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

planktoscope-assembly-053.jpg

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.

planktoscope-assembly-054.jpg

🔴 Locate the black connector present on the Raspberry Pi.

planktoscope-assembly-055.jpg

🔴 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.

planktoscope-assembly-056.jpg

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.

planktoscope-assembly-057.jpg

🔴 Secure the Ribbon Cable in the Raspberry Pi by pressing firmly on the black connector.

Chapter 8: Mount the PlanktoScope HAT on the Raspberry Pi🔗

planktoscope-assembly-059.jpg

  • Time: 2 min

Locate the PlanktoScope HAT present in bag I.

planktoscope-assembly-060.jpg

🔴 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.

planktoscope-assembly-061.jpg

🔴 Plug the PlanktoScope HAT into the Raspberry Pi.

Warning

Make sure the two black connectors are aligned before attaching them together.

planktoscope-assembly-062.jpg

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.

planktoscope-assembly-063.jpg

🟠 A4. Screw M2.5X5mm CHC - SS

planktoscope-assembly-064.jpg

🟣 Locate the 4 holes on the top of the PlanktoScope HAT and insert the four M2.5X5mm

planktoscope-assembly-065.jpg

🟡 B3. Allen key 2mm

planktoscope-assembly-066.jpg

Screw the four A4 screws through the PlanktoScope HAT onto the Standoff M2.5 - 16mm.

Note

🎬 Store this assembly for later.

Chapter 9: Place the Power Socket on Part M🔗

planktoscope-assembly-068.jpg

  • Time: 2 min
  • Locate the DC Power Jack from the Bag K.
  • Remove the Lock Ring from the DC Power Jack

planktoscope-assembly-069.jpg

planktoscope-assembly-070.jpg

  • 🔴 Lay the Part M down and make sure the pockets in these holes are facing upwards.
  • 🟣 Locate the Power Socket hole on Part M.

planktoscope-assembly-071.jpg

🔴 Insert the cable inside of the hole by being sure of the orientation of the Part M.

planktoscope-assembly-072.jpg

🟣 Flip the Part M and secure the DC Power Jack by hand on the Part M by screwing the Lock Ring.

Warning

Make sure the Lock Ring doesn’t spin on itself.

Note

🎬 Store this assembly for later.

Chapter 10: Mount the Raspberry Pi Camera HQ on Part B🔗

planktoscope-assembly-074.jpg

  • Time: 2 min

planktoscope-assembly-075.jpg

🟣 Locate the 4 holes on the top of the Part B.

planktoscope-assembly-076.jpg

🔵 A2. Standoff M2.5 - 15mm - Brass

planktoscope-assembly-077.jpg

Insert the four Standoff M2.5 - 15mm.

planktoscope-assembly-078.jpg

The result should be similar to the picture.

planktoscope-assembly-079.jpg

🟢 B4. Wrenches for standoffs

planktoscope-assembly-080.jpg

Using the small side of the Standoff Wrench, secure the 4 M2.5 - 15mm Standoffs

planktoscope-assembly-081.jpg

  • ✅ Make sure to screw until the Standoff is properly tightened into the hole.
  • ❌ Do not stop screwing before.

planktoscope-assembly-082.jpg

Locate the Raspberry Pi Camera HQ

planktoscope-assembly-083.jpg

Remove the lens cap Raspberry Pi Camera HQ.

planktoscope-assembly-084.jpg

Warning

Make sure your camera lens is clean. If it is not, gently wipe using cotton swab for this task.

planktoscope-assembly-085.jpg

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

planktoscope-assembly-086.jpg

🟠 A4. Screw M2.5X5mm CHC - SS

planktoscope-assembly-087.jpg

🟡 B3. Allen key 2mm

planktoscope-assembly-088.jpg

Use the allen key and tighten the Raspberry Pi Camera to the Standoffs.

planktoscope-assembly-089.jpg

The result should be similar to the picture.

Note

🎬 Store this assembly for later.

Chapter 11: Mount the Linear Stepper Motor on Part E🔗

planktoscope-assembly-091.jpg

Locate the Stepper Motors

Warning

Avoid touching the metal rods on the Stepper Motors

Info

You can touch the 🟣 gold stands

planktoscope-assembly-092.jpg

planktoscope-assembly-093.jpg

🟡 A5. Screw M2.5X10mm CHC - SS

planktoscope-assembly-094.jpg

🟡 B3. Allen key 2mm

planktoscope-assembly-095.jpg

  • 🔴 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.

planktoscope-assembly-096.jpg

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.

planktoscope-assembly-097.jpg

Use the 2mm allen key to fix the Stepper Motors.

The result should be similar to that picture.

planktoscope-assembly-098.jpg

The result should be similar to the picture.

planktoscope-assembly-099.jpg

Repeat the process on the other side with the other Stepper Motor.

planktoscope-assembly-100.jpg

Repeat the process on the other side with the other Stepper Motor.

planktoscope-assembly-101.jpg

The result should be similar to the picture.

Note

🎬 Store this assembly for later.

Chapter 12: Mount the LED on Part G🔗

planktoscope-assembly-103.jpg

  • Locate the LED and LED cable in Bag K.
  • 🟣 The LED will go on the end where the white plastic connector is smallest.

planktoscope-assembly-104.jpg

Insert the LED into the LED cable.

planktoscope-assembly-105.jpg

The result should be similar to the picture.

planktoscope-assembly-106.jpg

planktoscope-assembly-107.jpg

Locate part G.

planktoscope-assembly-108.jpg

🟣 Locate the LED hole on Part G.

planktoscope-assembly-109.jpg

We will now place the LED into the slot on part G.

planktoscope-assembly-110.jpg

Warning

Gently push the LED into the LED hole located on Part G. It should be a snug fit.

planktoscope-assembly-111.jpg

The result should be similar to the picture.

Info

🎬 Store this assembly for later.

Chapter 13: Mount the Peristaltic Pump on Part O and Part L🔗

planktoscope-assembly-113.jpg

  • Locate the Kamoer Peristaltic pump from the Bag F.
  • 🟣 Put aside the tubing contained in the little bag.

planktoscope-assembly-114.jpg

planktoscope-assembly-115.jpg

🟢 Insert the cable of the Peristaltic Pump into the hole on Part O and then insert the motor block assembly of the pump into it.

Warning

👁 Ensure the correct orientation of Part O and the Peristaltic Pump

planktoscope-assembly-116.jpg

🟡 A5. Screw M2.5X10mm CHC - SS

planktoscope-assembly-117.jpg

🟡 B3. Allen key 2mm B3

planktoscope-assembly-118.jpg

🟢 Insert the two M2.5X10mm in the two holes.

planktoscope-assembly-119.jpg

Screw the two M2.5X10mm into the two holes.

planktoscope-assembly-120.jpg

planktoscope-assembly-121.jpg

🔴 Lay the Part L down and make sure the pockets in these holes are facing upwards.

planktoscope-assembly-122.jpg

  • Place the Peristaltic Pump underneath part L, ensuring the correct orientation of these two parts.
  • 🔴 Insert the Peristaltic Pump into the allocated slot in Part L.

planktoscope-assembly-123.jpg

Insert the Peristaltic Pump into the allocated slot in Part L.

planktoscope-assembly-124.jpg

Insert the Peristaltic Pump into the allocated slot in Part L.

planktoscope-assembly-125.jpg

  • Lay the assembly down.
  • 🔴 Locate the four different holes.

planktoscope-assembly-126.jpg

🟡 A5.Screw M2.5X10mm CHC - SS

planktoscope-assembly-127.jpg

🟡 B3.Allen key 2mm

planktoscope-assembly-128.jpg

Screw the four M2.5X10mm in the located holes attaching the Part O to the Part L Peristaltic Pump.

planktoscope-assembly-129.jpg The result should be similar to the picture.

Info

We will use this part in the next step.

Chapter 14: Spiral wrap the LED and Peristaltic Pump cabling🔗

planktoscope-assembly-131.jpg

  • Locate the LED and housing, along with the pump and housing.
  • 🟣 Locate the spiral wrap from bag K.

planktoscope-assembly-132.jpg

  • Spiral wrap both sets of cables together.
  • There should be 4 cm (1.5 inches) between the connectors and the start of the spiral wrap.

planktoscope-assembly-133.jpg

Continue wrapping around the cables until you have used all of the spiral wrap, leaving small or no gaps.

Info

The result should look the same as the picture.

planktoscope-assembly-134.jpg

Info

The result should look the same as the picture.

Note

🎬 Store this assembly for later.

Chapter 15: Attaching the Stepper Motors to the Raspberry Pi Camera🔗

planktoscope-assembly-136.jpg

Locate the Stepper Motors with mount, and the Raspberry Pi Camera.

planktoscope-assembly-137.jpg Feed the Stepper Motor cables into the slots either side of the Raspberry Pi Camera.

Warning

Make sure the orientation is correct and matches the picture.

planktoscope-assembly-138.jpg Feed the Stepper Motor cables into the slots either side of the Raspberry Pi Camera.

Warning

Make sure the orientation is correct and matches the picture.

Then insert the cylindrical parts of the Stepper Motor into the slots.

planktoscope-assembly-139.jpg

Feed the Stepper Motor cables into the slots either side of the Raspberry Pi Camera.

Warning

Make sure the orientation is correct and matches the picture.

Then insert the cylindrical parts of the Stepper Motor into the slots.

Note

The result should be the same as the picture.

Chapter 16: Connecting the Raspberry Pi Camera to the Raspberry Pi HAT🔗

planktoscope-assembly-141.jpg

  • We will need the Raspberry Pi HAT with housing and Ribbon Cable along \ with the Raspberry Pi Camera with Stepper Motors and housing.
  • We will be connecting the 🟢Ribbon Cableto the 🟡black Raspberry Pi Camera connector that we removed it from earlier.

planktoscope-assembly-142.jpg

Gently feed the Ribbon Cable into the port of the Camera.

Warning

👁 Ensure the correct orientation of the Ribbon Cable with the blue end facing upwards.

planktoscope-assembly-143.jpg 🔴 Press down on the black connector on the Raspberry Pi camera board once the Ribbon Cable is in position.

planktoscope-assembly-144.jpg 🔴 B1.Small flat screwdriver 2mm

planktoscope-assembly-145.jpg

  • Now we will plug in the Stepper Mounts to the HAT.
  • 🔴The cables for the Stepper Mounts will be plugged into the HAT 🟣here.

Warning

Hold tight, a specific order is required.

planktoscope-assembly-146.jpg

Starting with the red cable, insert the cable in the far left port and tighten the screw situated above the port.

Note

The result should look the same as the picture.

planktoscope-assembly-147.jpg

Repeat this process with the order pictured here from left to right: 🔴 Red 🟡 Yellow 🔵 Blue ⚫ Black.

Chapter 17: Connect the LED and Peristaltic Pump to the Raspberry Pi🔗

planktoscope-assembly-149.jpg

We will now be connecting the LED and Peristaltic Pump with the Raspberry Pi HAT and Camera.

planktoscope-assembly-150.jpg

Place the LED housing onto the Stepper Mounts.

Warning

👁 Ensure correct orientation of both 🟣 parts by looking at the precut holes.

planktoscope-assembly-151.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-152.jpg

Now we will plug in the LED and Stepper Mount cables to the Raspberry Pi.

planktoscope-assembly-153.jpg

Feed the area of cabling that is not covered by the spiral wrap through the two holes to start. Then thread through to the spiral wrap so that it matches the picture.

planktoscope-assembly-154.jpg

We will now plug the cables into the correct ports.

planktoscope-assembly-155.jpg

🟣 The four wires (🔴 Red 🔵 Blue 🟢 Green ⚫ Black) enter the side port on the Raspberry Pi HAT.

planktoscope-assembly-156.jpg

🔴 The two wires (LED) enter on the port on top of the Raspberry Pi HAT.

planktoscope-assembly-157.jpg

The result should be similar to the picture.

Note

We will use this assembly in the next step.

Chapter 18: Connect the DC Power Jack to the Raspberry Pi🔗

planktoscope-assembly-159.jpg

  • 🟢 Locate the DC Power Jack
  • We will plug the DC Power Jack into the Raspberry Pi via the 🔵 blue port.

planktoscope-assembly-160.jpg

🔴 B1.Small flat screwdriver 2mm

planktoscope-assembly-161.jpg

  • Insert the 🔴 red cable of the DC Power Jack into the left side of the blue port.
  • Tighten the screw above.

planktoscope-assembly-162.jpg

  • Insert the ⚫ black cable of the DC Power Jack into the right side of the blue port.
  • Tighten the screw above.

planktoscope-assembly-163.jpg

Info

The result should be similar to the picture.

Note

We will use this assembly in the next step.

Chapter 19: Your PlanktoScope starts to take shape🔗

planktoscope-assembly-165.jpg

planktoscope-assembly-166.jpg

Locate Part I and Part H.

planktoscope-assembly-167.jpg

  • Slot Part H into Part I.
  • 🟣 Note the orientation. Part H goes into Part Iat the end with the rectangular slot (as opposed to the rectangle with bulbous hole).
  • 🟡 Also, the deeper slots on part H should be on the upper side.

planktoscope-assembly-168.jpg

🔴 Slot the Peristaltic Pump above the LED.

planktoscope-assembly-169.jpg

Note

The result should be the same as the picture.

planktoscope-assembly-170.jpg

Warning

👁 Ensure the correct orientation of the housing and the Peristaltic Pump.

planktoscope-assembly-171.jpg

At the other end, slot the DC Power Jack housing adjacent to the Raspberry Pi.

planktoscope-assembly-172-00.jpg planktoscope-assembly-172-00.jpg

Rotate so that the DC Power Jack is facing upwards. We will now slot the Raspberry Pi onto the rest of the housing.

planktoscope-assembly-173.jpg

Info

The result should be similar to that picture.

Note

🎬 Store this assembly for later.

Chapter 20: Inserting screws🔗

planktoscope-assembly-175.jpg

🟣 We will now insert eight M3 screws to fasten the housing together.

Note

🎬 Store this assembly for later.

planktoscope-assembly-176.jpg

🔴 A6. Screw M3X12mm BHC - SS

planktoscope-assembly-177.jpg

🟡 B3. Allen key 2mm

planktoscope-assembly-178.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-179.jpg

We will now turn over the PlanktoScope and repeat the process for the underside.

planktoscope-assembly-180.jpg

🟣 Insert eight more M3 screws on the underside.

planktoscope-assembly-181.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-182.jpg

Now turn the PlanktoScope on its side.

planktoscope-assembly-183.jpg

planktoscope-assembly-184.jpg

Warning

👁 Ensure the orientation of your PlanktoScope and Part K matches the picture.

planktoscope-assembly-185.jpg

Slot Part K onto the rest of the PlanktoScope.

Warning

🟢 Ensure the correct orientation. The result should look the same at the picture.

planktoscope-assembly-186.jpg

Content of Bag A: 🔴 A6. Screw M3X12mm BHC - SS

planktoscope-assembly-187.jpg

Content of Bag B: 🟡 B3. Allen key 2mm

planktoscope-assembly-188.jpg

🟣 Insert eight more M3 screws on the side to hold Part K in place.

planktoscope-assembly-189.jpg

planktoscope-assembly-190.jpg

We will now place Part J into position as the housing for the side.

Warning

👁 Ensure your PlanktoScope matches the orientation in the picture.

planktoscope-assembly-191.jpg

🟢 Place Part K onto the rest of the PlanktoScope and note the position of the cutout.

planktoscope-assembly-192.jpg

Content of Bag A: 🔴 A6. Screw M3X12mm BHC - SS

planktoscope-assembly-193.jpg

Content of Bag B: 🟡 B3. Allen key 2mm

planktoscope-assembly-194.jpg

🟣 Insert eight more M3 screws on the underside

planktoscope-assembly-195.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-196.jpg

planktoscope-assembly-197.jpg

Content of Bag A: 🟡 A5. Screw M2.5X10mm CHC - SS

planktoscope-assembly-198.jpg

Place the M2.5 screw through Part N. It will act as a cover for the electrical inputs.

planktoscope-assembly-199.jpg

  • Place the cover over the electrical inputs on the PlanktoScope.
  • 🟣 The screw will enter the hole located here.

planktoscope-assembly-200.jpg

Using the allen key, tighten the screw so that it is possible to move the cover with light force.

planktoscope-assembly-201.jpg

Info

The result should be the same as the picture.

Chapter 21: Insert the tubing in the Peristaltic Pump🔗

planktoscope-assembly-203.jpg

  • Orientate your PlanktoScope so that it matches the picture.
  • Twist off the orange top of the Peristaltic pump in an anti-clockwise direction.

planktoscope-assembly-205.jpg

You can now remove the Peristaltic Pump housing and 🟢 Rotor.

planktoscope-assembly-206.jpg

You can now remove the Peristaltic Pump housing and 🟢 Rotor.

planktoscope-assembly-207.jpg

🔴 Locate the Tube for the Peristaltic Pump in Bag F and remove it from the bag.

Warning

The tips of the Tubing that are covered by black rubber are very delicate and easily broken.

planktoscope-assembly-208.jpg

Insert the first plastic arch of the Tube into the slot on the Peristaltic Pump \ housing.

Info

The result should be similar to the picture.

planktoscope-assembly-209-00.jpg planktoscope-assembly-209-01.jpg

Insert the Rotor into the housing ensuring the correct orientation. The hole in the centre should be visible on the underside.

Info

The result should be similar to the picture.

planktoscope-assembly-210.jpg

Insert the Rotor into the housing. Then, thread the Tube around the Rotor and insert the other plastic arch into the second slot.

Info

The result should be similar to the picture.

planktoscope-assembly-211.jpg

  • Thread the Tube around around the Rotor and insert the other plastic arch into the second slot.
  • This will require stretching the Tube slightly.

planktoscope-assembly-212.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-213.jpg

Place the Peristaltic Pump housing back onto the PlanktoScope.

planktoscope-assembly-214.jpg

Achieve the angle shown in the picture between the Peristaltic Pump housing and PlanktoScope main body. Then, press and twist in a clockwise direction.

planktoscope-assembly-215.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-216.jpg

  • 🟣 Gently remove the black rubber covers for the Peristaltic Pump connectors by pinching the very tip and pulling away.
  • Once complete, locate Bag D which contains tubing.

planktoscope-assembly-217.jpg

Push the small piece of tubing from Bag D over the left-side connector of the Peristaltic Pump.

planktoscope-assembly-218.jpg

Place the long piece of tubing from Bag D over the right-side connector of the Peristaltic Pump.

planktoscope-assembly-219.jpg

Insert the connector from Bag D into the other end of the small piece of tubing.

planktoscope-assembly-220.jpg

planktoscope-assembly-221.jpg

Orientate Part P so that the magnets are face-down on the left-hand side.

planktoscope-assembly-222.jpg

Place Part P over the magnets adjacent to the Peristaltic Pump.

Info

The result should be similar to the picture.

planktoscope-assembly-223.jpg

🔴 From Bag M, Place the light blue Test Tube in the hole adjacent to the Peristaltic Pump.

planktoscope-assembly-224.jpg

Place the 🔵 dark blue Test Tube into the hole situated outside of the PlanktoScope.

planktoscope-assembly-225.jpg

🟢 Insert the other end of the long piece of tubing into the 🔵 dark blue Test Tube. This will serve as the waste container. The result should look the same as the picture.

planktoscope-assembly-226.jpg

planktoscope-assembly-227-00.jpg planktoscope-assembly-227-01.jpg planktoscope-assembly-227-02.jpg

  • Locate Part C
  • Locate 25 mm camera lens and Lock Ring from Bag J.
  • 25MM is printed on the lens.

planktoscope-assembly-228-00.jpg planktoscope-assembly-228-01.jpg

  • Remove the plastic lens cap.
  • Slot the 25 mm camera lens into Part C.

Info

The magnets are raised on the side where the lens lays flat.

Warning

Try not to touch the lens

Screw the Lock Ring onto the lens, flat-side down.

planktoscope-assembly-229-00.jpg planktoscope-assembly-229-01.jpg planktoscope-assembly-227-02.jpg

  • Locate Part D.
  • Locate 16 mm camera lens and Lock Ring from Bag J.
  • 16MM is printed on the lens.

planktoscope-assembly-230-00.jpg planktoscope-assembly-230-01.jpg

  • Remove the plastic lens cap.
  • Slot the 16 mm camera lens into Part D.

Info

The magnets are indented on the side that the lens lays flat.

Warning

Try not to touch the lens

Screw the Lock Ring onto the lens, flat-side down.

The result should be similar to that picture.

planktoscope-assembly-231-00.jpg planktoscope-assembly-231-01.jpg

Place both Lenses (C and D) together so that they flat together and both lenses are facing each other.

Info

The result should be similar to the picture.

planktoscope-assembly-232-01.jpg planktoscope-assembly-232-00.jpg planktoscope-assembly-232-02.jpg

Place the Lenses (both C and D) into position, adjacent to the camera.

The orientation of your PlanktoScope and Lenses should match the pictures.

planktoscope-assembly-233.jpg

  • Once together, place the lenses (both C and D) into position, adjacent to the camera.
  • Part C / 25mm lens should be furthest from the pump (orange piece).

Info

The result should be similar to the picture.

planktoscope-assembly-234.jpg

planktoscope-assembly-235.jpg

Info

The Fluidic Path will have a cardboard protector.

Please take extra precaution while handling this part and avoid touching the glass element of the piece.

Warning

The Fluidic Path is very delicate.

planktoscope-assembly-236.jpg

Place the Tube Clamp over the long piece of tube at the end of the Fluidic Path.

planktoscope-assembly-237.jpg

Place the white clamp over the long piece of tube at the end of the Fluidic Path.

Info

The result should look the same as the picture.

planktoscope-assembly-238.jpg

Press down on the Tube Clamp so that it clicks into place with just one click.

Info

The result should look the same as the picture.

planktoscope-assembly-239.jpg

Insert a small plastic Connector into the end of the tubing, below the Tube Clamp.

planktoscope-assembly-240.jpg

Make sure the tubing is over the Connector.

Info

The result should look the same as the picture.

planktoscope-assembly-241.jpg

Remove the cardboard protector from the Fluidic Path.

planktoscope-assembly-242.jpg

Warning

A reminder, the glass part of the Fluidic Path is very delicate. Please try not to touch it.

planktoscope-assembly-243.jpg

Place another Connector at the end of the tubing.

planktoscope-assembly-244.jpg

The result should be the same as the picture.

planktoscope-assembly-245.jpg

⚠ Gently place the Fluidic Path in the designated indentation on Part F.

Warning

Do not touch the glass. 

  • You may have to slightly stretch the tubing to get the Fluidic Path into position.
  • The result should be the same as the picture.

planktoscope-assembly-246.jpg

If you have tape available, place a small piece at the the bottom of Part F so that the tubing remains fixed in its position.

Avoid placing tape over the glass.

Info

The result should be similar to the picture.

planktoscope-assembly-247-01.jpg planktoscope-assembly-247-00.jpg

To insert the syringe, place finger and thumb either side of part F where green circle is located. This ensures the tubing does not rotate while you twist the syringe into position in a clockwise direction.

planktoscope-assembly-248.jpg

Info

The result should be similar to the picture.

planktoscope-assembly-249-00.jpg planktoscope-assembly-249-01.jpg

  • Place the Fluidic Path into position between the mount and the Peristaltic Pump.
  • Connect the magnets to face each other.

planktoscope-assembly-250.jpg

The result should look the same as the pictures.

planktoscope-assembly-251-00.jpg planktoscope-assembly-251-01.jpg

  • 🟢 Connect the Fluidic Path to the Peristaltic Pump by twisting the two connectors together.
  • The result should be the same as the picture.

Build complete! 💯 💫🔗

planktoscope-assembly-251-01.jpg

The next stage is to plug in our PlanktoScope and connect it to the computer.

Hardware v2.5🔗

This page will help you to build the v2.5 hardware for a PlanktoScope.

Make an assembly kit🔗

If you do not already have an assembly kit, you will need to make a kit for yourself.

Assemble a PlanktoScope from a kit🔗

Once you have an assembly kit, you will need to assemble it into a PlanktoScope.

Next steps🔗

If you assembled your PlanktoScope from a kit provided by FairScope, you can proceed to our operation guide to learn how to operate your PlanktoScope. Otherwise, you will first need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi.

Hardware v2.5🔗

This page will help you to build the v2.5 hardware for a PlanktoScope.

Make an assembly kit🔗

If you do not already have an assembly kit, you will need to make a kit for yourself.

Assemble a PlanktoScope from a kit🔗

Once you have an assembly kit, you will need to assemble it into a PlanktoScope.

Next steps🔗

If you assembled your PlanktoScope from a kit provided by FairScope, you can proceed to our operation guide to learn how to operate your PlanktoScope. Otherwise, you will first need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi.

Kit Manufacturing🔗

manufacturing guide

Mechanical Structure🔗

CNC (computer numerical control) milling machines are used to fabricate parts with precise dimensions and shapes. The configuration of the feed rate and diameter plays a crucial role in the machining process and can significantly affect the quality and efficiency of the production of a workpiece.

case_parts_00

Manufacturing files🔗

Files Description
PlanktoScope-Case.dxf PlanktoScope Case export for CNC Milling

Tools🔗

Tool Specification
CNC Milling machine minimum traverse path at a minimum size of 600 mm to 1000 mm
End Mill Ø 6mm
End Mill Ø 3mm
End Mill Ø 2mm
End Mill Ø 1mm

case_00

Material🔗

Wood🔗

Valchromat is a wood-based composite material made from recycled wood fibers and colored with natural dyes. It is known for its durability, resistance to moisture and decay, and ability to be machined and finished in a similar way to solid wood. Here are some of the key characteristics of valchromat:

  • Durability: Valchromat is a highly durable material that is resistant to moisture, decay, and termites, making it ideal for use in outdoor or high-moisture environments.

  • Strength: Valchromat has a high mechanical strength, making it suitable for use in structural applications such as flooring, furniture, and doors.

  • Machinability: Valchromat can be machined using traditional woodworking tools, such as saws, routers, and drill bits. It can also be finished using sanding, staining, and painting techniques.

  • Sustainability: Valchromat is made from recycled wood fibers, which makes it a more sustainable option compared to traditional wood products. It is also produced using an eco-friendly manufacturing process that generates zero emissions.

  • Versatility: Valchromat is available in a variety of colors, including shades of red, yellow, green, blue, and black, making it suitable for a wide range of applications and design projects.

valchromat_colors

  • When compared to conventional MDF wood, valchromat has a number of advantages. It is more durable and resistant to moisture and decay, making it a better choice for use in outdoor or high-moisture environments. Valchromat is also more sustainable, as it is made from recycled wood fibers.

  • Valchromat can be processed using a CNC router in a similar way to MDF wood. However, it is important to consider the specific characteristics of valchromat when setting up the CNC router, such as the appropriate cutting speed and feed rate.

For the specific use case of the PlanktoScope Case, valchromat was used with a thickness of 8mm. This thickness may be suitable for a variety of applications, depending on the specific requirements and design of the project.

In summary, valchromat is a durable, strong, and versatile wood-based composite material that can be machined and finished in a similar way to solid wood. It is available in a variety of colors and is a more sustainable alternative to traditional wood products. When processed using a CNC router, it is important to consider the specific characteristics of valchromat in order to achieve the desired results.

Finishing🔗

Rubio Monocoat Plus is a wood finishing product that is designed to provide a durable, natural-looking finish to wood surfaces. It is made from plant-based oils and pigments, which give it a unique, transparent finish that enhances the natural beauty of the wood.

One of the key features of Rubio Monocoat Plus is its versatility and ease of use. It can be applied to a wide range of wood species, including hardwoods and softwoods, and can be used on both indoor and outdoor surfaces. It is also easy to apply, with a simple one-coat application process that allows users to achieve a professional-grade finish in a matter of hours.

Rubio Monocoat Plus is also environmentally friendly, with a low VOC (volatile organic compound) content and a biodegradable formula. This makes it a popular choice for those who are looking for a sustainable and eco-friendly wood finishing solution.

We use Rubio Monocoat Plus as a finishing product for Valchromat.

CNC workflow🔗

Here is a step-by-step guide on how to configure the feed rate and the diameter of the end mill of a CNC milling machine for the production of a workpiece, using the specified tools and configuration:

  1. Select the appropriate end mill: The end mill should be selected based on the material and shape of the workpiece, as well as the desired level of precision. For this specific production, the following end mills will be used:

    • 6mm end mill for straight flats
    • 2mm end mill for inner contours
    • 1mm end mill for small holes

  2. Determine the feed rate: The feed rate is the speed at which the end mill moves along the surface of the workpiece and is usually measured in millimeters per minute (mm/m). The appropriate feed rate will depend on the diameter of the end mill and the material and thickness of the workpiece. For this specific production, the following feed rates will be used:

    • 1500mm/min for 1-2mm end mills
    • 2500mm/min for 3mm end mills
    • 3500mm/min for 6mm end mills

  3. Load the end mill: Once the appropriate end mill has been selected, it can be loaded onto the spindle of the CNC milling machine.

  4. Set the workpiece: The workpiece should be securely clamped onto the table of the CNC milling machine.

  5. Set the machine parameters: The feed rate and end mill diameter should be entered into the machine's control panel or included in the machining program.

  6. Begin machining: The machining process should be carried out in the following sequence:

    • Mill the screw holes with a 2mm end mill and then with a 3mm end mill
    • Mill the corners with a 2mm end mill
    • Mill everything else with a 3mm end mill

By following these steps, you can properly configure the feed rate and the diameter of the end mill of a CNC milling machine for the production of a workpiece. It is important to follow the manufacturer's recommendations and guidelines for the specific CNC milling machine being used, as well as to use proper safety measures while operating the machine.

planktoscope_case_00.png

Finnish of the case parts🔗

Requirements for case parts🔗

Case tools🔗
  • Hammer
  • Air Compressor
  • Rubber gloves
  • Paper carpet pad
  • Clean piece of cotton fabric
  • Support material for drying the parts
Case part parts🔗
  • all case parts
  • Rubio Monocoat Oil Plus 2C
  • Rubio Monocoat Accelerator Component B
  • Magnets
  • Square nuts

Clean🔗

Stir🔗

Apply🔗

Dry🔗

Inserting the screws🔗

Inserting the magnets🔗

Package Housing part🔗

PlanktoScope Hat🔗

Welcome to the PCB production manual for the PlanktoScope Hat!

planktoscope_hat_front.png planktoscope_hat_back.png

A PCB (printed circuit board) is a crucial component of many electronic devices, providing a platform for connecting and mounting electronic components. The PCB production process involves several steps, including designing the PCB layout, fabricating the PCB, and assembling the electronic components onto the PCB.

The raw materials used in PCB production include copper sheets, fiberglass sheets, and various chemicals for etching and plating. These materials are used to create the circuitry patterns on the PCB.

There are two main types of electronic components that can be mounted onto a PCB: thru-hole components and surface mount components. Thru-hole components have leads that are inserted through holes in the PCB and soldered to the other side, while surface mount components are soldered directly onto the surface of the PCB. The choice between thru-hole and surface mount components depends on the specific requirements of the device being produced.

Note

Please note that this document describes a two-part production of the PCB. To reduce costs, the through hole components are assembled manually as described here. Depending on your budget and the services offered by the manufacturing company, this can also be ordered in the production of the PCB.

Manufacturing files🔗

Files Description
Planktoscope-Hat-gerbers.zip The exported Gerber files for PCB fabrication
Planktoscope-Hat-bom.csv The list of used SMD components
Planktoscope-Hat.pdf The SMD assembly footprints
Planktoscope-Hat-PnP-front.txt Pick-and-place machine instructions

PCB manufacturing process🔗

Placing an order🔗

To order a PCB board including assembly, follow these steps:

  • Select a manufacturing company based on your local availability, budget, delivery dates, and services such as assembly.

Note

If you need assistance with selecting a company, contact us. We can provide you with a list of companies we have worked with in the past.

  • Create a customer account if you do not already have one. Ensure to specify the correct tax, contact, and delivery information.

Warning

It is especially crucial to provide correct contact information, including a phone number if possible. Most manufacturing companies provide excellent customer service and will be happy to assist you during the order process.

  • Create a project and select the quantity of PCB boards you need for production.
  • Configure the order based on the values specified in this document.
  • Upload the bill of material (BOM) and validate the component availability.

Warning

It is crucial that you use the exact IC's like the RTC and EEPROM we specified. If a component is "end of life" (EOL), do not hesitate to contact us so we can help you find an alternative solution. For all other components, you are welcome to choose alternatives providet by the manufacturing company.

Info

The component costs will now be calculated, and the price should be displayed.

  • Upload the gerber files provided as a zip file in the repository under the following link.
  • Upload the assembly instructions provided as a zip file in the repository under the following link.
  • Check that there are no missing references in your order configuration.
  • Place the order based on your delivery requirements.
  • Select a payment method and complete the order process.

Configuration🔗

The following configuration parameters can be used for the production of the PCB.

Info

Please note that the naming may vary depanding on the manufacturing company you used and are only intended to provide you with support. You can, of course, adjust the parameters as you see fit.

Board dimensions🔗

65 mm x 100 mm

Circuit specifications🔗
Property Value
Material FR4
Thickness 1.6 mm
Finish Chem. gold
Number of layers 2
Specific stackup sans
SMD sides top
Finished external copper thickness (µ) 35 µm
Internal copper thickness (µ) without
IPC Class Class 2
Solder mask🔗
Property Value
Solder mask TOP + BOT
Mask colour green
Peelable mask without
Marking🔗
Property Value
Silkscreen (ink) TOP + BOT
Ink colour white
ROHS marking without
UL marking without
Date marking without
Specific options🔗
Property Value
Space between tracks > 0.15 mm
Min. drill hole size > 0.20 mm
Blind via with out
Cross blind no
Burried via na
Impedance control no
Edge plating no
Press-fit no
Carbon without
Via Fill without
Beveled edge without
Contersunk holes without
Contersunk holes (qty/PCB) without
Metallographic section without
Gold fingers (thickness) without
Gold fingers (qty/PCB) without

Quality assurance🔗

To ensure the quality of the produced PCB, request data validation from the customer support team. They can provide you with image files like the following to visually verify the manufacturing files you provide.

Warning

This step must be requested directly after completing the order process and confirmed promptly. Otherwise, the delivery date will be postponed or the order may be put on hold completely.

Top🔗

Planktoscope-Hat-validation-top.png

Bottom🔗

Planktoscope-Hat-validation-bottom.png

Copper layer 1🔗

Planktoscope-Hat-validation-layer1.png

Copper layer 2🔗

Planktoscope-Hat-validation-layer2.png

Mechanical🔗

Planktoscope-Hat-validation-mechanical.png

Component placement🔗

Planktoscope-Hat-validation-component-placement.png

Assembly of the Thru-Hole components🔗

Thru-Hole Requirements🔗

Thru-Hole tools🔗
Thru-Hole parts🔗
Files Description
Planktoscope-Hat-bom-through-hole.csv The list of used SMD components

Warning

When you solder this for the first time, take special care not to damage the board.

Info

To learn how to solder we recommend you the awesome Comic "Soldering is easy" by Mitch Altmal, Andie Nordgren and Jeff Keyzer

Soldering of the stepper motor driver🔗

Unpack the motor driver and the connector strips and take the breadboard aside.

Plug the connectors with the appropriate distance to the breadboard.

Info

The breadboard supports you during soldering to ensure the spacing and angle of the connectors, alternatively you can also use a third hand.

Now position the motor driver on the connector strips of the beadboard.

Warning

Make sure that the larger chip labeled trimatik is positioned on the bottom of the board and the four smaller chips are positioned on the top of the board as shown in the picture.

Now solder all pins of the connector strip.

Info

Soldering is sometimes like eating with chopsticks 🥢. It takes a bit of practice, but with time you learn how to hold the workpiece in place with one free finger and apply the solder with another, and then use the other hand to move the soldering iron to the workpiece and solder it.

Tip

You can also solder one pin on one side and then the opposite one to fix your workpiece, this ensures that nothing accidentally moves.

Soldering of the motor driver sockets🔗

Now take the PlanktoScope Hat board and the female connector of the stepper motor driver and position them as shown in the picture.

Now put the previously soldered motor driver on the socket connector to fix it for the soldering process. Turn the board as shown in the picture and place it carefully.

Now solder all pins of the connector strip.

Info

Soldering is sometimes like eating with chopsticks 🥢. It takes a bit of practice, but with time you learn how to hold the workpiece in place with one free finger and apply the solder with another, and then use the other hand to move the soldering iron to the workpiece and solder it.

Tip

You can also solder one pin on one side and then the opposite one to fix your workpiece, this ensures that nothing accidentally moves.

Repeat the procedure with the second motor driver. The end result should look like this.

Soldering the connection sockets🔗

Now solder the motor driver sockets, inserting the connector into the holes as shown.

Turn the board over and hold the loose connector while soldering it. Repeat the procedure with the second motor connector.

Info

Soldering is sometimes like eating with chopsticks 🥢. It takes a bit of practice, but with time you learn how to hold the workpiece in place with one free finger and apply the solder with another, and then use the other hand to move the soldering iron to the workpiece and solder it.

Repeat the procedure with the power connector. The end result should look like this.

Repeat the procedure with the led connector. The end result should look like this.

Soldering the Raspberry Pi connector🔗

Now solder the Raspberry Pi header connector with all 20 pins.

Warning

Be extremely careful when soldering the connections, make sure you don't accidentally bridge several contacts because you used too much solder or have cold solder joints because you had too little solder or too little heat.

Install and solder the cooling fan🔗

Install the fan with the four screws and nuts.

Warning

Pay attention to the running direction with the arrow marking on the side of the fan. The fan should blow on the cooler of the Raspberry Pi.

Cut off the excess cable of the fan and leave about 6 cm.

Feed the fan cable through the hole provided, check if you can reach the contacts on the board without any problems and trim it further if necessary and enisolate the ends.

Solder the fan cables according to the marking and color codes ⚫ GND, 🔴 VCC, 🟡 RPM, 🔵 PWM.

Note

If your fan doesn't have a 🔵 PWM connector, then that's not a problem, you can just leave it out.

Solder the display connector🔗

Insert the pin headers into the holes provided, hold them in place, carefully turn the board over and solder the connector.

Note

If you do not use an OLED display, you do not need to solder the connector.

Solder the configuration option jumpers🔗

Insert the pin headers into the holes provided, hold them in place, carefully turn the board over and solder the connector.

Note

If you do not use an OLED display, you do not need to solder the connector.

You have finished soldering the components🔗

The assembly of the thru-hole components for the planktoscope hat is now complete. The end result should look like this.

PlanktoScope Hard case🔗

Hard case Requirements🔗

Hard case tools🔗

  • double sided adhesive tape

Hard case parts🔗

  • Hard case

Case and double sided adhesive tape

Foam preparation🔗

Divide foam

Cut the foam block at the outer edge by gently tearing it apart with your fingers.

Warning

Be careful the foam tears easily and can not be repaired.

Tip

You can try in the middle of the foam block to see how the material can be cut through before you peel off with the edge.

Foam glue

Now lay a layer of two-sided adhesive tape on the upper inside edge of the case, with which we can later attach the show fabric.

Insert foam

Now insert the foam edge in to the case and glue it to the outer wall.

Note

Before you fix the foam, position it completely and check that it is placed flush with the edge of the case.

Kit composition🔗

Now divide all the components for the kit, and pack it in the hard case. You can find the full list of components for the kit in the v2.5 hardware BOM (Bill of Materials). However, this BOM does not include ordering links, since such links will need to be different for each country. If you've customized the v2.5 hardware BOM for your own v2.5 PlanktoScope kit (e.g. by finding and adding part ordering links from suppliers in your country for each component), please share your custom BOM to our GitHub Discussions thread for v2.5 Localized Hardware BOMs, so that other members of our community can learn from your work!

Kit Manufacturing🔗

manufacturing guide

Mechanical Structure🔗

CNC (computer numerical control) milling machines are used to fabricate parts with precise dimensions and shapes. The configuration of the feed rate and diameter plays a crucial role in the machining process and can significantly affect the quality and efficiency of the production of a workpiece.

case_parts_00

Manufacturing files🔗

Files Description
PlanktoScope-Case.dxf PlanktoScope Case export for CNC Milling

Tools🔗

Tool Specification
CNC Milling machine minimum traverse path at a minimum size of 600 mm to 1000 mm
End Mill Ø 6mm
End Mill Ø 3mm
End Mill Ø 2mm
End Mill Ø 1mm

case_00

Material🔗

Wood🔗

Valchromat is a wood-based composite material made from recycled wood fibers and colored with natural dyes. It is known for its durability, resistance to moisture and decay, and ability to be machined and finished in a similar way to solid wood. Here are some of the key characteristics of valchromat:

  • Durability: Valchromat is a highly durable material that is resistant to moisture, decay, and termites, making it ideal for use in outdoor or high-moisture environments.

  • Strength: Valchromat has a high mechanical strength, making it suitable for use in structural applications such as flooring, furniture, and doors.

  • Machinability: Valchromat can be machined using traditional woodworking tools, such as saws, routers, and drill bits. It can also be finished using sanding, staining, and painting techniques.

  • Sustainability: Valchromat is made from recycled wood fibers, which makes it a more sustainable option compared to traditional wood products. It is also produced using an eco-friendly manufacturing process that generates zero emissions.

  • Versatility: Valchromat is available in a variety of colors, including shades of red, yellow, green, blue, and black, making it suitable for a wide range of applications and design projects.

valchromat_colors

  • When compared to conventional MDF wood, valchromat has a number of advantages. It is more durable and resistant to moisture and decay, making it a better choice for use in outdoor or high-moisture environments. Valchromat is also more sustainable, as it is made from recycled wood fibers.

  • Valchromat can be processed using a CNC router in a similar way to MDF wood. However, it is important to consider the specific characteristics of valchromat when setting up the CNC router, such as the appropriate cutting speed and feed rate.

For the specific use case of the PlanktoScope Case, valchromat was used with a thickness of 8mm. This thickness may be suitable for a variety of applications, depending on the specific requirements and design of the project.

In summary, valchromat is a durable, strong, and versatile wood-based composite material that can be machined and finished in a similar way to solid wood. It is available in a variety of colors and is a more sustainable alternative to traditional wood products. When processed using a CNC router, it is important to consider the specific characteristics of valchromat in order to achieve the desired results.

Finishing🔗

Rubio Monocoat Plus is a wood finishing product that is designed to provide a durable, natural-looking finish to wood surfaces. It is made from plant-based oils and pigments, which give it a unique, transparent finish that enhances the natural beauty of the wood.

One of the key features of Rubio Monocoat Plus is its versatility and ease of use. It can be applied to a wide range of wood species, including hardwoods and softwoods, and can be used on both indoor and outdoor surfaces. It is also easy to apply, with a simple one-coat application process that allows users to achieve a professional-grade finish in a matter of hours.

Rubio Monocoat Plus is also environmentally friendly, with a low VOC (volatile organic compound) content and a biodegradable formula. This makes it a popular choice for those who are looking for a sustainable and eco-friendly wood finishing solution.

We use Rubio Monocoat Plus as a finishing product for Valchromat.

CNC workflow🔗

Here is a step-by-step guide on how to configure the feed rate and the diameter of the end mill of a CNC milling machine for the production of a workpiece, using the specified tools and configuration:

  1. Select the appropriate end mill: The end mill should be selected based on the material and shape of the workpiece, as well as the desired level of precision. For this specific production, the following end mills will be used:

    • 6mm end mill for straight flats
    • 2mm end mill for inner contours
    • 1mm end mill for small holes

  2. Determine the feed rate: The feed rate is the speed at which the end mill moves along the surface of the workpiece and is usually measured in millimeters per minute (mm/m). The appropriate feed rate will depend on the diameter of the end mill and the material and thickness of the workpiece. For this specific production, the following feed rates will be used:

    • 1500mm/min for 1-2mm end mills
    • 2500mm/min for 3mm end mills
    • 3500mm/min for 6mm end mills

  3. Load the end mill: Once the appropriate end mill has been selected, it can be loaded onto the spindle of the CNC milling machine.

  4. Set the workpiece: The workpiece should be securely clamped onto the table of the CNC milling machine.

  5. Set the machine parameters: The feed rate and end mill diameter should be entered into the machine's control panel or included in the machining program.

  6. Begin machining: The machining process should be carried out in the following sequence:

    • Mill the screw holes with a 2mm end mill and then with a 3mm end mill
    • Mill the corners with a 2mm end mill
    • Mill everything else with a 3mm end mill

By following these steps, you can properly configure the feed rate and the diameter of the end mill of a CNC milling machine for the production of a workpiece. It is important to follow the manufacturer's recommendations and guidelines for the specific CNC milling machine being used, as well as to use proper safety measures while operating the machine.

planktoscope_case_00.png

Finnish of the case parts🔗

Requirements for case parts🔗

Case tools🔗
  • Hammer
  • Air Compressor
  • Rubber gloves
  • Paper carpet pad
  • Clean piece of cotton fabric
  • Support material for drying the parts
Case part parts🔗
  • all case parts
  • Rubio Monocoat Oil Plus 2C
  • Rubio Monocoat Accelerator Component B
  • Magnets
  • Square nuts

Clean🔗

Stir🔗

Apply🔗

Dry🔗

Inserting the screws🔗

Inserting the magnets🔗

Package Housing part🔗

PlanktoScope Hat🔗

Welcome to the PCB production manual for the PlanktoScope Hat!

planktoscope_hat_front.png planktoscope_hat_back.png

A PCB (printed circuit board) is a crucial component of many electronic devices, providing a platform for connecting and mounting electronic components. The PCB production process involves several steps, including designing the PCB layout, fabricating the PCB, and assembling the electronic components onto the PCB.

The raw materials used in PCB production include copper sheets, fiberglass sheets, and various chemicals for etching and plating. These materials are used to create the circuitry patterns on the PCB.

There are two main types of electronic components that can be mounted onto a PCB: thru-hole components and surface mount components. Thru-hole components have leads that are inserted through holes in the PCB and soldered to the other side, while surface mount components are soldered directly onto the surface of the PCB. The choice between thru-hole and surface mount components depends on the specific requirements of the device being produced.

Note

Please note that this document describes a two-part production of the PCB. To reduce costs, the through hole components are assembled manually as described here. Depending on your budget and the services offered by the manufacturing company, this can also be ordered in the production of the PCB.

Manufacturing files🔗

Files Description
Planktoscope-Hat-gerbers.zip The exported Gerber files for PCB fabrication
Planktoscope-Hat-bom.csv The list of used SMD components
Planktoscope-Hat.pdf The SMD assembly footprints
Planktoscope-Hat-PnP-front.txt Pick-and-place machine instructions

PCB manufacturing process🔗

Placing an order🔗

To order a PCB board including assembly, follow these steps:

  • Select a manufacturing company based on your local availability, budget, delivery dates, and services such as assembly.

Note

If you need assistance with selecting a company, contact us. We can provide you with a list of companies we have worked with in the past.

  • Create a customer account if you do not already have one. Ensure to specify the correct tax, contact, and delivery information.

Warning

It is especially crucial to provide correct contact information, including a phone number if possible. Most manufacturing companies provide excellent customer service and will be happy to assist you during the order process.

  • Create a project and select the quantity of PCB boards you need for production.
  • Configure the order based on the values specified in this document.
  • Upload the bill of material (BOM) and validate the component availability.

Warning

It is crucial that you use the exact IC's like the RTC and EEPROM we specified. If a component is "end of life" (EOL), do not hesitate to contact us so we can help you find an alternative solution. For all other components, you are welcome to choose alternatives providet by the manufacturing company.

Info

The component costs will now be calculated, and the price should be displayed.

  • Upload the gerber files provided as a zip file in the repository under the following link.
  • Upload the assembly instructions provided as a zip file in the repository under the following link.
  • Check that there are no missing references in your order configuration.
  • Place the order based on your delivery requirements.
  • Select a payment method and complete the order process.

Configuration🔗

The following configuration parameters can be used for the production of the PCB.

Info

Please note that the naming may vary depanding on the manufacturing company you used and are only intended to provide you with support. You can, of course, adjust the parameters as you see fit.

Board dimensions🔗

65 mm x 100 mm

Circuit specifications🔗
Property Value
Material FR4
Thickness 1.6 mm
Finish Chem. gold
Number of layers 2
Specific stackup sans
SMD sides top
Finished external copper thickness (µ) 35 µm
Internal copper thickness (µ) without
IPC Class Class 2
Solder mask🔗
Property Value
Solder mask TOP + BOT
Mask colour green
Peelable mask without
Marking🔗
Property Value
Silkscreen (ink) TOP + BOT
Ink colour white
ROHS marking without
UL marking without
Date marking without
Specific options🔗
Property Value
Space between tracks > 0.15 mm
Min. drill hole size > 0.20 mm
Blind via with out
Cross blind no
Burried via na
Impedance control no
Edge plating no
Press-fit no
Carbon without
Via Fill without
Beveled edge without
Contersunk holes without
Contersunk holes (qty/PCB) without
Metallographic section without
Gold fingers (thickness) without
Gold fingers (qty/PCB) without

Quality assurance🔗

To ensure the quality of the produced PCB, request data validation from the customer support team. They can provide you with image files like the following to visually verify the manufacturing files you provide.

Warning

This step must be requested directly after completing the order process and confirmed promptly. Otherwise, the delivery date will be postponed or the order may be put on hold completely.

Top🔗

Planktoscope-Hat-validation-top.png

Bottom🔗

Planktoscope-Hat-validation-bottom.png

Copper layer 1🔗

Planktoscope-Hat-validation-layer1.png

Copper layer 2🔗

Planktoscope-Hat-validation-layer2.png

Mechanical🔗

Planktoscope-Hat-validation-mechanical.png

Component placement🔗

Planktoscope-Hat-validation-component-placement.png

Assembly of the Thru-Hole components🔗

Thru-Hole Requirements🔗

Thru-Hole tools🔗
Thru-Hole parts🔗
Files Description
Planktoscope-Hat-bom-through-hole.csv The list of used SMD components

Warning

When you solder this for the first time, take special care not to damage the board.

Info

To learn how to solder we recommend you the awesome Comic "Soldering is easy" by Mitch Altmal, Andie Nordgren and Jeff Keyzer

Soldering of the stepper motor driver🔗

Unpack the motor driver and the connector strips and take the breadboard aside.

Plug the connectors with the appropriate distance to the breadboard.

Info

The breadboard supports you during soldering to ensure the spacing and angle of the connectors, alternatively you can also use a third hand.

Now position the motor driver on the connector strips of the beadboard.

Warning

Make sure that the larger chip labeled trimatik is positioned on the bottom of the board and the four smaller chips are positioned on the top of the board as shown in the picture.

Now solder all pins of the connector strip.

Info

Soldering is sometimes like eating with chopsticks 🥢. It takes a bit of practice, but with time you learn how to hold the workpiece in place with one free finger and apply the solder with another, and then use the other hand to move the soldering iron to the workpiece and solder it.

Tip

You can also solder one pin on one side and then the opposite one to fix your workpiece, this ensures that nothing accidentally moves.

Soldering of the motor driver sockets🔗

Now take the PlanktoScope Hat board and the female connector of the stepper motor driver and position them as shown in the picture.

Now put the previously soldered motor driver on the socket connector to fix it for the soldering process. Turn the board as shown in the picture and place it carefully.

Now solder all pins of the connector strip.

Info

Soldering is sometimes like eating with chopsticks 🥢. It takes a bit of practice, but with time you learn how to hold the workpiece in place with one free finger and apply the solder with another, and then use the other hand to move the soldering iron to the workpiece and solder it.

Tip

You can also solder one pin on one side and then the opposite one to fix your workpiece, this ensures that nothing accidentally moves.

Repeat the procedure with the second motor driver. The end result should look like this.

Soldering the connection sockets🔗

Now solder the motor driver sockets, inserting the connector into the holes as shown.

Turn the board over and hold the loose connector while soldering it. Repeat the procedure with the second motor connector.

Info

Soldering is sometimes like eating with chopsticks 🥢. It takes a bit of practice, but with time you learn how to hold the workpiece in place with one free finger and apply the solder with another, and then use the other hand to move the soldering iron to the workpiece and solder it.

Repeat the procedure with the power connector. The end result should look like this.

Repeat the procedure with the led connector. The end result should look like this.

Soldering the Raspberry Pi connector🔗

Now solder the Raspberry Pi header connector with all 20 pins.

Warning

Be extremely careful when soldering the connections, make sure you don't accidentally bridge several contacts because you used too much solder or have cold solder joints because you had too little solder or too little heat.

Install and solder the cooling fan🔗

Install the fan with the four screws and nuts.

Warning

Pay attention to the running direction with the arrow marking on the side of the fan. The fan should blow on the cooler of the Raspberry Pi.

Cut off the excess cable of the fan and leave about 6 cm.

Feed the fan cable through the hole provided, check if you can reach the contacts on the board without any problems and trim it further if necessary and enisolate the ends.

Solder the fan cables according to the marking and color codes ⚫ GND, 🔴 VCC, 🟡 RPM, 🔵 PWM.

Note

If your fan doesn't have a 🔵 PWM connector, then that's not a problem, you can just leave it out.

Solder the display connector🔗

Insert the pin headers into the holes provided, hold them in place, carefully turn the board over and solder the connector.

Note

If you do not use an OLED display, you do not need to solder the connector.

Solder the configuration option jumpers🔗

Insert the pin headers into the holes provided, hold them in place, carefully turn the board over and solder the connector.

Note

If you do not use an OLED display, you do not need to solder the connector.

You have finished soldering the components🔗

The assembly of the thru-hole components for the planktoscope hat is now complete. The end result should look like this.

PlanktoScope Hard case🔗

Hard case Requirements🔗

Hard case tools🔗

  • double sided adhesive tape

Hard case parts🔗

  • Hard case

Case and double sided adhesive tape

Foam preparation🔗

Divide foam

Cut the foam block at the outer edge by gently tearing it apart with your fingers.

Warning

Be careful the foam tears easily and can not be repaired.

Tip

You can try in the middle of the foam block to see how the material can be cut through before you peel off with the edge.

Foam glue

Now lay a layer of two-sided adhesive tape on the upper inside edge of the case, with which we can later attach the show fabric.

Insert foam

Now insert the foam edge in to the case and glue it to the outer wall.

Note

Before you fix the foam, position it completely and check that it is placed flush with the edge of the case.

Kit composition🔗

Now divide all the components for the kit, and pack it in the hard case. You can find the full list of components for the kit in the v2.5 hardware BOM (Bill of Materials). However, this BOM does not include ordering links, since such links will need to be different for each country. If you've customized the v2.5 hardware BOM for your own v2.5 PlanktoScope kit (e.g. by finding and adding part ordering links from suppliers in your country for each component), please share your custom BOM to our GitHub Discussions thread for v2.5 Localized Hardware BOMs, so that other members of our community can learn from your work!

Setup🔗

This section of the PlanktoScope documentation will help you get to a working PlanktoScope. Every PlanktoScope has two aspects which have to work together: the hardware and the software. Depending on what hardware you already have, you should start at different places in the documentation:

  • "I have a product from FairScope": you probably received either a fully-assembled Planktoscope or a PlanktoScope do-it-yourself assembly kit. For more information, see the FairScope product section of this page.
  • "I have a fully assembled PlanktoScope, and it was not assembled by FairScope": you will need to ensure that you have the latest version of the PlanktoScope software installed on the PlanktoScope, and that the PlanktoScope hardware works. For more information, see the Fully-assembled PlanktoScope section of this page.
  • "I have a kit of hardware parts to assemble into a PlanktoScope, and it was not provided by FairScope": you will need to assemble your PlanktoScope hardware and then set up the software on it. For more information, see the DIY kit section of this page.
  • "I don't have any of the hardware for the PlanktoScope": you have several options for getting the PlanktoScope hardware. For more information, see the No hardware yet section of this page.

FairScope product🔗

You probably purchased either a fully-assembled PlanktoScope or a do-it-yourself assembly kit from FairScope. The various sections of this documentation will provide you with instructions for how to proceed:

  • If you purchased a fully-assembled PlanktoScope, it is ready for you to use! You should go to our operation guide to learn how to operate your PlanktoScope.
  • If you purchased a do-it-yourself assembly kit from FairScope, you should go to our hardware setup guide to learn how to assemble your kit into a working PlanktoScope. The software will already have been set up for you, so after you finish setting up the hardware you can proceed to our operation guide to learn how to operate your PlanktoScope.

Fully-assembled PlanktoScope🔗

If you have a fully-assembled PlanktoScope which was provided to you by FairScope, please refer instead to the Fairscope product section of this page. If someone else provided you with a PlanktoScope, you might need to do some additional hardware setup, software setup, calibration, and/or troubleshooting - please talk to them to figure out what might be needed. The various sections of this documentation site may be a useful resource for you:

  • Depending on what software is pre-installed on your PlanktoScope, and how old the software is, our software setup guide may be useful to help you update the software. You should always ensure that you are running the most recent available version of the PlanktoScope software.
  • Depending on what software configuration your PlanktoScope is running, our operation guide may be useful to help you operate your PlanktoScope.

DIY kit🔗

If you have a DIY assembly kit which was provided to you by FairScope, please refer instead to the Fairscope product section of this page. If someone else provided you with a DIY assembly kit, the process for assembling it into a PlanktoScope may be different from what is described in this documentation site - please talk to them to figure out what you should do. The various sections of this documentation site may be a useful resource for you:

  • Depending on what is included in your DIY kit, our hardware setup guide may be useful to assemble a PlanktoScope from your kit.
  • Depending on what is on the micro-SD card included with your DIY kit (if it includes a micro-SD card), our software setup guide may be useful to help you update the software. You should always ensure that you are running the most recent available version of the PlanktoScope software.
  • Depending on what software configuration your PlanktoScope is running, our operation guide may be useful to help you operate your PlanktoScope.

No hardware yet🔗

If you don't have any hardware for a PlanktoScope yet, you have a few options depending on how much work you want to do, what your budget is, and how much troubleshooting you are willing to do:

  1. Purchase a fully pre-assembled PlanktoScope.
  2. Purchase a DIY kit of parts to assemble into a PlanktoScope.
  3. Both make your own kit of parts and assemble it into a PlanktoScope.

Buy a pre-assembled PlanktoScope🔗

You can buy a PlanktoScope from FairScope, which is a small business started by the inventor of the PlanktoScope in order to make it easier for people to obtain PlanktoScopes. If you buy a PlanktoScope from FairScope, it will be fully standard, fully assembled, and fully tested. It will already have been calibrated in order to produce scientific data which can be compared with data from other PlanktoScopes, without requiring you to perform any additional calibration steps. The software will be pre-installed, so that once you receive your PlanktoScope you can immediately start using it.

We recommend this approach for:

  • Anyone who wants a PlanktoScope which "just works" out-of-the-box.
  • Scientists who just want to collect data and don't want to become engineers.
  • Anyone who just wants to use the PlanktoScope as a tool, rather than tinkering with their PlanktoScope as a project.

Buy a DIY kit🔗

If you are on a budget which does not allow you to buy a fully-assembled PlanktoScope from FairScope, you can instead buy a do-it-yourself assembly kit from FairScope. By assembling your PlanktoScope yourself, you will gain a deeper understanding of how it works, how to troubleshoot any problems you might encounter, and how to repair your PlanktoScope if you damage its hardware. If you make any mistakes while assembling the PlanktoScope, you will have to do some troubleshooting. You will also need to calibrate your PlanktoScope if you want to use it to produce data useful for scientists.

We recommend this approach for:

  • Anyone who wants a standard PlanktoScope but is on a limited budget, and has some interest in building things and troubleshooting problems.
  • Anyone who wants to approach the PlanktoScope as a project and not just a tool, but who has a limited tolerance of technical complexity.
  • Anyone who wants a do-it-yourself experience but does not have access to a laser cutter or CNC mill.
  • Anyone who wants a standard set of parts as the foundation for customizing their PlanktoScope.
  • Engineers and makers who don't want to worry about figuring out suppliers and making their own one-time supply chain in order to obtain all the hardware parts needed to build a single PlanktoScope.

Make a kit and assemble it🔗

If you don't want to purchase a pre-assembled PlanktoScope or a DIY assembly kit from FairScope, you will need to make your own assembly kit, and then assemble it into a PlanktoScope. This will require identifying sellers who will provide you with the necessary parts, and it will require identifying a way either to fabricate various mechanical parts yourself or to use a commercial service to fabricate those parts for you. Depending on which version of the PlanktoScope hardware you want to build, you might also need to assemble a custom printed circuit board (or work with a commercial service to assemble it for you). Once you have a kit, you can begin to assemble your PlanktoScope from it. You will almost certainly have to do some troubleshooting of problems with how you assembled your hardware, which is a great learning opportunity - but only if you're interested in it.

We recommend this approach for:

  • Anyone who is on an extremely limited budget but has lots of time and some hardware engineering experience.
  • Makers who are already familiar with laser cutting or CNC milling, and with soldering or PCB assembly (the necessary skills will depend on the version of PlanktoScope hardware being built).
  • Hobbyists and students who are primarily interested in the PlanktoScope as an engineering project and want to figure out everything by themselves.
  • Anyone who wants to design and build an extremely non-standard PlanktoScope, whether for fun or to use it for unconventional purposes.

Next steps🔗

After finishing any necessary hardware setup and all necessary software setup for your PlanktoScope, you can proceed to our guide on how to operate your PlanktoScope.

Setup🔗

This section of the PlanktoScope documentation will help you get to a working PlanktoScope. Every PlanktoScope has two aspects which have to work together: the hardware and the software. Depending on what hardware you already have, you should start at different places in the documentation:

  • "I have a product from FairScope": you probably received either a fully-assembled Planktoscope or a PlanktoScope do-it-yourself assembly kit. For more information, see the FairScope product section of this page.
  • "I have a fully assembled PlanktoScope, and it was not assembled by FairScope": you will need to ensure that you have the latest version of the PlanktoScope software installed on the PlanktoScope, and that the PlanktoScope hardware works. For more information, see the Fully-assembled PlanktoScope section of this page.
  • "I have a kit of hardware parts to assemble into a PlanktoScope, and it was not provided by FairScope": you will need to assemble your PlanktoScope hardware and then set up the software on it. For more information, see the DIY kit section of this page.
  • "I don't have any of the hardware for the PlanktoScope": you have several options for getting the PlanktoScope hardware. For more information, see the No hardware yet section of this page.

FairScope product🔗

You probably purchased either a fully-assembled PlanktoScope or a do-it-yourself assembly kit from FairScope. The various sections of this documentation will provide you with instructions for how to proceed:

  • If you purchased a fully-assembled PlanktoScope, it is ready for you to use! You should go to our operation guide to learn how to operate your PlanktoScope.
  • If you purchased a do-it-yourself assembly kit from FairScope, you should go to our hardware setup guide to learn how to assemble your kit into a working PlanktoScope. The software will already have been set up for you, so after you finish setting up the hardware you can proceed to our operation guide to learn how to operate your PlanktoScope.

Fully-assembled PlanktoScope🔗

If you have a fully-assembled PlanktoScope which was provided to you by FairScope, please refer instead to the Fairscope product section of this page. If someone else provided you with a PlanktoScope, you might need to do some additional hardware setup, software setup, calibration, and/or troubleshooting - please talk to them to figure out what might be needed. The various sections of this documentation site may be a useful resource for you:

  • Depending on what software is pre-installed on your PlanktoScope, and how old the software is, our software setup guide may be useful to help you update the software. You should always ensure that you are running the most recent available version of the PlanktoScope software.
  • Depending on what software configuration your PlanktoScope is running, our operation guide may be useful to help you operate your PlanktoScope.

DIY kit🔗

If you have a DIY assembly kit which was provided to you by FairScope, please refer instead to the Fairscope product section of this page. If someone else provided you with a DIY assembly kit, the process for assembling it into a PlanktoScope may be different from what is described in this documentation site - please talk to them to figure out what you should do. The various sections of this documentation site may be a useful resource for you:

  • Depending on what is included in your DIY kit, our hardware setup guide may be useful to assemble a PlanktoScope from your kit.
  • Depending on what is on the micro-SD card included with your DIY kit (if it includes a micro-SD card), our software setup guide may be useful to help you update the software. You should always ensure that you are running the most recent available version of the PlanktoScope software.
  • Depending on what software configuration your PlanktoScope is running, our operation guide may be useful to help you operate your PlanktoScope.

No hardware yet🔗

If you don't have any hardware for a PlanktoScope yet, you have a few options depending on how much work you want to do, what your budget is, and how much troubleshooting you are willing to do:

  1. Purchase a fully pre-assembled PlanktoScope.
  2. Purchase a DIY kit of parts to assemble into a PlanktoScope.
  3. Both make your own kit of parts and assemble it into a PlanktoScope.

Buy a pre-assembled PlanktoScope🔗

You can buy a PlanktoScope from FairScope, which is a small business started by the inventor of the PlanktoScope in order to make it easier for people to obtain PlanktoScopes. If you buy a PlanktoScope from FairScope, it will be fully standard, fully assembled, and fully tested. It will already have been calibrated in order to produce scientific data which can be compared with data from other PlanktoScopes, without requiring you to perform any additional calibration steps. The software will be pre-installed, so that once you receive your PlanktoScope you can immediately start using it.

We recommend this approach for:

  • Anyone who wants a PlanktoScope which "just works" out-of-the-box.
  • Scientists who just want to collect data and don't want to become engineers.
  • Anyone who just wants to use the PlanktoScope as a tool, rather than tinkering with their PlanktoScope as a project.

Buy a DIY kit🔗

If you are on a budget which does not allow you to buy a fully-assembled PlanktoScope from FairScope, you can instead buy a do-it-yourself assembly kit from FairScope. By assembling your PlanktoScope yourself, you will gain a deeper understanding of how it works, how to troubleshoot any problems you might encounter, and how to repair your PlanktoScope if you damage its hardware. If you make any mistakes while assembling the PlanktoScope, you will have to do some troubleshooting. You will also need to calibrate your PlanktoScope if you want to use it to produce data useful for scientists.

We recommend this approach for:

  • Anyone who wants a standard PlanktoScope but is on a limited budget, and has some interest in building things and troubleshooting problems.
  • Anyone who wants to approach the PlanktoScope as a project and not just a tool, but who has a limited tolerance of technical complexity.
  • Anyone who wants a do-it-yourself experience but does not have access to a laser cutter or CNC mill.
  • Anyone who wants a standard set of parts as the foundation for customizing their PlanktoScope.
  • Engineers and makers who don't want to worry about figuring out suppliers and making their own one-time supply chain in order to obtain all the hardware parts needed to build a single PlanktoScope.

Make a kit and assemble it🔗

If you don't want to purchase a pre-assembled PlanktoScope or a DIY assembly kit from FairScope, you will need to make your own assembly kit, and then assemble it into a PlanktoScope. This will require identifying sellers who will provide you with the necessary parts, and it will require identifying a way either to fabricate various mechanical parts yourself or to use a commercial service to fabricate those parts for you. Depending on which version of the PlanktoScope hardware you want to build, you might also need to assemble a custom printed circuit board (or work with a commercial service to assemble it for you). Once you have a kit, you can begin to assemble your PlanktoScope from it. You will almost certainly have to do some troubleshooting of problems with how you assembled your hardware, which is a great learning opportunity - but only if you're interested in it.

We recommend this approach for:

  • Anyone who is on an extremely limited budget but has lots of time and some hardware engineering experience.
  • Makers who are already familiar with laser cutting or CNC milling, and with soldering or PCB assembly (the necessary skills will depend on the version of PlanktoScope hardware being built).
  • Hobbyists and students who are primarily interested in the PlanktoScope as an engineering project and want to figure out everything by themselves.
  • Anyone who wants to design and build an extremely non-standard PlanktoScope, whether for fun or to use it for unconventional purposes.

Next steps🔗

After finishing any necessary hardware setup and all necessary software setup for your PlanktoScope, you can proceed to our guide on how to operate your PlanktoScope.

Post-Installation Configuration🔗

After installing the PlanktoScope software onto your PlanktoScope, you will need to configure the software to match your PlanktoScope hardware and your operational requirements.

Currently, all post-installation configuration is performed in the PlanktoScope software's Node-RED dashboard. To access it, you should first open the PlanktoScope's landing page in your web browser, e.g. following the instructions in the software installation guide. Then you should click the "Node-RED dashboard" link at the top of the "Browser applications" section of the landing page.

Hardware Settings🔗

You will need to choose hardware settings for the PlanktoScope software to match the actual configuration of your PlanktoScope hardware. To do this, open the navigation sidebar of the Node-RED dashboard and go to the "Hardware Settings" page. You will see a dropdown menu to select the hardware version. You should select the correct version for your PlanktoScope. This will replace all existing hardware settings with the default settings for that PlanktoScope hardware version.

Next steps🔗

Now that you have configured the PlanktoScope software, you can proceed to our guide on how to operate your PlanktoScope.

Post-Installation Configuration🔗

After installing the PlanktoScope software onto your PlanktoScope, you will need to configure the software to match your PlanktoScope hardware and your operational requirements.

Currently, all post-installation configuration is performed in the PlanktoScope software's Node-RED dashboard. To access it, you should first open the PlanktoScope's landing page in your web browser, e.g. following the instructions in the software installation guide. Then you should click the "Node-RED dashboard" link at the top of the "Browser applications" section of the landing page.

Hardware Version🔗

Info

This step is only required if you are using a planktoscopehat SD card image; it is not needed on the adafruithat and fairscope-latest SD card images.

The first time you start the PlanktoScope, you will need to select the hardware version of your PlanktoScope for the PlanktoScope software to match the actual configuration of your PlanktoScope hardware. To do this, open the Node-RED dashboard. You should see a homepage with a drop-down menu to select your PlanktoScope hardware version. You should select the correct version for your PlanktoScope. After you select a hardware version, the PlanktoScope will show the Node-RED dashboard's normal homepage navigation buttons; you should also wait several seconds for the PlanktoScope software to restart and load the updated hardware settings.

Next steps🔗

Now that you have configured the PlanktoScope software, you can proceed to our guide on how to operate your PlanktoScope.

PlanktoScope Software🔗

This section of the PlanktoScope documentation will help you to set up the necessary software for your PlanktoScope hardware. Our documentation splits the PlanktoScope software setup process into two phases: installing the PlanktoScope software onto the micro-SD card of the Raspberry Pi computer in your PlanktoScope, and configuring the PlanktoScope software after installation.

The PlanktoScope software is an operating system, the PlanktoScope OS, distributed as an SD card image to be run on the PlanktoScope hardware's embedded Raspberry Pi computer.

If you are building your own PlanktoScope from your own hardware kit, you will need to install and set up the PlanktoScope OS yourself. If you received a PlanktoScope from FairScope, a working and pre-configured version of the PlanktoScope OS is already pre-installed, and you can skip the software setup process and proceed to our guide on how to operate your PlanktoScope. - but you still might wish to update your PlanktoScope to the latest release of the PlanktoScope OS, in which case you should reinstall the PlanktoScope software by going through our software setup guide below.

In order to install the PlanktoScope software, you will first need to choose an SD card image file to use for installation, and then you will install that SD card image and perform some configuration of the software.

Choosing an SD card image🔗

PlanktoScope SD card image files are identified with a version number as well as a hardware configuration tag - for example, the SD card image file named planktoscope-v2024.0.0+planktoscopehat.img.gz is for v2020.0.0 of the PlanktoScope OS, configured to work with versions of the PlanktoScope hardware based on the custom PlanktoScope HAT (rather than the Adafruit Stepper Motor HAT). Thus, you will need to choose both a version number (e.g. v2023.9.0) and a hardware configuration (e.g. planktoscopehat).

PlanktoScope OS versions🔗

Because the PlanktoScope project aims to release occasional updates to the PlanktoScope OS in order to fix various software problems and make various improvements to the software, multiple versions of the PlanktoScope OS exist, and new versions will be released in the future. In general, each version of the PlanktoScope OS will be compatible with all previous officially-released versions of the PlanktoScope hardware (which are all versions listed in the hardware changelog without the description of a "prototype"). The PlanktoScope documentation describes the latest stable release of the PlanktoScope OS, and you should always use the latest stable release on your PlanktoScopes.

PlanktoScope OS versions are independent of hardware versions, and (starting in 2023) use a different version numbering system from the hardware (see the Hardware setup guide for an overview of some hardware versions). Now, OS version numbers have three numeric components: the year of the release, a minor number (which is incremented for releases with new features and/or backwards-incompatible changes), and a patch number (which is incremented for minor bugfixes). You may see references to the following SD card image versions in online discussions of the PlanktoScope software:

  • v2.3: this release, from December 2021, was the last release of the PlanktoScope software in the old version numbering system in which the software and hardware were released together. The v2.3 OS is preinstalled on most PlanktoScopes sold by FairScope during 2023.

  • v2023.9.0: this release, from the end of 2023, is the first software release in the new version numbering system, and it is currently the latest release of the PlanktoScope OS. The number 9 should not be interpreted as having any special meaning.

  • v2024.0.0: this version is the first release of the PlanktoScope OS in 2024.

  • v2024.1.0: this version will be the second release of the PlanktoScope OS in 2024.

Hardware configurations🔗

Currently, each version of the PlanktoScope OS is provided as two SD card images, corresponding to the two different hardware configurations supported by the PlanktoScope software:

  • adafruithat: this configuration of the PlanktoScope OS is compatible with v2.1 of the PlanktoScope hardware, which uses the Adafruit Stepper Motor HAT. The default configuration files are for hardware v2.1, but you can select other hardware versions in the post-installation configuration process.

  • planktoscopehat: this configuration of the PlanktoScope OS is compatible with all versions of the PlanktoScope hardware starting with hardware v2.3; those hardware versions use a custom HAT. Note that in software versions v2.3 and v2023.9.0, the word pscopehat was used instead of planktoscopehat. The default configuration files are for hardware v2.5, but you can select other hardware versions in the post-installation configuration process.

  • fairscope-latest: this configuration of the PlanktoScope OS is identical to the planktoscopehat, but it also changes the default configuration files to be for hardware version v2.6 instead of hardware version 2.5.

If you have a PlanktoScope from FairScope, you should probably use the fairscope-latest SD card image; otherwise, if you have a non-FairScope PlanktoScope with hardware version v2.3 or later, you should probably use the planktoscopehat SD card image; otherwise, if you have a v2.1 PlanktoScope, you should probably use an adafruithat SD card image.

Installation🔗

After you have chosen a PlanktoScope OS SD card image for the desired OS version and hardware configuration, you should follow our standard installation guide in order to install that SD card image into your PlanktoScope. If the official PlanktoScope SD card images don't meet your requirements and you have successfully set up and used the PlanktoScope OS in the past via the standard installation process, then you may also find the non-standard installation guide useful.

Post-installation configuration🔗

The first time you start the PlanktoScope after installing or updating the software, you should change some settings in the PlanktoScope software in order to match the configuration of your PlanktoScope hardware. Refer to our post-installation configuration guide for details.

Next steps🔗

After installing the PlanktoScope software (or after ensuring that the PlanktoScope software is installed) and performing all necessary post-installation configuration, then you can proceed to our guide on how to operate your PlanktoScope.

PlanktoScope Software🔗

This section of the PlanktoScope documentation will help you to set up the necessary software for your PlanktoScope hardware. Our documentation splits the PlanktoScope software setup process into two phases: installing the PlanktoScope software onto the micro-SD card of the Raspberry Pi computer in your PlanktoScope, and configuring the PlanktoScope software after installation.

The PlanktoScope software is an operating system, the PlanktoScope OS, distributed as an SD card image to be run on the PlanktoScope hardware's embedded Raspberry Pi computer.

If you are building your own PlanktoScope from your own hardware kit, you will need to install and set up the PlanktoScope OS yourself. If you received a PlanktoScope from FairScope, a working and pre-configured version of the PlanktoScope OS is already pre-installed, and you can skip the software setup process and proceed to our guide on how to operate your PlanktoScope. - but you still might wish to update your PlanktoScope to the latest release of the PlanktoScope OS, in which case you should reinstall the PlanktoScope software by going through our software setup guide below.

In order to install the PlanktoScope software, you will first need to choose an SD card image file to use for installation, and then you will install that SD card image and perform some configuration of the software.

Choosing an SD card image🔗

PlanktoScope SD card image files are identified with a version number as well as a hardware configuration tag - for example, the SD card image file named planktoscope-v2024.0.0+planktoscopehat.img.gz is for v2020.0.0 of the PlanktoScope OS, configured to work with versions of the PlanktoScope hardware based on the custom PlanktoScope HAT (rather than the Adafruit Stepper Motor HAT). Thus, you will need to choose both a version number (e.g. v2023.9.0) and a hardware configuration (e.g. planktoscopehat).

PlanktoScope OS versions🔗

Because the PlanktoScope project aims to release occasional updates to the PlanktoScope OS in order to fix various software problems and make various improvements to the software, multiple versions of the PlanktoScope OS exist, and new versions will be released in the future. In general, each version of the PlanktoScope OS will be compatible with all previous officially-released versions of the PlanktoScope hardware (which are all versions listed in the hardware changelog without the description of a "prototype"). The PlanktoScope documentation describes the latest stable release of the PlanktoScope OS, and you should always use the latest stable release on your PlanktoScopes.

PlanktoScope OS versions are independent of hardware versions, and (starting in 2023) use a different version numbering system from the hardware (see the Hardware setup guide for an overview of some hardware versions). Now, OS version numbers have three numeric components: the year of the release, a minor number (which is incremented for releases with new features and/or backwards-incompatible changes), and a patch number (which is incremented for minor bugfixes). You may see references to the following SD card image versions in online discussions of the PlanktoScope software:

  • v2.3: this release, from December 2021, was the last release of the PlanktoScope software in the old version numbering system in which the software and hardware were released together. The v2.3 OS is preinstalled on most PlanktoScopes sold by FairScope during 2023.

  • v2023.9.0: this release, from the end of 2023, is the first software release in the new version numbering system, and it is currently the latest release of the PlanktoScope OS. The number 9 should not be interpreted as having any special meaning.

  • v2024.0.0: this version is the first release of the PlanktoScope OS in 2024.

  • v2024.1.0: this version will be the second release of the PlanktoScope OS in 2024.

Hardware configurations🔗

Currently, each version of the PlanktoScope OS is provided as three SD card images which support the two different types of hardware configurations supported by the PlanktoScope software:

  • adafruithat: this configuration of the PlanktoScope OS is compatible with v2.1 of the PlanktoScope hardware, which uses the Adafruit Stepper Motor HAT.

  • planktoscopehat: this configuration of the PlanktoScope OS is compatible with all versions of the PlanktoScope hardware starting with hardware v2.3; those hardware versions use the PlanktoScope HAT instead of the Adafruit Stepper Motor HAT. This configuration requires you to select the hardware version of your PlanktoScope in the post-installation configuration process.

  • fairscope-latest: this configuration of the PlanktoScope OS is identical to the planktoscopehat configuration, except that this one sets the default settings to be for hardware version v2.6 so that you won't need to select the hardware version of your PlanktoScope in the post-installation configuration process.

If you have a PlanktoScope from FairScope, you should probably use the fairscope-latest SD card image; otherwise, if you have a non-FairScope PlanktoScope with hardware version v2.3 or later, you should probably use the planktoscopehat SD card image; otherwise, if you have a v2.1 PlanktoScope, you should probably use an adafruithat SD card image.

Installation🔗

After you have chosen a PlanktoScope OS SD card image for the desired OS version and hardware configuration, you should follow our standard installation guide in order to install that SD card image into your PlanktoScope. If the official PlanktoScope SD card images don't meet your requirements and you have successfully set up and used the PlanktoScope OS in the past via the standard installation process, then you may also find the non-standard installation guide useful.

Post-installation configuration🔗

The first time you start the PlanktoScope after installing or updating the software, you should change some settings in the PlanktoScope software in order to match the configuration of your PlanktoScope hardware. Refer to our post-installation configuration guide for details.

Next steps🔗

After installing the PlanktoScope software (or after ensuring that the PlanktoScope software is installed) and performing all necessary post-installation configuration, then you can proceed to our guide on how to operate your PlanktoScope.

Standard Installation🔗

easy install

This page provides instructions for installing the most recent standard version of the PlanktoScope OS on a PlanktoScope.

Set up the SD card🔗

If you purchased a fully-assembled PlanktoScope or a DIY-assembly PlanktoScope kit from FairScope which includes a microSD card, then the SD card is already set up with the PlanktoScope OS, and you should skip to the next step.

Prerequisites🔗

In order to complete this step, you will need all of the following:

  1. A microSD card for your Raspberry Pi.
  2. A separate computer which can flash SD card images to your microSD card.

Download the PlanktoScope software SD card image🔗

For ease of setup, we provide an SD card image file with the PlanktoScope OS. You can download it from the latest software release on the releases page for the PlanktoScope project on GitHub.

Each released version of the PlanktoScope OS has downloadable SD card images under the "Assets" dropdown. Depending on whether your PlanktoScope is from FairScope and on whether it uses an Adafruit Stepper HAT or the PlanktoScope HAT, you should download the corresponding .img.xz file.

Write the image to the SD card🔗

To write the image file to your microSD card:

  1. Download, install, and start the latest version of the Raspberry Pi Imager.
  2. Plug your microSD card into your computer; you may need to use a microSD-to-SD-card adapter, and/or an SD-card-to-USB adapter.
  3. Press the "Choose Device" button. Select "No filtering" from the menu. It actually doesn't matter what you select here.
  4. Press the "Choose OS" button. Select "Use custom" from the menu (this is why it doesn't matter what you selected in the "Choose Device" menu). In the file dialog, open the PlanktoScope SD card image file you downloaded in the previous section of this setup guide.
  5. Press the "Choose Storage" button. Select your SD card from the menu.
  6. Press the "Next" button. A pop-up dialog should appear asking if you would like to customize the OS. You should probably press the "No" button unless you are already experienced with the PlanktoScope software, because most of the settings inside don't matter to typical users of the PlanktoScope software, and because it's possible to break the software with incorrect settings.
  7. A pop-up dialog should appear asking you to confirm whether you selected the correct SD card and want to wipe all data on the SD card in order to write the PlanktoScope SD card image to your SD card. If you are ready, press the "Yes" button.
  8. The Raspberry Pi Imager will begin overwriting your SD card with the PlanktoScope SD card image. This will take a while to finish.

Once flashing is complete, unmount the SD card and remove it from the computer.

Insert the SD card into the PlanktoScope🔗

Insert the microSD card into the Raspberry Pi computer installed in your PlanktoScope.

Connect to the PlanktoScope🔗

Power on your PlanktoScope, and wait for it to start up. Note that it may take a few minutes to start up. Once it has finished starting up, it should create a new isolated Wi-Fi network whose name starts with the word pkscope followed by the unique randomly-generated name of your PlanktoScope.

Note that you will not be able to access the PlanktoScope's graphical user interface by plugging in a display to the Raspberry Pi. This is because the SD card image we provide does not include a graphical desktop or web browser, in order to keep the SD card image file smaller and to keep the PlanktoScope's Raspberry Pi running more efficiently. Instead, you will need to connect another device (e.g. a phone or a computer) directly to the PlanktoScope's Raspberry Pi, either over its isolated Wi-Fi network or over an Ethernet cable.

After you connect another device directly to the PlanktoScope's Raspberry Pi, then you can open a web browser on the device to access the PlanktoScope's graphical user interface at one of the following URLs (try them in the following order, and just use the first one which works):

  • http://planktoscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)
  • http://pkscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)
  • http://home.pkscope (this should work unless your web browser is configured to use a Private DNS provider)
  • http://192.168.4.1 (this should always work)
  • http://192.168.5.1 (this should always work)

The web browser should show a landing page with some information about your PlanktoScope and a list of links, including links to apps running on your PlanktoScope.

Next steps🔗

Now that you have installed the software and accessed the PlanktoScope software's user interface from your web browser, you should proceed to our guide for configuring your PlanktoScope.

Standard Installation🔗

easy install

This page provides instructions for installing the most recent standard version of the PlanktoScope OS on a PlanktoScope.

Set up the SD card🔗

If you purchased a fully-assembled PlanktoScope or a DIY-assembly PlanktoScope kit from FairScope which includes a microSD card, then the SD card is already set up with the PlanktoScope OS, and you should skip to the next step.

Prerequisites🔗

In order to complete this step, you will need all of the following:

  1. A microSD card for your Raspberry Pi.
  2. A separate computer which can flash SD card images to your microSD card.

Download the PlanktoScope software SD card image🔗

For ease of setup, we distribute the PlanktoScope OS as SD card image files. You can download the latest release from the releases page for the PlanktoScope project on GitHub. Each released version of the PlanktoScope OS has downloadable SD card images under the "Assets" dropdown, which has multiple SD card image files corresponding to different types of PlanktoScope hardware; for information about how to select the appropriate SD card image for your PlanktoScope hardware, refer to the "Hardware configurations" section of the software setup overview.

Write the image to the SD card🔗

To write the image file to your microSD card:

  1. Download, install, and start the latest version of the Raspberry Pi Imager.
  2. Plug your microSD card into your computer; you may need to use a microSD-to-SD-card adapter, and/or an SD-card-to-USB adapter.
  3. Press the "Choose Device" button. Select "No filtering" from the menu. It actually doesn't matter what you select here.
  4. Press the "Choose OS" button. Select "Use custom" from the menu (this is why it doesn't matter what you selected in the "Choose Device" menu). In the file dialog, open the PlanktoScope SD card image file you downloaded in the previous section of this setup guide.
  5. Press the "Choose Storage" button. Select your SD card from the menu.
  6. Press the "Next" button. A pop-up dialog should appear asking if you would like to customize the OS. You should probably press the "No" button unless you are already experienced with the PlanktoScope software, because most of the settings inside don't matter to typical users of the PlanktoScope software, and because it's possible to break the software with incorrect settings.
  7. A pop-up dialog should appear asking you to confirm whether you selected the correct SD card and want to wipe all data on the SD card in order to write the PlanktoScope SD card image to your SD card. If you are ready, press the "Yes" button.
  8. The Raspberry Pi Imager will begin overwriting your SD card with the PlanktoScope SD card image. This will take a while to finish.

Once flashing is complete, unmount the SD card and remove it from the computer.

Insert the SD card into the PlanktoScope🔗

Insert the microSD card into the Raspberry Pi computer installed in your PlanktoScope.

Connect to the PlanktoScope🔗

Power on your PlanktoScope, and wait for it to start up. Note that it may take a few minutes to start up. Once it has finished starting up, it should create a new isolated Wi-Fi network whose name starts with the word pkscope followed by the unique randomly-generated name of your PlanktoScope.

Note that you will not be able to access the PlanktoScope's graphical user interface by plugging in a display to the Raspberry Pi. This is because the SD card image we provide does not include a graphical desktop or web browser, in order to keep the SD card image file smaller and to keep the PlanktoScope's Raspberry Pi running more efficiently. Instead, you will need to connect another device (e.g. a phone or a computer) directly to the PlanktoScope's Raspberry Pi, either over its isolated Wi-Fi network or over an Ethernet cable.

After you connect another device directly to the PlanktoScope's Raspberry Pi, then you can open a web browser on the device to access the PlanktoScope's graphical user interface at one of the following URLs (try them in the following order, and just use the first one which works):

  • http://planktoscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)
  • http://pkscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)
  • http://home.pkscope (this should work unless your web browser is configured to use a Private DNS provider)
  • http://192.168.4.1 (this should always work)
  • http://192.168.5.1 (this should always work)

The web browser should show a landing page with some information about your PlanktoScope and a list of links, including links to apps running on your PlanktoScope.

Next steps🔗

Now that you have installed the software and accessed the PlanktoScope software's user interface from your web browser, you should proceed to our guide for configuring your PlanktoScope.

Troubleshooting🔗

We don't yet have documentation to help you troubleshoot problems with your PlanktoScope yet! For now, you should sign up to join the PlanktoScope community on Slack, and ask for help in the #3-start-testing channel on Slack.

Troubleshooting🔗

We don't yet have documentation to help you troubleshoot problems with your PlanktoScope yet! For now, you should sign up to join the PlanktoScope community on Slack, and ask for help in the #3-start-testing channel on Slack.