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:
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\u2019s still a lot we don\u2019t know about what\u2019s happening with groups of plankton and how they\u2019re 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.
"},{"location":"#what-is-the-planktoscope-project","title":"What is the PlanktoScope project?","text":"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.
"},{"location":"#who-are-planktoscopes-for","title":"Who are PlanktoScopes for?","text":"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!
"},{"location":"faq/","title":"Frequently Asked Questions","text":"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!
"},{"location":"faq/#can-i-purchase-a-planktoscope","title":"Can I purchase a PlanktoScope?","text":"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.
"},{"location":"faq/#where-do-i-get-support-or-find-the-necessary-tools-to-build-planktoscope","title":"Where do I get support or find the necessary tools to build PlanktoScope?","text":"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.
"},{"location":"community/","title":"The PlanktoScope Community","text":"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.
"},{"location":"community/#engage-on-github","title":"Engage on GitHub","text":"Feel free to visit the GitHub and engage if you want.
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.
"},{"location":"community/#chat-on-slack","title":"Chat on Slack","text":"The community is using Slack to communicate.
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.
"},{"location":"community/#classify-on-ecotaxa","title":"Classify on EcoTaxa","text":"To join EcoTaxa, you just need to create an account.
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.
"},{"location":"community/code-of-conduct/","title":"Contributor Covenant Code of Conduct","text":""},{"location":"community/code-of-conduct/#our-pledge","title":"Our Pledge","text":"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.
"},{"location":"community/code-of-conduct/#our-standards","title":"Our Standards","text":"Examples of behavior that contributes to a positive environment for our community include:
Examples of unacceptable behavior include:
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.
"},{"location":"community/code-of-conduct/#scope","title":"Scope","text":"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.
"},{"location":"community/code-of-conduct/#enforcement","title":"Enforcement","text":"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.
"},{"location":"community/code-of-conduct/#enforcement-guidelines","title":"Enforcement Guidelines","text":"Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
"},{"location":"community/code-of-conduct/#1-correction","title":"1. Correction","text":"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.
"},{"location":"community/code-of-conduct/#2-warning","title":"2. Warning","text":"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.
"},{"location":"community/code-of-conduct/#3-temporary-ban","title":"3. Temporary Ban","text":"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.
"},{"location":"community/code-of-conduct/#4-permanent-ban","title":"4. Permanent Ban","text":"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.
"},{"location":"community/code-of-conduct/#attribution","title":"Attribution","text":"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.
"},{"location":"community/license/","title":"Our work is fully open source","text":"That's the headline, yes.
"},{"location":"community/license/#hardware-files","title":"Hardware files","text":"We released our hardware files (everything in the hardware directory) under a CERN OHL-S license.
Our source code (everything in the directories flows and scripts) is released under a GPL-3.0 license.
Everything else is released under a Creative Commons CC-BY-SA license.
"},{"location":"community/trainings/","title":"Trainings","text":"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.
"},{"location":"community/trainings/#the-train-the-trainer-program","title":"The Train the trainer program","text":"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.
"},{"location":"community/trainings/#event-types","title":"Event types","text":""},{"location":"community/trainings/#build-workshop","title":"Build workshop","text":"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.
"},{"location":"community/trainings/#selecting-the-production-site","title":"Selecting the production site","text":"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:
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.
"},{"location":"community/trainings/#material-procurement","title":"Material procurement","text":"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:
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.
"},{"location":"community/trainings/#prepare-the-kit","title":"Prepare the Kit","text":"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:
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.
"},{"location":"community/trainings/#conducting-the-workshop","title":"Conducting the workshop","text":"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!
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!
"},{"location":"community/trainings/#hackathon","title":"Hackathon","text":"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!
"},{"location":"community/trainings/#general-planning-methods","title":"General planning methods","text":"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.
"},{"location":"community/trainings/#building-a-team","title":"Building a team","text":"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.
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.
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.
"},{"location":"community/trainings/#selecting-digital-tools","title":"Selecting digital tools","text":"The right tools can help to facilitate communication, collaboration, and organization, making the workshop experience more productive and enjoyable for everyone.
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.
"},{"location":"community/trainings/#determining-the-need","title":"Determining the need","text":"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:
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.
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.
"},{"location":"community/trainings/#financial-planning","title":"Financial planning","text":"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:
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.
"},{"location":"community/trainings/#creating-a-timetable","title":"Creating a timetable","text":"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:
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:
When announcing the event, it is important to include the following information:
Tip
If you already have a group of interested people, send a link to the announcement via email or chat and invite them personally.
"},{"location":"community/trainings/#preparing-a-presentation","title":"Preparing a presentation","text":"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.
Here are some topics that should be covered in a presentation:
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.
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.
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.
"},{"location":"community/trainings/#follow-up","title":"Follow-up","text":"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:
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:
For more information on how to contribute to this document and improve this training program, please see the contribute section on Writing Documentation.
"},{"location":"community/contribute/documentation/","title":"Writing Documentation","text":"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\nAfter 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.
"},{"location":"community/contribute/documentation/#extensions-available","title":"Extensions available","text":"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.
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.
"},{"location":"community/contribute/github/#assumptions","title":"Assumptions","text":"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.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.
"},{"location":"community/contribute/github/#git-commits","title":"Git Commits","text":"As minimal requirements, your commit message should:
We don't follow any other convention, but if you want to use one, we recommend this one.
"},{"location":"community/contribute/github/#pull-requests","title":"Pull Requests","text":"Some notes on PRs:
master before merging. Fortunately, this project integrates a bot to automatically enforce this requirement without the PR author having to do it manually.PlanktoScope tools follow the Semantic Versioning Convention.
"},{"location":"community/contribute/github/#automation-to-rebase-and-merge-the-prs","title":"Automation to Rebase and Merge the PRs","text":"This project integrates a bot that helps us manage pull requests merging. Read more about this.
"},{"location":"community/contribute/github/#how-to-publish-the-release","title":"How to Publish the Release","text":"\u26a0\ufe0f Before doing anything, make sure you got through the guide about Releasing an Integration.
\u26a0\ufe0f 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 \u2764\ufe0f
"},{"location":"community/contribute/hardware/","title":"Hardware Development","text":""},{"location":"community/contribute/hardware/#planktoscope-case","title":"PlanktoScope Case","text":"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:
By following these steps, you will be able to successfully install a development environment and participate in the PlanktoScope Case using Autodesk Fusion 360.
"},{"location":"community/contribute/hardware/#planktoscope-hat","title":"PlanktoScope Hat","text":"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:
By following these steps, you can set up a development environment that allows you to contribute to the PlanktoScope Hat using Autodesk Eagle.
"},{"location":"community/contribute/software/","title":"How to help development for the PlanktoScope code","text":"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!)
"},{"location":"community/contribute/software/#node-red","title":"Node-Red","text":"Node-Red is our main process. We use the flow to manage our user interface through a dashboard instance.
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:
sudo apt-get install nodejssudo apt-get install npmsudo npm install -g --unsafe-perm node-rednode-redBy 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.
"},{"location":"community/contribute/software/#python","title":"Python","text":"The python code is separated in four main processes, each with a specific set of responsibilities:
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.
"},{"location":"operation/","title":"Operation","text":"This page provides basic instructions for operating your PlanktoScope.
"},{"location":"operation/#connect-directly-to-your-planktoscope","title":"Connect directly to your PlanktoScope","text":"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.
"},{"location":"operation/#connect-with-an-ethernet-cable","title":"Connect with an Ethernet cable","text":"You can connect your computer to the PlanktoScope by plugging an Ethernet cable between your computer and your PlanktoScope's Raspberry Pi.
"},{"location":"operation/#connect-with-the-planktoscopes-isolated-wi-fi-network","title":"Connect with the PlanktoScope's isolated Wi-Fi network","text":"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.
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.
Unless you have changed the password of your PlanktoScope's Wi-Fi network, the password should be copepode.
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\u00a0(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\u00a0(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:
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.
"},{"location":"operation/#how-to-image-plankton","title":"How to image plankton","text":"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:
If you want to create an SD card image from your PlanktoScope to use on other PlanktoScopes, you can follow the following steps.
"},{"location":"operation/clone-sd/#prepare-the-sd-card-for-cloning","title":"Prepare the SD card for cloning","text":"Depending on whether you want to make an SD card image to reuse across multiple machines or whether you only want to make an exact backup of your SD card image, you will need to perform different steps to prepare your SD card for cloning.
"},{"location":"operation/clone-sd/#clone-your-sd-card","title":"Clone your SD card","text":""},{"location":"operation/clone-sd/#prepare-for-cloning-to-reuse-in-other-machines","title":"Prepare for cloning to reuse in other machines","text":"Normally, your SD card contains some information (a machine-specific ID, system secrets, and SSH secrets) which should never be replicated across multiple PlanktoScopes, and some information (apt package cache) which you would probably consider a waste of space which unnecessarily increases the size of the SD card image you want to make. We provide a preparation script at /usr/libexec/prepare-custom-image to remove this information; it also allows an SD card image created from your SD card to automatically resize itself to match the size of any SD card it's flashed to in the future. After you make any changes you want to make on your PlanktoScope for your SD card image, you should run the preparation script on the PlanktoScope with the command:
sudo /usr/libexec/prepare-custom-image\nOnce this script finishes running, it will shut down your PlanktoScope's Raspberry Pi.
Next, you should remove the SD card from your PlanktoScope and plug it into another computer, so that you can clone the SD card into an SD card image; this guide assumes that your other computer runs Linux. With your SD card plugged into your other computer, you can mount the SD card's rootfs partition to delete any other sensitive files which were not removed by the /usr/libexec/prepare-custom-image script. For example, you may also want to delete or edit some or all of the following files from the rootfs partition in order to remove any sensitive or machine-specific information:
etc/wpa_supplicant/wpa_supplicant.conf: Wi-Fi configuration and network secrets.home/pi/.ssh/authorized_keys: SSH public keys of devices authorized to remotely connect to the PlanktoScope.home/pi/data/: all images acquired before by the PlanktoScope - this directory may be large, and you probably don't want to copy those datasets across all your other PlanktoScopes.home/pi/.bash_history: Bash command history.home/pi/.python_history: Python command history.home/pi/.gitconfig: Git configuration, which may contain user-specific details.Info
You can also delete the files listed above before running the /usr/libexec/prepare-custom-image script; the effect is the same. Either way, those files will be permanently deleted on your SD card. However, if you want to keep those files on your SD card, you should make backup copies of those files, and then you can copy those files back onto your SD card after you finish cloning the SD card to an image.
Next, proceed to the Make an SD card image section of this guide.
"},{"location":"operation/clone-sd/#prepare-an-exact-backup","title":"Prepare an exact backup","text":"If you want to make an exact backup of your SD card and you don't want to reuse your SD card image across multiple PlanktoScopes, then you shouldn't run the /usr/libexec/prepare-custom-image script: that script will delete some files which you probably want to keep. Instead, you should edit the /boot/cmdline.txt file to add the string init=/usr/lib/raspberrypi-sys-mods/firstboot to the end of the file, for example resulting in a file which looks something like:
console=tty1 root=PARTUUID=someuniqueidhere rootfstype=ext4 fsck.repair=yes rootwait init=/usr/lib/raspberrypi-sys-mods/firstboot\nNext, you should remove the SD card from your PlanktoScope and plug it into another computer, so that you can clone the SD card into an SD card image; this guide assumes that your other computer runs Linux. Then proceed to the Make an SD card image section of this guide.
Warning
After you have finished cloning the SD card to an SD card image, you should edit the /boot/cmdline.txt file to remove the init=/usr/lib/raspberrypi-sys-mods/firstboot string, before booting up the Raspberry Pi with your SD card again. This will prevent the first-boot script from deleting the SSH server keys already on your SD card.
Now that your SD card is plugged into a Linux computer, you will need to determine the path of the device file corresponding to your SD card. Usually it will look something like /dev/mmcblk0, /dev/sda, or /dev/sdb; it should always be some file in /dev. To identify the device file for your SD card, run the command sudo fdisk -l in your terminal. The output may look something like:
Disk /dev/nvme0n1: 1.82 TiB, 2000398934016 bytes, 3907029168 sectors\nDisk model: WD_BLACK SN770 2TB\nUnits: sectors of 1 * 512 = 512 bytes\nSector size (logical/physical): 512 bytes / 512 bytes\nI/O size (minimum/optimal): 512 bytes / 512 bytes\nDisklabel type: gpt\nDisk identifier: D18C4567-ADF2-4987-987F-CDA411988C8E\n\nDevice Start End Sectors Size Type\n/dev/nvme0n1p1 2048 1230847 1228800 600M EFI System\n/dev/nvme0n1p2 1230848 3327999 2097152 1G Linux filesystem\n/dev/nvme0n1p3 3328000 3907028991 3903700992 1.8T Linux filesystem\n\nDisk /dev/mmcblk0: 58.29 GiB, 62587404288 bytes, 122241024 sectors\nUnits: sectors of 1 * 512 = 512 bytes\nSector size (logical/physical): 512 bytes / 512 bytes\nI/O size (minimum/optimal): 512 bytes / 512 bytes\nDisklabel type: dos\nDisk identifier: 0xa2033091\nTo determine which disk device corresponds to your SD card, you should check the size of each device to find the one which approximately matches the size of your SD card. In the above example, the 64 GB SD card is at /dev/mmcblk0.
Next, you should unmount the SD card from your system (or ensure that the device is already not mounted on your system). If you're unsure whether the SD card is mounted, you should use the umount command. For example, if your device is /dev/mmcblk0, you will need to run:
sudo umount /dev/mmcblk0p1\nsudo umount /dev/mmcblk0p2\nIf the devices were already not mounted, you should expect to see (and you can safely ignore) error messages which look like:
umount: /dev/mmcblk0p1: not mounted.\numount: /dev/mmcblk0p2: not mounted.\nTo clone the Raspberry Pi's SD card to an image file which you can write to other SD cards, you should follow the instructions at https://github.com/mgomesborges/raspberry-pi/blob/master/setup/clone-sd-card.md or https://raspberrytips.com/create-image-sd-card/ . For example, if you are using a Linux computer and the SD card shows up as /dev/mmcblk0, you could run the following command (replacing file paths and names accordingly):
sudo dd bs=4M if=/dev/mmcblk0 of=/some/path/here/image-name-here.img status=progress\nThis will create a .img file (at /some/path/here/image-name-here.img) as large as your SD card - make sure you have enough space on your hard drive for the file! If your SD card is large, this process may take a long time; this greatly depends on the speed of your SD card reader. For example, a slow SD card reader may take 30 minutes in order to clone a 32 GB SD card.
In order to make the SD card practical to share, you should shrink and compress the SD card image file using the PiShrink tool. For example, on Linux you could run the following set of commands (again replacing file paths and names accordingly):
cd /some/path/here\nwget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh\nchmod +x pishrink.sh\nsudo ./pishrink.sh -za image-name-here.img\nIf you had set up the PlanktoScope software on a Raspberry Pi OS Lite image, you should get a image-name-here.img.gz file which is at least 2 GB in size.
You can now use this SD card image with the non-standard installation guide for installing the PlanktoScope OS on an SD card for one or more PlanktoScopes.
"},{"location":"operation/maintenance/","title":"Maintenance and Repair","text":"Instructions for maintaining and repairing the PlanktoScope.
"},{"location":"operation/maintenance/#cleaning-the-optics","title":"Cleaning the optics","text":"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.
"},{"location":"operation/sample-collection/","title":"Sample collection","text":"The most common way to collect samples for the PlanktoScope is to use a plankton net.
"},{"location":"operation/sample-collection/#plankton-net","title":"Plankton Net","text":"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.
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.
"},{"location":"operation/user-interface/","title":"User interface guide","text":"This guide will help you understand how to use the Node-RED dashboard, which is the primary user interface for operating the PlanktoScope.
"},{"location":"operation/user-interface/#home","title":"Home","text":"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):
Tip
This list is also available from any other tab and allows you to quickly navigate between tabs.
"},{"location":"operation/user-interface/#machine-shutdown","title":"Machine shutdown","text":"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 if you turn off power without shutting down the machine through the software!
To shutdown the machine, first unlock the shutdown button by clicking on \"Unlock Button\".
You can then click on \"Shutdown\". The machine will ask for a final confirmation and will then shut itself down.
"},{"location":"operation/user-interface/#sample-tab","title":"Sample Tab","text":"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.
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.
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.
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.
"},{"location":"operation/user-interface/#optic-configuration","title":"Optic Configuration","text":"This page allows you to control the optical setup of the acquisition.
In the Optic Characterization block, you can control to turn the light on or not. You also have to choose the optics in use in the machine.
Warning
For now, the characteristics shown here are not true values (except if you use the 25mm/16mm lens couple).
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\".
"},{"location":"operation/user-interface/#fluidic-acquisition","title":"Fluidic Acquisition","text":"Finally, this is where the magic happens! You will be able to chose the final parameters of your capture.
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.
"},{"location":"operation/user-interface/#gallery","title":"Gallery","text":"This simple page will allow you to preview and download the captured data.
"},{"location":"operation/user-interface/#system-monitoring","title":"System Monitoring","text":"This tab allows you to monitor the physical characteristics of the machine and follow the processor load, CPU temperature, memory use and disk usage.
You also can find information about the software version you are using, the machine name and its camera.
"},{"location":"operation/user-interface/#wifi","title":"Wifi","text":"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 Personal security is supported; Wi-Fi networks without passwords are not supported.
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.
"},{"location":"operation/user-interface/#administration","title":"Administration","text":"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.
"},{"location":"operation/user-interface/#hardware-settings","title":"Hardware Settings","text":"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.
"},{"location":"reference/","title":"Technical Reference","text":"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.
"},{"location":"reference/#key-features","title":"Key Features","text":"Here are some key features of the PlanktoScope:
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:
"},{"location":"reference/hardware/changelog/#v26","title":"v2.6","text":"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.
"},{"location":"reference/hardware/changelog/#v25","title":"v2.5","text":"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.
"},{"location":"reference/hardware/changelog/#v24","title":"v2.4","text":"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.
"},{"location":"reference/hardware/changelog/#v23","title":"v2.3","text":"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.
"},{"location":"reference/hardware/changelog/#v22","title":"v2.2","text":"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.
"},{"location":"reference/hardware/changelog/#v21","title":"v2.1","text":"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.
"},{"location":"reference/hardware/changelog/#v10","title":"v1.0","text":"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.
"},{"location":"reference/hardware/hat/","title":"PlanktoScope Hat Hardware","text":""},{"location":"reference/hardware/hat/#buses-and-gpio-pinout","title":"Buses and GPIO pinout","text":""},{"location":"reference/hardware/hat/#i2c1-bus","title":"I2C1 Bus","text":""},{"location":"reference/hardware/hat/#rtc-rv-3028-c7","title":"RTC RV-3028-C7","text":"Address 0x52 Configured through a kernel driver.
"},{"location":"reference/hardware/hat/#oled-display","title":"OLED Display","text":"Address 0x3c
"},{"location":"reference/hardware/hat/#led-control-lm36011","title":"LED control: LM36011","text":"Address 0x64 Control through specific software, current range from 0 to 376mA in normal mode, up to 1.5A in flash mode.
"},{"location":"reference/hardware/hat/#spi0-bus","title":"SPI0 Bus","text":""},{"location":"reference/hardware/hat/#motor-controller-0-tmc5160","title":"Motor Controller 0: TMC5160","text":"Chip Enable: SPI0_CE0 Motor Enable: GPIO23
Diagnostic output: GPIO16 for Error output GPIO20 for Stall output
"},{"location":"reference/hardware/hat/#motor-controller-1-tmc5160","title":"Motor Controller 1: TMC5160","text":"Chip Enable: SPI0_CE1 Motor Enable: GPIO5
Diagnostic output: GPIO16 for Error output GPIO20 for Stall output
"},{"location":"reference/hardware/hat/#gpio","title":"GPIO","text":""},{"location":"reference/hardware/hat/#fan-control","title":"Fan control","text":"PWM1 control through GPIO13
"},{"location":"reference/hardware/hat/#led-output-selection","title":"LED Output selection","text":"GPIO18: high for LED1, low for LED2
"},{"location":"reference/hardware/hat/#led-strobe","title":"LED Strobe","text":"GPIO22 for pulse
"},{"location":"reference/hardware/hat/#i2c0-bus","title":"I2C0 Bus","text":""},{"location":"reference/hardware/hat/#eeprom-m24c32","title":"EEPROM M24C32","text":"Address 0x50 For HAT information only.
"},{"location":"reference/hardware/product-specs/","title":"Product Specifications","text":"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.
"},{"location":"reference/hardware/product-specs/#v26","title":"v2.6","text":"Overview:
Enclosure:
Optics:
Imaging characteristics:
Internal camera: Raspberry Pi High Quality Camera
Lenses:
Illumination: white LED
Fluidics:
Flow cell: capillary with rectangular cross-section
Internal tubing:
Peristaltic pump
Other internal electronics:
Embedded computer: Raspberry Pi 4 Model B
Control board: PlanktoScope HAT v1.2
External interfaces & connectivity:
External AC-to-DC power adapter:
Image acquisition throughput:
Samples:
Object size range:
Overview:
Enclosure:
Optics:
Imaging characteristics:
Internal camera: Raspberry Pi High Quality Camera
Lenses:
Illumination: white LED
Fluidics:
Flow cell: capillary with rectangular cross-section
Internal tubing:
Peristaltic pump
Other internal electronics:
Embedded computer: Raspberry Pi 4 Model B
Control board: PlanktoScope HAT v1.2
External interfaces & connectivity:
External AC-to-DC power adapter:
Image acquisition throughput:
Samples:
Object size range:
Overview:
Enclosure:
Optics:
Imaging characteristics:
Internal camera: Raspberry Pi Camera Module 2
Lenses:
Illumination: white LED
Fluidics:
Flow cell: ibidi \u00b5-Slide I Luer channel slide
Internal tubing:
Peristaltic pump
Other internal electronics:
Embedded computer: Raspberry Pi 4 Model B
Control boards:
Adafruit Stepper Motor HAT
Adafruit Ultimate GPS HAT
External interfaces & connectivity:
All notable changes to the PlanktoScope's software will be documented in this file.
The format is based on Keep a Changelog, and this project uses Calendar Versioning with a YYYY.minor.patch scheme for all releases after v2.3.0. All dates in this file are given in the UTC time zone.
/usr/libexec/prepare-custom-image (which must be invoked with sudo) to reset machine-specific files and re-enable partition resizing and shut down the Raspberry Pi, in order to automate common tasks needed for making a custom SD card image from a booted Raspberry Pi running the PlanktoScope OS. Support for this script should be considered experimental - this was mainly added as a workaround to a developer-experience regression introduced after v2023.9.0, in which an additional step is now needed after making an SD card image from a previously-booted SD card, or else the image will result in an error message loop (\"Partition #2 contains a ext4 signature\") during boot and will be unable to resize the image above 8 GB. That step is now included by the added script. Creation of custom SD card images from booted PlanktoScope OS images should still be considered an experimental workflow which may experience breaking changes to the developer experience at any time.ecotaxa_export.tsv filename for all metadata TSV files.planktoscopehat SD card image, the Node-RED dashboard's homepage now asks the user to set the hardware version (choosing between v2.3, v2.5, and v2.6) as a first-boot setup step; this dialog replaces the navigation buttons on the homepage until a hardware version is set.fairscope-latest SD card image is now provided which is identical to the planktoscopehat SD card image, except that its default settings configuration file is for the v2.6 PlanktoScope hardware (so that the homepage does not ask the user to choose a hardware version).factory-reset staged pallet bundle.planktoscope.local mDNS name was deprecated in v2023.9.0-beta.1, but now it's un-deprecated (i.e. official support for this name is added back to the project). As before, you can still use pkscope.local or the machine-specific mDNS name (of format pkscope-{machine-name}.local) instead of planktoscope.local.planktoscopehat SD card image has been reverted to be for the v2.5 PlanktoScope hardware (reverting a change made for v2024.0.0-alpha.2); in v2024.0.0-alpha.2, it was for the v2.6 hardware, while in previous versions it was still for the v2.5 hardware..img.xz files) rather than gzip compression (as .img.gz files).planktoscopehat SD card image, a hardware version is no longer set in the default config.json file provided on the image. Instead, the user must select their hardware version when they open the Node-RED dashboard's homepage for the first time.gcc has been removed from the SD card image, to help reduce SD card image size.config.json file should now be properly displayed as the default selection on the Node-RED dashboard's \"Fluidic Acquisition\" page.machine-name binary is no longer provided by the OS setup scripts, but instead is provided by Forklift for upgradeability (by upgrading the pallet applied to the Raspberry Pi) & removeability/replaceability (by switching to a different pallet which provides a different version of - or does not provide - the machine-name)./etc/hostname-template./etc/cockpit/cockpit.conf.d, and adding origins to allow in /etc/cockpit/origins.d, and adding templated origins (with string interpolation for the machine name, the hostname, and the custom domain) to allow in /etc/cockpit/origins-templates.d./etc/dnsmasq-templates.d, and by modifying the custom domain (which defaults to pkscope) in /etc/custom-domain./etc/hostapd/hostapd.conf.d, and adding templated drop-in files (with string interpolation for the machine name, the hostname, and the custom domain) in /etc/hostapd/hostapd.conf-templates.d./etc/hosts.d, and and adding templated snippets (with string interpolation for the machine name, the hostname, and the custom domain) in /etc/hosts-templates.d.pipeline-subtract-consecutive-masks feature flag in the apps/ps/backend/proc-segmenter package deployment of the local Forklift pallet and re-apply the pallet.planktoscopehat SD card image is now for the v2.6 PlanktoScope hardware; previously, it was still for the v2.5 hardware./etc config files, and some scripts in /usr are now managed by Forklift./etc is now a overlay filesystem with all manually-edited files saved at /var/lib/overlays/overrides/etc./usr is now a overlay filesystem with all manually-edited files saved at /var/lib/overlays/overrides/usr.pscopehat has been replaced with planktoscopehat everywhere. This means that any distro setup scripts/commands you previously used with pscopehat should be changed.picamera2 instead of raspimjpeg for camera control. This may require different ISO and white balance gains to be used. It also no longer limits the framerate of the camera preview, so the preview stream should adapt to the bandwidth available on your network connection and the system resources available to your web browser; this may increase resource usage on your web browser.planktoscopehat SD card image is now for the v2.6 PlanktoScope hardware; previously, it was (incorrectly) a mixture of v2.5 and v2.6 optical settings.lynx as an alternative terminal web browser to w3m for trying to work through captive portals on the Cockpit terminal.sudo.ufw has been replaced with firewalld. However, firewalld has not yet been properly configured./var/lib/planktoscope/machine-name instead of /home/pi/.local/etc/machine-name, and it's now saved without a trailing newline.cockpit-storaged, which was not useful enough to justify the number (and size of) unneeded dependencies it pulled in for the PlanktoScope software SD card image.apt-get update commands for a very minor speed-up in the distro setup process.sample_total_volume metadata field for all sample types, not just horizontal Plankton tows (corresponding to the \"Plankton net\", \"High Speed Net\", and \"Tara decknet\" sample types).dhcpcd service had started)./etc/hosts file and the hostname based on the machine name has now been split into two separate system services, planktoscope-org.update-hosts-machine-name.service and planktoscope-org.update-hostname-machine-name.service.(this release involves no changes from v2023.9.0-beta.2; it's just a promotion of v2023.9.0-beta.2 to a stable release)
"},{"location":"reference/software/changelog/#v202390-beta2-2023-12-02","title":"v2023.9.0-beta.2 - 2023-12-02","text":""},{"location":"reference/software/changelog/#added_4","title":"Added","text":"pscopehat builds of the PlanktoScope distro.v2023.9.0-beta.1) when the version is tagged, or else a pseudoversion (e.g. v2023.9.0-beta.1-36-gf276e84) which contains an abbreviated commit SHA and a list of the number of commits since the last tagged version. This version string is now also used for the acq_software metadata field.process_commit metadata field is now set once again. Now it depends on the new installer script provided by the github.com/PlanktoScope/install.planktoscope.community repo.process_source metadata field is no longer hard-coded in the Node-RED dashboard. Now it depends on the new installer script provided by the github.com/PlanktoScope/install.planktoscope.community repo./home/pi/PlanktoScope.pkscope.local from any web browser where planktoscope.local previously worked. We recommend using http://pkscope.local instead of http://planktoscope.local to access your PlanktoScope, for consistency with other domain name formats (see the \"Changes\" section for details)./home/pi/.local/etc/machine-name. It's updated when the PlanktoScope boots.home.planktoscope and {machine-name}.planktoscope (e.g. http://metal-slope-23501.planktoscope) has been changed from planktoscope to pkscope, so that the domain names are now of format home.pkscope and {machine-name}.pkscope. Similarly, the machine-specific mDNS name has been changed from format planktoscope-{machine-name}.local to pkscope-{machine-name}.local.PlanktoScope {machine-name} to the format pkscope-{machine-name}. This makes it easier to determine the machine-specific mDNS URL: just add .local, to get pkscope-{machine-name}.local (e.g. pkscope-metal-slope-23501.local).planktoscope to pkscope./home/pi/.local/etc/hostapd/ssid.snippet, instead of /home/pi/.local/bin/update-ssid-machine-name.sh.planktoscope.local mDNS name is no longer recommended. We will continue to support it for the foreseeable future (and definitely for at least one year), but we recommend using pkscope.local or the machine-specific mDNS name (of format pkscope-{machine-name}.local) instead./home/pi/.local/etc/cockpit/origins file has been removed, because it does not need to be persisted after being generated. Instead, a temporary file is generated and removed after being used./home/pi/.local/etc/hosts file has been removed from the setup files. Instead, it is now automatically generated by the setup scripts.192.168.4.1 and 192.168.5.1 can be used to access your PlanktoScope when your computer is connected directly to it, regardless of whether you are connecting over an Ethernet cable or the PlanktoScope's Wi-Fi hotspot.192.168.4.1 (over Wi-Fi, when running in wireless AP mode), 192.168.5.1 (over Ethernet), and planktoscope.local (over Wi-Fi or Ethernet, from a client device with mDNS support); this meant that Android devices could only connect to the PlanktoScope at 192.168.4.1, as they lack mDNS support. Now, client devices - even those without mDNS support - can connect to the PlanktoScope at home.planktoscope, and/or URLs like clear-field-33719.planktoscope and planktoscope-clear-field-33719.local (where clear-field-33719 is replaced with the PlanktoScope's Raspberry Pi's machine name, which is also part of the name of the PlanktoScope's Wi-Fi network - e.g. \"PlanktoScope clear-field-33719\")./ps/docs/ (so e.g. it's accessible at http://home.planktoscope/ps/docs/)/admin/cockpit/ (so e.g. it's accessible at http://home.planktoscope/admin/cockpit/)./admin/fs/ (so e.g. it's accessible at http://home.planktoscope/admin/fs/)/admin/portainer/ (so e.g. it's accessible at http://home.planktoscope/admin/portainer/). Note that you will need to open Portainer within a few minutes after booting (or rebooting) your PlanktoScope in order to create an admin account for Portainer./ps/data/browse/ (so e.g. it's accessible at http://home.planktoscope/ps/data/browse/ ), and it is now implemented using filebrowser, so that now you can delete folders, download folders, preview images, etc. As before, you can still access this from the \"Gallery\" page of the Node-RED dashboard.http://home.planktoscope or http://planktoscope.local), your browser will show a landing page with a list of links for easy access to the Node-RED dashboard, documentation, other embedded applications, and reference information about your PlanktoScope./ui on port 1880, e.g. with URLs like http://planktoscope.local:1880/ui or http://192.168.4.1:1880/ui; now, it should be accessed via a link on the landing page.hardware.json file, and the Node-RED dashboard will reload the settings; this prevents the hardware.json file from being changed into an inconsistent mixture of settings for different hardware versions, which was the previous (incorrect) behavior. The description on the \"Hardware Settings\" page is also now more specific about what happens when a hardware version is selected.pi and password copepode) for the Node-RED dashboard, the backend's hardware controller, and the backend's segmenter, and links to filebrowser directories for all log files created by the backend's hardware controller and segmenter.http://planktoscope.local:1880 or http://192.168.4.1:1880; now, it should be accessed via a link on the landing page .planktoscope as their hostname. Now, the hostname is of the format planktoscope-<machine-name>, e.g. planktoscope-metal-slope-23501 or planktoscope-plant-range-10581.FR (France) to US (USA).google.com to determine whether the connection was successful, so that the autohotspot script will revert to wireless AP mode if no internet access is available over the Wi-Fi network (e.g. if the connected Wi-Fi network is actually behaving like a captive portal, which would prevent the PlanktoScope from being accessed via a VPN over the internet - in which case the PlanktoScope would become accessible only over an Ethernet cable). This change is meant to make it easier to fix a PlanktoScope's Wi-Fi connection configuration when that configuration makes internet access impossible.1.1.1.1 (the static IP address of Cloudflare DNS, so a ping without DNS lookup) and checking whether the Wi-Fi network assigned an IP address to the Raspberry Pi, and reporting the results. This enables better troubleshooting of internet access issues on Wi-Fi networks./home/pi, but instead to subdirectories for the backend components under /home/pi/device-backend-logs. Note: the locations of log files may be changed again in the future, and/or file logging may be changed to use a different systemd-based mechanism in the future./usr/bin/stepper-disable and /usr/bin/autohotspotN scripts have been moved to /home/pi/.local/bin/release-gpio-steppers.sh and /home/pi/.local/bin/autohotspot.sh, respectively.gpio-init.service systemd service has been renamed to planktoscope-org.init-gpio-steppers.service.en_DK.UTF-8 locale was used for everything. Now it is only used for time, measurements, and paper dimensions, and the en_US.UTF-8 locale is the base locale for everything else. In the future we may provide GUI functionality for changing the base locale./ps/node-red-v2/ui on port 1880, but the embedded image streams and file gallery will not be properly displayed; and you can access the Node-RED editor at path /admin/ps/node-red-v2 on port 1880. However, you should instead access the Node-RED editor and Node-RED dashboard via the links on the PlanktoScope's landing page.planktoscope.local only works for devices connected directly to the PlanktoScope, either via an Ethernet cable or over Wi-Fi when the PlanktoScope is running in wireless AP mode. planktoscope.local no longer works on other networks, such as LANs or mesh VPNs, which the PlanktoScope might be connected to. On such networks, the machine-specific mDNS name (of format planktoscope-<machine-name>.local) should be used instead.hardware.json configuration file). This fixes issue #166 by preventing the Node-RED dashboard from saving an invalid value to the hardware.json file, which would crash the Python hardware controller after the next boot (or after the next time the Python hardware controller was restarted).adafruit-blinka and adafruit-platformdetect dependencies are now updated to their latest version, so that Python hardware controller will work on PlanktoScopes with recent (i.e. post-2021) versions of the Adafruit HAT./etc/wpa_supplicant/wpa_supplicant.conf file when checking if any networks found by scanning matched networks were specified in the wpa_supplicant.conf file; now it ignores them, so that commented-out networks don't incorrectly prevent the autohotspot from going into wireless AP mode./home/pi/data to a USB drive.metadata.json files). A file called integrity.check is created alongside the images. This file contains one line per file, with the filename, its size and a checksum of both its filename and its content./home/pi/data directory.raspimjpeg, controlled through a FIFO pipe/etc/wpa_supplicant/wpa_supplicant.conf file) to connect to an existing wifi network, it will try to connect to the network; and it will only start its own wifi hotspot if it failed to connect.PlanktoScope, and the password to it is now copepode.pi, and the default password is copepode for this user./home/pi/data.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.
"},{"location":"reference/software/product-specs/#v202400","title":"v2024.0.0","text":"Specs for v2024.0.0 are the same as in v2023.9.0, except for the following sections:
Regular operation:
Advanced operations:
Minimum for image acquisition (but not sufficient for on-board image processing):
Minimum for full functionality, including on-board image processing:
Recommended:
Forwards-incompatibilities:
Backwards-incompatibilities:
With minimum supported hardware for full functionality:
Regular operation:
Advanced operations:
Minimum for image acquisition (but not sufficient for on-board image processing):
Minimum for full functionality, including on-board image processing:
Recommended:
Forwards-incompatibilities:
Backwards-incompatibilities:
With minimum supported hardware for full functionality:
Regular operation:
Advanced operations:
Minimum for image acquisition (but not sufficient for on-board image processing):
Minimum for full functionality, including on-board image processing:
Recommended for full functionality:
Forwards-incompatibilities:
With minimum supported hardware for full functionality:
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:
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.
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:
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.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.software/stable branch of the PlanktoScope repository on GitHub will be advanced to the git commit of the \"stable\" release.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.
"},{"location":"reference/software/release-process/#choosing-a-release-channel","title":"Choosing a release channel","text":"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.
"},{"location":"reference/software/release-process/#upgrading-to-a-new-release-or-pre-release","title":"Upgrading to a new release or pre-release","text":"In order to use a new release or pre-release of the PlanktoScope OS, you will need to do one of the following:
Download the new SD card image for that release/pre-release, following the standard installation process.
Create a new custom SD card image for that release/pre-release, following the non-standard installation process.
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.
"},{"location":"reference/software/architecture/os/","title":"Operating System","text":"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:
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).
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.
"},{"location":"reference/software/architecture/os/#boot-sequence","title":"Boot sequence","text":"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 Raspberry Pi 4/5's boot flow, which consists of two bootloader stages to load the Raspberry Pi's firmware from the Raspberry Pi's SD card; in turn, the firmware loads the Linux kernel from the Raspberry Pi's SD card.
Debian's system initialization, which consists of an initramfs stage after the Linux kernel is loaded, followed by a stage for mounting the full filesystem from the Raspberry Pi's SD card and transferring control to the systemd init process as the root user-space process.
The systemd system manager's boot behavior, which initializes all necessary filesystems, drivers, and system services.
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.
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:
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.
forklift","text":"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.
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.
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)
"},{"location":"reference/software/architecture/os/#applying-published-customizations","title":"Applying published customizations","text":"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 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.
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.
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.
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.
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.
"},{"location":"reference/software/architecture/os/#data-processing","title":"Data processing","text":"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:
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.
"},{"location":"reference/software/architecture/os/#security","title":"Security","text":"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 \ud83d\ude43 - if you're interested in computer/network security and you'd like to help us as a volunteer on this project, please contact us!
"},{"location":"reference/software/functionalities/camera-settings/","title":"Camera Settings","text":"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.
The Node-RED dashboard's \"Shutter Speed\" setting, which is specified in units of microseconds (\u03bcs), 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 \u03bcs 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.
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.
"},{"location":"reference/software/functionalities/sample-imaging/","title":"Sample Imaging","text":"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\":
"},{"location":"reference/software/functionalities/sample-imaging/#stop-flow-imaging","title":"Stop-flow imaging","text":"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:
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.
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.
The PlanktoScope will capture and save an image of its entire field-of-view.
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.
"},{"location":"reference/software/functionalities/segmentation/#median-calculation-step","title":"Median-calculation step","text":"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.
"},{"location":"reference/software/functionalities/segmentation/#image-correction-step","title":"Image-correction step","text":"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.
"},{"location":"reference/software/functionalities/segmentation/#mask-calculation-step","title":"Mask-calculation step","text":"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:
\"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.
\"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.
\"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.
\"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.
\"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.
\"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.
"},{"location":"reference/software/functionalities/segmentation/#object-extraction-step","title":"Object-extraction step","text":"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 \u00b5m. 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 \u00b5m per pixel; then the area (in units of \u00b5m2) 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.
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.
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 * \u03c0 * 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 * \u03c0 * 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.
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.
"},{"location":"reference/software/interfaces/exported-metadata/","title":"Exported Metadata","text":"TODO
"},{"location":"reference/software/interfaces/mqtt/","title":"Planktoscope MQTT API Reference","text":"The MQTT API is the primary programming interface for controlling the PlanktoScope. The API is served by the PlanktoScope's Python backend, and data is sent across the API with the following architecture:
flowchart TD\n API[API Client] -->|Command| Broker[MQTT Broker]\n Broker -->|Command| Backend[Python Backend]\n Backend -->|Status Update| Broker[MQTT Broker]\n Broker -->|Status Update| APIMost messages in the MQTT API are organized according to a request-response pattern in which the API client sends a command as a request to take some action, and then the Python backend sends one or more responses as status updates about how the Python backend's state has changed as a result of the command:
Every MQTT message in the PlanktoScope's MQTT API is published on a specific topic, which is a slash-delimited path of strings (e.g. actuator/pump). Every MQTT message in the PlanktoScope's MQTT API carries a payload, which is a JSON object serialized as a string:
action field of the payload object; other fields of the payload object are parameters of the command.status, which is a string containing a status or error message.In the rest of this reference document, we organize our description of the MQTT API into sections corresponding to distinct functionalities of the Python backend:
"},{"location":"reference/software/interfaces/mqtt/#pump","title":"Pump","text":"The Pump API controls the movement of fluid through the PlanktoScope:
actuator/pumpstatus/pumpmove, stopmove command","text":"The move command initiates movement of fluid through the PlanktoScope by driving the PlanktoScope pump's stepper motor. For example, this command makes the pump move 10 mL of fluid forwards through the PlanktoScope's fluidic path, at a rate of 1 mL/min:
{\n \"action\": \"move\",\n \"direction\": \"FORWARD\",\n \"volume\": 10,\n \"flowrate\": 1\n}\nThe move command has the following parameters:
action Specifies the move command. string move direction Direction to run the pump. string FORWARD, BACKWARD volume Total volume of sample to pump before stopping automatically (mL). float 0 < volume flowrate Speed of pumping (mL/min). float 0 < flowrate \u2264 45 mL/min"},{"location":"reference/software/interfaces/mqtt/#move-command-responses","title":"move command responses","text":"The Python backend can send status updates on the status/pump topic, in response to the move command. The status field of such status updates can have any of the following values:
Started The pump has started moving in response to a valid move command. Error, the message is missing an argument One or more required parameters (direction, volume, flowrate) are missing in the move command. Error, The flowrate should not be == 0 An invalid value (0) was provided for the flowrate field. Done The pump has successfully stopped after fully pumping the specified volume of sample. Note: the MQTT API does not yet completely specify error messages in response to invalid values for the direction, volume, and flowrate parameters.
stop command","text":"The stop command interrupts any ongoing movement of fluid through the PlanktoScope and cuts off power to the PlanktoScope pump's stepper motor:
{\n \"action\": \"stop\"\n}\nThe stop command has the following parameters:
action Specifies the stop command. string stop"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses","title":"stop command responses","text":"The Python backend can send status updates on the status/pump topic, in response to the stop command. The status field of such status updates can have any of the following values:
Interrupted The pump has stopped moving in response to a valid stop command, interrupting any ongoing move command.Sent in response to any Pump stop command, and any Imager stop command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates","title":"Non-response status updates","text":"The Python backend can send status updates on the status/pump topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Ready The backend has become ready to respond to Pump commands. Dead The backend will no longer respond to Pump commands."},{"location":"reference/software/interfaces/mqtt/#focus","title":"Focus","text":"The Focus API controls the movement of the sample stage focusing motors in the PlanktoScope:
actuator/focusstatus/focusmove, stopmove command","text":"The move command initiates movement of the focusing stage by a specified displacement. For example, this command makes the stage move up by 0.26 mm at a speed of 1 mm/s:
{\n \"action\": \"move\",\n \"direction\": \"UP\",\n \"distance\": 0.26,\n \"speed\": 1\n}\nThe move command has the following parameters:
action Specifies the move command. string move direction Direction to move the sample stage. string UP, DOWN distance Total distance to move the stage before stopping automatically (in mm). float 0 < distance \u2264 45.0 speed Speed of movement (in mm/s).Defaults to 5. float 0 < speed \u2264 5.0 (optional)"},{"location":"reference/software/interfaces/mqtt/#move-command-responses_1","title":"move command responses","text":"The Python backend can send status updates on the status/focus topic in response to the move command. The status field of such status updates can have any of the following values:
Started The focusing motors have started moving in response to a valid move command. Error The move command is missing the distance and/or direction fields. Done The focusing motors have successfully stopped after moving the specified distance."},{"location":"reference/software/interfaces/mqtt/#stop-command_1","title":"stop command","text":"The stop command interrupts any ongoing movement of the focusing stage and cuts off power to the focusing motors:
{\n \"action\": \"stop\"\n}\nThe stop command has the following parameters:
action Specifies the stop command. string stop"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_1","title":"stop command responses","text":"The Python backend can send status updates on the status/focus topic, in response to the stop command. The status field of such status updates can have any of the following values:
Interrupted The focusing motors have stopped moving in response to a valid stop command, interrupting any ongoing stop command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_1","title":"Non-response status updates","text":"The Python backend can send status updates on the status/focus topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Ready The backend has become ready to respond to Focus commands. Dead The backend will no longer respond to Focus commands."},{"location":"reference/software/interfaces/mqtt/#light","title":"Light","text":"The Light API controls the state of the LED lighting system in the PlanktoScope:
actuator/lightstatus/lighton, offon command","text":"The on command turns on the sample illumination LED. For example:
{\n \"action\": \"on\"\n \"led\": \"1\"\n}\nThe on command has the following parameters:
action Specifies the on command. string on led Specifies the LED to turn on.Defaults to 1. integer 1\u00a0(optional)"},{"location":"reference/software/interfaces/mqtt/#on-command-responses","title":"on command responses","text":"The Python backend can send status updates on the status/light topic in response to the on command. The status field of such status updates can have any of the following values:
Led 1: On The LED turned on successfully. Error with LED number An invalid value was provided for the led field of the command."},{"location":"reference/software/interfaces/mqtt/#off-command","title":"off command","text":"The off command turns off the sample illumination LED. For example:
{\n \"action\": \"off\"\n}\nThe off command has the following parameters:
action Specifies the off command. string off led Specifies the LED to turn on.Defaults to 1 integer 1"},{"location":"reference/software/interfaces/mqtt/#off-command-responses","title":"off command responses","text":"The Python backend can send status updates on the status/light topic in response to the off command. The status field of such status updates can have any of the following values:
Led 1: Off The LED turned off successfully. Error with LED number An invalid value was provided for the led field of the command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_2","title":"Non-response status updates","text":"The Python backend can send status updates on the status/light topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Ready The backend has become ready to respond to Light commands. Dead The backend will no longer respond to Light commands."},{"location":"reference/software/interfaces/mqtt/#imager","title":"Imager","text":"The Imager API controls image acquisition with the PlanktoScope's hardware, as well as the PlanktoScope's camera:
imager/imagestatus/imagersettings, update_config, image, stopFor details on how images are acquired, refer to our technical reference on sample imaging in the PlanktoScope.
Generally, commands should be sent in the following order:
settings command: Configure the camera settings.update_config command: Update the dataset metadata for the next image acquisition.image command: Initiate image acquisition.stop command: Stop any in-progress image acquisition.settings command","text":"The settings command changes the camera settings. The fields iso, shutter_speed, white_balance_gain and white_balance are optional - if a field is omitted, its setting will not be changed. Here's an example of a command with values specified for all fields:
{\n \"action\": \"settings\",\n \"settings\": {\n \"iso\": 100,\n \"shutter_speed\": 40,\n \"white_balance_gain\": { \"red\": 100, \"blue\": 100 },\n \"white_balance\": \"auto\",\n }\n}\nThe settings command has the following parameters:
action Specifies the settings command. string settings iso Simulated ISO image sensitivity. int 0 < iso \u2264 650 (higher values may be accepted for certain cameras) (optional) shutter_speed Exposure time (in \u03bcs). int 125 \u2264 shutter_speed\u00a0(optional) white_balance_gain.red White balance red gain. float 0.0 \u2264 white_balance_gain.red\u00a0\u2264 32.0 (optional) white_balance_gain.blue White balance blue gain. float 0.0\u00a0\u2264\u00a0white_balance_gain.blue\u00a0\u2264 32.0 (optional) white_balance White balance mode. (off\u00a0specifies the use of manual white balance gains) string auto, off\u00a0(optional)"},{"location":"reference/software/interfaces/mqtt/#settings-command-responses","title":"settings command responses","text":"The Python backend can send status updates on the status/imager topic in response to the settings command. The status field of such status updates can have any of the following values:
Camera settings updated The camera settings have been successfully updated. Camera settings error The settings command is missing required parameters. Iso number not valid The provided iso\u00a0value is not allowed. Shutter speed not valid The provided shutter_speed\u00a0value is not allowed. White balance gain not valid The provided white_balance_gain\u00a0object is not valid or has an invalid value. White balance mode {white_balance} not valid The provided white_balance\u00a0value is not allowed."},{"location":"reference/software/interfaces/mqtt/#update_config-command","title":"update_config command","text":"The update_config command sets/changes the metadata which will be saved with the dataset which to be acquired by the next image command. For example:
{\n \"action\": \"update_config\",\n \"config\": {\n \"sample_project\": \"fairscope bzh\",\n \"sample_id\": \"fairscope_bzh_estacade\",\n \"sample_uuid\": \"uuid-1234\",\n \"sample_ship\": \"Fairscope\",\n \"sample_operator\": \"jeremy\",\n \"sample_sampling_gear\": \"net\",\n \"sample_concentrated_sample_volume\": 70,\n \"sample_total_volume\": 100,\n \"sample_dilution_factor\": 10,\n \"sample_speed_through_water\": \"5 knots\",\n \"sample_instrument\": \"PlanktoScope v2.6\",\n \"sample_bottom_depth\": \"N/A\",\n \"sample_depth_min\": 0.1,\n \"sample_depth_max\": 0.5,\n \"sample_temperature\": \"N/A\",\n \"sample_salinity\": \"N/A\",\n \"sample_date\": \"2024-05-15\",\n \"acq_id\": \"fairscope_bzh_estacade_2\",\n \"acq_instrument\": \"PlanktoScope v2.6\",\n \"acq_magnification\": \"1.2\",\n \"acq_camera_id\": \"deep-point-8125\",\n \"acq_camera_lens\": \"N/A\",\n \"acq_software\": \"PlanktoScope v2024.0.0-alpha.1\",\n \"acq_atlas_id\": \"N/A\",\n \"acq_resolution\": \"1080p\",\n \"acq_stacks_count\": \"N/A\",\n \"acq_time_between_frames\": 0.3,\n \"acq_brightness\": \"N/A\",\n \"acq_contrast\": \"N/A\",\n \"acq_sharpness\": \"N/A\",\n \"acq_saturation\": \"N/A\",\n \"acq_gamma\": \"N/A\",\n \"acq_uuid\": \"acq-uuid-5678\",\n \"acq_volume\": 2.50,\n \"acq_imaged_volume\": 1.04,\n \"acq_minimum_mesh\": 300,\n \"acq_maximum_mesh\": 300,\n \"acq_min_esd\": 300,\n \"acq_max_esd\": 300,\n \"acq_camera_name\": \"HQ Camera\",\n \"acq_nb_frame\": 500,\n \"acq_local_datetime\": \"2024-05-15T09:00:00Z\",\n \"acq_caamera_iso\": 400,\n \"acq_camera_shutter_speed\": 500,\n \"object_date\": \"2024-05-15\",\n \"object_time\": \"09:00:00Z\",\n \"object_lat\": 48.7273,\n \"object_lon\": -3.9814,\n \"object_depth_min\": 0.1,\n \"object_depth_max\": 0.5,\n \"process_pixel\": 0.75,\n \"process_datetime\": \"2024-05-15T09:00:00Z\",\n \"process_id\": \"Process01\",\n \"process_uuid\": \"proc-uuid-7890\",\n \"process_source\": \"https://www.github.com/PlanktonPlanet/PlanktoScope\",\n \"process_commit\": \"CommitHash\",\n \"sample_gear_net_opening\": 300,\n \"object_date_end\": \"2024-05-15\",\n \"object_time_end\": \"10:00:00Z\",\n \"object_lat_end\": 48.7274,\n \"object_lon_end\": -3.9815\n }\n}\nThe metadata should contain comprehensive information about the sample, acquisition process, object details, and processing parameters to ensure accurate tracking and reproducibility of the dataset. The update_config command has the following parameters:
Sample information:
Field Description Typesample_project Project name. string sample_id Sample identifier. integer sample_uuid Sample UUID. string sample_ship Ship name. string sample_operator Operator name. string sample_sampling_gear Sampling gear description. string sample_concentrated_sample_volume Concentrated sample volume. float sample_total_volume Total volume. float sample_dilution_factor Dilution factor. float sample_speed_through_water Speed through water. float Acquisition information:
Field Description Typeacq_id Acquisition identifier. integer acq_instrument Acquisition instrument. string acq_magnification Magnification level. string acq_camera_id Camera identifier. integer acq_camera_lens Camera lens. string acq_software Acquisition software. string acq_volume Acquisition volume. float acq_imaged_volume Imaged volume. float acq_minimum_mesh Minimum mesh size. float acq_maximum_mesh Maximum mesh size. float acq_min_esd Minimum equivalent spherical diameter. float acq_max_esd Maximum equivalent spherical diameter. float acq_camera_name Camera name. string acq_nb_frame Number of frames captured. integer acq_local_datetime Local date and time of acquisition. string acq_camera_resolution Camera resolution. string acq_camera_iso Camera ISO setting. float acq_camera_shutter_speed Camera shutter speed. float Object information:
Field Description Typeobject_date Date of the object recording. string object_time Time of the object recording. string object_lat Latitude of the sample location. float object_lon Longitude of the sample location. float object_depth_min Minimum depth of the sample location. float object_depth_max Maximum depth of the sample location. float object_date_end End date of the object recording. string object_time_end End time of the object recording. string object_lat_end End latitude of the sample location. float object_lon_end End longitude of the sample location. float Processing information:
Field Description Typeprocess_pixel Pixel processing method. string process_datetime Date and time of processing. string process_id Processing identifier. integer process_uuid Processing UUID. string process_source Source of processing software or method. string process_commit Commit hash of the software used. string"},{"location":"reference/software/interfaces/mqtt/#update_config-command-responses","title":"update_config command responses","text":"The Python backend can send status updates on the status/imager topic in response to the update_config command. The status field of such status updates can have any of the following values:
Config updated The metadata has been successfully updated. Configuration message error The command is missing the required\u00a0config field. Busy Image acquisition is already in progress, so dataset metadata cannot be changed."},{"location":"reference/software/interfaces/mqtt/#image-command","title":"image command","text":"The image command initiates acquisition of one raw image dataset consisting of a specified number of images, via stop-flow imaging. For example, this command initiates acquisition of 200 images, with 1 mL of sample pumped between each image and an image stabilization period of 0.1 seconds between the end of pumping and the triggering of the image capture for each acquired image:
{\n \"action\": \"image\",\n \"pump_direction\": \"FORWARD\",\n \"volume\": 1,\n \"nb_frame\": 200,\n \"sleep\": 0.1\n}\nA valid update_config command with a unique (object_date, sample_id, acq_id) combination must be sent some time before each image command. If an update_config command has not been sent before the image command, the image command will trigger a \u201cStarted\u201d response status and then do nothing (this is a software bug which needs to be fixed so that an error status is reported instead).
The image command has the following parameters:
pump_direction Direction of sample pumping. string FORWARD, BACKWARD. volume Volume (in mL) of sample to pump between each captured image. float 0 < volume nb_frame Number of frames to capture. integer 0 < nb_frame sleep Duration (in s) to wait after pumping has stopped before saving an image, to allow the sample objects to stabilize in the image. float 0 < sleep"},{"location":"reference/software/interfaces/mqtt/#image-command-responses","title":"image command responses","text":"The Python backend can send status updates on the status/imager topic, in response to the image command. The status field of such status updates can have any of the following values:
Started The image capture process has started successfully. Error At least one field of the\u00a0image\u00a0command is missing or has an invalid value. Error: missing camera No camera is available to use for image acquisition. Configuration update error: object_date is missing! The last time the update_config\u00a0command was sent, it did not have an object_date\u00a0parameter. Configuration update error: Chosen id are already in use! The\u00a0(object_date, sample_id, acq_id)\u00a0combination for the dataset (set by the last update_config\u00a0command) is already used by a previous dataset. Image {index}/{nb_frame} saved to {filename} An image has been successfully captured and saved. Image {index}/{nb_frame} WAS NOT CAPTURED! STOPPING THE PROCESS! An error occurred during image capture; the ongoing image acquisition has finished with failure, resulting in an incomplete dataset. Done The image acquisition finished successfully, resulting in a complete dataset."},{"location":"reference/software/interfaces/mqtt/#stop-command_2","title":"stop command","text":"This message interrupts any in-progress image acquisition routine and stops any ongoing sample pumping.
{\n \"action\": \"stop\"\n}\nThe stop command has the following parameters:
action Specifies the stop\u00a0command. string stop"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_2","title":"stop command responses","text":"The Python backend can send status updates on the status/imager topic, in response to the stop command. The status field of such status updates can have any of the following values:
Interrupted The image capture process was stopped successfully."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_3","title":"Non-response status updates","text":"The Python backend can send status updates on the status/imager topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Starting up The backend will soon attempt to initialize the camera. Error: missing camera A camera was not detected. Ready The camera is now operational, and the backend has become ready to respond to Imager commands. Dead The backend will no longer respond to Imager commands."},{"location":"reference/software/interfaces/mqtt/#segmenter","title":"Segmenter","text":"The Segmenter API controls the processing of acquired images:
segmenter/segmentstatus/segmenter, status/segmenter/object_id, status/segmenter/metricsegmentFor details on how images are processed, refer to our technical reference on image segmentation in the PlanktoScope.
"},{"location":"reference/software/interfaces/mqtt/#segment-command","title":"segment command","text":"The segment command initiates processing of images stored in the specified path, optionally exporting the results to an EcoTaxa-compatible archive. The various settings parameters of this command provide control over the behavior of image processing. For example, this command initiates processing of all images in the /path/to/segment directory:
{\n \"action\": \"segment\",\n \"path\": \"/path/to/segment\",\n \"settings\": {\n \"force\": false,\n \"recursive\": true,\n \"ecotaxa\": true,\n \"keep\": true\n }\n}\nThe segment command has the following parameters:
path Path to the directory of images to process.Defaults to /home/pi/data/img. file path (string) any subdirectory of\u00a0/home/pi/data/img (optional) settings.force Force re-segmentation of already-processed directories, ignoring the existence of\u00a0done\u00a0files which otherwise prevent already-segmented directories from being processed again.Defaults to false. boolean true, false (optional) settings.recursive Process datasets in all subdirectories of\u00a0path.Defaults to true. boolean true, false (optional) settings.ecotaxa Export an EcoTaxa-compatible archive.Defaults to true. boolean true, false (optional) settings.keep Keep ROI files generated when exporting an EcoTaxa-compatible archive. It has no effect if settings.ecotaxa\u00a0is false.Defaults to true. boolean true, false (optional)"},{"location":"reference/software/interfaces/mqtt/#segment-command-responses","title":"segment command responses","text":"The Python backend can send status updates on the status/segmenter topic, in response to the segment command. The status field of such status updates can have any of the following values:
Started The segmentation process has begun. Busy The segmenter is currently running and cannot update configurations. Calculating flat The frame background is being calculated. Segmenting image %s, image %d/%d Segmentation of a specific image is in progress. An exception was raised during the segmentation: %s. An error occurred during segmentation. Done Processing has finished for the specified datasets. As the Python backend performs segmentation, it will repeatedly send additional status updates on the status/segmenter/object_id topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:
object_id A scikit-image region label. integer As the Python backend performs segmentation, it will repeatedly send additional status updates on the status/segmenter/metric topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:
name An object ID, which is a undersctore-delimited concatenation of the name of the raw image which was processed and the object ID reported by status/segmenter/object_id. string metadata Metadata for the object. struct The metadata field of status updates sent on the status/segmenter/metric topic is an object with the following fields:
label Label of the object. integer width Width of the smallest rectangle enclosing the object. integer height Height of the smallest rectangle enclosing the object. integer bx X coordinate of the top left point of the smallest rectangle enclosing the object. integer by Y coordinate of the top left point of the smallest rectangle enclosing the object. integer circ Circularity: (4 \u2217 \u03c0 \u2217 Area) / Perimeter^2. A value of 1 indicates a perfect circle, approaching 0 indicates an elongated polygon. float area_exc Surface area of the object excluding holes, in square pixels. integer area Surface area of the object in square pixels. integer %area Percentage of object\u2019s surface area that is comprised of holes. float major Primary axis of the best fitting ellipse for the object. float minor Secondary axis of the best fitting ellipse for the object. float y Y position of the center of gravity of the object. float x X position of the center of gravity of the object. float convex_area The area of the smallest polygon within which all points in the object fit. integer perim The length of the outside boundary of the object. float elongation The result of dividing the major parameter by the minor parameter. float perimareaexc The result of dividing the perim parameter by the area_exc parameter. float perimmajor The result of dividing the perim parameter by the major parameter. float circex (4 \u2217 \u03c0 \u2217 area_exc) / perim^2. float angle Angle between the primary axis and a line parallel to the x-axis of the image. float bounding_box_area Area of the bounding box enclosing the object. integer eccentricity Eccentricity of the object. float equivalent_diameter Diameter of a circle with the same area as the object. float euler_number Euler number of the object. integer extent Ratio of object area to bounding box area. float local_centroid_col Column position of the local centroid. float local_centroid_row Row position of the local centroid. float solidity Ratio of object area to convex area. float MeanHue Mean hue value of the object. float MeanSaturation Mean saturation value of the object. float MeanValue Mean value (brightness) of the object. float StdHue Standard deviation of the hue value of the object. float StdSaturation Standard deviation of the saturation value of the object. float StdValue Standard deviation of the value (brightness) of the object. float"},{"location":"reference/software/interfaces/mqtt/#stop-command_3","title":"stop command","text":"The stop command interrupts any ongoing image processing. For example:
{\n \"action\": \"stop\"\n}\nThe stop command has the following parameters:
action string \"stop\" Specifies the action to stop segmentation. Warning
The functionality for this command has not yet been implemented. Currently an Interrupted status is sent as a response on the segmenter/segment topic even though no interruption will actual happen.
stop command responses","text":"The Python backend can send status updates on the segmenter/segment topic, in response to the stop command. The status field of such status updates can have any of the following values:
Interrupted The segmentation process was interrupted."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_4","title":"Non-response status updates","text":"The Python backend can send status updates on the status/segmenter topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Ready The backend has become ready to respond to Segmenter commands. Dead The backend will no longer respond to Segmenter commands."},{"location":"reference/software/subsystems/installation/","title":"Installation","text":"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.
"},{"location":"reference/software/subsystems/installation/#installation-bootstrap-script","title":"Installation bootstrap script","text":"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:
The script loads some parameters (set by environment variables and/or corresponding command-line arguments) which set the behavior of the script.
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.
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.
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.
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.
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.
-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:\u00a0github.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\u00a0query-type\u00a0parameter:branch: query should be a branch name (e.g. software/beta).tag: query should be a Git tag name, excluding the tag prefix specified by the tag-prefix\u00a0parameter (e.g. v2024.0.0\u00a0if tag-prefix\u00a0is software\u00a0and the Git tag is\u00a0software/v2024.0.0).hash: query should be a commit hash and may be abbreviated (e.g. 2d6928e).software/stable -t--query-type QUERY_TYPE The type of version query set by the version-query\u00a0parameter.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\u00a0github.com/PlanktoScope/PlanktoScope\u00a0repo currently expect either none, segmenter-only,\u00a0adafruithat,\u00a0planktoscopehat, or fairscope-latest.Default value: planktoscopehat --tag-prefix TAG_PREFIX The prefix for Git version tags when resolving the version query (with query type\u00a0tag) and when resolving tags (for pseudoversion strings).\u00a0Default 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\u00a0parameter) which will be downloaded at the specified commit (set by the version-query\u00a0and query-type\u00a0parameters and - when query-type\u00a0is tag\u00a0- by the tag-prefix\u00a0parameter) 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\u00a0(or including the command-line flag) automatically confirms all prompts.FORCE (or not including the command-line flag) requires user input for confirmation on all prompts.-V--verbose VERBOSE Whether to display additional (verbose) output:VERBOSE=1\u00a0(or including the command-line flag) enables verbose output.VERBOSE (or not including the command-line flag) disables 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.
Currently the installer script creates two YAML files, both in the /usr/share/planktoscope directory.
/usr/share/planktoscope/installer-config.yml records the values of the parameters with which the installer script was invoked:
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\" /usr/share/planktoscope/installer-versioning.yml records information about the version of the PlanktoScope OS's distro setup scripts which was used to install the PlanktoScope OS:
repo The path of the Git repository which provided the distro setup scripts, with any leading protocol string (e.g. https://) removed.Example Values: \"github.com/PlanktoScope/PlanktoScope\"\"github.com/PlanktoScope/PlanktoScope\"commit The full hash of the exact commit which provided the distro setup scripts.Example Values: \"2d6928e596b28f0c4c268fecb588c85215b1027e\"\u00a0(for commit 2d6928e)\"4d8b882616a8374918730bc1c6d300edfd7a523a\"\u00a0(for commit 4d8b882)tag The full name of the Git tag (whose name starts with the prefix set by the tag-prefix\u00a0script parameter) at the exact commit which provided the distro setup scripts, if such a tag exists; otherwise, the empty string (\"\").Example Values: \"software/v2024.0.0-alpha.1\"\u00a0(so commit 2d6928e\u00a0has Git tag software/v2024.0.0-alpha.1)\"\"\u00a0(so commit 4d8b882\u00a0has 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\u00a0script parameter) exists at that commit, this is a version string which just the name of that tag, but with the tag-prefix\u00a0stripped from the name. Otherwise, this is a pseudo-version string with format \"{tag}-{distance}-g{commit}\", where:{tag}\u00a0is the name of the most recent ancestral tag (with a name starting with the prefix set by the tag-prefix\u00a0script parameter) reachable from the commit, but with the tag-prefix\u00a0stripped from the name.{distance}\u00a0distance (in number of commits) between the commit and the most recent ancestral tag.{commit}\u00a0consists of the first seven characters of the hash of the commit.\"v2024.0.0-alpha.1\"\u00a0(so commit 2d6928e\u00a0has Git tag software/v2024.0.0-alpha.1)\"v2024.0.0-alpha.1-4-g4d8b882\"\u00a0(so commit 4d8b882\u00a0is 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)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.
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.
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.
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.
"},{"location":"reference/software/subsystems/startup/#services","title":"Services","text":"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:
"},{"location":"reference/software/subsystems/startup/#software-deployment-execution","title":"Software deployment & execution","text":"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.
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.
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-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.)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:
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 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:
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:
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:
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:
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:
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:
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.
"},{"location":"setup/hardware/","title":"PlanktoScope Hardware","text":"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.
"},{"location":"setup/hardware/#hardware-versions","title":"Hardware versions","text":"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.
"},{"location":"setup/hardware/#hardware-v21","title":"Hardware v2.1","text":"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. Note that this hardware design specifies 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.
"},{"location":"setup/hardware/#hardware-v25","title":"Hardware v2.5","text":"This version includes many design improvements to solve various problems with the v2.1 hardware design, including:
Replacing the ibidi flowcell with a simpler glass capillary flowcell.
Replacing the Adafruit Stepper Motor HAT with a HAT designed specifically for the PlanktoScope (the PlanktoScope HAT).
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.
Making the Raspberry Pi's micro-SD card accessible without requiring disassembly of the PlanktoScope.
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.
"},{"location":"setup/hardware/#choosing-a-version","title":"Choosing a version","text":"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.
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.
After making an assembly kit (if necessary) and building a PlanktoScope from your assembly kit, you should proceed to our software setup guide.
"},{"location":"setup/hardware/index-noguides/","title":"PlanktoScope Hardware","text":"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.
"},{"location":"setup/hardware/v2.1/","title":"Hardware v2.1","text":"This page will help you to build the v2.1 hardware for a PlanktoScope.
"},{"location":"setup/hardware/v2.1/#make-an-assembly-kit","title":"Make an assembly kit","text":"If you do not already have an assembly kit, you will need to make a kit for yourself. Note: you will need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi, as part of the assembly kit.
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.
"},{"location":"setup/hardware/v2.1/#assemble-a-planktoscope-from-a-kit","title":"Assemble a PlanktoScope from a kit","text":"Once you have an assembly kit, you will need to assemble it into a PlanktoScope.
"},{"location":"setup/hardware/v2.1/#next-steps","title":"Next steps","text":"Once you have assembled your PlanktoScope, you can proceed to our operation guide\u00a0to learn how to operate your PlanktoScope.
"},{"location":"setup/hardware/v2.1/assembly/","title":"Assembly guide of the PlanktoScope","text":"You can also use CAD renders and photos from the following links as a supplementary material for this assembly guide:
For the assembly guide below, the pieces of the laser-cut structure are referred to by single-letter labels (A, J, L, K, H, F, E, C, B, N, M, D, G, I) according to the following assignments:
"},{"location":"setup/hardware/v2.1/assembly/#step-1-gather-everything-you-need","title":"Step 1: Gather everything you need","text":"For the full list of all required tools and parts, please refer to the v2.1 hardware kit production guide.
Make sure you have your screwdriver kit, soldering iron, and components ready. Also, remember to flash the PlanktoScope image disk on the SD card before installing the Raspberry Pi.
If you are not familiar with any process, such as soldering, tapping, or wiring, try and familiarize yourself with the topics first.
Soldering deals with high heat and potentially toxic materials, so make sure to use the proper precautions.
"},{"location":"setup/hardware/v2.1/assembly/#step-2-standoff-installation","title":"Step 2: Standoff installation","text":"Place 8 standoffs (M2.5 6mm) into the designated holes on the laser-cut base A. A pair of pliers make the job more comfortable. Do not overtighten as it is possible to crack the base material.
"},{"location":"setup/hardware/v2.1/assembly/#step-3-motor-hat-preparation","title":"Step 3: Motor HAT preparation","text":"Insert and solder the terminal blocks and headers onto the motor driver PCB.
Place the motor driver PCB on to the indicated standoffs.
"},{"location":"setup/hardware/v2.1/assembly/#step-4-magnets-setup","title":"Step 4: Magnets setup","text":"Now is a good time to think about how the magnets will function within the microscope. The magnets in the sample stage will need to attract to the magnets on the flow cell holder. The magnets in the objective holder will need to attract the magnets on the mount. Keep this in mind as you are adding your magnets and tapping your respective M12 holders so your orientation will be correct.
You can now fix your magnets into their appropriate holes on sample stage B. It is recommended to glue the magnets in place. If the magnets are too large to fit in, the holes can be widened with a handheld drill. However, they should be quite snug in place. Before you glue them in place make sure that the polarity is maintained, as they will be impossible to remove after gluing.
"},{"location":"setup/hardware/v2.1/assembly/#step-5-sample-stage-assembly","title":"Step 5: Sample stage assembly","text":"Don\u2019t be alarmed by the color swap, this is the sample stage B. You can now fit the pegs on the driver mounts into the corresponding holes on the sample stage. They should be glued in place with superglue or epoxy. You can spin the shaft to align the driver mounts on the 2 steppers if it helps making the process easier.
You should now have a sample stage and motor assembly that looks like this.
"},{"location":"setup/hardware/v2.1/assembly/#step-6-lenses-tapping-and-mounting","title":"Step 6: Lenses tapping and mounting","text":"You now need to tap the holes for the M12 lenses in stage and mount M and D. It is helpful for alignment to do both the objeDtive and tube lens mount together. It is important to do this as straight as possible. A drop of mineral or olive oil can help the process. Be careful to use a right-hand tap (that goes down when turning clockwise).
You can now screw the objective lens (the 25mm one) in part D.
"},{"location":"setup/hardware/v2.1/assembly/#step-7-camera-preparation","title":"Step 7: Camera preparation","text":"You can now unscrew the lens from the Pi camera, being careful not to disturb the sensor below.
"},{"location":"setup/hardware/v2.1/assembly/#step-8-camera-mount","title":"Step 8: Camera mount","text":"You can mount the camera using the appropriate holes on the camera mount G. Be careful to avoid getting oil or dust on the sensor.
"},{"location":"setup/hardware/v2.1/assembly/#step-9-led-preparation","title":"Step 9: LED preparation","text":"The LED can then be wired up and put into its mount F. If you wire the LED yourself, remember to give enough length to reach the motor driver on the other end of the microscope. You can also add a bit of glue to fix F to the motor mount E at this time to make assembly easier, though it is not required.
Warning
This picture shows the correct wiring for the LED. Please make sure the red wire is on the long pin of the LED.
"},{"location":"setup/hardware/v2.1/assembly/#step-10-vertical-slices-assembly","title":"Step 10: Vertical slices assembly","text":"You can now start placing the motor mount/LED assembly- B,
C,
D,
E,
F,
and G into the base A.
"},{"location":"setup/hardware/v2.1/assembly/#step-11-pump-setup","title":"Step 11: Pump setup","text":"The pump can then be mounted in place on H. Thread the wires through the hole with the pump tubing pointed toward the holes on the mount.
Fix the pump in place.
"},{"location":"setup/hardware/v2.1/assembly/#step-12-pump-mounting","title":"Step 12: Pump mounting","text":"You can now mount the pump on base A.
Your setup should look like this. Don't worry about the wiring, we'll have a look at it in the next step!
"},{"location":"setup/hardware/v2.1/assembly/#step-13-motor-hat-wiring","title":"Step 13: Motor HAT wiring","text":"You will now want to wire the steppers and pump to the terminals on the motor driver board.
Info
The PlanktoScope uses only bipolar stepper motors (with 4 wires coming out, and two coils inside), so you need to identify the two wires working together for each coil. The RepRap Wiki has great information on how to do this, either with a multimeter or without.
You can find more information about stepper motors and how they work in this document.
Tip
If your wires are too short, you can invert the pump and the focus wiring. However, you will have to remember to change the configuration later on.
Tip
Make sure the wires are properly connected by pulling on them a little. They should not come loose.
"},{"location":"setup/hardware/v2.1/assembly/#step-14-raspberry-pi-setup-and-installation","title":"Step 14: Raspberry Pi setup and installation","text":"At this point, you can insert your flashed SD card into your Raspberry Pi. If you did not already flash your SD card with the PlanktoScope OS, refer to our guide for doing so. The heat sink can also be added to the processor.
Mount the Raspberry Pi containing the flashed SD card on the standoffs attached to the laser cut base A.
"},{"location":"setup/hardware/v2.1/assembly/#step-15-standoffs","title":"Step 15: Standoffs","text":"Add 8 standoffs (M2.5 15mm) to fix the motor driver board and the Raspberry Pi to the base.
"},{"location":"setup/hardware/v2.1/assembly/#step-16-camera-flex-cable","title":"Step 16: Camera flex cable","text":"At this point you can use the Pi camera flex cable to connect the camera to the Pi. This is done by gently pulling up the tensioners, inserting the cable in the right orientation, then pushing the tensioners back in place to set the cable. Try not to kink or fold the flex cable too much as it is possible to damage it.
"},{"location":"setup/hardware/v2.1/assembly/#step-17-power-supply-wiring","title":"Step 17: Power supply wiring","text":"The power wires can be wired into place on the motor driver board.
Tip
Make sure the wires are properly connected by pulling on them a little. They should not come loose.
"},{"location":"setup/hardware/v2.1/assembly/#step-18-prepare-the-gps-hat","title":"Step 18: Prepare the GPS HAT","text":"Tip
If you don't have a GPS HAT, you can just skip the assembly steps related to the GPS HAT - the PlanktoScope software will still work without GPS.
Insert the battery to power the GPS HAT and solder the terminal mounts in place.
"},{"location":"setup/hardware/v2.1/assembly/#step-19-install-the-gps-hat","title":"Step 19: Install the GPS HAT","text":"Mount the GPS HAT over the motor driver PCB using the standoffs attached to the laser cut base A.
"},{"location":"setup/hardware/v2.1/assembly/#step-20-install-the-fan-hat","title":"Step 20: Install the Fan HAT","text":"Place the cooling fan HAT above the Raspberry Pi by mounting it to the standoffs on base A.
Warning
Be careful to slide the camera flat cable in the slot in the HAT above the connector.
"},{"location":"setup/hardware/v2.1/assembly/#step-21-secure-the-hats","title":"Step 21: Secure the HATS","text":"Secure the cooling fan HAT and GPS HAT by tightening the 8 screws to the standoffs on base A
"},{"location":"setup/hardware/v2.1/assembly/#step-22-install-back-panel","title":"Step 22: Install back panel","text":"Insert the laser cut border I into base A.
"},{"location":"setup/hardware/v2.1/assembly/#step-23-gps-output-connector","title":"Step 23: GPS output connector","text":"Insert the power and GPS connectors into side plate J.
"},{"location":"setup/hardware/v2.1/assembly/#step-24-install-side-panel","title":"Step 24: Install side panel","text":"Place the side plate J into the designated slots on the base. You can connect the GPS cable to its connector on the board.
Warning
The GPS connector is quite fragile, make sure to align it properly before inserting it.
"},{"location":"setup/hardware/v2.1/assembly/#step-25-install-the-other-side-panel","title":"Step 25: Install the other side panel","text":"Mount the side plate K on base A using the assigned slots.
"},{"location":"setup/hardware/v2.1/assembly/#step-26-secure-the-sides-together","title":"Step 26: Secure the sides together","text":"Secure the laser cut sides with the screws and nuts.
"},{"location":"setup/hardware/v2.1/assembly/#step-27-secure-the-sides-to-the-base-plate","title":"Step 27: Secure the sides to the base plate","text":"Secure the laser cut sides to the base plate A with the screws and nuts.
Warning
To make this easier, you can turn the assembly upside down or on its side. Be careful when doing so as the plates may fall.
"},{"location":"setup/hardware/v2.1/assembly/#step-28-insert-the-camera-ribbon-cable-in-the-camera","title":"Step 28: Insert the camera ribbon cable in the camera","text":"You can now connect the camera flex cable into the connector on the camera board. Once again, gently pull up the tensioners, insert the cable in the right orientation, and push the tensioners back in place to set the cable. Try not to kink or fold the flex cable too much as it is possible to damage it.
"},{"location":"setup/hardware/v2.1/assembly/#step-29-assemble-the-gpio-ribbon-cable","title":"Step 29: Assemble the GPIO ribbon cable","text":"If you didn't get an already assembled ribbon cable, you need to build it yourself.
The orientation of the connector does not really matter. However, you need to make sure that both connectors are oriented in the same direction and are on the same side of the ribbon.
To assemble, slide the ribbon in its connector and close it off. You need to tighten it really hard. It's very warmly recommended to use a vice to do so.
Warning
Once assembled, the ribbon should NOT look like this:
It should rather look like this:
"},{"location":"setup/hardware/v2.1/assembly/#step-30-insert-the-ribbon-cable","title":"Step 30: Insert the ribbon cable","text":"Attach the GPIO ribbon to connect the cooling fan HAT to the GPS HAT.
Tip
You can try to route the flat ribbon from the camera under the ribbon cable you are connecting now.
"},{"location":"setup/hardware/v2.1/assembly/#step-31-fluidic-assembly","title":"Step 31: Fluidic assembly","text":"Feed in the tubing from syringe 1 to form the fluidic path as shown.
Feed in the tubing from syringe 2 to form the fluidic path as shown
Feed in a length of tubing as shown through motor mount H and illumination mount FE
"},{"location":"setup/hardware/v2.1/assembly/#step-32-close-your-planktoscope","title":"Step 32: Close your PlanktoScope","text":"Warning
Take a moment to check your wiring one last time. Also check the routing, make sure the LED wires and the pump stepper wires are in their dedicated channel.
Place the top L into the slots on the PlanktoScope body. Secure it in place with screws and nuts.
"},{"location":"setup/hardware/v2.1/assembly/#step-33-enjoy","title":"Step 33: Enjoy!","text":"Congratulations on a job well done. You can have some rest, get a tea and some biscuits!
Warning
If this was your first time assembling a PlanktoScope, you will probably need to do some troubleshooting of problems with the hardware assembly before your PlanktoScope will fully work. Refer to our troubleshooting documentation for assistance.
"},{"location":"setup/hardware/v2.1/assembly/#next-steps","title":"Next steps","text":"Once your PlanktoScope fully works, you can proceed to our operation guide\u00a0to learn how to operate your PlanktoScope.
"},{"location":"setup/hardware/v2.1/kit/","title":"Kit Production","text":""},{"location":"setup/hardware/v2.1/kit/#required-tools","title":"Required Tools","text":"Building the PlanktoScope involves components that can be sourced from various vendors, both online and locally. The assembly process is straightforward and can be completed within a few hours. Our website offers detailed guides for both hardware and software assembly, and the PlanktoScope community is ready to assist you with any questions or issues.
"},{"location":"setup/hardware/v2.1/kit/#soldering-station","title":"Soldering Station","text":"A soldering station with flux, or flux core solder, is necessary for making a few electrical connections. Purchase here.
"},{"location":"setup/hardware/v2.1/kit/#tap-wrench","title":"Tap Wrench","text":"Any tap wrench compatible with the M12x0.5 tap will work. Purchase here.
"},{"location":"setup/hardware/v2.1/kit/#m12-x-05-tap","title":"M12 x 0.5 Tap","text":"An M12x0.5 tap is required to secure the objective and tube lenses. Purchase here.
"},{"location":"setup/hardware/v2.1/kit/#screwdriver-kit","title":"Screwdriver Kit","text":"A screwdriver kit with multiple drivers simplifies many assembly operations. Purchase here.
"},{"location":"setup/hardware/v2.1/kit/#required-components","title":"Required Components","text":"Below is a comprehensive list of components required to build the PlanktoScope V2.1, along with links to purchase them in both the US and France.
"},{"location":"setup/hardware/v2.1/kit/#electronic-components","title":"Electronic Components","text":"Quantity Name Details US Link FR Link 1 Raspberry Pi 4 B (4GB) The single board computer from Raspberry Pi with 4GB of memory Amazon US DigiKey FR 1 Adafruit Stepper Motor HAT Controls 2 steppers: focus and pump stepper motors Amazon US Amazon FR 1 Adafruit Ultimate GPS HAT Stores date & time and logs GPS coordinates Amazon US DigiKey FR 1 Yahboom Cooling Fan HAT Cools and provides visual feedback with LEDs Amazon US Kubii FR 1 Hammer Header Male 2x20 Only one needed Amazon US Mouser FR 1 Stacking Header 2x20 Only one needed Amazon US Mouser FR 2 Pitch IDC Sockets 2x20 Two needed Amazon US Mouser FR 10cm GPIO Ribbon IDC 40P Only 10 cm needed Amazon US Amazon FR 1 Flex Cable for Pi Camera Longer flex cable needed Amazon US Amazon FR 1 DC Power Jack Socket Only one needed Amazon US Amazon FR 1 GPS Active Antenna Includes uPF to SMA adapter Amazon US Amazon FR 1 Micro HDMI Cable Optional, for development purposes Amazon US Amazon FR 1 Power Supply 3A (USB) Needs to provide 3A 5V Amazon US Amazon FR 1 Power Supply 1A (USB) Needs to provide 1A 5V Amazon US Mouser FR 1 USB Type-C to USB-A 2.0 To power the Raspberry Pi Amazon US Amazon FR 1 USB 5v to DC 12v Step Up Make sure this USB 5V / DC 12V step up converter limits the current at 0.8A Amazon US Amazon FR 1 Maschinenreich peristaltic pump 12V XP88-ST01 This pump can be replaced by others depending on its availability Amazon US 2 Linear Stepper Motor Make sure to select two linear stepper Amazon US 1 MicroSD Card + Adapter Minimum size is 32GB Amazon US Amazon FR 1 kit Heat sink kit for Raspberry Pi Only one kit needed Amazon US Mouser FR"},{"location":"setup/hardware/v2.1/kit/#fluidic-components","title":"Fluidic Components","text":"Quantity Name Details US Link FR Link 1 kit \u00b5-Slide I Luer Variety Pack Make sure to select uncoated Ibidi US Ibidi FR 2 HSW 20ml Syringe Two syringes needed Grainger US Darwin Microfluidics FR 1 kit \u00dcberStrainer Set 3 Optional strainer kit to filter the samples Pluriselect US 1m Silicone Tubing ID 1.6mm Ibidi website provides good but expensive tubing Ibidi US Darwin Microfluidics FR 2 Luer Lock Connector Female 1.6 mm Make sure to select the proper diameter Ibidi US Darwin Microfluidics FR 2 Luer Connector Male 1.6 mm Make sure to select the proper diameter Ibidi US Darwin Microfluidics FR"},{"location":"setup/hardware/v2.1/kit/#optic-components","title":"Optic Components","text":"Quantity Name Details US Link FR Link 1 LED white 5mm Intensity: 23,000 mcd, Forward Voltage: 3.5V, Current: 20mA, Beam Angle: 15\u00b0 DigiKey US Gotronic FR 1 kit Arducam M12 Lens Kit Includes 10 M12 Lenses for various angles of view Amazon US 1 M12 Lens 25mm IR 1/2\" 5MP Additional essential 25mm M12 lens Amazon US AliExpress 1 Pi Camera v2.1 Amazon US"},{"location":"setup/hardware/v2.1/kit/#hardware-components","title":"Hardware Components","text":"Quantity Name Details US Link FR Link 1 M2.5 Standoff Assortment Kit 6mm and 15mm standoffs Amazon US 1 M2 M3 M4 Screw Assortment Kit M2x8mm and M3x12mm screws and M3 nuts Amazon US 1 CR1220 Battery For the Adafruit Ultimate GPS HAT Amazon US Amazon FR 16 Magnets 6 x 2 mm Neodynium magnets to connect functional layers Amazon US"},{"location":"setup/hardware/v2.1/kit/#machine-your-structure","title":"Machine Your Structure","text":"To complete your PlanktoScope kit, you'll need to fabricate the structure. This can be done using laser cutting or CNC machining from a sheet of material. You can machine the structure locally at a FabLab or through a company specializing in laser cutting or CNC machining. The cost will vary depending on the material chosen and whether you machine it yourself or use a company.
"},{"location":"setup/hardware/v2.1/kit/#suggested-materials","title":"Suggested Materials","text":"Material Easy to Machine Robustness Water Resistance Price Recyclable Ideal For Transparent Acrylic \u2605\u2605\u2605\u2605\u2605 \u2605\u2606\u2606\u2606\u2606 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2606\u2606\u2606 \u2606\u2606\u2606\u2606\u2606 Seeing internal electronics Black Acrylic \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2606\u2606\u2606 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2606\u2606 \u2606\u2606\u2606\u2606\u2606 Removing surrounding light Marine Plywood \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2605\u2606 \u2605\u2606\u2606\u2606\u2606 Deploying at sea Basic Plywood \u2605\u2605\u2605\u2606\u2606 \u2605\u2605\u2606\u2606\u2606 \u2605\u2605\u2606\u2606\u2606 \u2605\u2606\u2606\u2606\u2606 \u2605\u2605\u2606\u2606\u2606 Cheap prototyping HDF Forescolor \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2606\u2606 \u2605\u2605\u2605\u2606\u2606 \u2605\u2605\u2605\u2605\u2605 Feeling good about recycling PP Waste, 100% Recycled \u2606\u2606\u2606\u2606\u2606 \u2606\u2606\u2606\u2606\u2606 \u2606\u2606\u2606\u2606\u2606 \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2605\u2605 Feeling good about recycling Aluminum \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2605 Robust professional setup"},{"location":"setup/hardware/v2.1/kit/#get-the-plan-and-machine-it","title":"Get the Plan and Machine It","text":"You can download the necessary fabrication patterns for the structure here; two versions are available, one for material with 5 mm thickness, and the other for material with 1/4 inch thickness:
Since DXF files don't include unit information, when you open or import one of these DXF files you may need to rescale all dimensions to achieve the correct sizes. You can check whether dimensions are correct by checking the length and width of part M against the actual dimensions shown below:
You can also compare the approximate dimensions of parts in the SVG file (for 5 mm thickness material) with the sizes of parts in your imported DXF file to check whether the rescaling result looks approximately correct.
"},{"location":"setup/hardware/v2.5/","title":"Hardware v2.5","text":"This page will help you to build the v2.5 hardware for a PlanktoScope.
"},{"location":"setup/hardware/v2.5/#make-an-assembly-kit","title":"Make an assembly kit","text":"If you do not already have an assembly kit, you will need to make a kit for yourself.
"},{"location":"setup/hardware/v2.5/#assemble-a-planktoscope-from-a-kit","title":"Assemble a PlanktoScope from a kit","text":"Once you have an assembly kit, you will need to assemble it into a PlanktoScope.
"},{"location":"setup/hardware/v2.5/#next-steps","title":"Next steps","text":"If you assembled your PlanktoScope from a kit provided by FairScope, you can proceed to our operation guide\u00a0to 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.
"},{"location":"setup/hardware/v2.5/assembly/","title":"Assembly","text":""},{"location":"setup/hardware/v2.5/assembly/#content-of-the-kit","title":"Content of the Kit","text":"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.
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 SandpaperIf any bags are missing, please go back to the BOM (Bill of Materials) and reorder the required components.
"},{"location":"setup/hardware/v2.5/assembly/#about-this-document","title":"About this document","text":"To read this document, follow these guidelines:
"},{"location":"setup/hardware/v2.5/assembly/#color-codes","title":"Color codes","text":"As you read through the document, be sure to pay attention to these visual cues to guide you through the build process.
"},{"location":"setup/hardware/v2.5/assembly/#requirements","title":"Requirements","text":""},{"location":"setup/hardware/v2.5/assembly/#tools","title":"Tools","text":"Content of\u00a0Bag B:
Content of\u00a0Bag A:
\ud83d\udc41 Locate the panel S1 and discover the 5 differents Parts F, P, K, J and I.
\ud83c\udfac Flip your panel S1.
\ud83d\udd34 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.
Gather all the necessary tools. You will need the B2 \ud83d\udfe0 Razor blade to cut the tabs.
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.
Once you have removed your Part from the main panel by cutting off all the tabs holding it, inspect it for potential residual tabs.
\ud83d\udfe3 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.
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.
\ud83d\udd34 Locate the inner tabs on the edges of the different Parts.
Cut out the tabs inside of all the Parts F, P, K, J and I detached from the panel S1.
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.
Repeat the process on the panel S2.
Warning
Be extremely careful because this is very sharp.
Discover the 11 differents Parts.
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.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-2-place-the-4-adhesive-pads-under-the-part-i","title":"Chapter 2: Place the 4 Adhesive Pads under the Part I","text":"To secure the PlanktoScope on slippery grounds using the adhesive pads, follow these steps. Gather all the necessary materials. You will need:
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-3-screw-the-four-standoffs-into-part-a","title":"Chapter 3: Screw the four Standoffs into Part A","text":"Now it's time to assemble the ground plate for the Raspberry Pi as the PlanktoScope main processing unit.
\ud83d\udfe2 A1. Standoff M2.5 - 6mm- Brass
\ud83d\udfe2 B4. Wrenches for standoffs
Keep going for each of the four holes.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-4-mount-the-heat-sinks-on-the-raspberry-pi","title":"Chapter 4: Mount the Heat Sinks on the Raspberry Pi","text":"Locate the Raspberry Pi 4 Model B packaging.
Warning
Be careful removing it from its packaging.
Place the four Heat Sinks next to your Raspberry Pi and mark the locations of the Heat Sinks on the Raspberry Pi.
Remove the protective labels under a Heat Sink and place the Heat Sink on the slot of the Raspberry Pi.
Remove the protective labels under all the Heat Sinks and place all the Heat Sinks on the slots of the Raspberry Pi.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-5-insert-the-micro-sd-card-in-the-raspberry-pi","title":"Chapter 5: Insert the micro SD card in the Raspberry Pi","text":"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.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-6-mount-the-raspberry-pi-on-the-part-a","title":"Chapter 6: Mount the Raspberry Pi on the Part A","text":"\ud83d\udfe3 A3. Standoff M2.5 - 16mm - SS
Screw by hand a Standoff M2.5 - 16mm on the Raspberry Pi.
\ud83d\udfe2 B4. Wrenches for standoffs
Locate the Raspberry Pi Camera HQ packaging.
Warning
Be careful removing it from its packaging.
Lay your Raspberry Pi Camera face down on a suitable surface.
\ud83d\udd34 The black connector is simply a push/pull fit. To disengage the cable, pull the two corners of the black connector down, away from the camera board. It will unclip to about 3mm, make sure you don't pull it off! If you're struggling, try pulling off one corner of the connector at a time.
Warning
Be careful with this, this part is delicate. Lift the black connector gently
Once the connector has been disengaged from the Raspberry Pi camera board, the cable will simply slide out!
\ud83d\udd34 Locate the black connector present on the Raspberry Pi.
\ud83d\udd34 The black connector is simply a push/pull fit. To disengage the cable, pull the two corners of the black connector down, away from the camera board. It will unclip to about 3mm, make sure you don't pull it off! If you're struggling, try pulling off one corner of the connector at a time.
Warning
Be careful, this part is delicate. Gently prise the black connector with nail or fingertip and thumb.
Insert the Ribbon Cable you just detached from the Raspberry Pi Camera in the Raspberry Pi.
\ud83d\udd34 Secure the Ribbon Cable in the Raspberry Pi by pressing firmly on the black connector.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-8-mount-the-planktoscope-hat-on-the-raspberry-pi","title":"Chapter 8: Mount the PlanktoScope HAT on the Raspberry Pi","text":"Locate the PlanktoScope HAT present in bag I.
\ud83d\udd34 Thread the Ribbon cable through the PlanktoScope HAT slot from the underside.
Warning
Make sure the two \ud83d\udfe3 black connectors are aligned before threading through the ribbon.
\ud83d\udd34 Plug the PlanktoScope HAT into the Raspberry Pi.
Warning
Make sure the two black connectors are aligned before attaching them together.
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.
\ud83d\udfe0 A4. Screw M2.5X5mm CHC - SS
\ud83d\udfe3 Locate the 4 holes on the top of the PlanktoScope HAT and insert the four M2.5X5mm
\ud83d\udfe1 B3. Allen key 2mm
Screw the four A4 screws through the PlanktoScope HAT onto the Standoff M2.5 - 16mm.
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-9-place-the-power-socket-on-part-m","title":"Chapter 9: Place the Power Socket on Part M","text":"\ud83d\udd34 Insert the cable inside of the hole by being sure of the orientation of the Part M.
\ud83d\udfe3 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\u2019t spin on itself.
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-10-mount-the-raspberry-pi-camera-hq-on-part-b","title":"Chapter 10: Mount the Raspberry Pi Camera HQ on Part B","text":"\ud83d\udfe3 Locate the 4 holes on the top of the Part B.
\ud83d\udd35 A2. Standoff M2.5 - 15mm - Brass
Insert the four Standoff M2.5 - 15mm.
The result should be similar to the picture.
\ud83d\udfe2 B4. Wrenches for standoffs
Using the small side of the Standoff Wrench, secure the 4 M2.5 - 15mm Standoffs
Locate the Raspberry Pi Camera HQ
Remove the lens cap Raspberry Pi Camera HQ.
Warning
Make sure your camera lens is clean. If it is not, gently wipe using cotton swab for this task.
Place the Raspberry Pi Camera HQ on top of the four Standoffs installed on Part B.
\ud83d\udfe3Ensure correct orientation of the Raspberry Pi Camera HQ. The black connector where the Ribbon Cable was removed is on the same side as the \ud83d\udfe2slot circled in green
\ud83d\udfe0 A4. Screw M2.5X5mm CHC - SS
\ud83d\udfe1 B3. Allen key 2mm
Use the allen key and tighten the Raspberry Pi Camera to the Standoffs.
The result should be similar to the picture.
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-11-mount-the-linear-stepper-motor-on-part-e","title":"Chapter 11: Mount the Linear Stepper Motor on Part E","text":"Locate the Stepper Motors
Warning
Avoid touching the metal rods on the Stepper Motors
Info
You can touch the \ud83d\udfe3 gold stands
\ud83d\udfe1 A5. Screw M2.5X10mm CHC - SS
\ud83d\udfe1 B3. Allen key 2mm
Attach the stepper motors to the screws we have just placed with the \ud83d\udd34 pockets positioned on opposite to the cabling.
The result should be similar to the picture.
Use the 2mm allen key to fix the Stepper Motors.
The result should be similar to that picture.
The result should be similar to the picture.
Repeat the process on the other side with the other Stepper Motor.
Repeat the process on the other side with the other Stepper Motor.
The result should be similar to the picture.
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-12-mount-the-led-on-part-g","title":"Chapter 12: Mount the\u00a0LED\u00a0on\u00a0Part G","text":"Insert the\u00a0LED into the LED cable.
The result should be similar to the\u00a0picture.
Locate part\u00a0G.
\ud83d\udfe3\u00a0Locate the LED hole on\u00a0Part G.
We\u00a0will\u00a0now\u00a0place\u00a0the\u00a0LED\u00a0into\u00a0the\u00a0slot\u00a0on part\u00a0G.
Warning
Gently push the LED into the LED\u00a0hole located on Part\u00a0G. It should be a snug fit.
The result should be similar to the\u00a0picture.
Info
\ud83c\udfac\u00a0Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-13-mount-the-peristaltic-pump-on-part-o-and-part-l","title":"Chapter 13: Mount the\u00a0Peristaltic Pump\u00a0on\u00a0Part O and\u00a0Part L","text":"\ud83d\udfe2\u00a0Insert the cable of the\u00a0Peristaltic Pump\u00a0into the hole on\u00a0Part O\u00a0and\u00a0then insert the motor block assembly\u00a0of the pump into it.
Warning
\ud83d\udc41 Ensure the correct orientation of\u00a0Part O\u00a0and the\u00a0Peristaltic Pump
\ud83d\udfe1\u00a0A5. Screw\u00a0M2.5X10mm\u00a0CHC - SS
\ud83d\udfe1\u00a0B3. Allen key 2mm B3
\ud83d\udfe2\u00a0Insert the two\u00a0M2.5X10mm\u00a0in the\u00a0two holes.
Screw the two\u00a0M2.5X10mm\u00a0into the\u00a0two holes.
\ud83d\udd34\u00a0Lay\u00a0the\u00a0Part\u00a0L\u00a0down and make\u00a0sure the pockets in these holes are\u00a0facing upwards.
Insert the\u00a0Peristaltic Pump\u00a0into the\u00a0allocated slot in\u00a0Part L.
Insert the\u00a0Peristaltic Pump\u00a0into the\u00a0allocated slot in\u00a0Part L.
\ud83d\udfe1\u00a0A5.Screw\u00a0M2.5X10mm\u00a0CHC - SS
\ud83d\udfe1\u00a0B3.Allen key 2mm
Screw the four M2.5X10mm in the\u00a0located\u00a0holes\u00a0attaching\u00a0the\u00a0Part\u00a0O\u00a0to\u00a0the\u00a0Part L Peristaltic Pump.
The result should be similar to the\u00a0picture.
Info
We will use this part in the next step.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-14-spiral-wrap-the-led-and-peristaltic-pump-cabling","title":"Chapter 14: Spiral wrap the LED and Peristaltic Pump cabling","text":"Continue wrapping around the\u00a0cables until you have used all of the\u00a0spiral wrap, leaving small or no gaps.
Info
The result should look the same as\u00a0the picture.
Info
The result should look the same as\u00a0the picture.
Note
\ud83c\udfac\u00a0Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-15-attaching-the-stepper-motors-to-the-raspberry-pi-camera","title":"Chapter 15: Attaching the\u00a0Stepper Motors\u00a0to the\u00a0Raspberry Pi Camera","text":"Locate the Stepper Motors with\u00a0mount, and the Raspberry Pi\u00a0Camera.
Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.
Warning
Make sure the orientation is\u00a0correct and matches the picture.
Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.
Warning
Make sure the orientation is\u00a0correct and matches the picture.
Then\u00a0insert\u00a0the\u00a0cylindrical\u00a0parts\u00a0of\u00a0the\u00a0Stepper Motor into the slots.
Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.
Warning
Make sure the orientation is\u00a0correct and matches the picture.
Then\u00a0insert\u00a0the\u00a0cylindrical\u00a0parts\u00a0of\u00a0the\u00a0Stepper Motor into the slots.
Note
The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-16-connecting-the-raspberry-pi-camera-to-the-raspberry-pi-hat","title":"Chapter 16: Connecting the\u00a0Raspberry Pi Camera\u00a0to the\u00a0Raspberry Pi HAT","text":"Gently feed the\u00a0Ribbon Cable\u00a0into the\u00a0port of the\u00a0Camera.
Warning
\ud83d\udc41 Ensure the correct orientation of\u00a0the\u00a0Ribbon Cable\u00a0with the blue end\u00a0facing upwards.
\ud83d\udd34\u00a0Press down on the black\u00a0connector on the Raspberry Pi\u00a0camera board once the Ribbon\u00a0Cable is in position.
\ud83d\udd34\u00a0B1.Small flat screwdriver 2mm
Warning
Hold tight, a specific order is\u00a0required.
Starting with the\u00a0red cable, insert the\u00a0cable in the far left port and tighten\u00a0the screw situated above the port.
Note
The result should look the same as\u00a0the picture.
Repeat this process with the order\u00a0pictured here from left to right:\u00a0\ud83d\udd34 Red\u00a0\ud83d\udfe1 Yellow\u00a0\ud83d\udd35 Blue\u00a0\u26ab Black.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-17-connect-the-led-and-peristaltic-pump-to-the-raspberry-pi","title":"Chapter 17: Connect the\u00a0LED\u00a0and\u00a0Peristaltic Pump\u00a0to the\u00a0Raspberry Pi","text":"We will now be connecting the LED\u00a0and Peristaltic Pump with the\u00a0Raspberry Pi HAT\u00a0and\u00a0Camera.
Place the LED housing onto the\u00a0Stepper Mounts.
Warning
\ud83d\udc41 Ensure correct orientation of both\u00a0\ud83d\udfe3 parts by looking at the\u00a0precut holes.
Info
The result should be similar to the\u00a0picture.
Now we will plug in the\u00a0LED and\u00a0Stepper Mount\u00a0cables to the\u00a0Raspberry Pi.
Feed the area of cabling that is not\u00a0covered by the\u00a0spiral wrap\u00a0through\u00a0the two holes to start. Then thread\u00a0through to the\u00a0spiral wrap\u00a0so that it\u00a0matches the picture.
We will now plug the cables into the\u00a0correct ports.
\ud83d\udfe3\u00a0The four wires (\ud83d\udd34 Red\u00a0\ud83d\udd35 Blue \ud83d\udfe2 Green \u26ab Black) enter the side port on the\u00a0Raspberry Pi HAT.
\ud83d\udd34 The two wires (LED) enter on the\u00a0port on top of the Raspberry Pi HAT.
The result should be similar to the\u00a0picture.
Note
We will use this assembly in the next\u00a0step.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-18-connect-the-dc-power-jack-to-the-raspberry-pi","title":"Chapter 18: Connect the\u00a0DC Power Jack\u00a0to the\u00a0Raspberry Pi","text":"\ud83d\udd34\u00a0B1.Small flat screwdriver 2mm
Info
The result should be similar to the\u00a0picture.
Note
We will use this assembly in the next\u00a0step.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-19-your-planktoscope-starts-to-take-shape","title":"Chapter 19: Your PlanktoScope starts to take shape","text":"Locate Part I\u00a0and\u00a0Part H.
\ud83d\udd34 Slot the\u00a0Peristaltic Pump\u00a0above\u00a0the\u00a0LED.
Note
The result should be the same as the\u00a0picture.
Warning
\ud83d\udc41 Ensure the correct orientation of\u00a0the housing and the\u00a0Peristaltic Pump.
At the other end, slot the\u00a0DC Power\u00a0Jack\u00a0housing adjacent to the\u00a0Raspberry Pi.
Rotate so that the DC Power Jack is\u00a0facing upwards. We will now slot the Raspberry Pi onto\u00a0the rest of the housing.
Info
The result should be similar to that\u00a0picture.
Note
\ud83c\udfac\u00a0Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-20-inserting-screws","title":"Chapter 20: Inserting screws","text":"\ud83d\udfe3 We\u00a0will\u00a0now\u00a0insert\u00a0eight\u00a0M3\u00a0screws\u00a0to fasten the housing together.
Note
\ud83c\udfac\u00a0Store this assembly for later.
\ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS
\ud83d\udfe1\u00a0B3. Allen key 2mm
Info
The result should be similar to the\u00a0picture.
We will now turn over the\u00a0PlanktoScope\u00a0and\u00a0repeat\u00a0the\u00a0process\u00a0for the underside.
\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0underside.
Info
The result should be similar to the\u00a0picture.
Now turn the PlanktoScope on its side.
Warning
\ud83d\udc41 Ensure the orientation of your\u00a0PlanktoScope and\u00a0Part K\u00a0matches\u00a0the picture.
Slot\u00a0Part K\u00a0onto the rest of the\u00a0PlanktoScope.
Warning
\ud83d\udfe2\u00a0Ensure the correct orientation. The\u00a0result should look the same at the\u00a0picture.
Content of\u00a0Bag A: \ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS
Content of\u00a0Bag B: \ud83d\udfe1\u00a0B3. Allen key 2mm
\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0side to hold\u00a0Part K\u00a0in place.
We will now place\u00a0Part J\u00a0into position\u00a0as the housing for the side.
Warning
\ud83d\udc41 Ensure your PlanktoScope matches\u00a0the orientation in the picture.
\ud83d\udfe2 Place\u00a0Part K\u00a0onto the rest of the\u00a0PlanktoScope and note the position\u00a0of the cutout.
Content of\u00a0Bag A: \ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS
Content of\u00a0Bag B: \ud83d\udfe1\u00a0B3. Allen key 2mm
\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0underside
Info
The result should be similar to the\u00a0picture.
Content of\u00a0Bag A: \ud83d\udfe1\u00a0A5. Screw M2.5X10mm CHC - SS
Place\u00a0the\u00a0M2.5\u00a0screw\u00a0through\u00a0Part\u00a0N. It\u00a0will\u00a0act\u00a0as\u00a0a\u00a0cover\u00a0for\u00a0the\u00a0electrical\u00a0inputs.
Using the allen key, tighten the screw\u00a0so that it is possible to move the\u00a0cover with light force.
Info
The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-21-insert-the-tubing-in-the-peristaltic-pump","title":"Chapter 21: Insert the tubing in the\u00a0Peristaltic Pump","text":"You can now remove the Peristaltic\u00a0Pump housing and\u00a0\ud83d\udfe2 Rotor.
You can now remove the Peristaltic\u00a0Pump housing and\u00a0\ud83d\udfe2 Rotor.
\ud83d\udd34 Locate the\u00a0Tube\u00a0for the Peristaltic\u00a0Pump in\u00a0Bag F\u00a0and remove it from the\u00a0bag.
Warning
The tips of the Tubing that are\u00a0covered by black rubber are very\u00a0delicate and easily broken.
Insert the first plastic arch of the\u00a0Tube\u00a0into the slot on the Peristaltic Pump\u00a0\\ housing.
Info
The result should be similar to the\u00a0picture.
Insert the\u00a0Rotor\u00a0into the housing\u00a0ensuring the correct orientation. The\u00a0hole in the centre should be visible on\u00a0the underside.
Info
The result should be similar to the\u00a0picture.
Insert the\u00a0Rotor\u00a0into the housing.\u00a0Then, thread the\u00a0Tube\u00a0around the\u00a0Rotor\u00a0and insert the other plastic\u00a0arch into the second slot.
Info
The result should be similar to the\u00a0picture.
Info
The result should be similar to the\u00a0picture.
Place the Peristaltic Pump housing\u00a0back onto the PlanktoScope.
Achieve the angle shown in the\u00a0picture between the Peristaltic Pump\u00a0housing and PlanktoScope main\u00a0body. Then, press and twist in a\u00a0clockwise direction.
Info
The result should be similar to the\u00a0picture.
Push the small piece of tubing from\u00a0Bag D\u00a0over the left-side connector of\u00a0the\u00a0Peristaltic Pump.
Place the long piece of tubing from\u00a0Bag D\u00a0over the right-side connector\u00a0of the\u00a0Peristaltic Pump.
Insert the connector from\u00a0Bag D\u00a0into\u00a0the other end of the\u00a0small piece of\u00a0tubing.
Orientate\u00a0Part P\u00a0so that the magnets\u00a0are face-down on the left-hand side.
Place Part P over the magnets\u00a0adjacent to the\u00a0Peristaltic Pump.
Info
The result should be similar to the\u00a0picture.
\ud83d\udd34 From\u00a0Bag M, Place the\u00a0light blue Test Tube in the hole adjacent to the\u00a0Peristaltic Pump.
Place the\u00a0\ud83d\udd35 dark blue Test Tube\u00a0into\u00a0the hole situated outside of the\u00a0PlanktoScope.
\ud83d\udfe2\u00a0Insert the other end of the long\u00a0piece of tubing into the\u00a0\ud83d\udd35 dark blue Test Tube. This will serve as the waste container.\u00a0The result should look the same as\u00a0the picture.
Info
The magnets are raised on the\u00a0side where the lens lays flat.
Warning
Try not to touch the lens
Screw the\u00a0Lock Ring\u00a0onto the lens,\u00a0flat-side down.
Info
The\u00a0magnets\u00a0are\u00a0indented\u00a0on\u00a0the\u00a0side that the lens lays flat.
Warning
Try not to touch the lens
Screw the\u00a0Lock Ring\u00a0onto the lens,\u00a0flat-side down.
The result should be similar to that\u00a0picture.
Place\u00a0both\u00a0Lenses (C\u00a0and\u00a0D)\u00a0together\u00a0so that they flat together and both\u00a0lenses are facing each other.
Info
The result should be similar to the\u00a0picture.
Place\u00a0the\u00a0Lenses\u00a0(both\u00a0C\u00a0and\u00a0D)\u00a0into\u00a0position, adjacent to the camera.
The orientation of your PlanktoScope\u00a0and Lenses should match the\u00a0pictures.
Info
The result should be similar to the\u00a0picture.
Info
The Fluidic Path will have a\u00a0cardboard protector.
Please take extra precaution while handling\u00a0this\u00a0part\u00a0and\u00a0avoid\u00a0touching\u00a0the glass element of the piece.
Warning
The Fluidic Path is very delicate.
Place the Tube Clamp over the long\u00a0piece\u00a0of\u00a0tube\u00a0at\u00a0the\u00a0end\u00a0of\u00a0the\u00a0Fluidic\u00a0Path.
Place the white clamp over the long\u00a0piece\u00a0of\u00a0tube\u00a0at\u00a0the\u00a0end\u00a0of\u00a0the\u00a0Fluidic Path.
Info
The result should look the same as\u00a0the picture.
Press down on the Tube Clamp so\u00a0that it clicks into place with just one\u00a0click.
Info
The result should look the same as\u00a0the picture.
Insert\u00a0a\u00a0small\u00a0plastic\u00a0Connector\u00a0into\u00a0the\u00a0end\u00a0of\u00a0the\u00a0tubing,\u00a0below\u00a0the\u00a0Tube\u00a0Clamp.
Make sure the tubing is over the\u00a0Connector.
Info
The result should look the same as\u00a0the picture.
Remove the cardboard protector\u00a0from the\u00a0Fluidic Path.
Warning
A reminder, the glass part of the\u00a0Fluidic\u00a0Path\u00a0is\u00a0very\u00a0delicate.\u00a0Please\u00a0try\u00a0not to touch it.
Place another Connector at the end\u00a0of the tubing.
The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.
\u26a0 Gently place the Fluidic Path in\u00a0the designated indentation on\u00a0Part F.
Warning
Do not touch the glass.\u00a0
If you have tape available, place a\u00a0small\u00a0piece\u00a0at\u00a0the\u00a0the\u00a0bottom\u00a0of\u00a0Part F so that the tubing remains fixed in\u00a0its position.
Avoid placing tape over the glass.
Info
The result should be similar to the\u00a0picture.
To\u00a0insert\u00a0the\u00a0syringe,\u00a0place\u00a0finger\u00a0and\u00a0thumb either side of part F where\u00a0green circle is located. This ensures\u00a0the tubing does not rotate while you\u00a0twist the syringe into position in a\u00a0clockwise direction.
Info
The result should be similar to the\u00a0picture.
The result should look the same as\u00a0the pictures.
Next, you will need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi.
"},{"location":"setup/hardware/v2.5/kit/","title":"Kit Production","text":""},{"location":"setup/hardware/v2.5/kit/#mechanical-structure","title":"Mechanical Structure","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#manufacturing-files","title":"Manufacturing files","text":"Files Description PlanktoScope-Case.dxf PlanktoScope Case export for CNC Milling"},{"location":"setup/hardware/v2.5/kit/#tools","title":"Tools","text":"Tool Specification CNC Milling machine minimum traverse path at a minimum size of 600 mm to 1000 mm End Mill \u00d8 6mm End Mill \u00d8 3mm End Mill \u00d8 2mm End Mill \u00d8 1mm"},{"location":"setup/hardware/v2.5/kit/#material","title":"Material","text":""},{"location":"setup/hardware/v2.5/kit/#wood","title":"Wood","text":"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.
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.
"},{"location":"setup/hardware/v2.5/kit/#finishing","title":"Finishing","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#cnc-workflow","title":"CNC workflow","text":"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:
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
1mm end mill for small holes
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
3500mm/min for 6mm end mills
Load the end mill: Once the appropriate end mill has been selected, it can be loaded onto the spindle of the CNC milling machine.
Set the workpiece: The workpiece should be securely clamped onto the table of the CNC milling machine.
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.
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
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.
"},{"location":"setup/hardware/v2.5/kit/#finnish-of-the-case-parts","title":"Finnish of the case parts","text":""},{"location":"setup/hardware/v2.5/kit/#requirements-for-case-parts","title":"Requirements for case parts","text":""},{"location":"setup/hardware/v2.5/kit/#case-tools","title":"Case tools","text":"Welcome to the PCB production manual for the PlanktoScope Hat!
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.
"},{"location":"setup/hardware/v2.5/kit/#manufacturing-files_1","title":"Manufacturing files","text":"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"},{"location":"setup/hardware/v2.5/kit/#pcb-manufacturing-process","title":"PCB manufacturing process","text":""},{"location":"setup/hardware/v2.5/kit/#placing-an-order","title":"Placing an order","text":"To order a PCB board including assembly, follow these steps:
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.
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.
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.
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.
"},{"location":"setup/hardware/v2.5/kit/#board-dimensions","title":"Board dimensions","text":"65 mm x 100 mm
"},{"location":"setup/hardware/v2.5/kit/#circuit-specifications","title":"Circuit specifications","text":"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 (\u00b5) 35 \u00b5m Internal copper thickness (\u00b5) without IPC Class Class 2"},{"location":"setup/hardware/v2.5/kit/#solder-mask","title":"Solder mask","text":"Property Value Solder mask TOP + BOT Mask colour green Peelable mask without"},{"location":"setup/hardware/v2.5/kit/#marking","title":"Marking","text":"Property Value Silkscreen (ink) TOP + BOT Ink colour white ROHS marking without UL marking without Date marking without"},{"location":"setup/hardware/v2.5/kit/#specific-options","title":"Specific options","text":"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"},{"location":"setup/hardware/v2.5/kit/#quality-assurance","title":"Quality assurance","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#top","title":"Top","text":""},{"location":"setup/hardware/v2.5/kit/#bottom","title":"Bottom","text":""},{"location":"setup/hardware/v2.5/kit/#copper-layer-1","title":"Copper layer 1","text":""},{"location":"setup/hardware/v2.5/kit/#copper-layer-2","title":"Copper layer 2","text":""},{"location":"setup/hardware/v2.5/kit/#mechanical","title":"Mechanical","text":""},{"location":"setup/hardware/v2.5/kit/#component-placement","title":"Component placement","text":""},{"location":"setup/hardware/v2.5/kit/#assembly-of-the-thru-hole-components","title":"Assembly of the Thru-Hole components","text":""},{"location":"setup/hardware/v2.5/kit/#thru-hole-requirements","title":"Thru-Hole Requirements","text":""},{"location":"setup/hardware/v2.5/kit/#thru-hole-tools","title":"Thru-Hole tools","text":"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
"},{"location":"setup/hardware/v2.5/kit/#soldering-of-the-stepper-motor-driver","title":"Soldering of the stepper motor driver","text":"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 \ud83e\udd62. 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.
"},{"location":"setup/hardware/v2.5/kit/#soldering-of-the-motor-driver-sockets","title":"Soldering of the motor driver sockets","text":"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 \ud83e\udd62. 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.
"},{"location":"setup/hardware/v2.5/kit/#soldering-the-connection-sockets","title":"Soldering the connection sockets","text":"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 \ud83e\udd62. 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.
"},{"location":"setup/hardware/v2.5/kit/#soldering-the-raspberry-pi-connector","title":"Soldering the Raspberry Pi connector","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#install-and-solder-the-cooling-fan","title":"Install and solder the cooling fan","text":"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 \u26ab GND, \ud83d\udd34 VCC, \ud83d\udfe1 RPM, \ud83d\udd35 PWM.
Note
If your fan doesn't have a \ud83d\udd35 PWM connector, then that's not a problem, you can just leave it out.
"},{"location":"setup/hardware/v2.5/kit/#solder-the-display-connector","title":"Solder the display connector","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#solder-the-configuration-option-jumpers","title":"Solder the configuration option jumpers","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#you-have-finished-soldering-the-components","title":"You have finished soldering the components","text":"The assembly of the thru-hole components for the planktoscope hat is now complete. The end result should look like this.
"},{"location":"setup/hardware/v2.5/kit/#planktoscope-hard-case","title":"PlanktoScope Hard case","text":""},{"location":"setup/hardware/v2.5/kit/#hard-case-requirements","title":"Hard case Requirements","text":""},{"location":"setup/hardware/v2.5/kit/#hard-case-tools","title":"Hard case tools","text":"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.
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.
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.
"},{"location":"setup/hardware/v2.5/kit/#kit-composition","title":"Kit composition","text":"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!
"},{"location":"setup/software/","title":"PlanktoScope Software","text":"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.
"},{"location":"setup/software/#choosing-an-sd-card-image","title":"Choosing an SD card image","text":"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).
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.
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.
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.
"},{"location":"setup/software/#post-installation-configuration","title":"Post-installation configuration","text":"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.
"},{"location":"setup/software/#next-steps","title":"Next steps","text":"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.
"},{"location":"setup/software/config/","title":"Post-Installation Configuration","text":"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.
"},{"location":"setup/software/config/#hardware-version","title":"Hardware Version","text":"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.
"},{"location":"setup/software/config/#next-steps","title":"Next steps","text":"Now that you have configured the PlanktoScope software, you can proceed to our guide on how to operate your PlanktoScope.
"},{"location":"setup/software/nonstandard-install/","title":"Non-Standard Installation","text":"This page provides instructions for setting up non-standard versions of the PlanktoScope OS on a PlanktoScope. The PlanktoScope project also uses this same process for creating the official PlanktoScope software SD card images used in the standard software installation process.
"},{"location":"setup/software/nonstandard-install/#prerequisites","title":"Prerequisites","text":"This guide assumes that:
If you have not used the PlanktoScope software before, you should first start with the standard software setup process in order to troubleshoot any problems with your PlanktoScope hardware; you can then try the non-standard setup process afterwards.
In order to complete the non-standard setup process, you will need all of the following:
The setup scripts for the PlanktoScope OS assume that you will be setting up the PlanktoScope software on a 64-bit version of the Raspberry Pi OS with Debian version 11 (bullseye), preferably the version released on 2023-03-12. You can choose any of the following three variants of that version of the Raspberry Pi OS, depending on your needs:
The standard PlanktoScope software SD card images are built on the Raspberry Pi OS Lite image, which only provides a command-line interface, without a graphical desktop environment or web browser; because the PlanktoScope's graphical user interface must be accessed from a web browser, you might prefer to use the \"Raspberry Pi OS with desktop\" image in order to have a graphical desktop environment with a web browser. This would allow you to operate the PlanktoScope by plugging in a display, keyboard, and mouse to your Raspberry Pi; otherwise, you will have to connect to the PlanktoScope from another device over Ethernet or Wi-Fi in order access the PlanktoScope's graphical user interface.
Warning
The latest version of Raspberry Pi OS, with Debian version 12 (bookworm), can be downloaded from the Raspberry Pi Operating system images page, but the PlanktoScope software setup scripts do not yet work on Debian version 12; that page also has links named \"Archive\" under the download buttons where you can find older versions with Debian version 11 (bullseye) under the \"Raspberry Pi OS (Legacy)\" section; those links are the same as the links we listed above.
"},{"location":"setup/software/nonstandard-install/#write-the-os-image-to-an-sd-card","title":"Write the OS image to an SD card","text":"Next, you will need to write your downloaded Raspberry Pi OS image file to your microSD card. 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.
To use a graphical application to write the image file to your microSD card, you can install the Raspberry Pi imager. Download the latest version of the Raspberry Pi Imager, install it, and start it. Select the Raspberry Pi OS image file (likely a .img, .img.gz, or .img.xz file) you just downloaded, and select the SD card you want to write the Raspberry Pi OS image to. Review your selections and click the appropriate button to begin writing the Raspberry Pi OS image to the SD card. The process should take several minutes.
If you'd instead prefer to write the image file to your microSD card from a command-line tool, you could instead use a tool like ddrescue on a Debian-based system, e.g. as follows:
gunzip planktoscope-v2.3-final.img.gz\nsudo ddrescue planktoscope-v2.3-final.img /dev/mmcblk0 --force\nWarning: be extremely careful when choosing the storage medium and ensure that you are writing the OS image file to the device which actually corresponds to the correct microSD card. Once the image has been written, data previously on the device will be lost and impossible to recover.
"},{"location":"setup/software/nonstandard-install/#configure-your-raspberry-pi","title":"Configure your Raspberry Pi","text":"Insert the microSD card into your Raspberry Pi and connect your Pi to a screen, a mouse, and a keyboard. Double-check the connections before plugging in power.
The first boot to the desktop may take up to 120 seconds. This is normal and is caused by the image expanding the filesystem to the whole SD card. DO NOT REBOOT before you reach the desktop.
Eventually, the display will ask you to configure some settings for the Raspberry Pi. You will be asked to choose language settings and a keyboard layout; you should choose settings appropriate for you. The standard PlanktoScope SD card images use the en_US.UTF-8 locale and the \"Generic 104-key PC, English (US)\" keyboard layout. The display will also ask you to set a username and password for the default user account on the Raspberry Pi; you must choose pi as the username, and you should choose a password you can remember. By default, the standard PlanktoScope SD card images use copepode as the password - so you may want to choose a different password for better security. Refer to the official Getting Started with your Raspberry Pi guide for additional details and instructions on configuring settings for the Raspberry Pi.
Next, configure your Raspberry Pi to get internet access - your Raspberry Pi will need to download software packages from the internet as part of the installation process for the PlanktoScope OS. If you have an Ethernet cable you can plug into your Raspberry Pi, that will be the simplest option for setup, because it won't require you to edit any files or run any commands on your Raspberry Pi; when we make our official SD card images with the PlanktoScope OS, we use an Ethernet cable. Otherwise, you will need to connect your Raspberry Pi to a wifi network with internet access; you can refer to the Raspberry Pi project's network configuration guide.
"},{"location":"setup/software/nonstandard-install/#set-up-the-planktoscope-os","title":"Set up the PlanktoScope OS","text":""},{"location":"setup/software/nonstandard-install/#run-the-installation-script","title":"Run the installation script","text":"Depending on whether you're installing the software on a PlanktoScope with the PlanktoScope HAT (which is the standard HAT on v2.3 hardware and later) or with the Adafruit Stepper Motor HAT (which is the standard HAT on v2.1 hardware), you will need to adjust the commands below. Specifically, if you're installing the software for a PlanktoScope with the Adafruit Stepper Motor HAT, you will need to replace the word planktoscopehat with the word adafruithat in any of the commands below.
Log in to your Raspberry Pi and (if you installed a version of Raspberry Pi OS with a graphical desktop) open a terminal. Then type in one of the following commands, depending on which release channel you want to use for installation (refer to our technical reference document on release channels to understand which release channel to use):
StableBetaEdgewget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- -v software/stable -H planktoscopehat\nThis will install the most recent stable release of the PlanktoScope OS (or, if the most recent release of the PlanktoScope software is a stable release, to install that stable release). This is recommended for most users.
wget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- -v software/beta -H planktoscopehat\nThis will install the most recent beta prerelease of the PlanktoScope OS (or, if the most recent prerelease/release of the PlanktoScope software is a stable release, to install that stable release). The beta prerelease probably contains bugs which will be fixed before the next stable release.
wget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- -v master -H planktoscopehat\nThis will install the current unstable development version of the PlanktoScope OS. This version is likely to be broken in various ways.
Instead of installing the latest version on the \"stable\", \"beta\", or \"edge\" release channel, you can also install a specific tagged release or pre-release of the PlanktoScope software. For example, to install the v2024.0.0-alpha.1 pre-release of the PlanktoScope software, you would run the following command:
wget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- -t tag -v v2024.0.0-alpha.1 -H planktoscopehat\nYou can also choose to install the PlanktoScope software from some other repository on GitHub instead of github.com/PlanktoScope/PlanktoScope, by using the -r command-line option; for more information including usage examples, you can refer to the reference page for the installation script's command-line parameters, and/or you can get usage instructions by running the following command:
wget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- --help\nThe installation process will take a long time (around 15 - 30 minutes, depending on the speed of your internet connection and your microSD card) to finish.
If an error occurs during this setup process, you will need to wipe the Raspberry Pi's microSD card, flash the Raspberry Pi OS image onto it again, and try running the setup steps again. Otherwise, you will eventually see a message reporting that the setup script finished setting up the PlanktoScope application environment.
"},{"location":"setup/software/nonstandard-install/#connect-to-the-planktoscope","title":"Connect to the PlanktoScope","text":"Next, you will need to restart the Raspberry Pi, e.g. with the following command:
sudo reboot now\nThis step is necessary to finish the PlanktoScope software setup process.
Afterwards, your PlanktoScope's Raspberry Pi will either connect to a Wi-Fi network (if you had previously configured it to connect to a Wi-Fi network) or make a new isolated Wi-Fi network whose name starts with the word pkscope followed by the unique randomly-generated name of your PlanktoScope, and whose password is copepode.
If you connect another device (e.g. a phone or computer) directly to the PlanktoScope's Raspberry Pi over its isolated Wi-Fi network or over an Ethernet cable, 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):
Note that if you had previously configured your PlanktoScope's Raspberry Pi to connect to a Wi-Fi network, it will not make its own isolated Wi-Fi network. On the Wi-Fi network it's connected to, it should be accessible at http://pkscope.local (if you're accessing it from a device and web browser with mDNS support, assuming the device is on the same network), assuming that no other PlanktoScope is connected to the same network. If multiple PlanktoScopes are connected to the same network, open http://pkscope.local and read the web page's \"Wrong PlanktoScope?\" section for instructions on what URL to use; you can determine your PlanktoScope's name by connecting a display to its Raspberry Pi, booting up the Raspberry Pi, and reading the name from the login prompt (e.g. if it says pkscope-chain-list-27764 login:, then the PlanktoScope is named pkscope-chain-list-27764).
You will only be able to access the PlanktoScope's graphical user interface by plugging in a display and keyboard and mouse to the Raspberry Pi if you had previously used a \"Raspberry Pi OS with desktop\" or \"Raspberry Pi OS with desktop and recommended software\" SD card image as the base for the PlanktoScope software's setup script. In that case, you can open a web browser window on the Raspberry Pi and open http://localhost or any of the previously-listed URLs.
"},{"location":"setup/software/nonstandard-install/#next-steps","title":"Next steps","text":"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.
"},{"location":"setup/software/standard-install/","title":"Standard Installation","text":"This page provides instructions for installing the most recent standard version of the PlanktoScope OS on a PlanktoScope.
"},{"location":"setup/software/standard-install/#set-up-the-sd-card","title":"Set up the SD card","text":"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.
"},{"location":"setup/software/standard-install/#prerequisites","title":"Prerequisites","text":"In order to complete this step, you will need all of the following:
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.
"},{"location":"setup/software/standard-install/#write-the-image-to-the-sd-card","title":"Write the image to the SD card","text":"To write the image file to your microSD card:
Once flashing is complete, unmount the SD card and remove it from the computer.
"},{"location":"setup/software/standard-install/#insert-the-sd-card-into-the-planktoscope","title":"Insert the SD card into the PlanktoScope","text":"Insert the microSD card into the Raspberry Pi computer installed in your PlanktoScope.
"},{"location":"setup/software/standard-install/#connect-to-the-planktoscope","title":"Connect to the PlanktoScope","text":"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. The password of this Wi-Fi network is copepode.
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):
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.
"},{"location":"setup/software/standard-install/#next-steps","title":"Next steps","text":"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.
"},{"location":"troubleshooting/","title":"Troubleshooting","text":"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.
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:
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\u2019s still a lot we don\u2019t know about what\u2019s happening with groups of plankton and how they\u2019re 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.
"},{"location":"#what-is-the-planktoscope-project","title":"What is the PlanktoScope project?","text":"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.
"},{"location":"#who-are-planktoscopes-for","title":"Who are PlanktoScopes for?","text":"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!
"},{"location":"faq/","title":"Frequently Asked Questions","text":"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!
"},{"location":"faq/#can-i-purchase-a-planktoscope","title":"Can I purchase a PlanktoScope?","text":"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.
"},{"location":"faq/#where-do-i-get-support-or-find-the-necessary-tools-to-build-planktoscope","title":"Where do I get support or find the necessary tools to build PlanktoScope?","text":"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.
"},{"location":"community/","title":"The PlanktoScope Community","text":"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.
"},{"location":"community/#engage-on-github","title":"Engage on GitHub","text":"Feel free to visit the GitHub and engage if you want.
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.
"},{"location":"community/#chat-on-slack","title":"Chat on Slack","text":"The community is using Slack to communicate.
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.
"},{"location":"community/#classify-on-ecotaxa","title":"Classify on EcoTaxa","text":"To join EcoTaxa, you just need to create an account.
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.
"},{"location":"community/code-of-conduct/","title":"Contributor Covenant Code of Conduct","text":""},{"location":"community/code-of-conduct/#our-pledge","title":"Our Pledge","text":"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.
"},{"location":"community/code-of-conduct/#our-standards","title":"Our Standards","text":"Examples of behavior that contributes to a positive environment for our community include:
Examples of unacceptable behavior include:
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.
"},{"location":"community/code-of-conduct/#scope","title":"Scope","text":"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.
"},{"location":"community/code-of-conduct/#enforcement","title":"Enforcement","text":"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.
"},{"location":"community/code-of-conduct/#enforcement-guidelines","title":"Enforcement Guidelines","text":"Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
"},{"location":"community/code-of-conduct/#1-correction","title":"1. Correction","text":"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.
"},{"location":"community/code-of-conduct/#2-warning","title":"2. Warning","text":"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.
"},{"location":"community/code-of-conduct/#3-temporary-ban","title":"3. Temporary Ban","text":"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.
"},{"location":"community/code-of-conduct/#4-permanent-ban","title":"4. Permanent Ban","text":"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.
"},{"location":"community/code-of-conduct/#attribution","title":"Attribution","text":"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.
"},{"location":"community/license/","title":"Our work is fully open source","text":"That's the headline, yes.
"},{"location":"community/license/#hardware-files","title":"Hardware files","text":"We released our hardware files (everything in the hardware directory) under a CERN OHL-S license.
Our source code (everything in the directories flows and scripts) is released under a GPL-3.0 license.
Everything else is released under a Creative Commons CC-BY-SA license.
"},{"location":"community/trainings/","title":"Trainings","text":"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.
"},{"location":"community/trainings/#the-train-the-trainer-program","title":"The Train the trainer program","text":"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.
"},{"location":"community/trainings/#event-types","title":"Event types","text":""},{"location":"community/trainings/#build-workshop","title":"Build workshop","text":"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.
"},{"location":"community/trainings/#selecting-the-production-site","title":"Selecting the production site","text":"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:
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.
"},{"location":"community/trainings/#material-procurement","title":"Material procurement","text":"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:
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.
"},{"location":"community/trainings/#prepare-the-kit","title":"Prepare the Kit","text":"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:
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.
"},{"location":"community/trainings/#conducting-the-workshop","title":"Conducting the workshop","text":"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!
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!
"},{"location":"community/trainings/#hackathon","title":"Hackathon","text":"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!
"},{"location":"community/trainings/#general-planning-methods","title":"General planning methods","text":"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.
"},{"location":"community/trainings/#building-a-team","title":"Building a team","text":"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.
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.
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.
"},{"location":"community/trainings/#selecting-digital-tools","title":"Selecting digital tools","text":"The right tools can help to facilitate communication, collaboration, and organization, making the workshop experience more productive and enjoyable for everyone.
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.
"},{"location":"community/trainings/#determining-the-need","title":"Determining the need","text":"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:
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.
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.
"},{"location":"community/trainings/#financial-planning","title":"Financial planning","text":"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:
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.
"},{"location":"community/trainings/#creating-a-timetable","title":"Creating a timetable","text":"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:
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:
When announcing the event, it is important to include the following information:
Tip
If you already have a group of interested people, send a link to the announcement via email or chat and invite them personally.
"},{"location":"community/trainings/#preparing-a-presentation","title":"Preparing a presentation","text":"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.
Here are some topics that should be covered in a presentation:
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.
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.
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.
"},{"location":"community/trainings/#follow-up","title":"Follow-up","text":"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:
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:
For more information on how to contribute to this document and improve this training program, please see the contribute section on Writing Documentation.
"},{"location":"community/contribute/documentation/","title":"Writing Documentation","text":"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\nAfter 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.
"},{"location":"community/contribute/documentation/#extensions-available","title":"Extensions available","text":"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.
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.
"},{"location":"community/contribute/github/#assumptions","title":"Assumptions","text":"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.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.
"},{"location":"community/contribute/github/#git-commits","title":"Git Commits","text":"As minimal requirements, your commit message should:
We don't follow any other convention, but if you want to use one, we recommend this one.
"},{"location":"community/contribute/github/#pull-requests","title":"Pull Requests","text":"Some notes on PRs:
master before merging. Fortunately, this project integrates a bot to automatically enforce this requirement without the PR author having to do it manually.PlanktoScope tools follow the Semantic Versioning Convention.
"},{"location":"community/contribute/github/#automation-to-rebase-and-merge-the-prs","title":"Automation to Rebase and Merge the PRs","text":"This project integrates a bot that helps us manage pull requests merging. Read more about this.
"},{"location":"community/contribute/github/#how-to-publish-the-release","title":"How to Publish the Release","text":"\u26a0\ufe0f Before doing anything, make sure you got through the guide about Releasing an Integration.
\u26a0\ufe0f 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 \u2764\ufe0f
"},{"location":"community/contribute/hardware/","title":"Hardware Development","text":""},{"location":"community/contribute/hardware/#planktoscope-case","title":"PlanktoScope Case","text":"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:
By following these steps, you will be able to successfully install a development environment and participate in the PlanktoScope Case using Autodesk Fusion 360.
"},{"location":"community/contribute/hardware/#planktoscope-hat","title":"PlanktoScope Hat","text":"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:
By following these steps, you can set up a development environment that allows you to contribute to the PlanktoScope Hat using Autodesk Eagle.
"},{"location":"community/contribute/software/","title":"How to help development for the PlanktoScope code","text":"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!)
"},{"location":"community/contribute/software/#node-red","title":"Node-Red","text":"Node-Red is our main process. We use the flow to manage our user interface through a dashboard instance.
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:
sudo apt-get install nodejssudo apt-get install npmsudo npm install -g --unsafe-perm node-rednode-redBy 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.
"},{"location":"community/contribute/software/#python","title":"Python","text":"The python code is separated in four main processes, each with a specific set of responsibilities:
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.
"},{"location":"operation/","title":"Operation","text":"This page provides basic instructions for operating your PlanktoScope.
"},{"location":"operation/#connect-directly-to-your-planktoscope","title":"Connect directly to your PlanktoScope","text":"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.
"},{"location":"operation/#connect-with-an-ethernet-cable","title":"Connect with an Ethernet cable","text":"You can connect your computer to the PlanktoScope by plugging an Ethernet cable between your computer and your PlanktoScope's Raspberry Pi.
"},{"location":"operation/#connect-with-the-planktoscopes-isolated-wi-fi-network","title":"Connect with the PlanktoScope's isolated Wi-Fi network","text":"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.
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.
Unless you have changed the password of your PlanktoScope's Wi-Fi network, the password should be copepode.
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\u00a0(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\u00a0(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:
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.
"},{"location":"operation/#how-to-image-plankton","title":"How to image plankton","text":"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:
If you want to create an SD card image from your PlanktoScope to use on other PlanktoScopes, you can follow the following steps.
"},{"location":"operation/clone-sd/#prepare-the-sd-card-for-cloning","title":"Prepare the SD card for cloning","text":"Depending on whether you want to make an SD card image to reuse across multiple machines or whether you only want to make an exact backup of your SD card image, you will need to perform different steps to prepare your SD card for cloning.
"},{"location":"operation/clone-sd/#clone-your-sd-card","title":"Clone your SD card","text":""},{"location":"operation/clone-sd/#prepare-for-cloning-to-reuse-in-other-machines","title":"Prepare for cloning to reuse in other machines","text":"Normally, your SD card contains some information (a machine-specific ID, system secrets, and SSH secrets) which should never be replicated across multiple PlanktoScopes, and some information (apt package cache) which you would probably consider a waste of space which unnecessarily increases the size of the SD card image you want to make. We provide a preparation script at /usr/libexec/prepare-custom-image to remove this information; it also allows an SD card image created from your SD card to automatically resize itself to match the size of any SD card it's flashed to in the future. After you make any changes you want to make on your PlanktoScope for your SD card image, you should run the preparation script on the PlanktoScope with the command:
sudo /usr/libexec/prepare-custom-image\nOnce this script finishes running, it will shut down your PlanktoScope's Raspberry Pi.
Next, you should remove the SD card from your PlanktoScope and plug it into another computer, so that you can clone the SD card into an SD card image; this guide assumes that your other computer runs Linux. With your SD card plugged into your other computer, you can mount the SD card's rootfs partition to delete any other sensitive files which were not removed by the /usr/libexec/prepare-custom-image script. For example, you may also want to delete or edit some or all of the following files from the rootfs partition in order to remove any sensitive or machine-specific information:
etc/wpa_supplicant/wpa_supplicant.conf: Wi-Fi configuration and network secrets.home/pi/.ssh/authorized_keys: SSH public keys of devices authorized to remotely connect to the PlanktoScope.home/pi/data/: all images acquired before by the PlanktoScope - this directory may be large, and you probably don't want to copy those datasets across all your other PlanktoScopes.home/pi/.bash_history: Bash command history.home/pi/.python_history: Python command history.home/pi/.gitconfig: Git configuration, which may contain user-specific details.Info
You can also delete the files listed above before running the /usr/libexec/prepare-custom-image script; the effect is the same. Either way, those files will be permanently deleted on your SD card. However, if you want to keep those files on your SD card, you should make backup copies of those files, and then you can copy those files back onto your SD card after you finish cloning the SD card to an image.
Next, proceed to the Make an SD card image section of this guide.
"},{"location":"operation/clone-sd/#prepare-an-exact-backup","title":"Prepare an exact backup","text":"If you want to make an exact backup of your SD card and you don't want to reuse your SD card image across multiple PlanktoScopes, then you shouldn't run the /usr/libexec/prepare-custom-image script: that script will delete some files which you probably want to keep. Instead, you should edit the /boot/cmdline.txt file to add the string init=/usr/lib/raspberrypi-sys-mods/firstboot to the end of the file, for example resulting in a file which looks something like:
console=tty1 root=PARTUUID=someuniqueidhere rootfstype=ext4 fsck.repair=yes rootwait init=/usr/lib/raspberrypi-sys-mods/firstboot\nNext, you should remove the SD card from your PlanktoScope and plug it into another computer, so that you can clone the SD card into an SD card image; this guide assumes that your other computer runs Linux. Then proceed to the Make an SD card image section of this guide.
Warning
After you have finished cloning the SD card to an SD card image, you should edit the /boot/cmdline.txt file to remove the init=/usr/lib/raspberrypi-sys-mods/firstboot string, before booting up the Raspberry Pi with your SD card again. This will prevent the first-boot script from deleting the SSH server keys already on your SD card.
Now that your SD card is plugged into a Linux computer, you will need to determine the path of the device file corresponding to your SD card. Usually it will look something like /dev/mmcblk0, /dev/sda, or /dev/sdb; it should always be some file in /dev. To identify the device file for your SD card, run the command sudo fdisk -l in your terminal. The output may look something like:
Disk /dev/nvme0n1: 1.82 TiB, 2000398934016 bytes, 3907029168 sectors\nDisk model: WD_BLACK SN770 2TB\nUnits: sectors of 1 * 512 = 512 bytes\nSector size (logical/physical): 512 bytes / 512 bytes\nI/O size (minimum/optimal): 512 bytes / 512 bytes\nDisklabel type: gpt\nDisk identifier: D18C4567-ADF2-4987-987F-CDA411988C8E\n\nDevice Start End Sectors Size Type\n/dev/nvme0n1p1 2048 1230847 1228800 600M EFI System\n/dev/nvme0n1p2 1230848 3327999 2097152 1G Linux filesystem\n/dev/nvme0n1p3 3328000 3907028991 3903700992 1.8T Linux filesystem\n\nDisk /dev/mmcblk0: 58.29 GiB, 62587404288 bytes, 122241024 sectors\nUnits: sectors of 1 * 512 = 512 bytes\nSector size (logical/physical): 512 bytes / 512 bytes\nI/O size (minimum/optimal): 512 bytes / 512 bytes\nDisklabel type: dos\nDisk identifier: 0xa2033091\nTo determine which disk device corresponds to your SD card, you should check the size of each device to find the one which approximately matches the size of your SD card. In the above example, the 64 GB SD card is at /dev/mmcblk0.
Next, you should unmount the SD card from your system (or ensure that the device is already not mounted on your system). If you're unsure whether the SD card is mounted, you should use the umount command. For example, if your device is /dev/mmcblk0, you will need to run:
sudo umount /dev/mmcblk0p1\nsudo umount /dev/mmcblk0p2\nIf the devices were already not mounted, you should expect to see (and you can safely ignore) error messages which look like:
umount: /dev/mmcblk0p1: not mounted.\numount: /dev/mmcblk0p2: not mounted.\nTo clone the Raspberry Pi's SD card to an image file which you can write to other SD cards, you should follow the instructions at https://github.com/mgomesborges/raspberry-pi/blob/master/setup/clone-sd-card.md or https://raspberrytips.com/create-image-sd-card/ . For example, if you are using a Linux computer and the SD card shows up as /dev/mmcblk0, you could run the following command (replacing file paths and names accordingly):
sudo dd bs=4M if=/dev/mmcblk0 of=/some/path/here/image-name-here.img status=progress\nThis will create a .img file (at /some/path/here/image-name-here.img) as large as your SD card - make sure you have enough space on your hard drive for the file! If your SD card is large, this process may take a long time; this greatly depends on the speed of your SD card reader. For example, a slow SD card reader may take 30 minutes in order to clone a 32 GB SD card.
In order to make the SD card practical to share, you should shrink and compress the SD card image file using the PiShrink tool. For example, on Linux you could run the following set of commands (again replacing file paths and names accordingly):
cd /some/path/here\nwget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh\nchmod +x pishrink.sh\nsudo ./pishrink.sh -za image-name-here.img\nIf you had set up the PlanktoScope software on a Raspberry Pi OS Lite image, you should get a image-name-here.img.gz file which is at least 2 GB in size.
You can now use this SD card image with the non-standard installation guide for installing the PlanktoScope OS on an SD card for one or more PlanktoScopes.
"},{"location":"operation/maintenance/","title":"Maintenance and Repair","text":"Instructions for maintaining and repairing the PlanktoScope.
"},{"location":"operation/maintenance/#cleaning-the-optics","title":"Cleaning the optics","text":"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.
"},{"location":"operation/sample-collection/","title":"Sample collection","text":"The most common way to collect samples for the PlanktoScope is to use a plankton net.
"},{"location":"operation/sample-collection/#plankton-net","title":"Plankton Net","text":"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.
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.
"},{"location":"operation/user-interface/","title":"User interface guide","text":"This guide will help you understand how to use the Node-RED dashboard, which is the primary user interface for operating the PlanktoScope.
"},{"location":"operation/user-interface/#home","title":"Home","text":"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):
Tip
This list is also available from any other tab and allows you to quickly navigate between tabs.
"},{"location":"operation/user-interface/#machine-shutdown","title":"Machine shutdown","text":"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 if you turn off power without shutting down the machine through the software!
To shutdown the machine, first unlock the shutdown button by clicking on \"Unlock Button\".
You can then click on \"Shutdown\". The machine will ask for a final confirmation and will then shut itself down.
"},{"location":"operation/user-interface/#sample-tab","title":"Sample Tab","text":"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.
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.
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.
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.
"},{"location":"operation/user-interface/#optic-configuration","title":"Optic Configuration","text":"This page allows you to control the optical setup of the acquisition.
In the Optic Characterization block, you can control to turn the light on or not. You also have to choose the optics in use in the machine.
Warning
For now, the characteristics shown here are not true values (except if you use the 25mm/16mm lens couple).
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\".
"},{"location":"operation/user-interface/#fluidic-acquisition","title":"Fluidic Acquisition","text":"Finally, this is where the magic happens! You will be able to chose the final parameters of your capture.
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.
"},{"location":"operation/user-interface/#gallery","title":"Gallery","text":"This simple page will allow you to preview and download the captured data.
"},{"location":"operation/user-interface/#system-monitoring","title":"System Monitoring","text":"This tab allows you to monitor the physical characteristics of the machine and follow the processor load, CPU temperature, memory use and disk usage.
You also can find information about the software version you are using, the machine name and its camera.
"},{"location":"operation/user-interface/#wifi","title":"Wifi","text":"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 Personal security is supported; Wi-Fi networks without passwords are not supported.
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.
"},{"location":"operation/user-interface/#administration","title":"Administration","text":"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.
"},{"location":"operation/user-interface/#hardware-settings","title":"Hardware Settings","text":"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.
"},{"location":"reference/","title":"Technical Reference","text":"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.
"},{"location":"reference/#key-features","title":"Key Features","text":"Here are some key features of the PlanktoScope:
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:
"},{"location":"reference/hardware/changelog/#v26","title":"v2.6","text":"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.
"},{"location":"reference/hardware/changelog/#v25","title":"v2.5","text":"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.
"},{"location":"reference/hardware/changelog/#v24","title":"v2.4","text":"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.
"},{"location":"reference/hardware/changelog/#v23","title":"v2.3","text":"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.
"},{"location":"reference/hardware/changelog/#v22","title":"v2.2","text":"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.
"},{"location":"reference/hardware/changelog/#v21","title":"v2.1","text":"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.
"},{"location":"reference/hardware/changelog/#v10","title":"v1.0","text":"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.
"},{"location":"reference/hardware/hat/","title":"PlanktoScope Hat Hardware","text":""},{"location":"reference/hardware/hat/#buses-and-gpio-pinout","title":"Buses and GPIO pinout","text":""},{"location":"reference/hardware/hat/#i2c1-bus","title":"I2C1 Bus","text":""},{"location":"reference/hardware/hat/#rtc-rv-3028-c7","title":"RTC RV-3028-C7","text":"Address 0x52 Configured through a kernel driver.
"},{"location":"reference/hardware/hat/#oled-display","title":"OLED Display","text":"Address 0x3c
"},{"location":"reference/hardware/hat/#led-control-lm36011","title":"LED control: LM36011","text":"Address 0x64 Control through specific software, current range from 0 to 376mA in normal mode, up to 1.5A in flash mode.
"},{"location":"reference/hardware/hat/#spi0-bus","title":"SPI0 Bus","text":""},{"location":"reference/hardware/hat/#motor-controller-0-tmc5160","title":"Motor Controller 0: TMC5160","text":"Chip Enable: SPI0_CE0 Motor Enable: GPIO23
Diagnostic output: GPIO16 for Error output GPIO20 for Stall output
"},{"location":"reference/hardware/hat/#motor-controller-1-tmc5160","title":"Motor Controller 1: TMC5160","text":"Chip Enable: SPI0_CE1 Motor Enable: GPIO5
Diagnostic output: GPIO16 for Error output GPIO20 for Stall output
"},{"location":"reference/hardware/hat/#gpio","title":"GPIO","text":""},{"location":"reference/hardware/hat/#fan-control","title":"Fan control","text":"PWM1 control through GPIO13
"},{"location":"reference/hardware/hat/#led-output-selection","title":"LED Output selection","text":"GPIO18: high for LED1, low for LED2
"},{"location":"reference/hardware/hat/#led-strobe","title":"LED Strobe","text":"GPIO22 for pulse
"},{"location":"reference/hardware/hat/#i2c0-bus","title":"I2C0 Bus","text":""},{"location":"reference/hardware/hat/#eeprom-m24c32","title":"EEPROM M24C32","text":"Address 0x50 For HAT information only.
"},{"location":"reference/hardware/product-specs/","title":"Product Specifications","text":"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.
"},{"location":"reference/hardware/product-specs/#v26","title":"v2.6","text":"Overview:
Enclosure:
Optics:
Imaging characteristics:
Internal camera: Raspberry Pi High Quality Camera
Lenses:
Illumination: white LED
Fluidics:
Flow cell: capillary with rectangular cross-section
Internal tubing:
Peristaltic pump
Other internal electronics:
Embedded computer: Raspberry Pi 4 Model B
Control board: PlanktoScope HAT v1.2
External interfaces & connectivity:
External AC-to-DC power adapter:
Image acquisition throughput:
Samples:
Object size range:
Overview:
Enclosure:
Optics:
Imaging characteristics:
Internal camera: Raspberry Pi High Quality Camera
Lenses:
Illumination: white LED
Fluidics:
Flow cell: capillary with rectangular cross-section
Internal tubing:
Peristaltic pump
Other internal electronics:
Embedded computer: Raspberry Pi 4 Model B
Control board: PlanktoScope HAT v1.2
External interfaces & connectivity:
External AC-to-DC power adapter:
Image acquisition throughput:
Samples:
Object size range:
Overview:
Enclosure:
Optics:
Imaging characteristics:
Internal camera: Raspberry Pi Camera Module 2
Lenses:
Illumination: white LED
Fluidics:
Flow cell: ibidi \u00b5-Slide I Luer channel slide
Internal tubing:
Peristaltic pump
Other internal electronics:
Embedded computer: Raspberry Pi 4 Model B
Control boards:
Adafruit Stepper Motor HAT
Adafruit Ultimate GPS HAT
External interfaces & connectivity:
All notable changes to the PlanktoScope's software will be documented in this file.
The format is based on Keep a Changelog, and this project uses Calendar Versioning with a YYYY.minor.patch scheme for all releases after v2.3.0. All dates in this file are given in the UTC time zone.
/usr/libexec/prepare-custom-image (which must be invoked with sudo) to reset machine-specific files and re-enable partition resizing and shut down the Raspberry Pi, in order to automate common tasks needed for making a custom SD card image from a booted Raspberry Pi running the PlanktoScope OS. Support for this script should be considered experimental - this was mainly added as a workaround to a developer-experience regression introduced after v2023.9.0, in which an additional step is now needed after making an SD card image from a previously-booted SD card, or else the image will result in an error message loop (\"Partition #2 contains a ext4 signature\") during boot and will be unable to resize the image above 8 GB. That step is now included by the added script. Creation of custom SD card images from booted PlanktoScope OS images should still be considered an experimental workflow which may experience breaking changes to the developer experience at any time.ecotaxa_export.tsv filename for all metadata TSV files.planktoscopehat SD card image, the Node-RED dashboard's homepage now asks the user to set the hardware version (choosing between v2.3, v2.5, and v2.6) as a first-boot setup step; this dialog replaces the navigation buttons on the homepage until a hardware version is set.fairscope-latest SD card image is now provided which is identical to the planktoscopehat SD card image, except that its default settings configuration file is for the v2.6 PlanktoScope hardware (so that the homepage does not ask the user to choose a hardware version).factory-reset staged pallet bundle.planktoscope.local mDNS name was deprecated in v2023.9.0-beta.1, but now it's un-deprecated (i.e. official support for this name is added back to the project). As before, you can still use pkscope.local or the machine-specific mDNS name (of format pkscope-{machine-name}.local) instead of planktoscope.local.planktoscopehat SD card image has been reverted to be for the v2.5 PlanktoScope hardware (reverting a change made for v2024.0.0-alpha.2); in v2024.0.0-alpha.2, it was for the v2.6 hardware, while in previous versions it was still for the v2.5 hardware..img.xz files) rather than gzip compression (as .img.gz files).planktoscopehat SD card image, a hardware version is no longer set in the default config.json file provided on the image. Instead, the user must select their hardware version when they open the Node-RED dashboard's homepage for the first time.gcc has been removed from the SD card image, to help reduce SD card image size.config.json file should now be properly displayed as the default selection on the Node-RED dashboard's \"Fluidic Acquisition\" page.machine-name binary is no longer provided by the OS setup scripts, but instead is provided by Forklift for upgradeability (by upgrading the pallet applied to the Raspberry Pi) & removeability/replaceability (by switching to a different pallet which provides a different version of - or does not provide - the machine-name)./etc/hostname-template./etc/cockpit/cockpit.conf.d, and adding origins to allow in /etc/cockpit/origins.d, and adding templated origins (with string interpolation for the machine name, the hostname, and the custom domain) to allow in /etc/cockpit/origins-templates.d./etc/dnsmasq-templates.d, and by modifying the custom domain (which defaults to pkscope) in /etc/custom-domain./etc/hostapd/hostapd.conf.d, and adding templated drop-in files (with string interpolation for the machine name, the hostname, and the custom domain) in /etc/hostapd/hostapd.conf-templates.d./etc/hosts.d, and and adding templated snippets (with string interpolation for the machine name, the hostname, and the custom domain) in /etc/hosts-templates.d.pipeline-subtract-consecutive-masks feature flag in the apps/ps/backend/proc-segmenter package deployment of the local Forklift pallet and re-apply the pallet.planktoscopehat SD card image is now for the v2.6 PlanktoScope hardware; previously, it was still for the v2.5 hardware./etc config files, and some scripts in /usr are now managed by Forklift./etc is now a overlay filesystem with all manually-edited files saved at /var/lib/overlays/overrides/etc./usr is now a overlay filesystem with all manually-edited files saved at /var/lib/overlays/overrides/usr.pscopehat has been replaced with planktoscopehat everywhere. This means that any distro setup scripts/commands you previously used with pscopehat should be changed.picamera2 instead of raspimjpeg for camera control. This may require different ISO and white balance gains to be used. It also no longer limits the framerate of the camera preview, so the preview stream should adapt to the bandwidth available on your network connection and the system resources available to your web browser; this may increase resource usage on your web browser.planktoscopehat SD card image is now for the v2.6 PlanktoScope hardware; previously, it was (incorrectly) a mixture of v2.5 and v2.6 optical settings.lynx as an alternative terminal web browser to w3m for trying to work through captive portals on the Cockpit terminal.sudo.ufw has been replaced with firewalld. However, firewalld has not yet been properly configured./var/lib/planktoscope/machine-name instead of /home/pi/.local/etc/machine-name, and it's now saved without a trailing newline.cockpit-storaged, which was not useful enough to justify the number (and size of) unneeded dependencies it pulled in for the PlanktoScope software SD card image.apt-get update commands for a very minor speed-up in the distro setup process.sample_total_volume metadata field for all sample types, not just horizontal Plankton tows (corresponding to the \"Plankton net\", \"High Speed Net\", and \"Tara decknet\" sample types).dhcpcd service had started)./etc/hosts file and the hostname based on the machine name has now been split into two separate system services, planktoscope-org.update-hosts-machine-name.service and planktoscope-org.update-hostname-machine-name.service.(this release involves no changes from v2023.9.0-beta.2; it's just a promotion of v2023.9.0-beta.2 to a stable release)
"},{"location":"reference/software/changelog/#v202390-beta2-2023-12-02","title":"v2023.9.0-beta.2 - 2023-12-02","text":""},{"location":"reference/software/changelog/#added_4","title":"Added","text":"pscopehat builds of the PlanktoScope distro.v2023.9.0-beta.1) when the version is tagged, or else a pseudoversion (e.g. v2023.9.0-beta.1-36-gf276e84) which contains an abbreviated commit SHA and a list of the number of commits since the last tagged version. This version string is now also used for the acq_software metadata field.process_commit metadata field is now set once again. Now it depends on the new installer script provided by the github.com/PlanktoScope/install.planktoscope.community repo.process_source metadata field is no longer hard-coded in the Node-RED dashboard. Now it depends on the new installer script provided by the github.com/PlanktoScope/install.planktoscope.community repo./home/pi/PlanktoScope.pkscope.local from any web browser where planktoscope.local previously worked. We recommend using http://pkscope.local instead of http://planktoscope.local to access your PlanktoScope, for consistency with other domain name formats (see the \"Changes\" section for details)./home/pi/.local/etc/machine-name. It's updated when the PlanktoScope boots.home.planktoscope and {machine-name}.planktoscope (e.g. http://metal-slope-23501.planktoscope) has been changed from planktoscope to pkscope, so that the domain names are now of format home.pkscope and {machine-name}.pkscope. Similarly, the machine-specific mDNS name has been changed from format planktoscope-{machine-name}.local to pkscope-{machine-name}.local.PlanktoScope {machine-name} to the format pkscope-{machine-name}. This makes it easier to determine the machine-specific mDNS URL: just add .local, to get pkscope-{machine-name}.local (e.g. pkscope-metal-slope-23501.local).planktoscope to pkscope./home/pi/.local/etc/hostapd/ssid.snippet, instead of /home/pi/.local/bin/update-ssid-machine-name.sh.planktoscope.local mDNS name is no longer recommended. We will continue to support it for the foreseeable future (and definitely for at least one year), but we recommend using pkscope.local or the machine-specific mDNS name (of format pkscope-{machine-name}.local) instead./home/pi/.local/etc/cockpit/origins file has been removed, because it does not need to be persisted after being generated. Instead, a temporary file is generated and removed after being used./home/pi/.local/etc/hosts file has been removed from the setup files. Instead, it is now automatically generated by the setup scripts.192.168.4.1 and 192.168.5.1 can be used to access your PlanktoScope when your computer is connected directly to it, regardless of whether you are connecting over an Ethernet cable or the PlanktoScope's Wi-Fi hotspot.192.168.4.1 (over Wi-Fi, when running in wireless AP mode), 192.168.5.1 (over Ethernet), and planktoscope.local (over Wi-Fi or Ethernet, from a client device with mDNS support); this meant that Android devices could only connect to the PlanktoScope at 192.168.4.1, as they lack mDNS support. Now, client devices - even those without mDNS support - can connect to the PlanktoScope at home.planktoscope, and/or URLs like clear-field-33719.planktoscope and planktoscope-clear-field-33719.local (where clear-field-33719 is replaced with the PlanktoScope's Raspberry Pi's machine name, which is also part of the name of the PlanktoScope's Wi-Fi network - e.g. \"PlanktoScope clear-field-33719\")./ps/docs/ (so e.g. it's accessible at http://home.planktoscope/ps/docs/)/admin/cockpit/ (so e.g. it's accessible at http://home.planktoscope/admin/cockpit/)./admin/fs/ (so e.g. it's accessible at http://home.planktoscope/admin/fs/)/admin/portainer/ (so e.g. it's accessible at http://home.planktoscope/admin/portainer/). Note that you will need to open Portainer within a few minutes after booting (or rebooting) your PlanktoScope in order to create an admin account for Portainer./ps/data/browse/ (so e.g. it's accessible at http://home.planktoscope/ps/data/browse/ ), and it is now implemented using filebrowser, so that now you can delete folders, download folders, preview images, etc. As before, you can still access this from the \"Gallery\" page of the Node-RED dashboard.http://home.planktoscope or http://planktoscope.local), your browser will show a landing page with a list of links for easy access to the Node-RED dashboard, documentation, other embedded applications, and reference information about your PlanktoScope./ui on port 1880, e.g. with URLs like http://planktoscope.local:1880/ui or http://192.168.4.1:1880/ui; now, it should be accessed via a link on the landing page.hardware.json file, and the Node-RED dashboard will reload the settings; this prevents the hardware.json file from being changed into an inconsistent mixture of settings for different hardware versions, which was the previous (incorrect) behavior. The description on the \"Hardware Settings\" page is also now more specific about what happens when a hardware version is selected.pi and password copepode) for the Node-RED dashboard, the backend's hardware controller, and the backend's segmenter, and links to filebrowser directories for all log files created by the backend's hardware controller and segmenter.http://planktoscope.local:1880 or http://192.168.4.1:1880; now, it should be accessed via a link on the landing page .planktoscope as their hostname. Now, the hostname is of the format planktoscope-<machine-name>, e.g. planktoscope-metal-slope-23501 or planktoscope-plant-range-10581.FR (France) to US (USA).google.com to determine whether the connection was successful, so that the autohotspot script will revert to wireless AP mode if no internet access is available over the Wi-Fi network (e.g. if the connected Wi-Fi network is actually behaving like a captive portal, which would prevent the PlanktoScope from being accessed via a VPN over the internet - in which case the PlanktoScope would become accessible only over an Ethernet cable). This change is meant to make it easier to fix a PlanktoScope's Wi-Fi connection configuration when that configuration makes internet access impossible.1.1.1.1 (the static IP address of Cloudflare DNS, so a ping without DNS lookup) and checking whether the Wi-Fi network assigned an IP address to the Raspberry Pi, and reporting the results. This enables better troubleshooting of internet access issues on Wi-Fi networks./home/pi, but instead to subdirectories for the backend components under /home/pi/device-backend-logs. Note: the locations of log files may be changed again in the future, and/or file logging may be changed to use a different systemd-based mechanism in the future./usr/bin/stepper-disable and /usr/bin/autohotspotN scripts have been moved to /home/pi/.local/bin/release-gpio-steppers.sh and /home/pi/.local/bin/autohotspot.sh, respectively.gpio-init.service systemd service has been renamed to planktoscope-org.init-gpio-steppers.service.en_DK.UTF-8 locale was used for everything. Now it is only used for time, measurements, and paper dimensions, and the en_US.UTF-8 locale is the base locale for everything else. In the future we may provide GUI functionality for changing the base locale./ps/node-red-v2/ui on port 1880, but the embedded image streams and file gallery will not be properly displayed; and you can access the Node-RED editor at path /admin/ps/node-red-v2 on port 1880. However, you should instead access the Node-RED editor and Node-RED dashboard via the links on the PlanktoScope's landing page.planktoscope.local only works for devices connected directly to the PlanktoScope, either via an Ethernet cable or over Wi-Fi when the PlanktoScope is running in wireless AP mode. planktoscope.local no longer works on other networks, such as LANs or mesh VPNs, which the PlanktoScope might be connected to. On such networks, the machine-specific mDNS name (of format planktoscope-<machine-name>.local) should be used instead.hardware.json configuration file). This fixes issue #166 by preventing the Node-RED dashboard from saving an invalid value to the hardware.json file, which would crash the Python hardware controller after the next boot (or after the next time the Python hardware controller was restarted).adafruit-blinka and adafruit-platformdetect dependencies are now updated to their latest version, so that Python hardware controller will work on PlanktoScopes with recent (i.e. post-2021) versions of the Adafruit HAT./etc/wpa_supplicant/wpa_supplicant.conf file when checking if any networks found by scanning matched networks were specified in the wpa_supplicant.conf file; now it ignores them, so that commented-out networks don't incorrectly prevent the autohotspot from going into wireless AP mode./home/pi/data to a USB drive.metadata.json files). A file called integrity.check is created alongside the images. This file contains one line per file, with the filename, its size and a checksum of both its filename and its content./home/pi/data directory.raspimjpeg, controlled through a FIFO pipe/etc/wpa_supplicant/wpa_supplicant.conf file) to connect to an existing wifi network, it will try to connect to the network; and it will only start its own wifi hotspot if it failed to connect.PlanktoScope, and the password to it is now copepode.pi, and the default password is copepode for this user./home/pi/data.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.
"},{"location":"reference/software/product-specs/#v202400","title":"v2024.0.0","text":"Specs for v2024.0.0 are the same as in v2023.9.0, except for the following sections:
Regular operation:
Advanced operations:
Minimum for image acquisition (but not sufficient for on-board image processing):
Minimum for full functionality, including on-board image processing:
Recommended:
Forwards-incompatibilities:
Backwards-incompatibilities:
With minimum supported hardware for full functionality:
Regular operation:
Advanced operations:
Minimum for image acquisition (but not sufficient for on-board image processing):
Minimum for full functionality, including on-board image processing:
Recommended:
Forwards-incompatibilities:
Backwards-incompatibilities:
With minimum supported hardware for full functionality:
Regular operation:
Advanced operations:
Minimum for image acquisition (but not sufficient for on-board image processing):
Minimum for full functionality, including on-board image processing:
Recommended for full functionality:
Forwards-incompatibilities:
With minimum supported hardware for full functionality:
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:
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.
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:
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.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.software/stable branch of the PlanktoScope repository on GitHub will be advanced to the git commit of the \"stable\" release.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.
"},{"location":"reference/software/release-process/#choosing-a-release-channel","title":"Choosing a release channel","text":"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.
"},{"location":"reference/software/release-process/#upgrading-to-a-new-release-or-pre-release","title":"Upgrading to a new release or pre-release","text":"In order to use a new release or pre-release of the PlanktoScope OS, you will need to do one of the following:
Download the new SD card image for that release/pre-release, following the standard installation process.
Create a new custom SD card image for that release/pre-release, following the non-standard installation process.
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.
"},{"location":"reference/software/architecture/os/","title":"Operating System","text":"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:
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).
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.
"},{"location":"reference/software/architecture/os/#boot-sequence","title":"Boot sequence","text":"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 Raspberry Pi 4/5's boot flow, which consists of two bootloader stages to load the Raspberry Pi's firmware from the Raspberry Pi's SD card; in turn, the firmware loads the Linux kernel from the Raspberry Pi's SD card.
Debian's system initialization, which consists of an initramfs stage after the Linux kernel is loaded, followed by a stage for mounting the full filesystem from the Raspberry Pi's SD card and transferring control to the systemd init process as the root user-space process.
The systemd system manager's boot behavior, which initializes all necessary filesystems, drivers, and system services.
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.
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:
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.
forklift","text":"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.
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.
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)
"},{"location":"reference/software/architecture/os/#applying-published-customizations","title":"Applying published customizations","text":"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 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.
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.
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.
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.
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.
"},{"location":"reference/software/architecture/os/#data-processing","title":"Data processing","text":"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:
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.
"},{"location":"reference/software/architecture/os/#security","title":"Security","text":"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 \ud83d\ude43 - if you're interested in computer/network security and you'd like to help us as a volunteer on this project, please contact us!
"},{"location":"reference/software/functionalities/camera-settings/","title":"Camera Settings","text":"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.
The Node-RED dashboard's \"Shutter Speed\" setting, which is specified in units of microseconds (\u03bcs), 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 \u03bcs 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.
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.
"},{"location":"reference/software/functionalities/sample-imaging/","title":"Sample Imaging","text":"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\":
"},{"location":"reference/software/functionalities/sample-imaging/#stop-flow-imaging","title":"Stop-flow imaging","text":"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:
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.
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.
The PlanktoScope will capture and save an image of its entire field-of-view.
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.
"},{"location":"reference/software/functionalities/segmentation/#median-calculation-step","title":"Median-calculation step","text":"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.
"},{"location":"reference/software/functionalities/segmentation/#image-correction-step","title":"Image-correction step","text":"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.
"},{"location":"reference/software/functionalities/segmentation/#mask-calculation-step","title":"Mask-calculation step","text":"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:
\"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.
\"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.
\"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.
\"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.
\"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.
\"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.
"},{"location":"reference/software/functionalities/segmentation/#object-extraction-step","title":"Object-extraction step","text":"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 \u00b5m. 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 \u00b5m per pixel; then the area (in units of \u00b5m2) 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.
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.
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 * \u03c0 * 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 * \u03c0 * 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.
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.
"},{"location":"reference/software/interfaces/exported-metadata/","title":"Exported Metadata","text":"TODO
"},{"location":"reference/software/interfaces/mqtt/","title":"Planktoscope MQTT API Reference","text":"The MQTT API is the primary programming interface for controlling the PlanktoScope. The API is served by the PlanktoScope's Python backend, and data is sent across the API with the following architecture:
flowchart TD\n API[API Client] -->|Command| Broker[MQTT Broker]\n Broker -->|Command| Backend[Python Backend]\n Backend -->|Status Update| Broker[MQTT Broker]\n Broker -->|Status Update| APIMost messages in the MQTT API are organized according to a request-response pattern in which the API client sends a command as a request to take some action, and then the Python backend sends one or more responses as status updates about how the Python backend's state has changed as a result of the command:
Every MQTT message in the PlanktoScope's MQTT API is published on a specific topic, which is a slash-delimited path of strings (e.g. actuator/pump). Every MQTT message in the PlanktoScope's MQTT API carries a payload, which is a JSON object serialized as a string:
action field of the payload object; other fields of the payload object are parameters of the command.status, which is a string containing a status or error message.In the rest of this reference document, we organize our description of the MQTT API into sections corresponding to distinct functionalities of the Python backend:
"},{"location":"reference/software/interfaces/mqtt/#pump","title":"Pump","text":"The Pump API controls the movement of fluid through the PlanktoScope:
actuator/pumpstatus/pumpmove, stopmove command","text":"The move command initiates movement of fluid through the PlanktoScope by driving the PlanktoScope pump's stepper motor. For example, this command makes the pump move 10 mL of fluid forwards through the PlanktoScope's fluidic path, at a rate of 1 mL/min:
{\n \"action\": \"move\",\n \"direction\": \"FORWARD\",\n \"volume\": 10,\n \"flowrate\": 1\n}\nThe move command has the following parameters:
action Specifies the move command. string move direction Direction to run the pump. string FORWARD, BACKWARD volume Total volume of sample to pump before stopping automatically (mL). float 0 < volume flowrate Speed of pumping (mL/min). float 0 < flowrate \u2264 45 mL/min"},{"location":"reference/software/interfaces/mqtt/#move-command-responses","title":"move command responses","text":"The Python backend can send status updates on the status/pump topic, in response to the move command. The status field of such status updates can have any of the following values:
Started The pump has started moving in response to a valid move command. Error, the message is missing an argument One or more required parameters (direction, volume, flowrate) are missing in the move command. Error, The flowrate should not be == 0 An invalid value (0) was provided for the flowrate field. Done The pump has successfully stopped after fully pumping the specified volume of sample. Note: the MQTT API does not yet completely specify error messages in response to invalid values for the direction, volume, and flowrate parameters.
stop command","text":"The stop command interrupts any ongoing movement of fluid through the PlanktoScope and cuts off power to the PlanktoScope pump's stepper motor:
{\n \"action\": \"stop\"\n}\nThe stop command has the following parameters:
action Specifies the stop command. string stop"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses","title":"stop command responses","text":"The Python backend can send status updates on the status/pump topic, in response to the stop command. The status field of such status updates can have any of the following values:
Interrupted The pump has stopped moving in response to a valid stop command, interrupting any ongoing move command.Sent in response to any Pump stop command, and any Imager stop command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates","title":"Non-response status updates","text":"The Python backend can send status updates on the status/pump topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Ready The backend has become ready to respond to Pump commands. Dead The backend will no longer respond to Pump commands."},{"location":"reference/software/interfaces/mqtt/#focus","title":"Focus","text":"The Focus API controls the movement of the sample stage focusing motors in the PlanktoScope:
actuator/focusstatus/focusmove, stopmove command","text":"The move command initiates movement of the focusing stage by a specified displacement. For example, this command makes the stage move up by 0.26 mm at a speed of 1 mm/s:
{\n \"action\": \"move\",\n \"direction\": \"UP\",\n \"distance\": 0.26,\n \"speed\": 1\n}\nThe move command has the following parameters:
action Specifies the move command. string move direction Direction to move the sample stage. string UP, DOWN distance Total distance to move the stage before stopping automatically (in mm). float 0 < distance \u2264 45.0 speed Speed of movement (in mm/s).Defaults to 5. float 0 < speed \u2264 5.0 (optional)"},{"location":"reference/software/interfaces/mqtt/#move-command-responses_1","title":"move command responses","text":"The Python backend can send status updates on the status/focus topic in response to the move command. The status field of such status updates can have any of the following values:
Started The focusing motors have started moving in response to a valid move command. Error The move command is missing the distance and/or direction fields. Done The focusing motors have successfully stopped after moving the specified distance."},{"location":"reference/software/interfaces/mqtt/#stop-command_1","title":"stop command","text":"The stop command interrupts any ongoing movement of the focusing stage and cuts off power to the focusing motors:
{\n \"action\": \"stop\"\n}\nThe stop command has the following parameters:
action Specifies the stop command. string stop"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_1","title":"stop command responses","text":"The Python backend can send status updates on the status/focus topic, in response to the stop command. The status field of such status updates can have any of the following values:
Interrupted The focusing motors have stopped moving in response to a valid stop command, interrupting any ongoing stop command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_1","title":"Non-response status updates","text":"The Python backend can send status updates on the status/focus topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Ready The backend has become ready to respond to Focus commands. Dead The backend will no longer respond to Focus commands."},{"location":"reference/software/interfaces/mqtt/#light","title":"Light","text":"The Light API controls the state of the LED lighting system in the PlanktoScope:
actuator/lightstatus/lighton, offon command","text":"The on command turns on the sample illumination LED. For example:
{\n \"action\": \"on\"\n \"led\": \"1\"\n}\nThe on command has the following parameters:
action Specifies the on command. string on led Specifies the LED to turn on.Defaults to 1. integer 1\u00a0(optional)"},{"location":"reference/software/interfaces/mqtt/#on-command-responses","title":"on command responses","text":"The Python backend can send status updates on the status/light topic in response to the on command. The status field of such status updates can have any of the following values:
Led 1: On The LED turned on successfully. Error with LED number An invalid value was provided for the led field of the command."},{"location":"reference/software/interfaces/mqtt/#off-command","title":"off command","text":"The off command turns off the sample illumination LED. For example:
{\n \"action\": \"off\"\n}\nThe off command has the following parameters:
action Specifies the off command. string off led Specifies the LED to turn on.Defaults to 1 integer 1"},{"location":"reference/software/interfaces/mqtt/#off-command-responses","title":"off command responses","text":"The Python backend can send status updates on the status/light topic in response to the off command. The status field of such status updates can have any of the following values:
Led 1: Off The LED turned off successfully. Error with LED number An invalid value was provided for the led field of the command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_2","title":"Non-response status updates","text":"The Python backend can send status updates on the status/light topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Ready The backend has become ready to respond to Light commands. Dead The backend will no longer respond to Light commands."},{"location":"reference/software/interfaces/mqtt/#imager","title":"Imager","text":"The Imager API controls image acquisition with the PlanktoScope's hardware, as well as the PlanktoScope's camera:
imager/imagestatus/imagersettings, update_config, image, stopFor details on how images are acquired, refer to our technical reference on sample imaging in the PlanktoScope.
Generally, commands should be sent in the following order:
settings command: Configure the camera settings.update_config command: Update the dataset metadata for the next image acquisition.image command: Initiate image acquisition.stop command: Stop any in-progress image acquisition.settings command","text":"The settings command changes the camera settings. The fields iso, shutter_speed, white_balance_gain and white_balance are optional - if a field is omitted, its setting will not be changed. Here's an example of a command with values specified for all fields:
{\n \"action\": \"settings\",\n \"settings\": {\n \"iso\": 100,\n \"shutter_speed\": 40,\n \"white_balance_gain\": { \"red\": 100, \"blue\": 100 },\n \"white_balance\": \"auto\",\n }\n}\nThe settings command has the following parameters:
action Specifies the settings command. string settings iso Simulated ISO image sensitivity. int 0 < iso \u2264 650 (higher values may be accepted for certain cameras) (optional) shutter_speed Exposure time (in \u03bcs). int 125 \u2264 shutter_speed\u00a0(optional) white_balance_gain.red White balance red gain. float 0.0 \u2264 white_balance_gain.red\u00a0\u2264 32.0 (optional) white_balance_gain.blue White balance blue gain. float 0.0\u00a0\u2264\u00a0white_balance_gain.blue\u00a0\u2264 32.0 (optional) white_balance White balance mode. (off\u00a0specifies the use of manual white balance gains) string auto, off\u00a0(optional)"},{"location":"reference/software/interfaces/mqtt/#settings-command-responses","title":"settings command responses","text":"The Python backend can send status updates on the status/imager topic in response to the settings command. The status field of such status updates can have any of the following values:
Camera settings updated The camera settings have been successfully updated. Camera settings error The settings command is missing required parameters. Iso number not valid The provided iso\u00a0value is not allowed. Shutter speed not valid The provided shutter_speed\u00a0value is not allowed. White balance gain not valid The provided white_balance_gain\u00a0object is not valid or has an invalid value. White balance mode {white_balance} not valid The provided white_balance\u00a0value is not allowed."},{"location":"reference/software/interfaces/mqtt/#update_config-command","title":"update_config command","text":"The update_config command sets/changes the metadata which will be saved with the dataset which to be acquired by the next image command. For example:
{\n \"action\": \"update_config\",\n \"config\": {\n \"sample_project\": \"fairscope bzh\",\n \"sample_id\": \"fairscope_bzh_estacade\",\n \"sample_uuid\": \"uuid-1234\",\n \"sample_ship\": \"Fairscope\",\n \"sample_operator\": \"jeremy\",\n \"sample_sampling_gear\": \"net\",\n \"sample_concentrated_sample_volume\": 70,\n \"sample_total_volume\": 100,\n \"sample_dilution_factor\": 10,\n \"sample_speed_through_water\": \"5 knots\",\n \"sample_instrument\": \"PlanktoScope v2.6\",\n \"sample_bottom_depth\": \"N/A\",\n \"sample_depth_min\": 0.1,\n \"sample_depth_max\": 0.5,\n \"sample_temperature\": \"N/A\",\n \"sample_salinity\": \"N/A\",\n \"sample_date\": \"2024-05-15\",\n \"acq_id\": \"fairscope_bzh_estacade_2\",\n \"acq_instrument\": \"PlanktoScope v2.6\",\n \"acq_magnification\": \"1.2\",\n \"acq_camera_id\": \"deep-point-8125\",\n \"acq_camera_lens\": \"N/A\",\n \"acq_software\": \"PlanktoScope v2024.0.0-alpha.1\",\n \"acq_atlas_id\": \"N/A\",\n \"acq_resolution\": \"1080p\",\n \"acq_stacks_count\": \"N/A\",\n \"acq_time_between_frames\": 0.3,\n \"acq_brightness\": \"N/A\",\n \"acq_contrast\": \"N/A\",\n \"acq_sharpness\": \"N/A\",\n \"acq_saturation\": \"N/A\",\n \"acq_gamma\": \"N/A\",\n \"acq_uuid\": \"acq-uuid-5678\",\n \"acq_volume\": 2.50,\n \"acq_imaged_volume\": 1.04,\n \"acq_minimum_mesh\": 300,\n \"acq_maximum_mesh\": 300,\n \"acq_min_esd\": 300,\n \"acq_max_esd\": 300,\n \"acq_camera_name\": \"HQ Camera\",\n \"acq_nb_frame\": 500,\n \"acq_local_datetime\": \"2024-05-15T09:00:00Z\",\n \"acq_caamera_iso\": 400,\n \"acq_camera_shutter_speed\": 500,\n \"object_date\": \"2024-05-15\",\n \"object_time\": \"09:00:00Z\",\n \"object_lat\": 48.7273,\n \"object_lon\": -3.9814,\n \"object_depth_min\": 0.1,\n \"object_depth_max\": 0.5,\n \"process_pixel\": 0.75,\n \"process_datetime\": \"2024-05-15T09:00:00Z\",\n \"process_id\": \"Process01\",\n \"process_uuid\": \"proc-uuid-7890\",\n \"process_source\": \"https://www.github.com/PlanktonPlanet/PlanktoScope\",\n \"process_commit\": \"CommitHash\",\n \"sample_gear_net_opening\": 300,\n \"object_date_end\": \"2024-05-15\",\n \"object_time_end\": \"10:00:00Z\",\n \"object_lat_end\": 48.7274,\n \"object_lon_end\": -3.9815\n }\n}\nThe metadata should contain comprehensive information about the sample, acquisition process, object details, and processing parameters to ensure accurate tracking and reproducibility of the dataset. The update_config command has the following parameters:
Sample information:
Field Description Typesample_project Project name. string sample_id Sample identifier. integer sample_uuid Sample UUID. string sample_ship Ship name. string sample_operator Operator name. string sample_sampling_gear Sampling gear description. string sample_concentrated_sample_volume Concentrated sample volume. float sample_total_volume Total volume. float sample_dilution_factor Dilution factor. float sample_speed_through_water Speed through water. float Acquisition information:
Field Description Typeacq_id Acquisition identifier. integer acq_instrument Acquisition instrument. string acq_magnification Magnification level. string acq_camera_id Camera identifier. integer acq_camera_lens Camera lens. string acq_software Acquisition software. string acq_volume Acquisition volume. float acq_imaged_volume Imaged volume. float acq_minimum_mesh Minimum mesh size. float acq_maximum_mesh Maximum mesh size. float acq_min_esd Minimum equivalent spherical diameter. float acq_max_esd Maximum equivalent spherical diameter. float acq_camera_name Camera name. string acq_nb_frame Number of frames captured. integer acq_local_datetime Local date and time of acquisition. string acq_camera_resolution Camera resolution. string acq_camera_iso Camera ISO setting. float acq_camera_shutter_speed Camera shutter speed. float Object information:
Field Description Typeobject_date Date of the object recording. string object_time Time of the object recording. string object_lat Latitude of the sample location. float object_lon Longitude of the sample location. float object_depth_min Minimum depth of the sample location. float object_depth_max Maximum depth of the sample location. float object_date_end End date of the object recording. string object_time_end End time of the object recording. string object_lat_end End latitude of the sample location. float object_lon_end End longitude of the sample location. float Processing information:
Field Description Typeprocess_pixel Pixel processing method. string process_datetime Date and time of processing. string process_id Processing identifier. integer process_uuid Processing UUID. string process_source Source of processing software or method. string process_commit Commit hash of the software used. string"},{"location":"reference/software/interfaces/mqtt/#update_config-command-responses","title":"update_config command responses","text":"The Python backend can send status updates on the status/imager topic in response to the update_config command. The status field of such status updates can have any of the following values:
Config updated The metadata has been successfully updated. Configuration message error The command is missing the required\u00a0config field. Busy Image acquisition is already in progress, so dataset metadata cannot be changed."},{"location":"reference/software/interfaces/mqtt/#image-command","title":"image command","text":"The image command initiates acquisition of one raw image dataset consisting of a specified number of images, via stop-flow imaging. For example, this command initiates acquisition of 200 images, with 1 mL of sample pumped between each image and an image stabilization period of 0.1 seconds between the end of pumping and the triggering of the image capture for each acquired image:
{\n \"action\": \"image\",\n \"pump_direction\": \"FORWARD\",\n \"volume\": 1,\n \"nb_frame\": 200,\n \"sleep\": 0.1\n}\nA valid update_config command with a unique (object_date, sample_id, acq_id) combination must be sent some time before each image command. If an update_config command has not been sent before the image command, the image command will trigger a \u201cStarted\u201d response status and then do nothing (this is a software bug which needs to be fixed so that an error status is reported instead).
The image command has the following parameters:
pump_direction Direction of sample pumping. string FORWARD, BACKWARD. volume Volume (in mL) of sample to pump between each captured image. float 0 < volume nb_frame Number of frames to capture. integer 0 < nb_frame sleep Duration (in s) to wait after pumping has stopped before saving an image, to allow the sample objects to stabilize in the image. float 0 < sleep"},{"location":"reference/software/interfaces/mqtt/#image-command-responses","title":"image command responses","text":"The Python backend can send status updates on the status/imager topic, in response to the image command. The status field of such status updates can have any of the following values:
Started The image capture process has started successfully. Error At least one field of the\u00a0image\u00a0command is missing or has an invalid value. Error: missing camera No camera is available to use for image acquisition. Configuration update error: object_date is missing! The last time the update_config\u00a0command was sent, it did not have an object_date\u00a0parameter. Configuration update error: Chosen id are already in use! The\u00a0(object_date, sample_id, acq_id)\u00a0combination for the dataset (set by the last update_config\u00a0command) is already used by a previous dataset. Image {index}/{nb_frame} saved to {filename} An image has been successfully captured and saved. Image {index}/{nb_frame} WAS NOT CAPTURED! STOPPING THE PROCESS! An error occurred during image capture; the ongoing image acquisition has finished with failure, resulting in an incomplete dataset. Done The image acquisition finished successfully, resulting in a complete dataset."},{"location":"reference/software/interfaces/mqtt/#stop-command_2","title":"stop command","text":"This message interrupts any in-progress image acquisition routine and stops any ongoing sample pumping.
{\n \"action\": \"stop\"\n}\nThe stop command has the following parameters:
action Specifies the stop\u00a0command. string stop"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_2","title":"stop command responses","text":"The Python backend can send status updates on the status/imager topic, in response to the stop command. The status field of such status updates can have any of the following values:
Interrupted The image capture process was stopped successfully."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_3","title":"Non-response status updates","text":"The Python backend can send status updates on the status/imager topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Starting up The backend will soon attempt to initialize the camera. Error: missing camera A camera was not detected. Ready The camera is now operational, and the backend has become ready to respond to Imager commands. Dead The backend will no longer respond to Imager commands."},{"location":"reference/software/interfaces/mqtt/#segmenter","title":"Segmenter","text":"The Segmenter API controls the processing of acquired images:
segmenter/segmentstatus/segmenter, status/segmenter/object_id, status/segmenter/metricsegmentFor details on how images are processed, refer to our technical reference on image segmentation in the PlanktoScope.
"},{"location":"reference/software/interfaces/mqtt/#segment-command","title":"segment command","text":"The segment command initiates processing of images stored in the specified path, optionally exporting the results to an EcoTaxa-compatible archive. The various settings parameters of this command provide control over the behavior of image processing. For example, this command initiates processing of all images in the /path/to/segment directory:
{\n \"action\": \"segment\",\n \"path\": \"/path/to/segment\",\n \"settings\": {\n \"force\": false,\n \"recursive\": true,\n \"ecotaxa\": true,\n \"keep\": true\n }\n}\nThe segment command has the following parameters:
path Path to the directory of images to process.Defaults to /home/pi/data/img. file path (string) any subdirectory of\u00a0/home/pi/data/img (optional) settings.force Force re-segmentation of already-processed directories, ignoring the existence of\u00a0done\u00a0files which otherwise prevent already-segmented directories from being processed again.Defaults to false. boolean true, false (optional) settings.recursive Process datasets in all subdirectories of\u00a0path.Defaults to true. boolean true, false (optional) settings.ecotaxa Export an EcoTaxa-compatible archive.Defaults to true. boolean true, false (optional) settings.keep Keep ROI files generated when exporting an EcoTaxa-compatible archive. It has no effect if settings.ecotaxa\u00a0is false.Defaults to true. boolean true, false (optional)"},{"location":"reference/software/interfaces/mqtt/#segment-command-responses","title":"segment command responses","text":"The Python backend can send status updates on the status/segmenter topic, in response to the segment command. The status field of such status updates can have any of the following values:
Started The segmentation process has begun. Busy The segmenter is currently running and cannot update configurations. Calculating flat The frame background is being calculated. Segmenting image %s, image %d/%d Segmentation of a specific image is in progress. An exception was raised during the segmentation: %s. An error occurred during segmentation. Done Processing has finished for the specified datasets. As the Python backend performs segmentation, it will repeatedly send additional status updates on the status/segmenter/object_id topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:
object_id A scikit-image region label. integer As the Python backend performs segmentation, it will repeatedly send additional status updates on the status/segmenter/metric topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:
name An object ID, which is a undersctore-delimited concatenation of the name of the raw image which was processed and the object ID reported by status/segmenter/object_id. string metadata Metadata for the object. struct The metadata field of status updates sent on the status/segmenter/metric topic is an object with the following fields:
label Label of the object. integer width Width of the smallest rectangle enclosing the object. integer height Height of the smallest rectangle enclosing the object. integer bx X coordinate of the top left point of the smallest rectangle enclosing the object. integer by Y coordinate of the top left point of the smallest rectangle enclosing the object. integer circ Circularity: (4 \u2217 \u03c0 \u2217 Area) / Perimeter^2. A value of 1 indicates a perfect circle, approaching 0 indicates an elongated polygon. float area_exc Surface area of the object excluding holes, in square pixels. integer area Surface area of the object in square pixels. integer %area Percentage of object\u2019s surface area that is comprised of holes. float major Primary axis of the best fitting ellipse for the object. float minor Secondary axis of the best fitting ellipse for the object. float y Y position of the center of gravity of the object. float x X position of the center of gravity of the object. float convex_area The area of the smallest polygon within which all points in the object fit. integer perim The length of the outside boundary of the object. float elongation The result of dividing the major parameter by the minor parameter. float perimareaexc The result of dividing the perim parameter by the area_exc parameter. float perimmajor The result of dividing the perim parameter by the major parameter. float circex (4 \u2217 \u03c0 \u2217 area_exc) / perim^2. float angle Angle between the primary axis and a line parallel to the x-axis of the image. float bounding_box_area Area of the bounding box enclosing the object. integer eccentricity Eccentricity of the object. float equivalent_diameter Diameter of a circle with the same area as the object. float euler_number Euler number of the object. integer extent Ratio of object area to bounding box area. float local_centroid_col Column position of the local centroid. float local_centroid_row Row position of the local centroid. float solidity Ratio of object area to convex area. float MeanHue Mean hue value of the object. float MeanSaturation Mean saturation value of the object. float MeanValue Mean value (brightness) of the object. float StdHue Standard deviation of the hue value of the object. float StdSaturation Standard deviation of the saturation value of the object. float StdValue Standard deviation of the value (brightness) of the object. float"},{"location":"reference/software/interfaces/mqtt/#stop-command_3","title":"stop command","text":"The stop command interrupts any ongoing image processing. For example:
{\n \"action\": \"stop\"\n}\nThe stop command has the following parameters:
action string \"stop\" Specifies the action to stop segmentation. Warning
The functionality for this command has not yet been implemented. Currently an Interrupted status is sent as a response on the segmenter/segment topic even though no interruption will actual happen.
stop command responses","text":"The Python backend can send status updates on the segmenter/segment topic, in response to the stop command. The status field of such status updates can have any of the following values:
Interrupted The segmentation process was interrupted."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_4","title":"Non-response status updates","text":"The Python backend can send status updates on the status/segmenter topic which are not triggered by any command. The status field of such status updates can have any of the following values:
Ready The backend has become ready to respond to Segmenter commands. Dead The backend will no longer respond to Segmenter commands."},{"location":"reference/software/subsystems/installation/","title":"Installation","text":"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.
"},{"location":"reference/software/subsystems/installation/#installation-bootstrap-script","title":"Installation bootstrap script","text":"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:
The script loads some parameters (set by environment variables and/or corresponding command-line arguments) which set the behavior of the script.
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.
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.
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.
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.
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.
-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:\u00a0github.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\u00a0query-type\u00a0parameter:branch: query should be a branch name (e.g. software/beta).tag: query should be a Git tag name, excluding the tag prefix specified by the tag-prefix\u00a0parameter (e.g. v2024.0.0\u00a0if tag-prefix\u00a0is software\u00a0and the Git tag is\u00a0software/v2024.0.0).hash: query should be a commit hash and may be abbreviated (e.g. 2d6928e).software/stable -t--query-type QUERY_TYPE The type of version query set by the version-query\u00a0parameter.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\u00a0github.com/PlanktoScope/PlanktoScope\u00a0repo currently expect either none, segmenter-only,\u00a0adafruithat,\u00a0planktoscopehat, or fairscope-latest.Default value: planktoscopehat --tag-prefix TAG_PREFIX The prefix for Git version tags when resolving the version query (with query type\u00a0tag) and when resolving tags (for pseudoversion strings).\u00a0Default 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\u00a0parameter) which will be downloaded at the specified commit (set by the version-query\u00a0and query-type\u00a0parameters and - when query-type\u00a0is tag\u00a0- by the tag-prefix\u00a0parameter) 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\u00a0(or including the command-line flag) automatically confirms all prompts.FORCE (or not including the command-line flag) requires user input for confirmation on all prompts.-V--verbose VERBOSE Whether to display additional (verbose) output:VERBOSE=1\u00a0(or including the command-line flag) enables verbose output.VERBOSE (or not including the command-line flag) disables 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.
Currently the installer script creates two YAML files, both in the /usr/share/planktoscope directory.
/usr/share/planktoscope/installer-config.yml records the values of the parameters with which the installer script was invoked:
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\" /usr/share/planktoscope/installer-versioning.yml records information about the version of the PlanktoScope OS's distro setup scripts which was used to install the PlanktoScope OS:
repo The path of the Git repository which provided the distro setup scripts, with any leading protocol string (e.g. https://) removed.Example Values: \"github.com/PlanktoScope/PlanktoScope\"\"github.com/PlanktoScope/PlanktoScope\"commit The full hash of the exact commit which provided the distro setup scripts.Example Values: \"2d6928e596b28f0c4c268fecb588c85215b1027e\"\u00a0(for commit 2d6928e)\"4d8b882616a8374918730bc1c6d300edfd7a523a\"\u00a0(for commit 4d8b882)tag The full name of the Git tag (whose name starts with the prefix set by the tag-prefix\u00a0script parameter) at the exact commit which provided the distro setup scripts, if such a tag exists; otherwise, the empty string (\"\").Example Values: \"software/v2024.0.0-alpha.1\"\u00a0(so commit 2d6928e\u00a0has Git tag software/v2024.0.0-alpha.1)\"\"\u00a0(so commit 4d8b882\u00a0has 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\u00a0script parameter) exists at that commit, this is a version string which just the name of that tag, but with the tag-prefix\u00a0stripped from the name. Otherwise, this is a pseudo-version string with format \"{tag}-{distance}-g{commit}\", where:{tag}\u00a0is the name of the most recent ancestral tag (with a name starting with the prefix set by the tag-prefix\u00a0script parameter) reachable from the commit, but with the tag-prefix\u00a0stripped from the name.{distance}\u00a0distance (in number of commits) between the commit and the most recent ancestral tag.{commit}\u00a0consists of the first seven characters of the hash of the commit.\"v2024.0.0-alpha.1\"\u00a0(so commit 2d6928e\u00a0has Git tag software/v2024.0.0-alpha.1)\"v2024.0.0-alpha.1-4-g4d8b882\"\u00a0(so commit 4d8b882\u00a0is 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)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.
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.
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.
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.
"},{"location":"reference/software/subsystems/startup/#services","title":"Services","text":"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:
"},{"location":"reference/software/subsystems/startup/#software-deployment-execution","title":"Software deployment & execution","text":"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.
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.
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-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.)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:
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 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:
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:
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:
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:
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:
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:
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.
"},{"location":"setup/hardware/","title":"PlanktoScope Hardware","text":"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.
"},{"location":"setup/hardware/#hardware-versions","title":"Hardware versions","text":"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.
"},{"location":"setup/hardware/#hardware-v21","title":"Hardware v2.1","text":"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. Note that this hardware design specifies 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.
"},{"location":"setup/hardware/#hardware-v25","title":"Hardware v2.5","text":"This version includes many design improvements to solve various problems with the v2.1 hardware design, including:
Replacing the ibidi flowcell with a simpler glass capillary flowcell.
Replacing the Adafruit Stepper Motor HAT with a HAT designed specifically for the PlanktoScope (the PlanktoScope HAT).
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.
Making the Raspberry Pi's micro-SD card accessible without requiring disassembly of the PlanktoScope.
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.
"},{"location":"setup/hardware/#choosing-a-version","title":"Choosing a version","text":"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.
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.
After making an assembly kit (if necessary) and building a PlanktoScope from your assembly kit, you should proceed to our software setup guide.
"},{"location":"setup/hardware/index-noguides/","title":"PlanktoScope Hardware","text":"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.
"},{"location":"setup/hardware/v2.1/","title":"Hardware v2.1","text":"This page will help you to build the v2.1 hardware for a PlanktoScope.
"},{"location":"setup/hardware/v2.1/#make-an-assembly-kit","title":"Make an assembly kit","text":"If you do not already have an assembly kit, you will need to make a kit for yourself. Note: you will need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi, as part of the assembly kit.
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.
"},{"location":"setup/hardware/v2.1/#assemble-a-planktoscope-from-a-kit","title":"Assemble a PlanktoScope from a kit","text":"Once you have an assembly kit, you will need to assemble it into a PlanktoScope.
"},{"location":"setup/hardware/v2.1/#next-steps","title":"Next steps","text":"Once you have assembled your PlanktoScope, you can proceed to our operation guide\u00a0to learn how to operate your PlanktoScope.
"},{"location":"setup/hardware/v2.1/assembly/","title":"Assembly guide of the PlanktoScope","text":"You can also use CAD renders and photos from the following links as a supplementary material for this assembly guide:
For the assembly guide below, the pieces of the laser-cut structure are referred to by single-letter labels (A, J, L, K, H, F, E, C, B, N, M, D, G, I) according to the following assignments:
"},{"location":"setup/hardware/v2.1/assembly/#step-1-gather-everything-you-need","title":"Step 1: Gather everything you need","text":"For the full list of all required tools and parts, please refer to the v2.1 hardware kit production guide.
Make sure you have your screwdriver kit, soldering iron, and components ready. Also, remember to flash the PlanktoScope image disk on the SD card before installing the Raspberry Pi.
If you are not familiar with any process, such as soldering, tapping, or wiring, try and familiarize yourself with the topics first.
Soldering deals with high heat and potentially toxic materials, so make sure to use the proper precautions.
"},{"location":"setup/hardware/v2.1/assembly/#step-2-standoff-installation","title":"Step 2: Standoff installation","text":"Place 8 standoffs (M2.5 6mm) into the designated holes on the laser-cut base A. A pair of pliers make the job more comfortable. Do not overtighten as it is possible to crack the base material.
"},{"location":"setup/hardware/v2.1/assembly/#step-3-motor-hat-preparation","title":"Step 3: Motor HAT preparation","text":"Insert and solder the terminal blocks and headers onto the motor driver PCB.
Place the motor driver PCB on to the indicated standoffs.
"},{"location":"setup/hardware/v2.1/assembly/#step-4-magnets-setup","title":"Step 4: Magnets setup","text":"Now is a good time to think about how the magnets will function within the microscope. The magnets in the sample stage will need to attract to the magnets on the flow cell holder. The magnets in the objective holder will need to attract the magnets on the mount. Keep this in mind as you are adding your magnets and tapping your respective M12 holders so your orientation will be correct.
You can now fix your magnets into their appropriate holes on sample stage B. It is recommended to glue the magnets in place. If the magnets are too large to fit in, the holes can be widened with a handheld drill. However, they should be quite snug in place. Before you glue them in place make sure that the polarity is maintained, as they will be impossible to remove after gluing.
"},{"location":"setup/hardware/v2.1/assembly/#step-5-sample-stage-assembly","title":"Step 5: Sample stage assembly","text":"Don\u2019t be alarmed by the color swap, this is the sample stage B. You can now fit the pegs on the driver mounts into the corresponding holes on the sample stage. They should be glued in place with superglue or epoxy. You can spin the shaft to align the driver mounts on the 2 steppers if it helps making the process easier.
You should now have a sample stage and motor assembly that looks like this.
"},{"location":"setup/hardware/v2.1/assembly/#step-6-lenses-tapping-and-mounting","title":"Step 6: Lenses tapping and mounting","text":"You now need to tap the holes for the M12 lenses in stage and mount M and D. It is helpful for alignment to do both the objeDtive and tube lens mount together. It is important to do this as straight as possible. A drop of mineral or olive oil can help the process. Be careful to use a right-hand tap (that goes down when turning clockwise).
You can now screw the objective lens (the 25mm one) in part D.
"},{"location":"setup/hardware/v2.1/assembly/#step-7-camera-preparation","title":"Step 7: Camera preparation","text":"You can now unscrew the lens from the Pi camera, being careful not to disturb the sensor below.
"},{"location":"setup/hardware/v2.1/assembly/#step-8-camera-mount","title":"Step 8: Camera mount","text":"You can mount the camera using the appropriate holes on the camera mount G. Be careful to avoid getting oil or dust on the sensor.
"},{"location":"setup/hardware/v2.1/assembly/#step-9-led-preparation","title":"Step 9: LED preparation","text":"The LED can then be wired up and put into its mount F. If you wire the LED yourself, remember to give enough length to reach the motor driver on the other end of the microscope. You can also add a bit of glue to fix F to the motor mount E at this time to make assembly easier, though it is not required.
Warning
This picture shows the correct wiring for the LED. Please make sure the red wire is on the long pin of the LED.
"},{"location":"setup/hardware/v2.1/assembly/#step-10-vertical-slices-assembly","title":"Step 10: Vertical slices assembly","text":"You can now start placing the motor mount/LED assembly- B,
C,
D,
E,
F,
and G into the base A.
"},{"location":"setup/hardware/v2.1/assembly/#step-11-pump-setup","title":"Step 11: Pump setup","text":"The pump can then be mounted in place on H. Thread the wires through the hole with the pump tubing pointed toward the holes on the mount.
Fix the pump in place.
"},{"location":"setup/hardware/v2.1/assembly/#step-12-pump-mounting","title":"Step 12: Pump mounting","text":"You can now mount the pump on base A.
Your setup should look like this. Don't worry about the wiring, we'll have a look at it in the next step!
"},{"location":"setup/hardware/v2.1/assembly/#step-13-motor-hat-wiring","title":"Step 13: Motor HAT wiring","text":"You will now want to wire the steppers and pump to the terminals on the motor driver board.
Info
The PlanktoScope uses only bipolar stepper motors (with 4 wires coming out, and two coils inside), so you need to identify the two wires working together for each coil. The RepRap Wiki has great information on how to do this, either with a multimeter or without.
You can find more information about stepper motors and how they work in this document.
Tip
If your wires are too short, you can invert the pump and the focus wiring. However, you will have to remember to change the configuration later on.
Tip
Make sure the wires are properly connected by pulling on them a little. They should not come loose.
"},{"location":"setup/hardware/v2.1/assembly/#step-14-raspberry-pi-setup-and-installation","title":"Step 14: Raspberry Pi setup and installation","text":"At this point, you can insert your flashed SD card into your Raspberry Pi. If you did not already flash your SD card with the PlanktoScope OS, refer to our guide for doing so. The heat sink can also be added to the processor.
Mount the Raspberry Pi containing the flashed SD card on the standoffs attached to the laser cut base A.
"},{"location":"setup/hardware/v2.1/assembly/#step-15-standoffs","title":"Step 15: Standoffs","text":"Add 8 standoffs (M2.5 15mm) to fix the motor driver board and the Raspberry Pi to the base.
"},{"location":"setup/hardware/v2.1/assembly/#step-16-camera-flex-cable","title":"Step 16: Camera flex cable","text":"At this point you can use the Pi camera flex cable to connect the camera to the Pi. This is done by gently pulling up the tensioners, inserting the cable in the right orientation, then pushing the tensioners back in place to set the cable. Try not to kink or fold the flex cable too much as it is possible to damage it.
"},{"location":"setup/hardware/v2.1/assembly/#step-17-power-supply-wiring","title":"Step 17: Power supply wiring","text":"The power wires can be wired into place on the motor driver board.
Tip
Make sure the wires are properly connected by pulling on them a little. They should not come loose.
"},{"location":"setup/hardware/v2.1/assembly/#step-18-prepare-the-gps-hat","title":"Step 18: Prepare the GPS HAT","text":"Tip
If you don't have a GPS HAT, you can just skip the assembly steps related to the GPS HAT - the PlanktoScope software will still work without GPS.
Insert the battery to power the GPS HAT and solder the terminal mounts in place.
"},{"location":"setup/hardware/v2.1/assembly/#step-19-install-the-gps-hat","title":"Step 19: Install the GPS HAT","text":"Mount the GPS HAT over the motor driver PCB using the standoffs attached to the laser cut base A.
"},{"location":"setup/hardware/v2.1/assembly/#step-20-install-the-fan-hat","title":"Step 20: Install the Fan HAT","text":"Place the cooling fan HAT above the Raspberry Pi by mounting it to the standoffs on base A.
Warning
Be careful to slide the camera flat cable in the slot in the HAT above the connector.
"},{"location":"setup/hardware/v2.1/assembly/#step-21-secure-the-hats","title":"Step 21: Secure the HATS","text":"Secure the cooling fan HAT and GPS HAT by tightening the 8 screws to the standoffs on base A
"},{"location":"setup/hardware/v2.1/assembly/#step-22-install-back-panel","title":"Step 22: Install back panel","text":"Insert the laser cut border I into base A.
"},{"location":"setup/hardware/v2.1/assembly/#step-23-gps-output-connector","title":"Step 23: GPS output connector","text":"Insert the power and GPS connectors into side plate J.
"},{"location":"setup/hardware/v2.1/assembly/#step-24-install-side-panel","title":"Step 24: Install side panel","text":"Place the side plate J into the designated slots on the base. You can connect the GPS cable to its connector on the board.
Warning
The GPS connector is quite fragile, make sure to align it properly before inserting it.
"},{"location":"setup/hardware/v2.1/assembly/#step-25-install-the-other-side-panel","title":"Step 25: Install the other side panel","text":"Mount the side plate K on base A using the assigned slots.
"},{"location":"setup/hardware/v2.1/assembly/#step-26-secure-the-sides-together","title":"Step 26: Secure the sides together","text":"Secure the laser cut sides with the screws and nuts.
"},{"location":"setup/hardware/v2.1/assembly/#step-27-secure-the-sides-to-the-base-plate","title":"Step 27: Secure the sides to the base plate","text":"Secure the laser cut sides to the base plate A with the screws and nuts.
Warning
To make this easier, you can turn the assembly upside down or on its side. Be careful when doing so as the plates may fall.
"},{"location":"setup/hardware/v2.1/assembly/#step-28-insert-the-camera-ribbon-cable-in-the-camera","title":"Step 28: Insert the camera ribbon cable in the camera","text":"You can now connect the camera flex cable into the connector on the camera board. Once again, gently pull up the tensioners, insert the cable in the right orientation, and push the tensioners back in place to set the cable. Try not to kink or fold the flex cable too much as it is possible to damage it.
"},{"location":"setup/hardware/v2.1/assembly/#step-29-assemble-the-gpio-ribbon-cable","title":"Step 29: Assemble the GPIO ribbon cable","text":"If you didn't get an already assembled ribbon cable, you need to build it yourself.
The orientation of the connector does not really matter. However, you need to make sure that both connectors are oriented in the same direction and are on the same side of the ribbon.
To assemble, slide the ribbon in its connector and close it off. You need to tighten it really hard. It's very warmly recommended to use a vice to do so.
Warning
Once assembled, the ribbon should NOT look like this:
It should rather look like this:
"},{"location":"setup/hardware/v2.1/assembly/#step-30-insert-the-ribbon-cable","title":"Step 30: Insert the ribbon cable","text":"Attach the GPIO ribbon to connect the cooling fan HAT to the GPS HAT.
Tip
You can try to route the flat ribbon from the camera under the ribbon cable you are connecting now.
"},{"location":"setup/hardware/v2.1/assembly/#step-31-fluidic-assembly","title":"Step 31: Fluidic assembly","text":"Feed in the tubing from syringe 1 to form the fluidic path as shown.
Feed in the tubing from syringe 2 to form the fluidic path as shown
Feed in a length of tubing as shown through motor mount H and illumination mount FE
"},{"location":"setup/hardware/v2.1/assembly/#step-32-close-your-planktoscope","title":"Step 32: Close your PlanktoScope","text":"Warning
Take a moment to check your wiring one last time. Also check the routing, make sure the LED wires and the pump stepper wires are in their dedicated channel.
Place the top L into the slots on the PlanktoScope body. Secure it in place with screws and nuts.
"},{"location":"setup/hardware/v2.1/assembly/#step-33-enjoy","title":"Step 33: Enjoy!","text":"Congratulations on a job well done. You can have some rest, get a tea and some biscuits!
Warning
If this was your first time assembling a PlanktoScope, you will probably need to do some troubleshooting of problems with the hardware assembly before your PlanktoScope will fully work. Refer to our troubleshooting documentation for assistance.
"},{"location":"setup/hardware/v2.1/assembly/#next-steps","title":"Next steps","text":"Once your PlanktoScope fully works, you can proceed to our operation guide\u00a0to learn how to operate your PlanktoScope.
"},{"location":"setup/hardware/v2.1/kit/","title":"Kit Production","text":""},{"location":"setup/hardware/v2.1/kit/#required-tools","title":"Required Tools","text":"Building the PlanktoScope involves components that can be sourced from various vendors, both online and locally. The assembly process is straightforward and can be completed within a few hours. Our website offers detailed guides for both hardware and software assembly, and the PlanktoScope community is ready to assist you with any questions or issues.
"},{"location":"setup/hardware/v2.1/kit/#soldering-station","title":"Soldering Station","text":"A soldering station with flux, or flux core solder, is necessary for making a few electrical connections. Purchase here.
"},{"location":"setup/hardware/v2.1/kit/#tap-wrench","title":"Tap Wrench","text":"Any tap wrench compatible with the M12x0.5 tap will work. Purchase here.
"},{"location":"setup/hardware/v2.1/kit/#m12-x-05-tap","title":"M12 x 0.5 Tap","text":"An M12x0.5 tap is required to secure the objective and tube lenses. Purchase here.
"},{"location":"setup/hardware/v2.1/kit/#screwdriver-kit","title":"Screwdriver Kit","text":"A screwdriver kit with multiple drivers simplifies many assembly operations. Purchase here.
"},{"location":"setup/hardware/v2.1/kit/#required-components","title":"Required Components","text":"Below is a comprehensive list of components required to build the PlanktoScope V2.1, along with links to purchase them in both the US and France.
"},{"location":"setup/hardware/v2.1/kit/#electronic-components","title":"Electronic Components","text":"Quantity Name Details US Link FR Link 1 Raspberry Pi 4 B (4GB) The single board computer from Raspberry Pi with 4GB of memory Amazon US DigiKey FR 1 Adafruit Stepper Motor HAT Controls 2 steppers: focus and pump stepper motors Amazon US Amazon FR 1 Adafruit Ultimate GPS HAT Stores date & time and logs GPS coordinates Amazon US DigiKey FR 1 Yahboom Cooling Fan HAT Cools and provides visual feedback with LEDs Amazon US Kubii FR 1 Hammer Header Male 2x20 Only one needed Amazon US Mouser FR 1 Stacking Header 2x20 Only one needed Amazon US Mouser FR 2 Pitch IDC Sockets 2x20 Two needed Amazon US Mouser FR 10cm GPIO Ribbon IDC 40P Only 10 cm needed Amazon US Amazon FR 1 Flex Cable for Pi Camera Longer flex cable needed Amazon US Amazon FR 1 DC Power Jack Socket Only one needed Amazon US Amazon FR 1 GPS Active Antenna Includes uPF to SMA adapter Amazon US Amazon FR 1 Micro HDMI Cable Optional, for development purposes Amazon US Amazon FR 1 Power Supply 3A (USB) Needs to provide 3A 5V Amazon US Amazon FR 1 Power Supply 1A (USB) Needs to provide 1A 5V Amazon US Mouser FR 1 USB Type-C to USB-A 2.0 To power the Raspberry Pi Amazon US Amazon FR 1 USB 5v to DC 12v Step Up Make sure this USB 5V / DC 12V step up converter limits the current at 0.8A Amazon US Amazon FR 1 Maschinenreich peristaltic pump 12V XP88-ST01 This pump can be replaced by others depending on its availability Amazon US 2 Linear Stepper Motor Make sure to select two linear stepper Amazon US 1 MicroSD Card + Adapter Minimum size is 32GB Amazon US Amazon FR 1 kit Heat sink kit for Raspberry Pi Only one kit needed Amazon US Mouser FR"},{"location":"setup/hardware/v2.1/kit/#fluidic-components","title":"Fluidic Components","text":"Quantity Name Details US Link FR Link 1 kit \u00b5-Slide I Luer Variety Pack Make sure to select uncoated Ibidi US Ibidi FR 2 HSW 20ml Syringe Two syringes needed Grainger US Darwin Microfluidics FR 1 kit \u00dcberStrainer Set 3 Optional strainer kit to filter the samples Pluriselect US 1m Silicone Tubing ID 1.6mm Ibidi website provides good but expensive tubing Ibidi US Darwin Microfluidics FR 2 Luer Lock Connector Female 1.6 mm Make sure to select the proper diameter Ibidi US Darwin Microfluidics FR 2 Luer Connector Male 1.6 mm Make sure to select the proper diameter Ibidi US Darwin Microfluidics FR"},{"location":"setup/hardware/v2.1/kit/#optic-components","title":"Optic Components","text":"Quantity Name Details US Link FR Link 1 LED white 5mm Intensity: 23,000 mcd, Forward Voltage: 3.5V, Current: 20mA, Beam Angle: 15\u00b0 DigiKey US Gotronic FR 1 kit Arducam M12 Lens Kit Includes 10 M12 Lenses for various angles of view Amazon US 1 M12 Lens 25mm IR 1/2\" 5MP Additional essential 25mm M12 lens Amazon US AliExpress 1 Pi Camera v2.1 Amazon US"},{"location":"setup/hardware/v2.1/kit/#hardware-components","title":"Hardware Components","text":"Quantity Name Details US Link FR Link 1 M2.5 Standoff Assortment Kit 6mm and 15mm standoffs Amazon US 1 M2 M3 M4 Screw Assortment Kit M2x8mm and M3x12mm screws and M3 nuts Amazon US 1 CR1220 Battery For the Adafruit Ultimate GPS HAT Amazon US Amazon FR 16 Magnets 6 x 2 mm Neodynium magnets to connect functional layers Amazon US"},{"location":"setup/hardware/v2.1/kit/#machine-your-structure","title":"Machine Your Structure","text":"To complete your PlanktoScope kit, you'll need to fabricate the structure. This can be done using laser cutting or CNC machining from a sheet of material. You can machine the structure locally at a FabLab or through a company specializing in laser cutting or CNC machining. The cost will vary depending on the material chosen and whether you machine it yourself or use a company.
"},{"location":"setup/hardware/v2.1/kit/#suggested-materials","title":"Suggested Materials","text":"Material Easy to Machine Robustness Water Resistance Price Recyclable Ideal For Transparent Acrylic \u2605\u2605\u2605\u2605\u2605 \u2605\u2606\u2606\u2606\u2606 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2606\u2606\u2606 \u2606\u2606\u2606\u2606\u2606 Seeing internal electronics Black Acrylic \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2606\u2606\u2606 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2606\u2606 \u2606\u2606\u2606\u2606\u2606 Removing surrounding light Marine Plywood \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2605\u2606 \u2605\u2606\u2606\u2606\u2606 Deploying at sea Basic Plywood \u2605\u2605\u2605\u2606\u2606 \u2605\u2605\u2606\u2606\u2606 \u2605\u2605\u2606\u2606\u2606 \u2605\u2606\u2606\u2606\u2606 \u2605\u2605\u2606\u2606\u2606 Cheap prototyping HDF Forescolor \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2606\u2606 \u2605\u2605\u2605\u2606\u2606 \u2605\u2605\u2605\u2605\u2605 Feeling good about recycling PP Waste, 100% Recycled \u2606\u2606\u2606\u2606\u2606 \u2606\u2606\u2606\u2606\u2606 \u2606\u2606\u2606\u2606\u2606 \u2605\u2605\u2605\u2605\u2606 \u2605\u2605\u2605\u2605\u2605 Feeling good about recycling Aluminum \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2605 \u2605\u2605\u2605\u2605\u2605 Robust professional setup"},{"location":"setup/hardware/v2.1/kit/#get-the-plan-and-machine-it","title":"Get the Plan and Machine It","text":"You can download the necessary fabrication patterns for the structure here; two versions are available, one for material with 5 mm thickness, and the other for material with 1/4 inch thickness:
Since DXF files don't include unit information, when you open or import one of these DXF files you may need to rescale all dimensions to achieve the correct sizes. You can check whether dimensions are correct by checking the length and width of part M against the actual dimensions shown below:
You can also compare the approximate dimensions of parts in the SVG file (for 5 mm thickness material) with the sizes of parts in your imported DXF file to check whether the rescaling result looks approximately correct.
"},{"location":"setup/hardware/v2.5/","title":"Hardware v2.5","text":"This page will help you to build the v2.5 hardware for a PlanktoScope.
"},{"location":"setup/hardware/v2.5/#make-an-assembly-kit","title":"Make an assembly kit","text":"If you do not already have an assembly kit, you will need to make a kit for yourself.
"},{"location":"setup/hardware/v2.5/#assemble-a-planktoscope-from-a-kit","title":"Assemble a PlanktoScope from a kit","text":"Once you have an assembly kit, you will need to assemble it into a PlanktoScope.
"},{"location":"setup/hardware/v2.5/#next-steps","title":"Next steps","text":"If you assembled your PlanktoScope from a kit provided by FairScope, you can proceed to our operation guide\u00a0to 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.
"},{"location":"setup/hardware/v2.5/assembly/","title":"Assembly","text":""},{"location":"setup/hardware/v2.5/assembly/#content-of-the-kit","title":"Content of the Kit","text":"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.
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 SandpaperIf any bags are missing, please go back to the BOM (Bill of Materials) and reorder the required components.
"},{"location":"setup/hardware/v2.5/assembly/#about-this-document","title":"About this document","text":"To read this document, follow these guidelines:
"},{"location":"setup/hardware/v2.5/assembly/#color-codes","title":"Color codes","text":"As you read through the document, be sure to pay attention to these visual cues to guide you through the build process.
"},{"location":"setup/hardware/v2.5/assembly/#requirements","title":"Requirements","text":""},{"location":"setup/hardware/v2.5/assembly/#tools","title":"Tools","text":"Content of\u00a0Bag B:
Content of\u00a0Bag A:
\ud83d\udc41 Locate the panel S1 and discover the 5 differents Parts F, P, K, J and I.
\ud83c\udfac Flip your panel S1.
\ud83d\udd34 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.
Gather all the necessary tools. You will need the B2 \ud83d\udfe0 Razor blade to cut the tabs.
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.
Once you have removed your Part from the main panel by cutting off all the tabs holding it, inspect it for potential residual tabs.
\ud83d\udfe3 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.
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.
\ud83d\udd34 Locate the inner tabs on the edges of the different Parts.
Cut out the tabs inside of all the Parts F, P, K, J and I detached from the panel S1.
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.
Repeat the process on the panel S2.
Warning
Be extremely careful because this is very sharp.
Discover the 11 differents Parts.
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.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-2-place-the-4-adhesive-pads-under-the-part-i","title":"Chapter 2: Place the 4 Adhesive Pads under the Part I","text":"To secure the PlanktoScope on slippery grounds using the adhesive pads, follow these steps. Gather all the necessary materials. You will need:
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-3-screw-the-four-standoffs-into-part-a","title":"Chapter 3: Screw the four Standoffs into Part A","text":"Now it's time to assemble the ground plate for the Raspberry Pi as the PlanktoScope main processing unit.
\ud83d\udfe2 A1. Standoff M2.5 - 6mm- Brass
\ud83d\udfe2 B4. Wrenches for standoffs
Keep going for each of the four holes.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-4-mount-the-heat-sinks-on-the-raspberry-pi","title":"Chapter 4: Mount the Heat Sinks on the Raspberry Pi","text":"Locate the Raspberry Pi 4 Model B packaging.
Warning
Be careful removing it from its packaging.
Place the four Heat Sinks next to your Raspberry Pi and mark the locations of the Heat Sinks on the Raspberry Pi.
Remove the protective labels under a Heat Sink and place the Heat Sink on the slot of the Raspberry Pi.
Remove the protective labels under all the Heat Sinks and place all the Heat Sinks on the slots of the Raspberry Pi.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-5-insert-the-micro-sd-card-in-the-raspberry-pi","title":"Chapter 5: Insert the micro SD card in the Raspberry Pi","text":"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.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-6-mount-the-raspberry-pi-on-the-part-a","title":"Chapter 6: Mount the Raspberry Pi on the Part A","text":"\ud83d\udfe3 A3. Standoff M2.5 - 16mm - SS
Screw by hand a Standoff M2.5 - 16mm on the Raspberry Pi.
\ud83d\udfe2 B4. Wrenches for standoffs
Locate the Raspberry Pi Camera HQ packaging.
Warning
Be careful removing it from its packaging.
Lay your Raspberry Pi Camera face down on a suitable surface.
\ud83d\udd34 The black connector is simply a push/pull fit. To disengage the cable, pull the two corners of the black connector down, away from the camera board. It will unclip to about 3mm, make sure you don't pull it off! If you're struggling, try pulling off one corner of the connector at a time.
Warning
Be careful with this, this part is delicate. Lift the black connector gently
Once the connector has been disengaged from the Raspberry Pi camera board, the cable will simply slide out!
\ud83d\udd34 Locate the black connector present on the Raspberry Pi.
\ud83d\udd34 The black connector is simply a push/pull fit. To disengage the cable, pull the two corners of the black connector down, away from the camera board. It will unclip to about 3mm, make sure you don't pull it off! If you're struggling, try pulling off one corner of the connector at a time.
Warning
Be careful, this part is delicate. Gently prise the black connector with nail or fingertip and thumb.
Insert the Ribbon Cable you just detached from the Raspberry Pi Camera in the Raspberry Pi.
\ud83d\udd34 Secure the Ribbon Cable in the Raspberry Pi by pressing firmly on the black connector.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-8-mount-the-planktoscope-hat-on-the-raspberry-pi","title":"Chapter 8: Mount the PlanktoScope HAT on the Raspberry Pi","text":"Locate the PlanktoScope HAT present in bag I.
\ud83d\udd34 Thread the Ribbon cable through the PlanktoScope HAT slot from the underside.
Warning
Make sure the two \ud83d\udfe3 black connectors are aligned before threading through the ribbon.
\ud83d\udd34 Plug the PlanktoScope HAT into the Raspberry Pi.
Warning
Make sure the two black connectors are aligned before attaching them together.
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.
\ud83d\udfe0 A4. Screw M2.5X5mm CHC - SS
\ud83d\udfe3 Locate the 4 holes on the top of the PlanktoScope HAT and insert the four M2.5X5mm
\ud83d\udfe1 B3. Allen key 2mm
Screw the four A4 screws through the PlanktoScope HAT onto the Standoff M2.5 - 16mm.
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-9-place-the-power-socket-on-part-m","title":"Chapter 9: Place the Power Socket on Part M","text":"\ud83d\udd34 Insert the cable inside of the hole by being sure of the orientation of the Part M.
\ud83d\udfe3 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\u2019t spin on itself.
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-10-mount-the-raspberry-pi-camera-hq-on-part-b","title":"Chapter 10: Mount the Raspberry Pi Camera HQ on Part B","text":"\ud83d\udfe3 Locate the 4 holes on the top of the Part B.
\ud83d\udd35 A2. Standoff M2.5 - 15mm - Brass
Insert the four Standoff M2.5 - 15mm.
The result should be similar to the picture.
\ud83d\udfe2 B4. Wrenches for standoffs
Using the small side of the Standoff Wrench, secure the 4 M2.5 - 15mm Standoffs
Locate the Raspberry Pi Camera HQ
Remove the lens cap Raspberry Pi Camera HQ.
Warning
Make sure your camera lens is clean. If it is not, gently wipe using cotton swab for this task.
Place the Raspberry Pi Camera HQ on top of the four Standoffs installed on Part B.
\ud83d\udfe3Ensure correct orientation of the Raspberry Pi Camera HQ. The black connector where the Ribbon Cable was removed is on the same side as the \ud83d\udfe2slot circled in green
\ud83d\udfe0 A4. Screw M2.5X5mm CHC - SS
\ud83d\udfe1 B3. Allen key 2mm
Use the allen key and tighten the Raspberry Pi Camera to the Standoffs.
The result should be similar to the picture.
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-11-mount-the-linear-stepper-motor-on-part-e","title":"Chapter 11: Mount the Linear Stepper Motor on Part E","text":"Locate the Stepper Motors
Warning
Avoid touching the metal rods on the Stepper Motors
Info
You can touch the \ud83d\udfe3 gold stands
\ud83d\udfe1 A5. Screw M2.5X10mm CHC - SS
\ud83d\udfe1 B3. Allen key 2mm
Attach the stepper motors to the screws we have just placed with the \ud83d\udd34 pockets positioned on opposite to the cabling.
The result should be similar to the picture.
Use the 2mm allen key to fix the Stepper Motors.
The result should be similar to that picture.
The result should be similar to the picture.
Repeat the process on the other side with the other Stepper Motor.
Repeat the process on the other side with the other Stepper Motor.
The result should be similar to the picture.
Note
\ud83c\udfac Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-12-mount-the-led-on-part-g","title":"Chapter 12: Mount the\u00a0LED\u00a0on\u00a0Part G","text":"Insert the\u00a0LED into the LED cable.
The result should be similar to the\u00a0picture.
Locate part\u00a0G.
\ud83d\udfe3\u00a0Locate the LED hole on\u00a0Part G.
We\u00a0will\u00a0now\u00a0place\u00a0the\u00a0LED\u00a0into\u00a0the\u00a0slot\u00a0on part\u00a0G.
Warning
Gently push the LED into the LED\u00a0hole located on Part\u00a0G. It should be a snug fit.
The result should be similar to the\u00a0picture.
Info
\ud83c\udfac\u00a0Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-13-mount-the-peristaltic-pump-on-part-o-and-part-l","title":"Chapter 13: Mount the\u00a0Peristaltic Pump\u00a0on\u00a0Part O and\u00a0Part L","text":"\ud83d\udfe2\u00a0Insert the cable of the\u00a0Peristaltic Pump\u00a0into the hole on\u00a0Part O\u00a0and\u00a0then insert the motor block assembly\u00a0of the pump into it.
Warning
\ud83d\udc41 Ensure the correct orientation of\u00a0Part O\u00a0and the\u00a0Peristaltic Pump
\ud83d\udfe1\u00a0A5. Screw\u00a0M2.5X10mm\u00a0CHC - SS
\ud83d\udfe1\u00a0B3. Allen key 2mm B3
\ud83d\udfe2\u00a0Insert the two\u00a0M2.5X10mm\u00a0in the\u00a0two holes.
Screw the two\u00a0M2.5X10mm\u00a0into the\u00a0two holes.
\ud83d\udd34\u00a0Lay\u00a0the\u00a0Part\u00a0L\u00a0down and make\u00a0sure the pockets in these holes are\u00a0facing upwards.
Insert the\u00a0Peristaltic Pump\u00a0into the\u00a0allocated slot in\u00a0Part L.
Insert the\u00a0Peristaltic Pump\u00a0into the\u00a0allocated slot in\u00a0Part L.
\ud83d\udfe1\u00a0A5.Screw\u00a0M2.5X10mm\u00a0CHC - SS
\ud83d\udfe1\u00a0B3.Allen key 2mm
Screw the four M2.5X10mm in the\u00a0located\u00a0holes\u00a0attaching\u00a0the\u00a0Part\u00a0O\u00a0to\u00a0the\u00a0Part L Peristaltic Pump.
The result should be similar to the\u00a0picture.
Info
We will use this part in the next step.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-14-spiral-wrap-the-led-and-peristaltic-pump-cabling","title":"Chapter 14: Spiral wrap the LED and Peristaltic Pump cabling","text":"Continue wrapping around the\u00a0cables until you have used all of the\u00a0spiral wrap, leaving small or no gaps.
Info
The result should look the same as\u00a0the picture.
Info
The result should look the same as\u00a0the picture.
Note
\ud83c\udfac\u00a0Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-15-attaching-the-stepper-motors-to-the-raspberry-pi-camera","title":"Chapter 15: Attaching the\u00a0Stepper Motors\u00a0to the\u00a0Raspberry Pi Camera","text":"Locate the Stepper Motors with\u00a0mount, and the Raspberry Pi\u00a0Camera.
Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.
Warning
Make sure the orientation is\u00a0correct and matches the picture.
Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.
Warning
Make sure the orientation is\u00a0correct and matches the picture.
Then\u00a0insert\u00a0the\u00a0cylindrical\u00a0parts\u00a0of\u00a0the\u00a0Stepper Motor into the slots.
Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.
Warning
Make sure the orientation is\u00a0correct and matches the picture.
Then\u00a0insert\u00a0the\u00a0cylindrical\u00a0parts\u00a0of\u00a0the\u00a0Stepper Motor into the slots.
Note
The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-16-connecting-the-raspberry-pi-camera-to-the-raspberry-pi-hat","title":"Chapter 16: Connecting the\u00a0Raspberry Pi Camera\u00a0to the\u00a0Raspberry Pi HAT","text":"Gently feed the\u00a0Ribbon Cable\u00a0into the\u00a0port of the\u00a0Camera.
Warning
\ud83d\udc41 Ensure the correct orientation of\u00a0the\u00a0Ribbon Cable\u00a0with the blue end\u00a0facing upwards.
\ud83d\udd34\u00a0Press down on the black\u00a0connector on the Raspberry Pi\u00a0camera board once the Ribbon\u00a0Cable is in position.
\ud83d\udd34\u00a0B1.Small flat screwdriver 2mm
Warning
Hold tight, a specific order is\u00a0required.
Starting with the\u00a0red cable, insert the\u00a0cable in the far left port and tighten\u00a0the screw situated above the port.
Note
The result should look the same as\u00a0the picture.
Repeat this process with the order\u00a0pictured here from left to right:\u00a0\ud83d\udd34 Red\u00a0\ud83d\udfe1 Yellow\u00a0\ud83d\udd35 Blue\u00a0\u26ab Black.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-17-connect-the-led-and-peristaltic-pump-to-the-raspberry-pi","title":"Chapter 17: Connect the\u00a0LED\u00a0and\u00a0Peristaltic Pump\u00a0to the\u00a0Raspberry Pi","text":"We will now be connecting the LED\u00a0and Peristaltic Pump with the\u00a0Raspberry Pi HAT\u00a0and\u00a0Camera.
Place the LED housing onto the\u00a0Stepper Mounts.
Warning
\ud83d\udc41 Ensure correct orientation of both\u00a0\ud83d\udfe3 parts by looking at the\u00a0precut holes.
Info
The result should be similar to the\u00a0picture.
Now we will plug in the\u00a0LED and\u00a0Stepper Mount\u00a0cables to the\u00a0Raspberry Pi.
Feed the area of cabling that is not\u00a0covered by the\u00a0spiral wrap\u00a0through\u00a0the two holes to start. Then thread\u00a0through to the\u00a0spiral wrap\u00a0so that it\u00a0matches the picture.
We will now plug the cables into the\u00a0correct ports.
\ud83d\udfe3\u00a0The four wires (\ud83d\udd34 Red\u00a0\ud83d\udd35 Blue \ud83d\udfe2 Green \u26ab Black) enter the side port on the\u00a0Raspberry Pi HAT.
\ud83d\udd34 The two wires (LED) enter on the\u00a0port on top of the Raspberry Pi HAT.
The result should be similar to the\u00a0picture.
Note
We will use this assembly in the next\u00a0step.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-18-connect-the-dc-power-jack-to-the-raspberry-pi","title":"Chapter 18: Connect the\u00a0DC Power Jack\u00a0to the\u00a0Raspberry Pi","text":"\ud83d\udd34\u00a0B1.Small flat screwdriver 2mm
Info
The result should be similar to the\u00a0picture.
Note
We will use this assembly in the next\u00a0step.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-19-your-planktoscope-starts-to-take-shape","title":"Chapter 19: Your PlanktoScope starts to take shape","text":"Locate Part I\u00a0and\u00a0Part H.
\ud83d\udd34 Slot the\u00a0Peristaltic Pump\u00a0above\u00a0the\u00a0LED.
Note
The result should be the same as the\u00a0picture.
Warning
\ud83d\udc41 Ensure the correct orientation of\u00a0the housing and the\u00a0Peristaltic Pump.
At the other end, slot the\u00a0DC Power\u00a0Jack\u00a0housing adjacent to the\u00a0Raspberry Pi.
Rotate so that the DC Power Jack is\u00a0facing upwards. We will now slot the Raspberry Pi onto\u00a0the rest of the housing.
Info
The result should be similar to that\u00a0picture.
Note
\ud83c\udfac\u00a0Store this assembly for later.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-20-inserting-screws","title":"Chapter 20: Inserting screws","text":"\ud83d\udfe3 We\u00a0will\u00a0now\u00a0insert\u00a0eight\u00a0M3\u00a0screws\u00a0to fasten the housing together.
Note
\ud83c\udfac\u00a0Store this assembly for later.
\ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS
\ud83d\udfe1\u00a0B3. Allen key 2mm
Info
The result should be similar to the\u00a0picture.
We will now turn over the\u00a0PlanktoScope\u00a0and\u00a0repeat\u00a0the\u00a0process\u00a0for the underside.
\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0underside.
Info
The result should be similar to the\u00a0picture.
Now turn the PlanktoScope on its side.
Warning
\ud83d\udc41 Ensure the orientation of your\u00a0PlanktoScope and\u00a0Part K\u00a0matches\u00a0the picture.
Slot\u00a0Part K\u00a0onto the rest of the\u00a0PlanktoScope.
Warning
\ud83d\udfe2\u00a0Ensure the correct orientation. The\u00a0result should look the same at the\u00a0picture.
Content of\u00a0Bag A: \ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS
Content of\u00a0Bag B: \ud83d\udfe1\u00a0B3. Allen key 2mm
\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0side to hold\u00a0Part K\u00a0in place.
We will now place\u00a0Part J\u00a0into position\u00a0as the housing for the side.
Warning
\ud83d\udc41 Ensure your PlanktoScope matches\u00a0the orientation in the picture.
\ud83d\udfe2 Place\u00a0Part K\u00a0onto the rest of the\u00a0PlanktoScope and note the position\u00a0of the cutout.
Content of\u00a0Bag A: \ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS
Content of\u00a0Bag B: \ud83d\udfe1\u00a0B3. Allen key 2mm
\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0underside
Info
The result should be similar to the\u00a0picture.
Content of\u00a0Bag A: \ud83d\udfe1\u00a0A5. Screw M2.5X10mm CHC - SS
Place\u00a0the\u00a0M2.5\u00a0screw\u00a0through\u00a0Part\u00a0N. It\u00a0will\u00a0act\u00a0as\u00a0a\u00a0cover\u00a0for\u00a0the\u00a0electrical\u00a0inputs.
Using the allen key, tighten the screw\u00a0so that it is possible to move the\u00a0cover with light force.
Info
The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.
"},{"location":"setup/hardware/v2.5/assembly/#chapter-21-insert-the-tubing-in-the-peristaltic-pump","title":"Chapter 21: Insert the tubing in the\u00a0Peristaltic Pump","text":"You can now remove the Peristaltic\u00a0Pump housing and\u00a0\ud83d\udfe2 Rotor.
You can now remove the Peristaltic\u00a0Pump housing and\u00a0\ud83d\udfe2 Rotor.
\ud83d\udd34 Locate the\u00a0Tube\u00a0for the Peristaltic\u00a0Pump in\u00a0Bag F\u00a0and remove it from the\u00a0bag.
Warning
The tips of the Tubing that are\u00a0covered by black rubber are very\u00a0delicate and easily broken.
Insert the first plastic arch of the\u00a0Tube\u00a0into the slot on the Peristaltic Pump\u00a0\\ housing.
Info
The result should be similar to the\u00a0picture.
Insert the\u00a0Rotor\u00a0into the housing\u00a0ensuring the correct orientation. The\u00a0hole in the centre should be visible on\u00a0the underside.
Info
The result should be similar to the\u00a0picture.
Insert the\u00a0Rotor\u00a0into the housing.\u00a0Then, thread the\u00a0Tube\u00a0around the\u00a0Rotor\u00a0and insert the other plastic\u00a0arch into the second slot.
Info
The result should be similar to the\u00a0picture.
Info
The result should be similar to the\u00a0picture.
Place the Peristaltic Pump housing\u00a0back onto the PlanktoScope.
Achieve the angle shown in the\u00a0picture between the Peristaltic Pump\u00a0housing and PlanktoScope main\u00a0body. Then, press and twist in a\u00a0clockwise direction.
Info
The result should be similar to the\u00a0picture.
Push the small piece of tubing from\u00a0Bag D\u00a0over the left-side connector of\u00a0the\u00a0Peristaltic Pump.
Place the long piece of tubing from\u00a0Bag D\u00a0over the right-side connector\u00a0of the\u00a0Peristaltic Pump.
Insert the connector from\u00a0Bag D\u00a0into\u00a0the other end of the\u00a0small piece of\u00a0tubing.
Orientate\u00a0Part P\u00a0so that the magnets\u00a0are face-down on the left-hand side.
Place Part P over the magnets\u00a0adjacent to the\u00a0Peristaltic Pump.
Info
The result should be similar to the\u00a0picture.
\ud83d\udd34 From\u00a0Bag M, Place the\u00a0light blue Test Tube in the hole adjacent to the\u00a0Peristaltic Pump.
Place the\u00a0\ud83d\udd35 dark blue Test Tube\u00a0into\u00a0the hole situated outside of the\u00a0PlanktoScope.
\ud83d\udfe2\u00a0Insert the other end of the long\u00a0piece of tubing into the\u00a0\ud83d\udd35 dark blue Test Tube. This will serve as the waste container.\u00a0The result should look the same as\u00a0the picture.
Info
The magnets are raised on the\u00a0side where the lens lays flat.
Warning
Try not to touch the lens
Screw the\u00a0Lock Ring\u00a0onto the lens,\u00a0flat-side down.
Info
The\u00a0magnets\u00a0are\u00a0indented\u00a0on\u00a0the\u00a0side that the lens lays flat.
Warning
Try not to touch the lens
Screw the\u00a0Lock Ring\u00a0onto the lens,\u00a0flat-side down.
The result should be similar to that\u00a0picture.
Place\u00a0both\u00a0Lenses (C\u00a0and\u00a0D)\u00a0together\u00a0so that they flat together and both\u00a0lenses are facing each other.
Info
The result should be similar to the\u00a0picture.
Place\u00a0the\u00a0Lenses\u00a0(both\u00a0C\u00a0and\u00a0D)\u00a0into\u00a0position, adjacent to the camera.
The orientation of your PlanktoScope\u00a0and Lenses should match the\u00a0pictures.
Info
The result should be similar to the\u00a0picture.
Info
The Fluidic Path will have a\u00a0cardboard protector.
Please take extra precaution while handling\u00a0this\u00a0part\u00a0and\u00a0avoid\u00a0touching\u00a0the glass element of the piece.
Warning
The Fluidic Path is very delicate.
Place the Tube Clamp over the long\u00a0piece\u00a0of\u00a0tube\u00a0at\u00a0the\u00a0end\u00a0of\u00a0the\u00a0Fluidic\u00a0Path.
Place the white clamp over the long\u00a0piece\u00a0of\u00a0tube\u00a0at\u00a0the\u00a0end\u00a0of\u00a0the\u00a0Fluidic Path.
Info
The result should look the same as\u00a0the picture.
Press down on the Tube Clamp so\u00a0that it clicks into place with just one\u00a0click.
Info
The result should look the same as\u00a0the picture.
Insert\u00a0a\u00a0small\u00a0plastic\u00a0Connector\u00a0into\u00a0the\u00a0end\u00a0of\u00a0the\u00a0tubing,\u00a0below\u00a0the\u00a0Tube\u00a0Clamp.
Make sure the tubing is over the\u00a0Connector.
Info
The result should look the same as\u00a0the picture.
Remove the cardboard protector\u00a0from the\u00a0Fluidic Path.
Warning
A reminder, the glass part of the\u00a0Fluidic\u00a0Path\u00a0is\u00a0very\u00a0delicate.\u00a0Please\u00a0try\u00a0not to touch it.
Place another Connector at the end\u00a0of the tubing.
The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.
\u26a0 Gently place the Fluidic Path in\u00a0the designated indentation on\u00a0Part F.
Warning
Do not touch the glass.\u00a0
If you have tape available, place a\u00a0small\u00a0piece\u00a0at\u00a0the\u00a0the\u00a0bottom\u00a0of\u00a0Part F so that the tubing remains fixed in\u00a0its position.
Avoid placing tape over the glass.
Info
The result should be similar to the\u00a0picture.
To\u00a0insert\u00a0the\u00a0syringe,\u00a0place\u00a0finger\u00a0and\u00a0thumb either side of part F where\u00a0green circle is located. This ensures\u00a0the tubing does not rotate while you\u00a0twist the syringe into position in a\u00a0clockwise direction.
Info
The result should be similar to the\u00a0picture.
The result should look the same as\u00a0the pictures.
Next, you will need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi.
"},{"location":"setup/hardware/v2.5/kit/","title":"Kit Production","text":""},{"location":"setup/hardware/v2.5/kit/#mechanical-structure","title":"Mechanical Structure","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#manufacturing-files","title":"Manufacturing files","text":"Files Description PlanktoScope-Case.dxf PlanktoScope Case export for CNC Milling"},{"location":"setup/hardware/v2.5/kit/#tools","title":"Tools","text":"Tool Specification CNC Milling machine minimum traverse path at a minimum size of 600 mm to 1000 mm End Mill \u00d8 6mm End Mill \u00d8 3mm End Mill \u00d8 2mm End Mill \u00d8 1mm"},{"location":"setup/hardware/v2.5/kit/#material","title":"Material","text":""},{"location":"setup/hardware/v2.5/kit/#wood","title":"Wood","text":"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.
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.
"},{"location":"setup/hardware/v2.5/kit/#finishing","title":"Finishing","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#cnc-workflow","title":"CNC workflow","text":"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:
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
1mm end mill for small holes
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
3500mm/min for 6mm end mills
Load the end mill: Once the appropriate end mill has been selected, it can be loaded onto the spindle of the CNC milling machine.
Set the workpiece: The workpiece should be securely clamped onto the table of the CNC milling machine.
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.
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
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.
"},{"location":"setup/hardware/v2.5/kit/#finnish-of-the-case-parts","title":"Finnish of the case parts","text":""},{"location":"setup/hardware/v2.5/kit/#requirements-for-case-parts","title":"Requirements for case parts","text":""},{"location":"setup/hardware/v2.5/kit/#case-tools","title":"Case tools","text":"Welcome to the PCB production manual for the PlanktoScope Hat!
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.
"},{"location":"setup/hardware/v2.5/kit/#manufacturing-files_1","title":"Manufacturing files","text":"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"},{"location":"setup/hardware/v2.5/kit/#pcb-manufacturing-process","title":"PCB manufacturing process","text":""},{"location":"setup/hardware/v2.5/kit/#placing-an-order","title":"Placing an order","text":"To order a PCB board including assembly, follow these steps:
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.
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.
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.
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.
"},{"location":"setup/hardware/v2.5/kit/#board-dimensions","title":"Board dimensions","text":"65 mm x 100 mm
"},{"location":"setup/hardware/v2.5/kit/#circuit-specifications","title":"Circuit specifications","text":"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 (\u00b5) 35 \u00b5m Internal copper thickness (\u00b5) without IPC Class Class 2"},{"location":"setup/hardware/v2.5/kit/#solder-mask","title":"Solder mask","text":"Property Value Solder mask TOP + BOT Mask colour green Peelable mask without"},{"location":"setup/hardware/v2.5/kit/#marking","title":"Marking","text":"Property Value Silkscreen (ink) TOP + BOT Ink colour white ROHS marking without UL marking without Date marking without"},{"location":"setup/hardware/v2.5/kit/#specific-options","title":"Specific options","text":"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"},{"location":"setup/hardware/v2.5/kit/#quality-assurance","title":"Quality assurance","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#top","title":"Top","text":""},{"location":"setup/hardware/v2.5/kit/#bottom","title":"Bottom","text":""},{"location":"setup/hardware/v2.5/kit/#copper-layer-1","title":"Copper layer 1","text":""},{"location":"setup/hardware/v2.5/kit/#copper-layer-2","title":"Copper layer 2","text":""},{"location":"setup/hardware/v2.5/kit/#mechanical","title":"Mechanical","text":""},{"location":"setup/hardware/v2.5/kit/#component-placement","title":"Component placement","text":""},{"location":"setup/hardware/v2.5/kit/#assembly-of-the-thru-hole-components","title":"Assembly of the Thru-Hole components","text":""},{"location":"setup/hardware/v2.5/kit/#thru-hole-requirements","title":"Thru-Hole Requirements","text":""},{"location":"setup/hardware/v2.5/kit/#thru-hole-tools","title":"Thru-Hole tools","text":"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
"},{"location":"setup/hardware/v2.5/kit/#soldering-of-the-stepper-motor-driver","title":"Soldering of the stepper motor driver","text":"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 \ud83e\udd62. 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.
"},{"location":"setup/hardware/v2.5/kit/#soldering-of-the-motor-driver-sockets","title":"Soldering of the motor driver sockets","text":"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 \ud83e\udd62. 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.
"},{"location":"setup/hardware/v2.5/kit/#soldering-the-connection-sockets","title":"Soldering the connection sockets","text":"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 \ud83e\udd62. 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.
"},{"location":"setup/hardware/v2.5/kit/#soldering-the-raspberry-pi-connector","title":"Soldering the Raspberry Pi connector","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#install-and-solder-the-cooling-fan","title":"Install and solder the cooling fan","text":"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 \u26ab GND, \ud83d\udd34 VCC, \ud83d\udfe1 RPM, \ud83d\udd35 PWM.
Note
If your fan doesn't have a \ud83d\udd35 PWM connector, then that's not a problem, you can just leave it out.
"},{"location":"setup/hardware/v2.5/kit/#solder-the-display-connector","title":"Solder the display connector","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#solder-the-configuration-option-jumpers","title":"Solder the configuration option jumpers","text":"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.
"},{"location":"setup/hardware/v2.5/kit/#you-have-finished-soldering-the-components","title":"You have finished soldering the components","text":"The assembly of the thru-hole components for the planktoscope hat is now complete. The end result should look like this.
"},{"location":"setup/hardware/v2.5/kit/#planktoscope-hard-case","title":"PlanktoScope Hard case","text":""},{"location":"setup/hardware/v2.5/kit/#hard-case-requirements","title":"Hard case Requirements","text":""},{"location":"setup/hardware/v2.5/kit/#hard-case-tools","title":"Hard case tools","text":"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.
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.
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.
"},{"location":"setup/hardware/v2.5/kit/#kit-composition","title":"Kit composition","text":"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!
"},{"location":"setup/hardware/v2.6/","title":"Index","text":"This is a marktext document avec
"},{"location":"setup/software/","title":"PlanktoScope Software","text":"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.
"},{"location":"setup/software/#choosing-an-sd-card-image","title":"Choosing an SD card image","text":"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).
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.
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.
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.
"},{"location":"setup/software/#post-installation-configuration","title":"Post-installation configuration","text":"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.
"},{"location":"setup/software/#next-steps","title":"Next steps","text":"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.
"},{"location":"setup/software/config/","title":"Post-Installation Configuration","text":"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.
"},{"location":"setup/software/config/#hardware-version","title":"Hardware Version","text":"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.
"},{"location":"setup/software/config/#next-steps","title":"Next steps","text":"Now that you have configured the PlanktoScope software, you can proceed to our guide on how to operate your PlanktoScope.
"},{"location":"setup/software/nonstandard-install/","title":"Non-Standard Installation","text":"This page provides instructions for setting up non-standard versions of the PlanktoScope OS on a PlanktoScope. The PlanktoScope project also uses this same process for creating the official PlanktoScope software SD card images used in the standard software installation process.
"},{"location":"setup/software/nonstandard-install/#prerequisites","title":"Prerequisites","text":"This guide assumes that:
If you have not used the PlanktoScope software before, you should first start with the standard software setup process in order to troubleshoot any problems with your PlanktoScope hardware; you can then try the non-standard setup process afterwards.
In order to complete the non-standard setup process, you will need all of the following:
The setup scripts for the PlanktoScope OS assume that you will be setting up the PlanktoScope software on a 64-bit version of the Raspberry Pi OS with Debian version 11 (bullseye), preferably the version released on 2023-03-12. You can choose any of the following three variants of that version of the Raspberry Pi OS, depending on your needs:
The standard PlanktoScope software SD card images are built on the Raspberry Pi OS Lite image, which only provides a command-line interface, without a graphical desktop environment or web browser; because the PlanktoScope's graphical user interface must be accessed from a web browser, you might prefer to use the \"Raspberry Pi OS with desktop\" image in order to have a graphical desktop environment with a web browser. This would allow you to operate the PlanktoScope by plugging in a display, keyboard, and mouse to your Raspberry Pi; otherwise, you will have to connect to the PlanktoScope from another device over Ethernet or Wi-Fi in order access the PlanktoScope's graphical user interface.
Warning
The latest version of Raspberry Pi OS, with Debian version 12 (bookworm), can be downloaded from the Raspberry Pi Operating system images page, but the PlanktoScope software setup scripts do not yet work on Debian version 12; that page also has links named \"Archive\" under the download buttons where you can find older versions with Debian version 11 (bullseye) under the \"Raspberry Pi OS (Legacy)\" section; those links are the same as the links we listed above.
"},{"location":"setup/software/nonstandard-install/#write-the-os-image-to-an-sd-card","title":"Write the OS image to an SD card","text":"Next, you will need to write your downloaded Raspberry Pi OS image file to your microSD card. 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.
To use a graphical application to write the image file to your microSD card, you can install the Raspberry Pi imager. Download the latest version of the Raspberry Pi Imager, install it, and start it. Select the Raspberry Pi OS image file (likely a .img, .img.gz, or .img.xz file) you just downloaded, and select the SD card you want to write the Raspberry Pi OS image to. Review your selections and click the appropriate button to begin writing the Raspberry Pi OS image to the SD card. The process should take several minutes.
If you'd instead prefer to write the image file to your microSD card from a command-line tool, you could instead use a tool like ddrescue on a Debian-based system, e.g. as follows:
gunzip planktoscope-v2.3-final.img.gz\nsudo ddrescue planktoscope-v2.3-final.img /dev/mmcblk0 --force\nWarning: be extremely careful when choosing the storage medium and ensure that you are writing the OS image file to the device which actually corresponds to the correct microSD card. Once the image has been written, data previously on the device will be lost and impossible to recover.
"},{"location":"setup/software/nonstandard-install/#configure-your-raspberry-pi","title":"Configure your Raspberry Pi","text":"Insert the microSD card into your Raspberry Pi and connect your Pi to a screen, a mouse, and a keyboard. Double-check the connections before plugging in power.
The first boot to the desktop may take up to 120 seconds. This is normal and is caused by the image expanding the filesystem to the whole SD card. DO NOT REBOOT before you reach the desktop.
Eventually, the display will ask you to configure some settings for the Raspberry Pi. You will be asked to choose language settings and a keyboard layout; you should choose settings appropriate for you. The standard PlanktoScope SD card images use the en_US.UTF-8 locale and the \"Generic 104-key PC, English (US)\" keyboard layout. The display will also ask you to set a username and password for the default user account on the Raspberry Pi; you must choose pi as the username, and you should choose a password you can remember. By default, the standard PlanktoScope SD card images use copepode as the password - so you may want to choose a different password for better security. Refer to the official Getting Started with your Raspberry Pi guide for additional details and instructions on configuring settings for the Raspberry Pi.
Next, configure your Raspberry Pi to get internet access - your Raspberry Pi will need to download software packages from the internet as part of the installation process for the PlanktoScope OS. If you have an Ethernet cable you can plug into your Raspberry Pi, that will be the simplest option for setup, because it won't require you to edit any files or run any commands on your Raspberry Pi; when we make our official SD card images with the PlanktoScope OS, we use an Ethernet cable. Otherwise, you will need to connect your Raspberry Pi to a wifi network with internet access; you can refer to the Raspberry Pi project's network configuration guide.
"},{"location":"setup/software/nonstandard-install/#set-up-the-planktoscope-os","title":"Set up the PlanktoScope OS","text":""},{"location":"setup/software/nonstandard-install/#run-the-installation-script","title":"Run the installation script","text":"Depending on whether you're installing the software on a PlanktoScope with the PlanktoScope HAT (which is the standard HAT on v2.3 hardware and later) or with the Adafruit Stepper Motor HAT (which is the standard HAT on v2.1 hardware), you will need to adjust the commands below. Specifically, if you're installing the software for a PlanktoScope with the Adafruit Stepper Motor HAT, you will need to replace the word planktoscopehat with the word adafruithat in any of the commands below.
Log in to your Raspberry Pi and (if you installed a version of Raspberry Pi OS with a graphical desktop) open a terminal. Then type in one of the following commands, depending on which release channel you want to use for installation (refer to our technical reference document on release channels to understand which release channel to use):
StableBetaEdgewget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- -v software/stable -H planktoscopehat\nThis will install the most recent stable release of the PlanktoScope OS (or, if the most recent release of the PlanktoScope software is a stable release, to install that stable release). This is recommended for most users.
wget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- -v software/beta -H planktoscopehat\nThis will install the most recent beta prerelease of the PlanktoScope OS (or, if the most recent prerelease/release of the PlanktoScope software is a stable release, to install that stable release). The beta prerelease probably contains bugs which will be fixed before the next stable release.
wget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- -v master -H planktoscopehat\nThis will install the current unstable development version of the PlanktoScope OS. This version is likely to be broken in various ways.
Instead of installing the latest version on the \"stable\", \"beta\", or \"edge\" release channel, you can also install a specific tagged release or pre-release of the PlanktoScope software. For example, to install the v2024.0.0-alpha.1 pre-release of the PlanktoScope software, you would run the following command:
wget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- -t tag -v v2024.0.0-alpha.1 -H planktoscopehat\nYou can also choose to install the PlanktoScope software from some other repository on GitHub instead of github.com/PlanktoScope/PlanktoScope, by using the -r command-line option; for more information including usage examples, you can refer to the reference page for the installation script's command-line parameters, and/or you can get usage instructions by running the following command:
wget -O - https://install.planktoscope.community/distro.sh \\\n | sh -s -- --help\nThe installation process will take a long time (around 15 - 30 minutes, depending on the speed of your internet connection and your microSD card) to finish.
If an error occurs during this setup process, you will need to wipe the Raspberry Pi's microSD card, flash the Raspberry Pi OS image onto it again, and try running the setup steps again. Otherwise, you will eventually see a message reporting that the setup script finished setting up the PlanktoScope application environment.
"},{"location":"setup/software/nonstandard-install/#connect-to-the-planktoscope","title":"Connect to the PlanktoScope","text":"Next, you will need to restart the Raspberry Pi, e.g. with the following command:
sudo reboot now\nThis step is necessary to finish the PlanktoScope software setup process.
Afterwards, your PlanktoScope's Raspberry Pi will either connect to a Wi-Fi network (if you had previously configured it to connect to a Wi-Fi network) or make a new isolated Wi-Fi network whose name starts with the word pkscope followed by the unique randomly-generated name of your PlanktoScope, and whose password is copepode.
If you connect another device (e.g. a phone or computer) directly to the PlanktoScope's Raspberry Pi over its isolated Wi-Fi network or over an Ethernet cable, 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):
Note that if you had previously configured your PlanktoScope's Raspberry Pi to connect to a Wi-Fi network, it will not make its own isolated Wi-Fi network. On the Wi-Fi network it's connected to, it should be accessible at http://pkscope.local (if you're accessing it from a device and web browser with mDNS support, assuming the device is on the same network), assuming that no other PlanktoScope is connected to the same network. If multiple PlanktoScopes are connected to the same network, open http://pkscope.local and read the web page's \"Wrong PlanktoScope?\" section for instructions on what URL to use; you can determine your PlanktoScope's name by connecting a display to its Raspberry Pi, booting up the Raspberry Pi, and reading the name from the login prompt (e.g. if it says pkscope-chain-list-27764 login:, then the PlanktoScope is named pkscope-chain-list-27764).
You will only be able to access the PlanktoScope's graphical user interface by plugging in a display and keyboard and mouse to the Raspberry Pi if you had previously used a \"Raspberry Pi OS with desktop\" or \"Raspberry Pi OS with desktop and recommended software\" SD card image as the base for the PlanktoScope software's setup script. In that case, you can open a web browser window on the Raspberry Pi and open http://localhost or any of the previously-listed URLs.
"},{"location":"setup/software/nonstandard-install/#next-steps","title":"Next steps","text":"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.
"},{"location":"setup/software/standard-install/","title":"Standard Installation","text":"This page provides instructions for installing the most recent standard version of the PlanktoScope OS on a PlanktoScope.
"},{"location":"setup/software/standard-install/#set-up-the-sd-card","title":"Set up the SD card","text":"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.
"},{"location":"setup/software/standard-install/#prerequisites","title":"Prerequisites","text":"In order to complete this step, you will need all of the following:
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.
"},{"location":"setup/software/standard-install/#write-the-image-to-the-sd-card","title":"Write the image to the SD card","text":"To write the image file to your microSD card:
Once flashing is complete, unmount the SD card and remove it from the computer.
"},{"location":"setup/software/standard-install/#insert-the-sd-card-into-the-planktoscope","title":"Insert the SD card into the PlanktoScope","text":"Insert the microSD card into the Raspberry Pi computer installed in your PlanktoScope.
"},{"location":"setup/software/standard-install/#connect-to-the-planktoscope","title":"Connect to the PlanktoScope","text":"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. The password of this Wi-Fi network is copepode.
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):
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.
"},{"location":"setup/software/standard-install/#next-steps","title":"Next steps","text":"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.
"},{"location":"troubleshooting/","title":"Troubleshooting","text":"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.