From cfab292bfe1d73d092e652a3c8068ff39bec9142 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Mon, 25 Nov 2024 15:26:32 +0000
Subject: [PATCH] Deploy
 https://github.com/PlanktoScope/PlanktoScope/commit/e5776a1be994d44b4f71e27664898a45217935ec

---
 .../social/reference/software/changelog.png     | Bin 41307 -> 0 bytes
 .../social/reference/software/product-specs.png | Bin 0 -> 51084 bytes
 site/search/search_index.json                   |   2 +-
 site/setup/hardware/v2.6/index.html             |   2 +-
 site/sitemap.xml.gz                             | Bin 578 -> 578 bytes
 5 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/site/assets/images/social/reference/software/changelog.png b/site/assets/images/social/reference/software/changelog.png
index 99f3efa67bedf0d8fed37a3fcba01dd9cd269691..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 100644
GIT binary patch
literal 0
HcmV?d00001

literal 41307
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
LwZHPOnLYj=0vDlK

diff --git a/site/assets/images/social/reference/software/product-specs.png b/site/assets/images/social/reference/software/product-specs.png
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..38c9bc1f43cea482ed671af01b588ad6774525cf 100644
GIT binary patch
literal 51084
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
J372m^_z%fQ3FH6(

literal 0
HcmV?d00001

diff --git a/site/search/search_index.json b/site/search/search_index.json
index a80e317..0a30bed 100644
--- a/site/search/search_index.json
+++ b/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"PlanktoScope Documentation","text":"<p>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:</p> <ol> <li>\"I want to get a PlanktoScope!\"</li> <li>\"I want to learn how to operate a PlanktoScope!\"</li> <li>\"I want to fix something which isn't working on my PlanktoScope!\"</li> <li>\"I want to get involved in the PlanktoScope community!\"</li> <li>\"I want to study the design of the PlanktoScope!\"</li> </ol>"},{"location":"#what-is-planktoscope","title":"What is PlanktoScope?","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p></p>"},{"location":"#what-is-the-planktoscope-project","title":"What is the PlanktoScope project?","text":"<p>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.</p>"},{"location":"#who-are-planktoscopes-for","title":"Who are PlanktoScopes for?","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>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!</p>"},{"location":"faq/","title":"Frequently Asked Questions","text":"<p>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!</p>"},{"location":"faq/#can-i-purchase-a-planktoscope","title":"Can I purchase a PlanktoScope?","text":"<p>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.</p>"},{"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":"<p>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.</p> <p>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.</p>"},{"location":"community/","title":"The PlanktoScope Community","text":"<p>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.</p> <p>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.</p>"},{"location":"community/#engage-on-github","title":"Engage on GitHub","text":"<p>Feel free to visit the GitHub and engage if you want.</p> <p></p> <p>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.</p> <p>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.</p>"},{"location":"community/#chat-on-slack","title":"Chat on Slack","text":"<p>The community is using Slack to communicate.</p> <p></p> <p>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.</p> <p>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.</p>"},{"location":"community/#classify-on-ecotaxa","title":"Classify on EcoTaxa","text":"<p>To join EcoTaxa, you just need to create an account.</p> <p></p> <p>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.</p> <p>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.</p>"},{"location":"community/code-of-conduct/","title":"Contributor Covenant Code of Conduct","text":""},{"location":"community/code-of-conduct/#our-pledge","title":"Our Pledge","text":"<p>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.</p> <p>We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.</p>"},{"location":"community/code-of-conduct/#our-standards","title":"Our Standards","text":"<p>Examples of behavior that contributes to a positive environment for our community include:</p> <ul> <li>Demonstrating empathy and kindness toward other people</li> <li>Being respectful of differing opinions, viewpoints, and experiences</li> <li>Giving and gracefully accepting constructive feedback</li> <li>Accepting responsibility and apologizing to those affected by our mistakes,   and learning from the experience</li> <li>Focusing on what is best not just for us as individuals, but for the overall   community</li> </ul> <p>Examples of unacceptable behavior include:</p> <ul> <li>The use of sexualized language or imagery, and sexual attention or advances of   any kind</li> <li>Trolling, insulting or derogatory comments, and personal or political attacks</li> <li>Public or private harassment</li> <li>Publishing others' private information, such as a physical or email address,   without their explicit permission</li> <li>Other conduct which could reasonably be considered inappropriate in a   professional setting</li> </ul>"},{"location":"community/code-of-conduct/#enforcement-responsibilities","title":"Enforcement Responsibilities","text":"<p>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.</p> <p>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.</p>"},{"location":"community/code-of-conduct/#scope","title":"Scope","text":"<p>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.</p>"},{"location":"community/code-of-conduct/#enforcement","title":"Enforcement","text":"<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at &lt; thibaut at fairscope.com &gt; . All complaints will be reviewed and investigated promptly and fairly.</p> <p>All community leaders are obligated to respect the privacy and security of the reporter of any incident.</p>"},{"location":"community/code-of-conduct/#enforcement-guidelines","title":"Enforcement Guidelines","text":"<p>Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:</p>"},{"location":"community/code-of-conduct/#1-correction","title":"1. Correction","text":"<p>Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.</p> <p>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.</p>"},{"location":"community/code-of-conduct/#2-warning","title":"2. Warning","text":"<p>Community Impact: A violation through a single incident or series of actions.</p> <p>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.</p>"},{"location":"community/code-of-conduct/#3-temporary-ban","title":"3. Temporary Ban","text":"<p>Community Impact: A serious violation of community standards, including sustained inappropriate behavior.</p> <p>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.</p>"},{"location":"community/code-of-conduct/#4-permanent-ban","title":"4. Permanent Ban","text":"<p>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.</p> <p>Consequence: A permanent ban from any sort of public interaction within the community.</p>"},{"location":"community/code-of-conduct/#attribution","title":"Attribution","text":"<p>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.</p> <p>Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.</p> <p>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.</p>"},{"location":"community/license/","title":"Our work is fully open source","text":"<p>That's the headline, yes.</p>"},{"location":"community/license/#hardware-files","title":"Hardware files","text":"<p>We released our hardware files (everything in the <code>hardware</code> directory) under a CERN OHL-S license.</p>"},{"location":"community/license/#software-source","title":"Software source","text":"<p>Our source code (everything in the directories <code>flows</code> and <code>scripts</code>) is released under a GPL-3.0 license.</p>"},{"location":"community/license/#everything-else-documentation-pictures-etc","title":"Everything else (documentation, pictures, etc...)","text":"<p>Everything else is released under a Creative Commons CC-BY-SA license.</p>"},{"location":"community/trainings/","title":"Trainings","text":"<p>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.</p>"},{"location":"community/trainings/#the-train-the-trainer-program","title":"The Train the trainer program","text":"<p>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.</p> <p>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.</p>"},{"location":"community/trainings/#event-types","title":"Event types","text":""},{"location":"community/trainings/#build-workshop","title":"Build workshop","text":"<p>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.</p>"},{"location":"community/trainings/#selecting-the-production-site","title":"Selecting the production site","text":"<p>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:</p> <ol> <li>Check the Manufacturing and Assembly Guides: Before choosing a production site, make sure to review the PlanktoScope Kit Manufacturing Guide and the Device Assembly Guide. These guides will provide detailed information on the necessary tools and equipment required for the production of the PlanktoScope Kits.</li> <li>Visit Fablab and Hackspaces: Consider visiting Fablabs or Hackspaces in your region. These organizations often have a culture of openness and may be willing to support you with your project. They may have the necessary tools and equipment to produce the PlanktoScope Kits, as well as the knowledge and expertise to guide you through the production process.</li> <li>Commercial Manufacturing: Look for a facility that has the capability to handle small scale production runs, a good quality control process and a logistic plan to ship the product to the final destination. Many</li> </ol> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#material-procurement","title":"Material procurement","text":"<p>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:</p> <ol> <li>Prepare the order list: Use the bill of materials (BOM) as a starting point to create a comprehensive list of all materials needed for the workshop. Expand it with additional columns for suppliers, delivery dates, prices, shipping costs, and import taxes.</li> <li>Plan for packaging: Plan for extra packaging so you can assemble the parts as shown in the instructions. Try to minimize plastic as much as possible.</li> <li>Research suppliers: Research suppliers and see if there are local options, if you can consolidate orders to save costs and ensure timely delivery.</li> <li>Compare prices: Compare the prices of different suppliers to minimize the total cost.</li> <li>Plan for spare parts: Plan for spare parts in case something is broken or lost.</li> <li>Check your Budget: Check your budget and ensure that you have enough funds to cover the cost of all materials, shipping, and any additional expenses before placing your orders.</li> <li>Place orders: Once you have identified the best suppliers, place orders for all of the materials that you need. Be sure to factor in lead time when placing orders to ensure that the materials will arrive in time for the workshop.</li> <li>Track orders: Keep track of your orders and expected delivery dates, mark a component when it arrives. Contact suppliers if there are any delays or problems with delivery.</li> <li>Communicate: Communicate with participants if there are issues with timely delivery. It may make sense to postpone the workshop if there is not enough time to prepare and test everything. The participants will be grateful and will understand if it helps to ensure that everything runs smoothly.</li> </ol> <p>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.</p> <p>Note</p> <p>If you have difficulty finding the components you need, contact us and we will be happy to help you find the right alternative.</p> <p>Warning</p> <p>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.</p> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#prepare-the-kit","title":"Prepare the Kit","text":"<p>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:</p> <ol> <li>Review the Bill of Materials (BOM): Review the Bill of Materials (BOM) for the PlanktoScope to ensure that you have all the necessary parts and materials for the workshop. The parts list can be found in the Device Assembly Guide and lists all components and quantities needed to build a microscope.</li> <li>Divide the kit components according to the BOM: Once the materials have been received, divide the kit components from the orders according to the Bill of Materials (BOM) of the PlanktoScope. This will ensure that each participant receives the correct components and that there are no missing parts.</li> <li>Have extra components: Have extra components on hand in case of any missing or damaged parts during the workshop.</li> <li>Package the kits: Package the kits in a way that makes it easy for the participants to find and use the components during the workshop.</li> <li>Label materials: Label the packages as described in Device Assembly Guide so that they are easy to find and distribute during the workshop.</li> <li>Preparation of the housing parts: Prepare the housing parts by applying the surface sealant and insert the nuts to screw the housing as described in the Kit Manufacturing Guide.</li> <li>Cutting and soldering of electronic cables: Cut and solder the electronic cables for the PlanktoScope. This will save time during the workshop and ensure that the participants have all the necessary cables to complete the assembly.</li> <li>Setting up the embedded development environment: Set up the embedded development environment and flash the eeprom of the PlanktoScope hat. This will ensure that the PlanktoScope hat is ready to be used during the workshop.</li> <li>Download the Raspberry Pi image: Download the Raspberry Pi image and flash it to the SD card. This will ensure that the participants have a ready to use image for the PlanktoScope.</li> <li>Test the kits: Test the kits before the workshop to ensure that all components are working correctly and that the instructions are clear and easy to follow. This will help to ensure that the participants have a positive and productive experience during the workshop.</li> </ol> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#conducting-the-workshop","title":"Conducting the workshop","text":"<p>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!</p> <ol> <li>Prepare the presentation: Prepare the presentation device and start your slides.</li> <li>Check-In: Once the Participants arrive, complete the check-in, share the agenda and set expectations for the workshop.</li> <li>Venue: Provide information about the venue, including where to find restrooms and where to buy food.</li> <li>Digital tools: Provide information about the digital tools that will be used during the workshop, such as the platform for collaboration, the survey tool and the chat channel, and how to access them.</li> <li>Data privacy: Inform about the privacy policy and the forms that need to be signed by the participants if you want to take photos.</li> <li>Introduction round: Begin with a round of introductions and give everyone a chance to introduce themselves, their background, and their interest in the project.</li> <li>Provide an overview: Provide details about the project, including the general mode of operation, the working materials such as the kit, the documentation and the git repository.</li> <li>Provide the Kits and Tools: Provide the Kit and Tools to each participant with a kit and the necessary tools.</li> <li>Follow the build instructions: Depending on the format you have chosen, start implementing by following the Kit Manufacturing guide or Device Assembly guide</li> <li>Follow the operation instructions: Now that you have successfully assembled the PlanktoScope, you can proceed to operation of the PlanktoScope by following the Getting started and User interface instructions.</li> <li>Final Test: For a final test you can use for example pure cultures or a sample taken with a Plankton net from a surrounding waters.</li> </ol>"},{"location":"community/trainings/#field-trip","title":"Field trip","text":"<p>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!</p>"},{"location":"community/trainings/#hackathon","title":"Hackathon","text":"<p>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!</p>"},{"location":"community/trainings/#general-planning-methods","title":"General planning methods","text":"<p>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.</p> <p>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.</p>"},{"location":"community/trainings/#building-a-team","title":"Building a team","text":"<p>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.</p> <ol> <li>Identify the roles and responsibilities: Determine the key areas that need to be covered during the workshop and assign specific roles to team members. For example, one team member may be responsible for organizing logistics, while another may be responsible for creating the agenda.</li> <li>Assemble the team: Once the roles and responsibilities have been identified, begin assembling the team. Consider individuals with relevant skills and experiences, as well as those who have a passion for the topic of the workshop. It is also important to have a mix of team members from different departments or backgrounds to bring a variety of perspectives to the planning process.</li> <li>Communicate effectively: Establish clear lines of communication within the team to ensure that everyone is on the same page. This can be done through regular meetings, email, or a team collaboration platform.</li> <li>Encourage participation: Encourage team members to actively participate in the planning process by sharing their ideas and feedback. This will help to ensure that everyone feels invested in the success of the workshop.</li> <li>Appoint a leader: Appoint a leader for the team who will be responsible for coordinating the planning process and ensuring that the team stays on track. The leader should be someone who is organized, a good communicator, and able to delegate tasks effectively.</li> </ol>"},{"location":"community/trainings/#communication-channels","title":"Communication channels","text":"<p>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.</p> <ol> <li>Choose the right channels: Once the needs have been identified, choose the communication channels that will best serve those needs. Email, chat, and video conferencing are all popular options. If the group is small, a group chat or email chain may be sufficient. If the group is larger or more dispersed, a video conferencing platform may be more appropriate.</li> <li>Make sure they are accessible: Ensure that the communication channels you choose are accessible to all participants. This may include providing training or support for those who are less familiar with the tools you are using.</li> <li>Communicate expectations: Clearly communicate the expectations for using the communication channels to the participants. This includes guidelines for how often and when to check the channels, as well as how to respond to messages.</li> <li>Continuity: Make sure that you have continuity in the communication channels after the workshop. This will help to build a fluent community and to keep the participants connected and engaged. Use the same channels to share updates and resources, or to organize follow-up events or activities.</li> </ol> <p>Note</p> <p>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.</p> <p>Note</p> <p>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.</p> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#selecting-digital-tools","title":"Selecting digital tools","text":"<p>The right tools can help to facilitate communication, collaboration, and organization, making the workshop experience more productive and enjoyable for everyone.</p> <ol> <li>Use web-based tools: Whenever possible, use web-based tools that can be accessed from any device with an internet connection. This will make it easier for participants to access and use the tools, regardless of their location or device.</li> <li>Use collaborative note-taking tools: You might use web-based tools like HedgeDoc that allow participants to collaboratively collect notes during the workshop. This can help to ensure that everyone has access to the same information, and can help to make the workshop experience more productive and enjoyable for everyone.</li> <li>Use survey tools: You might use survey tools like LimeSurvey to gather information about the participants' needs and expectations for the workshop. This can help to ensure that the workshop is relevant, valuable, and effective for them.</li> <li>Use ticketing tools: You might use tools like Pretix to manage ticketing for the workshop. This can help to simplify the registration process, and can also provide valuable information about the attendees.</li> </ol>"},{"location":"community/trainings/#find-your-audience","title":"Find your audience","text":"<p>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.</p> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#determining-the-need","title":"Determining the need","text":"<p>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:</p> <ol> <li>Surveys and questionnaires: Use surveys and questionnaires to gather information about the participants' needs and expectations for the workshop. This can include their level of experience and knowledge, their specific interests and goals, and any challenges or concerns they may have.</li> <li>Pre-workshop consultation: Schedule pre-workshop consultations with the participants to discuss their needs and expectations in more detail. This can help to identify any specific areas of interest or concern, and can also provide an opportunity to address any questions or concerns the participants may have.</li> <li>Audience analysis: Analyze the characteristics of the audience, such as their profession, level of education and experience, and any other relevant details. This will give you a better idea of the type of content that will be most relevant and useful for the participants.</li> <li>Feedback: Ask for feedback from participants after the workshop and take it into account when planning future workshops. This feedback can be used to improve the overall experience and to tailor the workshop to better meet the needs of the participants.</li> </ol>"},{"location":"community/trainings/#defining-the-goals","title":"Defining the goals","text":"<p>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.</p> <ol> <li>Number of participants: The workshop should be designed for a specific number of participants. Depending on the available resources, the number of participants can range from small groups of 4-8 people to larger groups of 8-12 people.</li> <li>Number of microscopes: The goal of the workshop is to build a specific number of PlanktoScope Microscopes. It is important to have the necessary materials and tools for each participant to build their own microscope.</li> <li>Content: The workshop will include both theoretical and practical content. The theoretical content will cover the principles of open-source hardware and software and the specific design of the PlanktoScope Microscope. The practical content will focus on the assembly and usage of the microscope, including hands-on experience with soldering and other techniques.</li> </ol> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#financial-planning","title":"Financial planning","text":"<p>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:</p> <ol> <li>Decide on the cost of the kits: One of the first things to consider is whether you want to offer the kits for sale to the participants or if you want them to purchase the kits themselves. If you choose to offer the kits for sale, you will need to factor in the cost of materials and other expenses, such as shipping and handling. If you choose to have the participants purchase the kits themselves, you will need to provide them with information on where to purchase the kits and the estimated cost.</li> <li>Check for funding opportunities: There may be organizations or foundations that would be willing to support your workshop financially. It's a good idea to research potential sources of funding such as grants, sponsorships, and crowdfunding campaigns. Additionally, look for local or regional organizations that are working in the same field as your workshop, they might be interested in supporting your initiative.</li> <li>Reach out to potential sponsors: Once you have identified potential sources of funding, reach out to them to inquire about their funding opportunities. Be prepared to provide them with information about the workshop, including the goals, objectives, and expected outcomes. Be sure to include information about the open-source nature of the project, as this may make it more attractive to organizations with an interest in open-source technology.</li> <li>Look for cost-saving options: In addition to securing funding, there are also ways to save money on expenses. Consider renting equipment or space rather than purchasing it. Reach out to local universities or community organizations to see if they have equipment or space that you can use for the workshop at a reduced cost or for free.</li> </ol> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#creating-a-timetable","title":"Creating a timetable","text":"<p>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:</p> <ol> <li>Plan for more than just a day: A workshop may take more than one day to complete, so be sure to plan accordingly. Consider the amount of time required to cover all the topics, and allocate enough time for each one.</li> <li>Assign an expected duration to each item on the schedule: Assign an expected duration to each item on the schedule so that participants know how much time they should expect to spend on each topic. This will also help you to ensure that you have allocated enough time for each topic.</li> <li>Allocate time for breaks and activities: Make sure to allocate time for breaks, meals and other activities such as group discussions, teamwork, or hands-on activities. This will help to keep the participants engaged and energized throughout the workshop.</li> <li>Plan for contingencies: Include some flexibility in the schedule to allow for unexpected events or delays. This will help to ensure that the workshop stays on track even if things don't go exactly as planned.</li> </ol>"},{"location":"community/trainings/#venue-selection","title":"Venue selection","text":"<p>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:</p> <ol> <li>Reach out to Universities, research institutions, Fablabs, Hackspaces or non-profit organizations: Reach out to organizations that might have an interest in the PlanktoScope, and a community that might support you with free access to their location.</li> <li>Check the equipment: Make sure the location is equipped with the necessary resources such as a whiteboard, projector/TV, and other equipment that may be required for the workshop.</li> <li>Check the accessibility: Check the accessibility of the location with the public transport system and parking availability.</li> <li>Check for food provision: Consider if there is a possibility to go shopping or how to provide food for the course participants during the workshop.</li> <li>Check the environment: Consider the environment of the location, make sure it is comfortable, has enough space and is well-ventilated for the workshop.</li> </ol>"},{"location":"community/trainings/#announcing-the-event","title":"Announcing the event","text":"<p>When announcing the event, it is important to include the following information:</p> <ol> <li>Date: Provide a specific date, start and end time for the workshop, and ensure there is enough lead time for preparation, including ordering or manufacturing materials and coordinating with suppliers. Allow ample time between announcing the workshop and the actual event.</li> <li>Goal: Clearly communicate the specific goal of the workshop, such as to build a fully functional planktoscope and learn how to use it.</li> <li>What attendees will learn in the workshop: Clearly outline the specific skills or knowledge that will be covered in the workshop, such as how to assemble the kit, soldering the through-hole components of the controller, and working with the software.</li> <li>Instructor's background: Provide some notes about the instructor's qualifications or experience that make them well-suited to lead the workshop, such as experience working with planktoscope.</li> <li>Target audience: Clearly indicate the target group of the workshop, such as researchers, engineers or designers.</li> <li>Previous knowledge: Specify any previous knowledge required for the workshop, such as soldering skills or experience working with open-source hardware and software.</li> <li>Implementation method: Describe the form of the workshop, such as a step-by-step guide.</li> <li>Documentation: Consider sharing the documentation beforehand, so they can familiarize themselves with the process.</li> <li>Cost: Clearly communicate the cost of the workshop.</li> <li>Schedule: Provide a clear and detailed schedule of the workshop, including the duration of the workshop, for example, one day of building and one day of using the plankoscope.</li> <li>Location: Provide the location of the workshop, including information on how to get there with public transportation or Arrival by car and parking. Also, provide a link to a map service</li> <li>Registration: Details of the registration process, including information on where to obtain a ticket and any deadlines for registration.</li> <li>Contact details: Additionally, it may be helpful to include contact information for any questions.</li> <li>Images: Include some visually appealing images, such as from a previous workshop or field trip, to show what attendees can expect from the event. This can additionally be a great way to build anticipation and excitement, thus motivating more people to attend the workshop.</li> <li>Media: Post your offer on a website or social media platform that is relevant to the workshop topic and your target audience. This way you can increase visibility and reach a wider audience, which increases the chances of getting more attendees.</li> </ol> <p>Tip</p> <p>If you already have a group of interested people, send a link to the announcement via email or chat and invite them personally.</p>"},{"location":"community/trainings/#preparing-a-presentation","title":"Preparing a presentation","text":"<p>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.</p> <ol> <li>Gather resources: Gather resources such as images, videos, and diagrams that can be used to support the presentation. These resources can be found on the Planktoscope website or other sources.</li> <li>Outline the main topics: Outline the main topics that will be covered during the workshop, such as the components of the microscope, the assembly process, and the use of the microscope.</li> <li>Prepare a handout: Prepare a handout or a guide that the participants can use during the workshop to follow the steps, and have it ready to be printed or shared digitally</li> <li>Practice the presentation: Practice the presentation several times before the workshop to ensure that it runs smoothly and that you are comfortable with the material.</li> <li>Be ready to adapt: Be ready to adapt the presentation during the workshop to fit the needs of the participants.</li> </ol> <p>Here are some topics that should be covered in a presentation:</p> <ol> <li>Event: Provide an overview of the event, including the goal of the workshop.</li> <li>Schedule: Provide an timetable for the event, including breaks, start and end times, and any planned activities for the next day.</li> <li>Venue: Provide information about the venue, including where to find restrooms and where to buy food.</li> <li>Instructor: Provide information about the instructor, including his or her background, and how to get in touch with him or her</li> <li>Digital tools: Provide information about the digital tools that will be used during the workshop, such as the platform for collaboration, the survey tool and the chat channel, and how to access them</li> <li>Data privacy: Provide information about the data privacy policy and the forms that need to be signed by the participants.</li> <li>Follow-ups: Point out follow-up actions such as the survey and that participation can be very helpful in improving the offer.</li> <li>Communication: Inform about the communication channels that will be used during the workshop and complete the onboarding.</li> <li>Introduction round: A round of introductions at the beginning of a workshop helps to create a sense of community and connection among the participants, allows the instructor to tailor the workshop to the group's needs, addresses potential language barriers, creates a sense of accountability, and helps participants to be more focused and relaxed.</li> <li>About the project: Provide details about the project, including the working materials such as the kit, the documentation, and the git repository.</li> </ol>"},{"location":"community/trainings/#send-an-final-reminder","title":"Send an final Reminder","text":"<p>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.</p> <ol> <li>Schedule for the event: Include a detailed schedule for the event, including breaks, start and end times, and any planned activities for the next day. This will help participants to plan their time and make the most of the workshop.</li> <li>About the venue: Provide detailed information about the venue, including the address, public transportation options, and parking situation. Make sure to include any specific instructions or requirements for accessing the venue.</li> <li>About the documentation: Provide a link to the documentation, such as the assembly and manufacturing guide, that the participants can familiarize themselves with before the workshop. This will help them to be better prepared and make the most of the workshop.</li> <li>Cancellation policy: Remind the participants that now is the last opportunity to cancel their registration. This will allow other individuals on the waiting list to attend the workshop.</li> <li>Final Instructions: Provide any final instructions or important information that the participants should be aware of before the workshop.</li> </ol>"},{"location":"community/trainings/#documenting-the-event","title":"Documenting the event","text":"<p>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.</p> <ol> <li>Equipment: Make sure you have the necessary equipment to document the event, including a camera (DSLR or mirrorless camera), lenses, memory cards, and batteries.</li> <li>Backup: Always make sure to have a backup plan for your equipment and photos, such as bringing extra memory cards and batteries.</li> <li>Lighting: Take into account the lighting conditions and make sure to have the right settings for your camera to capture the best possible images.</li> <li>Planning: Plan out the photos you want to take, taking into account the theme, location and schedule of the event.</li> <li>Composition: Pay attention to the composition of your photos and make sure to use techniques such as the rule of thirds and leading lines to create visually appealing images.</li> <li>Capturing candid moments: In addition to capturing posed shots, make sure to capture candid moments that capture the atmosphere and emotions of the event.</li> <li>Post-processing: Once the event is over, review and edit your photos to make them look their best.</li> <li>Data Privacy and Opt-Out: Pay attention to the privacy policy and get participants' consent before taking photos of them. Offer an opt-out option for participants who do not want to have photos taken. Clearly communicate what the photos will be used for and by whom, for example, to enhance this documentation.</li> <li>License: If your participants have agreed to share and use the photos, choose an appropriate license under which to license the photos. We recommend the Creative Commons license. For more information, see the project's license terms page.</li> <li>Sharing on Social Media: Share the photos on social media platforms to create a visual memory of the event and increase the visibility of the event.</li> </ol> <p>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.</p>"},{"location":"community/trainings/#follow-up","title":"Follow-up","text":"<p>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:</p> <ol> <li>Follow-up with participants: Send out a survey or contact participants individually to gather feedback on their experience during the workshop. This feedback can be used to improve future workshops and address any issues that may have arisen.</li> <li>Share resources and information: Share any relevant resources such as presentations, handouts, or any other materials that will help the participants continue their learning after the workshop.</li> <li>Build a community: Encourage participants to connect and share their experiences with each other. This can be done through online forums, social media groups, or other platforms. Building a community of enthusiasts and collaborators will help to ensure that the workshop's goals and objectives are met and that the participants leave the workshop with a sense of accomplishment.</li> <li>Continual learning: Provide additional training opportunities or resources for participants to continue their learning after the workshop. This could be through follow-up workshops, webinars, or online tutorials.</li> <li>Track progress: Keep track of the progress of the participants, check if they are applying what they learned during the workshop and give feedback to help them improve.</li> </ol>"},{"location":"community/trainings/#improve-this-training-program","title":"Improve this training program","text":"<p>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.</p> <p>Here are a few ways to improve this training program:</p> <ol> <li>Gather feedback: Regularly gather feedback from attendees, instructors and other stakeholders to understand how the program is being received and identify areas for improvement.</li> <li>Review and revise content: Review the content of the program and make changes as necessary to ensure that it is up-to-date, accurate, and relevant to the attendees.</li> <li>Continuously update the material: Continuously update the material, adding new information and best practices as it becomes available.</li> <li>Use different learning methods: Use different learning methods to accommodate different learning styles, such as hands-on activities, group discussions, and online resources.</li> <li>Encourage participation: Encourage participation and collaboration among attendees, creating an interactive and dynamic learning experience.</li> <li>Use modern technologies: Use modern technologies to enhance the learning experience, such as virtual reality, gamification, and AI-based learning.</li> <li>Assess the impact: Assess the impact of the program on the attendees and make changes as necessary to ensure that the program is achieving its intended goals.</li> </ol> <p>For more information on how to contribute to this document and improve this training program, please see the contribute section on Writing Documentation.</p>"},{"location":"community/contribute/documentation/","title":"Writing Documentation","text":"<p>The source files are in the main github repository, in the <code>docs</code> folder.</p> <p>They are simple Markdown files, that you can edit in any text editor of your choice.</p> <p>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.</p> <pre><code>hatch run docs:serve\n</code></pre> <p>After installing mkdocs, you can use <code>mkdocs serve</code> in the main folder of this repository to start the development server.</p> <p>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 <code>expert_setup.md</code>, please put all the related pictures in the <code>docs/expert_setup/</code> 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.</p> <p>Contributions should be made by creating pull requests on Github directly.</p>"},{"location":"community/contribute/documentation/#extensions-available","title":"Extensions available","text":"<p>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.</p> <ul> <li>SmartyPants: Converts ASCII dashes, quotes and ellipses to their HTML entity equivalents.</li> <li>Sane Lists: Alters the behavior of the Markdown List syntax to be less surprising.</li> <li>Admonition: Adds rST-style admonitions to Markdown documents.</li> <li>Table of contents: Generates a Table of Contents from a Markdown document and adds it into the resulting HTML document.</li> <li>Metadata: Adds a syntax for defining meta-data about a document.</li> <li>Tables: Adds the ability to create tables in Markdown documents.</li> <li>Fenced Code Blocks: Adds a secondary way to define code blocks.</li> </ul>"},{"location":"community/contribute/github/","title":"Contributing","text":"<p>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.</p> <p>There are several ways to join the development effort, share your progress with your build or just ask for help.</p> <p>We are using slack as a communication platform between interested parties. You can request to join by filling this form.</p> <p>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.</p>"},{"location":"community/contribute/github/#assumptions","title":"Assumptions","text":"<ol> <li>You're familiar with git and the Merge Request(PR) workflow.</li> <li>**You've read the PlanktoScope documentation.</li> <li>You know about the PlanktoScope community on Slack. Please use this for help.</li> </ol>"},{"location":"community/contribute/github/#how-to-contribute","title":"How to Contribute","text":"<ol> <li>Make sure that the contribution you want to make is explained or detailed in a GitHub issue! Find an existing issue or open a new one.</li> <li>Once done, fork the PlanktoScope repository in your Github account. Ask a mastertainer if you want your issue to be checked before making a PR.</li> <li>Create a new Git branch.</li> <li>Review the Development Workflow section that describes the steps to mastertain the repository.</li> <li>Make the changes on your branch.</li> <li>Submit the branch as a PR pointing to the <code>master</code> 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.</li> </ol>"},{"location":"community/contribute/github/#git-guidelines","title":"Git Guidelines","text":""},{"location":"community/contribute/github/#git-branches","title":"Git Branches","text":"<p>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.</p>"},{"location":"community/contribute/github/#git-commits","title":"Git Commits","text":"<p>As minimal requirements, your commit message should:</p> <ul> <li>be capitalized</li> <li>not finish by a dot or any other punctuation character (!,?)</li> <li>start with a verb so that we can read your commit message this way: \"This commit will ...\", where \"...\" is the commit message.   e.g.: \"Fix the home page button\" or \"Add more tests for create_index method\"</li> </ul> <p>We don't follow any other convention, but if you want to use one, we recommend this one.</p>"},{"location":"community/contribute/github/#pull-requests","title":"Pull Requests","text":"<p>Some notes on PRs:</p> <ul> <li>Convert your PR as a draft if your changes are a work in progress: no one will review it until you pass your PR as ready for review.   The draft PR can be very useful if you want to show that you are working on something and make your work visible.</li> <li>The branch related to the PR must be up-to-date with <code>master</code> before merging. Fortunately, this project integrates a bot to automatically enforce this requirement without the PR author having to do it manually.</li> <li>All PRs must be reviewed and approved by at least one mastertainer.</li> <li>The PR title should be accurate and descriptive of the changes. The title of the PR will be indeed automatically added to the next release changelogs.</li> </ul>"},{"location":"community/contribute/github/#release-process-for-internal-team-only","title":"Release Process (for internal team only)","text":"<p>PlanktoScope tools follow the Semantic Versioning Convention.</p>"},{"location":"community/contribute/github/#automation-to-rebase-and-merge-the-prs","title":"Automation to Rebase and Merge the PRs","text":"<p>This project integrates a bot that helps us manage pull requests merging. Read more about this.</p>"},{"location":"community/contribute/github/#how-to-publish-the-release","title":"How to Publish the Release","text":"<p>\u26a0\ufe0f Before doing anything, make sure you got through the guide about Releasing an Integration.</p> <p>\u26a0\ufe0f Every PR that is merged to <code>master</code> introducing changes to the PlanktoScope needs to modify the file ``, by increasing the version of the chart accordingly.</p> <p>Every PR that is merged to <code>master</code> 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.</p> <p>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</p>"},{"location":"community/contribute/hardware/","title":"Hardware Development","text":""},{"location":"community/contribute/hardware/#planktoscope-case","title":"PlanktoScope Case","text":"<p>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.</p> <p>To get started with the project, you will need to install a development environment on your computer. Here are the steps to follow:</p> <ul> <li>Download and install Fusion 360 from the Autodesk website.</li> <li>Create a free Autodesk account and log in to Fusion 360.</li> <li>Join the PlanktoScope Case team in Fusion 360. This will give you access to all of the project files and allow you to collaborate with other team members.</li> <li>Familiarize yourself with the Fusion 360 interface and tools. There are many resources available online, including tutorials and user guides, to help you get up to speed.</li> <li>Start designing and testing your case components in Fusion 360. You can use the software to create 3D models, run simulations and stress tests, and collaborate with other team members in real-time.</li> </ul> <p>By following these steps, you will be able to successfully install a development environment and participate in the PlanktoScope Case using Autodesk Fusion 360.</p>"},{"location":"community/contribute/hardware/#planktoscope-hat","title":"PlanktoScope Hat","text":"<p>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).</p> <p>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:</p> <ul> <li>Download and install Autodesk Eagle from the official website. Make sure to select the appropriate version for your operating system (Windows, Mac, or Linux).</li> <li>Follow the instructions provided by Autodesk to complete the installation process. This may involve entering a license key or activating the software through your Autodesk account.</li> <li>Once Autodesk Eagle is installed, you may need to install additional libraries or tools depending on the specific requirements of the PlanktoScope Hat. These may include libraries for communicating with specific hardware components, or tools for debugging and testing your designs.</li> <li>Once you have installed all the necessary tools and libraries, you should be ready to start working on the PlanktoScope Hat using Autodesk Eagle. You can begin by opening the project files and familiarizing yourself with the existing design, or by creating new designs as needed.</li> </ul> <p>By following these steps, you can set up a development environment that allows you to contribute to the PlanktoScope Hat using Autodesk Eagle.</p>"},{"location":"community/contribute/software/","title":"How to help development for the PlanktoScope code","text":"<p>We are using the Github Flow approach for our development efforts.</p> <p>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.</p> <p>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!)</p>"},{"location":"community/contribute/software/#node-red","title":"Node-Red","text":"<p>Node-Red is our main process. We use the flow to manage our user interface through a dashboard instance.</p> <p></p> <p>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.</p> <p>To set up a Node-RED development environment on a Debian operating system, you will need to follow these steps:</p> <ol> <li>Install Node.js: Node-RED requires Node.js to be installed on your system. You can install Node.js using the package manager by running the following command: <code>sudo apt-get install nodejs</code></li> <li>Install npm (Node Package Manager): npm is a package manager for Node.js that is used to install and manage Node-RED and its dependencies. You can install npm by running the following command: <code>sudo apt-get install npm</code></li> <li>Install Node-RED: Once Node.js and npm are installed, you can install Node-RED by running the following command: <code>sudo npm install -g --unsafe-perm node-red</code></li> <li>Start the Node-RED server: You can start the Node-RED server by running the following command: <code>node-red</code></li> <li>Access the Node-RED editor: You can access the Node-RED editor by opening a web browser and going to the URL http://localhost:1880.</li> </ol> <p>By following these steps, you will be able to set up a Node-RED development environment on your Debian operating system and start building applications with the visual, drag-and-drop interface.</p>"},{"location":"community/contribute/software/#python","title":"Python","text":"<p>The python code is separated in four main processes, each with a specific set of responsibilities:</p> <ul> <li>The main process controls all the others, starts everything up and cleans up on shutdown</li> <li>The stepper process manages the stepper movements.</li> <li>The imager process controls the camera and the streaming server via a state machine.</li> <li>The segmenter process manages the segmentation and its outputs.</li> </ul> <p>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.</p> <p>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.</p>"},{"location":"operation/","title":"Operation","text":"<p>This page provides basic instructions for operating your PlanktoScope.</p> <p></p>"},{"location":"operation/#connect-directly-to-your-planktoscope","title":"Connect directly to your PlanktoScope","text":"<p>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.</p>"},{"location":"operation/#connect-with-an-ethernet-cable","title":"Connect with an Ethernet cable","text":"<p>You can connect your computer to the PlanktoScope by plugging an Ethernet cable between your computer and your PlanktoScope's Raspberry Pi.</p>"},{"location":"operation/#connect-with-the-planktoscopes-isolated-wi-fi-network","title":"Connect with the PlanktoScope's isolated Wi-Fi network","text":"<p>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.</p> <p></p> <p>As you can see, the name of your PlanktoScope's Wi-Fi network will be of the format <code>pkscope-{random word}-{random word}-{random number}</code>. 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 <code>{random-word}-{random-word}-{random number}</code>, which is just the name of the Wi-Fi network but without the <code>pkscope-</code> prefix (e.g. <code>chain-list-27764</code>). You should connect to the Wi-Fi network specific to your PlanktoScope.</p> <p>Unless you have changed the password of your PlanktoScope's Wi-Fi network, the password should be <code>copepode</code>.</p>"},{"location":"operation/#access-your-planktoscopes-software","title":"Access your PlanktoScope's software","text":"<p>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):</p> <ul> <li>http://planktoscope.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)</li> <li>http://pkscope.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)</li> <li>http://home.pkscope\u00a0(this should work unless your web browser is configured to use a Private DNS provider)</li> <li>http://192.168.4.1\u00a0(this should always work)</li> <li>http://192.168.5.1\u00a0(this should always work)</li> </ul> <p>Tip</p> <p>If you know the machine name of your PlanktoScope (which has format <code>{random-word}-{random-word}-{random number}</code>, e.g. <code>chain-list-27764</code>, you can also try the following URLs after replacing <code>{machine-name}</code> with the actual machine name of your PlanktoScope:</p> <p><code>http://pkscope-{machine-name}.local</code>\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)</p> <p><code>http://{machine-name}.pkscope</code>\u00a0(this should work unless your web browser is configured to use a Private DNS provider)</p> <p>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.</p> <p>Warning</p> <p>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.</p> <p>One of the above URLs should work, and your web browser should show a landing page with a list of links:</p> <p></p> <p>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.</p>"},{"location":"operation/#how-to-image-plankton","title":"How to image plankton","text":"<p>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).</p> <p>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.</p> <p>You can then do an acquisition run. This is the best way to learn about the machine and this process!</p> <p>Warning</p> <p>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.</p> <p>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.</p> <p>For quantitative imaging of water samples, refer to the following protocols published by members of the PlanktoScope community:</p> <ul> <li>\"Planktoscope protocol for plankton imaging V.2\" for software v2.3+ and hardware v2.5. A PDF copy of this protocol is also available for offline use.</li> <li>\"Planktoscope protocol for plankton imaging V.1\" for software v2.3 and hardware v2.1-2.3. A PDF copy of this protocol is also available for offline use.</li> </ul>"},{"location":"operation/clone-sd/","title":"Clone your SD card","text":"<p>If you want to create an SD card image from your PlanktoScope to use on other PlanktoScopes, you can follow the following steps.</p>"},{"location":"operation/clone-sd/#prepare-the-sd-card-for-cloning","title":"Prepare the SD card for cloning","text":"<p>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.</p>"},{"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":"<p>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 <code>/usr/libexec/prepare-custom-image</code> 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:</p> <pre><code>sudo /usr/libexec/prepare-custom-image\n</code></pre> <p>Once this script finishes running, it will shut down your PlanktoScope's Raspberry Pi.</p> <p>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 <code>rootfs</code> partition to delete any other sensitive files which were not removed by the <code>/usr/libexec/prepare-custom-image</code> script. For example, you may also want to delete or edit some or all of the following files from the <code>rootfs</code> partition in order to remove any sensitive or machine-specific information:</p> <ul> <li><code>etc/wpa_supplicant/wpa_supplicant.conf</code>: Wi-Fi configuration and network secrets.</li> <li><code>home/pi/.ssh/authorized_keys</code>: SSH public keys of devices authorized to remotely connect to the PlanktoScope.</li> <li><code>home/pi/data/</code>: 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.</li> <li><code>home/pi/.bash_history</code>: Bash command history.</li> <li><code>home/pi/.python_history</code>: Python command history.</li> <li><code>home/pi/.gitconfig</code>: Git configuration, which may contain user-specific details.</li> </ul> <p>Info</p> <p>You can also delete the files listed above before running the <code>/usr/libexec/prepare-custom-image</code> 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.</p> <p>Next, proceed to the Make an SD card image section of this guide.</p>"},{"location":"operation/clone-sd/#prepare-an-exact-backup","title":"Prepare an exact backup","text":"<p>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 <code>/usr/libexec/prepare-custom-image</code> script: that script will delete some files which you probably want to keep. Instead, you should edit the <code>/boot/cmdline.txt</code> file to add the string <code>init=/usr/lib/raspberrypi-sys-mods/firstboot</code> to the end of the file, for example resulting in a file which looks something like:</p> <pre><code>console=tty1 root=PARTUUID=someuniqueidhere rootfstype=ext4 fsck.repair=yes rootwait init=/usr/lib/raspberrypi-sys-mods/firstboot\n</code></pre> <p>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. Then proceed to the Make an SD card image section of this guide.</p> <p>Warning</p> <p>After you have finished cloning the SD card to an SD card image, you should edit the <code>/boot/cmdline.txt</code> file to remove the <code>init=/usr/lib/raspberrypi-sys-mods/firstboot</code> 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.</p>"},{"location":"operation/clone-sd/#make-an-sd-card-image","title":"Make an SD card image","text":""},{"location":"operation/clone-sd/#locate-the-sd-card","title":"Locate the SD card","text":"<p>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 <code>/dev/mmcblk0</code>, <code>/dev/sda</code>, or <code>/dev/sdb</code>; it should always be some file in <code>/dev</code>. To identify the device file for your SD card, run the command <code>sudo fdisk -l</code> in your terminal. The output may look something like:</p> <pre><code>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\n</code></pre> <p>To 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 <code>/dev/mmcblk0</code>.</p> <p>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 <code>umount</code> command. For example, if your device is <code>/dev/mmcblk0</code>, you will need to run:</p> <pre><code>sudo umount /dev/mmcblk0p1\nsudo umount /dev/mmcblk0p2\n</code></pre> <p>If the devices were already not mounted, you should expect to see (and you can safely ignore) error messages which look like:</p> <pre><code>umount: /dev/mmcblk0p1: not mounted.\numount: /dev/mmcblk0p2: not mounted.\n</code></pre>"},{"location":"operation/clone-sd/#clone-the-sd-card-to-an-image","title":"Clone the SD card to an image","text":"<p>To 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 <code>/dev/mmcblk0</code>, you could run the following command (replacing file paths and names accordingly):</p> <pre><code>sudo dd bs=4M if=/dev/mmcblk0 of=/some/path/here/image-name-here.img status=progress\n</code></pre> <p>This will create a <code>.img</code> file (at <code>/some/path/here/image-name-here.img</code>) 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.</p>"},{"location":"operation/clone-sd/#shrink-the-sd-card-image","title":"Shrink the SD card image","text":"<p>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):</p> <pre><code>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\n</code></pre> <p>If you had set up the PlanktoScope software on a Raspberry Pi OS Lite image, you should get a <code>image-name-here.img.gz</code> file which is at least 2 GB in size.</p>"},{"location":"operation/clone-sd/#use-the-sd-card-image","title":"Use the SD card image","text":"<p>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.</p>"},{"location":"operation/maintenance/","title":"Maintenance and Repair","text":"<p>Instructions for maintaining and repairing the PlanktoScope.</p>"},{"location":"operation/maintenance/#cleaning-the-optics","title":"Cleaning the optics","text":"<ul> <li>Begin by turning off the microscope and unplugging it from any power source.   Gently remove any dust or debris using a soft, dry cloth.</li> <li>To clean the lenses and other optics, use a lens cleaning solution and a lens cleaning tissue or cloth. Gently wipe the optics in a circular motion, starting from the center and working outward. Avoid applying too much pressure or using a rough cloth, as this can scratch or damage the optics.</li> <li>Once you have finished cleaning the optics, use a dry cloth to remove any excess moisture or cleaning solution.</li> </ul>"},{"location":"operation/maintenance/#software-updates","title":"Software updates","text":"<p>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.</p> <p>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.</p>"},{"location":"operation/sample-collection/","title":"Sample collection","text":"<p>The most common way to collect samples for the PlanktoScope is to use a plankton net.</p>"},{"location":"operation/sample-collection/#plankton-net","title":"Plankton Net","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p></p> <p>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.</p> <p>Plankton nets can be made easily with a good sewind machine and some hardware.</p>"},{"location":"operation/user-interface/","title":"User interface guide","text":"<p>This guide will help you understand how to use the Node-RED dashboard, which is the primary user interface for operating the PlanktoScope.</p> <p></p>"},{"location":"operation/user-interface/#home","title":"Home","text":"<p>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.</p> <p>From here, you can quickly access any of the available tabs. The buttons are only the most used functionnalities of the machine. Three others tabs are accessible only through the hamburger menu on the top left of the screen (the three horizontal lines):</p> <ul> <li>Wifi</li> <li>Administration</li> <li>Hardware Config</li> </ul> <p></p> <p>Tip</p> <p>This list is also available from any other tab and allows you to quickly navigate between tabs.</p>"},{"location":"operation/user-interface/#machine-shutdown","title":"Machine shutdown","text":"<p>From this page, you can also shutdown the machine when you are done.</p> <p>Warning</p> <p>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!</p> <p>To shutdown the machine, first unlock the shutdown button by clicking on \"Unlock Button\".</p> <p></p> <p>You can then click on \"Shutdown\". The machine will ask for a final confirmation and will then shut itself down.</p> <p></p>"},{"location":"operation/user-interface/#sample-tab","title":"Sample Tab","text":"<p>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.</p> <p></p> <p>Depending on the device you choose, the page will change to reflect the needed information.</p> <p>There is a mechanism of validation of the submitted data. Please be careful to use the format given in example for each input field.</p> <p></p> <p>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.</p> <p></p> <p>Once all the fields are completed, you can go to the next tab by clicking the -&gt; arrow. This will make sure all the inserted data is valid.</p>"},{"location":"operation/user-interface/#optic-configuration","title":"Optic Configuration","text":"<p>This page allows you to control the optical setup of the acquisition.</p> <p></p> <p>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.</p> <p>Warning</p> <p>For now, the characteristics shown here are not true values (except if you use the 25mm/16mm lens couple).</p> <p>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.</p> <p>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.</p> <p>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.</p> <p>As with all the tabs, once you are satisfied with your focus and your image settings, you can click on \"Continue\".</p>"},{"location":"operation/user-interface/#fluidic-acquisition","title":"Fluidic Acquisition","text":"<p>Finally, this is where the magic happens! You will be able to chose the final parameters of your capture.</p> <p></p> <p>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.</p> <p>Warning</p> <p>Make sure the Total pumped volume is lower than the volume of your sample.</p>"},{"location":"operation/user-interface/#gallery","title":"Gallery","text":"<p>This simple page will allow you to preview and download the captured data.</p>"},{"location":"operation/user-interface/#system-monitoring","title":"System Monitoring","text":"<p>This tab allows you to monitor the physical characteristics of the machine and follow the processor load, CPU temperature, memory use and disk usage.</p> <p></p> <p>You also can find information about the software version you are using, the machine name and its camera.</p>"},{"location":"operation/user-interface/#wifi","title":"Wifi","text":"<p>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.</p> <p>Start by doing a network scan by clicking on the <code>Scan</code> 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 <code>Add the network</code> 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.</p> <p>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).</p> <p>Clicking on the button <code>Reset wifi networks</code> 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.</p> <p>Info</p> <p>For now, only WPA/WPA2 Personal security is supported; Wi-Fi networks without passwords are not supported.</p> <p>Warning</p> <p>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.</p>"},{"location":"operation/user-interface/#administration","title":"Administration","text":"<p>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.</p>"},{"location":"operation/user-interface/#hardware-settings","title":"Hardware Settings","text":"<p>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.</p>"},{"location":"reference/","title":"Technical Reference","text":"<p>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.</p>"},{"location":"reference/#key-features","title":"Key Features","text":"<p>Here are some key features of the PlanktoScope:</p> <ol> <li>Low cost: The PlanktoScope is designed to be affordable, with parts costing under $1000.</li> <li>Modular: The PlanktoScope is modular, meaning it can be easily reconfigured to meet the changing needs of users.</li> <li>Open-source: The PlanktoScope is based on open-source hardware and software, making it accessible to a wide community of engineers, researchers, and citizens.</li> <li>Versatility: The PlanktoScope is versatile, and can be used to study a variety of plankton types, including laboratory cultures and natural micro-plankton communities.</li> <li>High-throughput: The PlanktoScope is capable of high-throughput quantitative imaging, allowing users to analyze large numbers of samples quickly and efficiently.</li> <li>WiFi-enabled: The PlanktoScope can be controlled from any WiFi-enabled device, making it easy to use and deploy in a variety of settings.</li> <li>Portable: The PlanktoScope is small and portable, making it easy to transport and use in the field.</li> <li>Ease of use: The PlanktoScope is designed to be easy to use, with instructions for assembly and use available on the PlanktoScope website.</li> </ol>"},{"location":"reference/hardware/changelog/","title":"Changelog","text":"<p>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:</p>"},{"location":"reference/hardware/changelog/#v26","title":"v2.6","text":"<p>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.</p>"},{"location":"reference/hardware/changelog/#v25","title":"v2.5","text":"<p>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.</p>"},{"location":"reference/hardware/changelog/#v24","title":"v2.4","text":"<p>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.</p> <p>This version was only an internal prototype for the PlanktoScope development team.</p>"},{"location":"reference/hardware/changelog/#v23","title":"v2.3","text":"<p>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.</p> <p>This version was only an internal prototype for the PlanktoScope development team.</p>"},{"location":"reference/hardware/changelog/#v22","title":"v2.2","text":"<p>This was a prototype version of the hardware which replaced the Adafruit Stepper Motor HAT with a Waveshare Stepper Motor HAT.</p> <p>This version was only an internal prototype for the PlanktoScope development team.</p>"},{"location":"reference/hardware/changelog/#v21","title":"v2.1","text":"<p>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.</p>"},{"location":"reference/hardware/changelog/#v10","title":"v1.0","text":"<p>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.</p> <p>This design was complicated to assemble, and it suffered from unreliable electronic communication between the modules, so it was never publicly released.</p>"},{"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":"<p>Address 0x52 Configured through a kernel driver.</p>"},{"location":"reference/hardware/hat/#oled-display","title":"OLED Display","text":"<p>Address 0x3c</p>"},{"location":"reference/hardware/hat/#led-control-lm36011","title":"LED control: LM36011","text":"<p>Address 0x64 Control through specific software, current range from 0 to 376mA in normal mode, up to 1.5A in flash mode.</p>"},{"location":"reference/hardware/hat/#spi0-bus","title":"SPI0 Bus","text":""},{"location":"reference/hardware/hat/#motor-controller-0-tmc5160","title":"Motor Controller 0: TMC5160","text":"<p>Chip Enable: SPI0_CE0 Motor Enable: GPIO23</p> <p>Diagnostic output: GPIO16 for Error output GPIO20 for Stall output</p>"},{"location":"reference/hardware/hat/#motor-controller-1-tmc5160","title":"Motor Controller 1: TMC5160","text":"<p>Chip Enable: SPI0_CE1 Motor Enable: GPIO5</p> <p>Diagnostic output: GPIO16 for Error output GPIO20 for Stall output</p>"},{"location":"reference/hardware/hat/#gpio","title":"GPIO","text":""},{"location":"reference/hardware/hat/#fan-control","title":"Fan control","text":"<p>PWM1 control through GPIO13</p>"},{"location":"reference/hardware/hat/#led-output-selection","title":"LED Output selection","text":"<p>GPIO18: high for LED1, low for LED2</p>"},{"location":"reference/hardware/hat/#led-strobe","title":"LED Strobe","text":"<p>GPIO22 for pulse</p>"},{"location":"reference/hardware/hat/#i2c0-bus","title":"I2C0 Bus","text":""},{"location":"reference/hardware/hat/#eeprom-m24c32","title":"EEPROM M24C32","text":"<p>Address 0x50 For HAT information only.</p>"},{"location":"reference/hardware/product-specs/","title":"Product Specifications","text":"<p>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.</p>"},{"location":"reference/hardware/product-specs/#v26","title":"v2.6","text":"<p>Overview:</p> <ul> <li>Weight: 3.5 kg</li> <li> <p>Enclosure:</p> <ul> <li>Dimensions: 27.5 cm (length) x 12.5 cm (width) x 10.5 cm (height)</li> <li>Material: bamboo plywood</li> <li>Fabrication process: CNC milling</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#functionalities","title":"Functionalities","text":"<ul> <li>Automated image acquisition, with a motorized pump and an embedded computer</li> <li>Precise focus adjustment, with motorized linear actuators</li> <li>Continuous mixing of input sample to prevent sedimentation of heavier particles, with a USB-powered bubbler</li> <li>On-board image processing, with the embedded computer</li> <li>Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer</li> <li>Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer</li> </ul>"},{"location":"reference/hardware/product-specs/#subsystems","title":"Subsystems","text":"<p>Optics:</p> <ul> <li> <p>Imaging characteristics:</p> <ul> <li>Optical magnification: 1.33</li> <li>Field of view: 3062 \u00b5m x 2295 \u00b5m</li> <li>Optical pixel size: 0.75 \u00b5m</li> <li>Depth of field: 95 \u00b5m</li> </ul> </li> <li> <p>Internal camera: Raspberry Pi High Quality Camera</p> <ul> <li>Sensor: Sony IMX477R</li> <li>Resolution: 12.3 Megapixels (4056 x 3040 pixels)</li> </ul> </li> <li> <p>Lenses:</p> <ul> <li>Objective lens: 12 mm focal length, M12</li> <li>Tube lens: 25 mm focal length, M12</li> <li>Lens mount: M12x0.5</li> </ul> </li> <li> <p>Illumination: white LED</p> </li> </ul> <p>Fluidics:</p> <ul> <li> <p>Flow cell: capillary with rectangular cross-section</p> <ul> <li>Thickness: 300 \u00b5m</li> <li>Material: glass</li> </ul> </li> <li> <p>Internal tubing:</p> <ul> <li>Material: Tygon S3 (contains no BPA or phthalates)</li> <li>Dimensions: 1.6 mm (1/16\") inner diameter, 3.2 mm (1/8\") outer diameter</li> <li>Connectors: Luer lock</li> </ul> </li> <li> <p>Peristaltic pump</p> </li> <li>Sample intake capacity: 20 mL</li> </ul> <p>Other internal electronics:</p> <ul> <li> <p>Embedded computer: Raspberry Pi 4 Model B</p> <ul> <li>Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz</li> <li>Memory: 4 GB RAM</li> <li>Storage: 128 GB capacity (micro-SD card, UHS speed class 3)</li> </ul> </li> <li> <p>Control board: PlanktoScope HAT v1.2</p> </li> </ul> <p>External interfaces &amp; connectivity:</p> <ul> <li>Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports</li> <li>Wired networking: Gigabit Ethernet</li> <li>Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi</li> <li>Power input: 12 V DC, up to 4 A of current draw (5.1 x 2.2 mm DC barrel jack, center positive)</li> <li>Latching push-button switch to toggle power</li> </ul> <p>External AC-to-DC power adapter:</p> <ul> <li>Input: 100-240 V AC, 50-60 Hz (IEC 60320 C8 socket)</li> <li>Output: 12 V DC, up to 4 A of current output (5.1 x 2.2 mm DC barrel jack, center positive)</li> <li>Dimensions: 126 mm (length) x 52 mm (width) x 35.5 mm (height)</li> <li>Weight: 0.25 kg</li> </ul>"},{"location":"reference/hardware/product-specs/#system-performance","title":"System performance","text":"<p>Image acquisition throughput:</p> <ul> <li>Volume of sample measured: 2.1 \u00b5L per acquired image</li> <li>Volume of sample pumped: ~15 \u00b5L per acquired image</li> <li>Maximum image acquisition rate: ~60 images/min</li> </ul> <p>Samples:</p> <ul> <li> <p>Object size range:</p> <ul> <li>Minimum for taxonomy: ~20 \u00b5m diameter for round objects</li> <li>Maximum: ~200 \u00b5m diameter for round objects (larger objects will clog the flow cell)</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#v25","title":"v2.5","text":"<p>Overview:</p> <ul> <li> <p>Enclosure:</p> <ul> <li>Dimensions: 27.5 cm (length) x 12.5 cm (width) x 10.5 cm (height)</li> <li>Material: bamboo plywood</li> <li>Fabrication process: CNC milling</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#functionalities_1","title":"Functionalities","text":"<ul> <li>Automated image acquisition, with a motorized pump and an embedded computer</li> <li>Precise focus adjustment, with motorized linear actuators</li> <li>Continuous mixing of input sample to prevent sedimentation of heavier particles, with a USB-powered bubbler</li> <li>On-board image processing, with the embedded computer</li> <li>Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer</li> <li>Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer</li> </ul>"},{"location":"reference/hardware/product-specs/#subsystems_1","title":"Subsystems","text":"<p>Optics:</p> <ul> <li> <p>Imaging characteristics:</p> <ul> <li>Field of view: 3670 \u00b5m x 2675 \u00b5m</li> <li>Optical pixel size: 0.88 \u00b5m</li> </ul> </li> <li> <p>Internal camera: Raspberry Pi High Quality Camera</p> <ul> <li>Sensor: Sony IMX477R</li> <li>Resolution: 12.3 Megapixels (4056 x 3040 pixels)</li> </ul> </li> <li> <p>Lenses:</p> <ul> <li>Objective lens: 16 mm focal length, M12</li> <li>Tube lens: 25 mm focal length, M12</li> <li>Lens mount: M12x0.5</li> </ul> </li> <li> <p>Illumination: white LED</p> </li> </ul> <p>Fluidics:</p> <ul> <li> <p>Flow cell: capillary with rectangular cross-section</p> <ul> <li>Thickness: 300 \u00b5m</li> <li>Material: glass</li> </ul> </li> <li> <p>Internal tubing:</p> <ul> <li>Material: Tygon S3 (contains no BPA or phthalates)</li> <li>Dimensions: 1.6 mm (1/16\") inner diameter, 3.2 mm (1/8\") outer diameter</li> <li>Connectors: Luer lock</li> </ul> </li> <li> <p>Peristaltic pump</p> </li> <li>Sample intake capacity: 20 mL</li> </ul> <p>Other internal electronics:</p> <ul> <li> <p>Embedded computer: Raspberry Pi 4 Model B</p> <ul> <li>Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz</li> <li>Memory: 4 GB RAM</li> <li>Storage: 128 GB capacity (micro-SD card, UHS speed class 3)</li> </ul> </li> <li> <p>Control board: PlanktoScope HAT v1.2</p> </li> </ul> <p>External interfaces &amp; connectivity:</p> <ul> <li>Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports</li> <li>Wired networking: Gigabit Ethernet</li> <li>Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi</li> <li>Power input: 12 V DC, up to 4 A of current draw (5.1 x 2.2 mm DC barrel jack, center positive)</li> <li>Latching push-button switch to toggle power</li> </ul> <p>External AC-to-DC power adapter:</p> <ul> <li>Input: 100-240 V AC, 50-60 Hz (IEC 60320 C8 socket)</li> <li>Output: 12 V DC, up to 4 A of current output (5.1 x 2.2 mm DC barrel jack, center positive)</li> <li>Dimensions: 126 mm (length) x 52 mm (width) x 35.5 mm (height)</li> <li>Weight: 0.25 kg</li> </ul>"},{"location":"reference/hardware/product-specs/#system-performance_1","title":"System performance","text":"<p>Image acquisition throughput:</p> <ul> <li>Volume of sample pumped: ~15 \u00b5L per acquired image</li> <li>Maximum image acquisition rate: ~60 images/min</li> </ul> <p>Samples:</p> <ul> <li> <p>Object size range:</p> <ul> <li>Maximum: ~200 \u00b5m diameter for round objects (larger objects will clog the flow cell)</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#v21","title":"v2.1","text":"<p>Overview:</p> <ul> <li> <p>Enclosure:</p> <ul> <li>Dimensions: ~32 cm (length) x ~5.5 cm (width) x ~15 cm (height)</li> <li>Material: acrylic, plywood, or fiberboard</li> <li>Fabrication process: laser cutting</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#functionalities_2","title":"Functionalities","text":"<ul> <li>Automated image acquisition, with a motorized pump and an embedded computer</li> <li>Precise focus adjustment, with motorized linear actuators</li> <li>On-board image processing, with the embedded computer</li> <li>Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer</li> <li>Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer</li> </ul>"},{"location":"reference/hardware/product-specs/#subsystems_2","title":"Subsystems","text":"<p>Optics:</p> <ul> <li> <p>Imaging characteristics:</p> <ul> <li>Field of view: 2300 \u00b5m x 1730 \u00b5m</li> <li>Optical pixel size: 0.75 \u00b5m</li> </ul> </li> <li> <p>Internal camera: Raspberry Pi Camera Module 2</p> <ul> <li>Sensor: Sony IMX219</li> <li>Resolution: 8 Megapixels (3280 x 2464 pixels)</li> </ul> </li> <li> <p>Lenses:</p> <ul> <li>Objective lens: 12 mm focal length, M12</li> <li>Tube lens: 25 mm focal length, M12</li> <li>Lens mount: M12x0.5</li> </ul> </li> <li> <p>Illumination: white LED</p> </li> </ul> <p>Fluidics:</p> <ul> <li> <p>Flow cell: ibidi \u00b5-Slide I Luer channel slide</p> <ul> <li>Thickness: 200 \u00b5m, 400 \u00b5m, 600 \u00b5m, or 800 \u00b5m</li> <li>Material: Plastic (no surface modification)</li> </ul> </li> <li> <p>Internal tubing:</p> <ul> <li>Material: Tygon S3 (contains no BPA or phthalates)</li> <li>Dimensions: 1.6 mm (1/16\") inner diameter, 3.2 mm (1/8\") outer diameter</li> <li>Connectors: Luer lock</li> </ul> </li> <li> <p>Peristaltic pump</p> </li> <li>Sample intake capacity: 20 mL</li> </ul> <p>Other internal electronics:</p> <ul> <li> <p>Embedded computer: Raspberry Pi 4 Model B</p> <ul> <li>Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz</li> <li>Memory: 4 GB RAM</li> </ul> </li> <li> <p>Control boards:</p> <ul> <li> <p>Adafruit Stepper Motor HAT</p> <ul> <li>Input voltage: 5 - 12 V DC</li> <li>Output voltage: 4.5 - 13.5 V DC</li> <li>Output current: up to 1.2 A continuous, 3 A peak</li> </ul> </li> <li> <p>Adafruit Ultimate GPS HAT</p> </li> </ul> </li> </ul> <p>External interfaces &amp; connectivity:</p> <ul> <li>Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports, 2 micro-HDMI ports</li> <li>Wired networking: Gigabit Ethernet</li> <li>Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi</li> <li>Power input for embedded computer: 5 V DC, up to 3 A of current draw (USB-C)</li> <li>Power input for motors: 5 - 12 V DC, depending on pump motor (5.1 x 2.2 mm DC barrel jack, center positive)</li> </ul>"},{"location":"reference/software/changelog/","title":"Changelog","text":"<p>All notable changes to the PlanktoScope's software will be documented in this file.</p> <p>The format is based on Keep a Changelog, and this project uses Calendar Versioning with a <code>YYYY.minor.patch</code> scheme for all releases after <code>v2.3.0</code>. All dates in this file are given in the UTC time zone.</p>"},{"location":"reference/software/changelog/#v202400-beta2-2024-09-19","title":"v2024.0.0-beta.2 - 2024-09-19","text":""},{"location":"reference/software/changelog/#added","title":"Added","text":"<ul> <li>(System: administration) Added a Forklift-deployed script <code>/usr/libexec/prepare-custom-image</code> (which must be invoked with <code>sudo</code>) 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.</li> </ul>"},{"location":"reference/software/changelog/#changed","title":"Changed","text":"<ul> <li>(Application: GUI) Changed the default ISO value from 100 to 150.</li> </ul>"},{"location":"reference/software/changelog/#fixed","title":"Fixed","text":"<ul> <li>(Application: backend) Changed the hardware controller's libcamera-based camera controller to initialize its default image gain based on camera sensor type in order to match the GUI's default ISO value of 150, instead of initializing default image gain to 1.0 regardless of camera sensor type.</li> <li>(Breaking change; Application: backend) Changed the segmenter to include the acquisition ID in the filename of the metadata TSV file included with the EcoTaxa export ZIP archive; this is necessary to allow efficient bulk importing of such ZIP archives into EcoTaxa, which was previously prevented by the use of the same <code>ecotaxa_export.tsv</code> filename for all metadata TSV files.</li> <li>(Application: GUI) The Grafana server's CPU allowance should now be limited to one core, in an attempt to prevent it from starving other programs of CPU time shortly after booting up under certain situations.</li> </ul>"},{"location":"reference/software/changelog/#v202400-beta1-2024-06-24","title":"v2024.0.0-beta.1 - 2024-06-24","text":""},{"location":"reference/software/changelog/#added_1","title":"Added","text":"<ul> <li>(Application: GUI) On the <code>planktoscopehat</code> 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.</li> <li>(Release) A <code>fairscope-latest</code> SD card image is now provided which is identical to the <code>planktoscopehat</code> 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).</li> <li>(System: administration) The Forklift pallet provided by default as the SD card image is now named (and pinned as) the <code>factory-reset</code> staged pallet bundle.</li> <li>(System: networking) The <code>planktoscope.local</code> 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 <code>pkscope.local</code> or the machine-specific mDNS name (of format <code>pkscope-{machine-name}.local</code>) instead of <code>planktoscope.local</code>.</li> </ul>"},{"location":"reference/software/changelog/#changed_1","title":"Changed","text":"<ul> <li>(Breaking change; Application: GUI) The default settings configuration file for the <code>planktoscopehat</code> 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.</li> <li>(Release) SD card images are now released with xz compression (as <code>.img.xz</code> files) rather than gzip compression (as <code>.img.gz</code> files).</li> </ul>"},{"location":"reference/software/changelog/#removed","title":"Removed","text":"<ul> <li>(Application: GUI) On the <code>planktoscopehat</code> SD card image, a hardware version is no longer set in the default <code>config.json</code> 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.</li> <li>(Application: GUI) The Node-RED dashboard's Administration page's \"Dashboard Errors\" panel has been removed, because it doesn't show any useful messages.</li> <li>(System) <code>gcc</code> has been removed from the SD card image, to help reduce SD card image size.</li> </ul>"},{"location":"reference/software/changelog/#fixed_1","title":"Fixed","text":"<ul> <li>(Application: GUI) The flowcell setting from the <code>config.json</code> file should now be properly displayed as the default selection on the Node-RED dashboard's \"Fluidic Acquisition\" page.</li> </ul>"},{"location":"reference/software/changelog/#v202400-beta0-2024-06-07","title":"v2024.0.0-beta.0 - 2024-06-07","text":""},{"location":"reference/software/changelog/#changed_2","title":"Changed","text":"<ul> <li>(Application: GUI) The ISO selector in the \"Optic Configuration\" page has been changed from a button group to a slider (with an increment of 50), to enable somewhat finer adjustment of the ISO setting.</li> <li>(Breaking change; System) The official SD card images of PlanktoScope OS are now based on the 64-bit (arm64) version of the 2024-03-12 build of Raspberry Pi OS 11 (bullseye), instead of the 32-bit (armhf) version of the 2023-05-03 build of Raspberry Pi OS 11 (bullseye). This increases the performance of the Python segmenter, potentially by a factor of 2. This is expected to break compatibility with the raspimjpeg-based imaging module. If you need a 32-bit version of PlanktoScope OS, you will need to run the OS setup scripts following the PlanktoScope project's documentation's \"Non-standard installation\" guide for software setup.</li> <li>(System: administration) The <code>machine-name</code> 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) &amp; removeability/replaceability (by switching to a different pallet which provides a different version of - or does not provide - the <code>machine-name</code>).</li> </ul>"},{"location":"reference/software/changelog/#deprecated","title":"Deprecated","text":"<ul> <li>(System: networking)</li> <li>(System) 32-bit versions of PlanktoScope OS (which can be set up on a 32-bit version of Raspberry Pi OS using the OS setup scripts) are no longer officially supported by the project, but they will continue to work for v2024.0.0 of PlanktoScope OS.</li> </ul>"},{"location":"reference/software/changelog/#removed_1","title":"Removed","text":"<ul> <li>(Application: GUI) The landing page's links to Portainer have been removed, as part of the deprecation in v2024.0.0-alpha.2 of the inclusion of Portainer by default in the PlanktoScope OS's SD card images.</li> </ul>"},{"location":"reference/software/changelog/#fixed_2","title":"Fixed","text":"<ul> <li>(Application: GUI) The landing page's links to offline PDF copies of the protocols.io protocols for PlanktoScope operation are no longer broken.</li> <li>(Application: GUI) The maximum allowed value in the ISO selector in the \"Optic Configuration\" page has been reduced from 800 to 650, but only for the planktoscopehat version of the Node-RED dashboard; maximum allowed value is still 800 in the adafruithat version of the Node-RED dashboard. This change is because v2024.0.0-alpha.2's change to the scaling factor for converting between ISO settings and camera gains in the picamera2 library has meant that ISO values above 650 were converted to image gain values which were silently rejected for the Raspberry Pi HQ Camera used PlanktoScopes with hardware version at or above v2.3; this, this change prevents users from setting ISO values which would be silently rejected by the Python hardware controller.</li> </ul>"},{"location":"reference/software/changelog/#v202400-alpha2-2024-04-25","title":"v2024.0.0-alpha.2 - 2024-04-25","text":""},{"location":"reference/software/changelog/#added_2","title":"Added","text":"<ul> <li>(System: administration) The hostname can now be customized by modifying the hostname template (with string interpolation for the machine name) in <code>/etc/hostname-template</code>.</li> <li>(System: administration) The Cockpit configuration can now be customized by adding configuration snippets as drop-in files in <code>/etc/cockpit/cockpit.conf.d</code>, and adding origins to allow in <code>/etc/cockpit/origins.d</code>, and adding templated origins (with string interpolation for the machine name, the hostname, and the custom domain) to allow in <code>/etc/cockpit/origins-templates.d</code>.</li> <li>(System: administration) The dnsmasq configuration can now be customized by adding templated drop-in configuration files (with string interpolation for the machine name, the hostname, and the custom domain) in <code>/etc/dnsmasq-templates.d</code>, and by modifying the custom domain (which defaults to <code>pkscope</code>) in <code>/etc/custom-domain</code>.</li> <li>(System: administration) The hostapd configuration can now be customized by adding configuration snippets as drop-in files in <code>/etc/hostapd/hostapd.conf.d</code>, and adding templated drop-in files (with string interpolation for the machine name, the hostname, and the custom domain) in <code>/etc/hostapd/hostapd.conf-templates.d</code>.</li> <li>(System: administration) The hosts file can now be customized can now be customized by adding snippets as drop-in files at <code>/etc/hosts.d</code>, and and adding templated snippets (with string interpolation for the machine name, the hostname, and the custom domain) in <code>/etc/hosts-templates.d</code>.</li> <li>(System: administration) SSH host keys for the SSH server are now automatically generated (if deleted or otherwise missing) during every boot, not just during the first boot.</li> </ul>"},{"location":"reference/software/changelog/#changed_3","title":"Changed","text":"<ul> <li>(Breaking change; Application: backend) Previously, the segmenter's default behavior was to subtract consecutive masks to try to mitigate image-processing issues with objects which get stuck to the flowcell during imaging. However, when different objects occupied the same space in consecutive frames, the subtraction behavior would subtract one object's mask from the mask of the other object in the following frame, which would produce clearly incorrect masks. This behavior is no longer enabled by default; in order to re-enable it, you should enable the <code>pipeline-subtract-consecutive-masks</code> feature flag in the <code>apps/ps/backend/proc-segmenter</code> package deployment of the local Forklift pallet and re-apply the pallet.</li> <li>(Application: backend, GUI) The image quality of frames in the camera preview stream is increased, and frames also have greater width and height.</li> <li>(Breaking change; Application: GUI) The default settings configuration file for the <code>planktoscopehat</code> SD card image is now for the v2.6 PlanktoScope hardware; previously, it was still for the v2.5 hardware.</li> <li>(Breaking change; System: administration) The minimum supported Forklift version for Forklift pallets has increased from v0.4.0 to v0.7.0, due to new integration between Forklift and the filesystem.</li> <li>(System: administration) Forklift has been upgraded to v0.7.0, so that pallets are staged before being applied (and with automatic fallback to the last successfully-applied staged pallet), and so that systemd services, <code>/etc</code> config files, and some scripts in <code>/usr</code> are now managed by Forklift.</li> <li>(System: administration) <code>/etc</code> is now a overlay filesystem with all manually-edited files saved at <code>/var/lib/overlays/overrides/etc</code>.</li> <li>(System: administration) <code>/usr</code> is now a overlay filesystem with all manually-edited files saved at <code>/var/lib/overlays/overrides/usr</code>.</li> </ul>"},{"location":"reference/software/changelog/#deprecated_1","title":"Deprecated","text":"<ul> <li>(System: administration, troubleshooting; Application: GUI) Portainer will no longer be installed/provided by default after v2024.0.0. This is because it requires inclusion of a relatively large Docker container image in the PlanktoScope OS's SD card image (which is constrained to be up to 2 GB in size so that it can be attached as an upload to GitHub Releases), and because it has an annoying first-time user experience (i.e. that a password must be set within a few minutes of boot, or else the Portainer container must be restarted), and because Dozzle already provides all the basic functionalities needed by most users, and because Portainer has never actually been used for troubleshooting within the past year of the project, and because Portainer has a nontrivial impact on the sizes of the PlanktoScope OS SD card images (which are limited to 2 GB).</li> <li>(System: administration; Application: GUI) The \"USB backup\" functionality of the Node-RED dashboard will be removed in v2024.1.0 (the next release after v2024.0.0). Instead, you should use the datasets file browser for backing up and deleting dataset files on your PlanktoScope.</li> <li>(Application: backend) The raspimjpeg-based imaging module in the Python hardware controller has not yet been deleted so that you can change the Python hardware controller code to switch back from the new picamera2-based imaging module if picamera2 ends up causing big problems for you. However, we are deprecating the raspimjpeg-based imaging module, and we will fully delete it in a future release (perhaps v2024.1.0, or perhaps later).</li> </ul>"},{"location":"reference/software/changelog/#fixed_3","title":"Fixed","text":"<ul> <li>(Application: GUI) The white balance input validation, which previously only allowed gains between 1.0 and 8.0, now allows gains in the full range allowed by the camera (i.e. between 0.0 and 32.0).</li> <li>(Application: backend, GUI) The incorrect scaling factor for converting between ISO settings (in the Node-RED dashboard) and image gains in the new picamera2-based imager is fixed.</li> <li>(System: networking) Some uncommon edge cases for packet forwarding (e.g. accessing a one of the PlanktoScope's static IP addresses on a network interface not associated with that static IP address) should work now.</li> </ul>"},{"location":"reference/software/changelog/#v202400-alpha1-2024-03-26","title":"v2024.0.0-alpha.1 - 2024-03-26","text":""},{"location":"reference/software/changelog/#changed_4","title":"Changed","text":"<ul> <li>(Breaking change; System: setup) The word <code>pscopehat</code> has been replaced with <code>planktoscopehat</code> everywhere. This means that any distro setup scripts/commands you previously used with <code>pscopehat</code> should be changed.</li> <li>(Breaking change; Application: hardware controller) The hardware controller now uses <code>picamera2</code> instead of <code>raspimjpeg</code> 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.</li> </ul>"},{"location":"reference/software/changelog/#deprecated_2","title":"Deprecated","text":"<ul> <li>(Application: GUI) The current Node-RED dashboard (both the version for the Adafruit HAT and the version for the PlanktoScope HAT) is transitioning to maintenance mode: no new features will be added, and any bugs will be only be fixed if someone volunteers to fix them. The current Node-RED dashboard will be completely replaced by a fully-rewritten Node-RED dashboard, though there is no timeline for completion of that new dashboard. Currently, our plan for deprecating and eventually removing the current Node-RED dashboard is as follows: maintenance mode (no new features, only some bugfixes), then deprecation (no maintenance; not enabled by default, but still installed), then removal (not installed by default, but anyone is free to install it and see if it still works); deprecation will not occur before the rewritten Node-RED dashboard is stable for general-purpose usage. If you have concerns, please share your feedback on GitHub, in an email, or on the PlanktoScope Slack.</li> </ul>"},{"location":"reference/software/changelog/#fixed_4","title":"Fixed","text":"<ul> <li>(Breaking change; Application: backend) The default hardware configuration file for the <code>planktoscopehat</code> 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.</li> <li>(Application: hardware controller) The camera no longer overexposes captured images compared to the camera preview stream, and it no longer produces camera timeout errors.</li> <li>(Application: backend) The segmenter should no longer have file permissions errors when trying to read or write files in directories created by Docker or by the Python hardware controller.</li> </ul>"},{"location":"reference/software/changelog/#v202400-alpha0-2024-02-06","title":"v2024.0.0-alpha.0 - 2024-02-06","text":""},{"location":"reference/software/changelog/#added_3","title":"Added","text":"<ul> <li>(System: networking) Added support to share internet access and browser application access over additional network interfaces: a second Wi-Fi module, an additional Ethernet adapter, and a USB networking interface (made by plugging a phone to the Raspberry Pi in USB tethering mode).</li> <li>(Application: GUI) The \"System Monitoring\" page now shows the current system time on the Raspberry Pi and the current time in the web browser of the client device.</li> <li>(Application: GUI) The \"System Monitoring\" page now detects when the Raspberry Pi's system time is very different from the web browser's time, and shows a message and a buttom to change the Raspberry Pi's system time to match the web browser's time.</li> <li>(Application: GUI) The \"System Monitoring\" page's system metrics panel is now collapsible, and it now includes an expandable \"Detailed History\" subsection to view additional information.</li> <li>(System: administration) Added Dozzle as a viewer for Docker container logs.</li> <li>(System: networking) Added <code>lynx</code> as an alternative terminal web browser to <code>w3m</code> for trying to work through captive portals on the Cockpit terminal.</li> <li>(System: administration) Added Prometheus as a metrics collection &amp; storage system.</li> <li>(System: administration) Added Grafana as a metrics visualization &amp; alerting system.</li> </ul>"},{"location":"reference/software/changelog/#changed_5","title":"Changed","text":"<ul> <li>(Application: GUI) The \"System Monitoring\" page now uses a Grafana dashboard to display metrics.</li> <li>(Application: GUI) The \"Fluidic Acquisition\" page now uses a numeric text input instead of a slider for adjusting the \"Pumped volume\" setting, to make it easier to change the setting to a different exact value.</li> <li>(Application: GUI) On the \"Sample\" page, the input fields of the \"Sample Location\"/\"Net Throw Location\"/\"Net Retrieval Location\"/\"Culture Date and Time\" panels no longer get cleared when pressing the \"Validate\" button.</li> <li>(System: administration) Docker commands can now be run without <code>sudo</code>.</li> <li>(System: security) <code>ufw</code> has been replaced with <code>firewalld</code>. However, <code>firewalld</code> has not yet been properly configured.</li> <li>(System) The PlanktoScope's machine name is now saved to <code>/var/lib/planktoscope/machine-name</code> instead of <code>/home/pi/.local/etc/machine-name</code>, and it's now saved without a trailing newline.</li> </ul>"},{"location":"reference/software/changelog/#removed_2","title":"Removed","text":"<ul> <li>(Application: GUI) The \"System Monitoring\" page no longer displays a gauge for the CPU usage, since that information does not need to be monitored to ensure system stability &amp; usability. Instead, a CPU usage history graph can be found in the new \"Detailed History\" subsection.</li> <li>(System: administration) Removed <code>cockpit-storaged</code>, which was not useful enough to justify the number (and size of) unneeded dependencies it pulled in for the PlanktoScope software SD card image.</li> <li>(System: setup) Removed some unnecessary <code>apt-get update</code> commands for a very minor speed-up in the distro setup process.</li> </ul>"},{"location":"reference/software/changelog/#fixed_5","title":"Fixed","text":"<ul> <li>(Application: GUI) The \"Filtered volume\" field (on the \"Sample\" page) is now saved as the <code>sample_total_volume</code> metadata field for all sample types, not just horizontal Plankton tows (corresponding to the \"Plankton net\", \"High Speed Net\", and \"Tara decknet\" sample types).</li> <li>(System) Boot time has been made faster by approximately 1 minute.</li> <li>(Application: GUI) On Mozilla Firefox, the embedded file browser in the Node-RED dashboard's \"Gallery\" page should now consistently load with the correct height, instead of sometimes loading with an absurdly small height.</li> <li>(System: networking) The Raspberry Pi now correctly detects a phone connected in USB tethering mode to share internet access regardless of when the phone was connected, instead of only detecting that phone if USB tethering mode was enabled early in startup (specifically, before the <code>dhcpcd</code> service had started).</li> <li>(System: networking) Functionality for automatically updating the <code>/etc/hosts</code> file and the hostname based on the machine name has now been split into two separate system services, <code>planktoscope-org.update-hosts-machine-name.service</code> and <code>planktoscope-org.update-hostname-machine-name.service</code>.</li> </ul>"},{"location":"reference/software/changelog/#v202390-2023-12-30","title":"v2023.9.0 - 2023-12-30","text":"<p>(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)</p>"},{"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":"<ul> <li>(Application) A hardware configuration file for PlanktoScope hardware v2.6, which was previously missing, has been added. It is now the default hardware configuration file for <code>pscopehat</code> builds of the PlanktoScope distro.</li> </ul>"},{"location":"reference/software/changelog/#changed_6","title":"Changed","text":"<ul> <li>(System: infrastructure) Forklift has been upgraded from v0.3.1 to v0.4.0, which includes breaking changes to the schema of Forklift repositories and pallets.</li> </ul>"},{"location":"reference/software/changelog/#removed_3","title":"Removed","text":"<ul> <li>(Application: documentation) The offline documentation included on the PlanktoScope now omits the hardware setup guides.</li> </ul>"},{"location":"reference/software/changelog/#fixed_6","title":"Fixed","text":"<ul> <li>(Application: GUI) The white balance gains are now only validated and sent to the backend after the user changes focus away from the input field, instead of being validated and sent 300 ms after the user pauses while editing the value in the input field. This prevents the input validation from being run while the user is still editing the value.</li> <li>(Application) The default brightness of the illumination LED for the pscopehat version of the backend (for the custom PlanktoScope HAT) has been reduced; this a temporary workaround to a bug with raspimjpeg where saved images are overexposed even on the default brightness settings with minimum shutter speed and ISO, despite the brightness of raspimjpeg's camera preview looking reasonable (see https://github.com/PlanktoScope/PlanktoScope/issues/259 for details).</li> <li>(Application: GUI) In the \"Sample\" page, when the minimal &amp; maximal fraction size fields and min &amp; max sampling depth fields are both displayed simultaneously, now the adafruithat version of the Node-RED dashboard shows the fraction size fields on one row and the sampling depth fields on another row, rather than showing them in adjacent columns. This way, the adafruithat version of the Node-RED dashboard now matches the layout in the pscopehat version of the Node-RED dashboard.</li> <li>(Application: GUI) The \"System Monitoring\" page now correctly displays the PlanktoScope hardware version in the \"Information\" panel's \"Instrument Type\" field.</li> <li>(Application: GUI) The \"System Monitoring\" and \"Fluidic Acquisition\" pages now display a software version string which is either a tagged version (e.g. <code>v2023.9.0-beta.1</code>) when the version is tagged, or else a pseudoversion (e.g. <code>v2023.9.0-beta.1-36-gf276e84</code>) 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 <code>acq_software</code> metadata field.</li> <li>(Application: GUI) The <code>process_commit</code> 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.</li> <li>(Application: GUI) The <code>process_source</code> 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.</li> <li>(System: infrastructure) The SD card setup scripts now apply the Forklift pallet in order to create the Docker Compose services and resources ahead-of-time (rather than waiting for the first boot to do that work), so that the first boot of the SD card image will be much faster.</li> <li>(System: infrastructure) The distro setup scripts now work even if they are run from a repository downloaded to some path other than <code>/home/pi/PlanktoScope</code>.</li> <li>(Application: GUI) The landing page now links to the new project documentation site for online documentation, instead of the old project documentation site.</li> </ul>"},{"location":"reference/software/changelog/#v202390-beta1-2023-09-14","title":"v2023.9.0-beta.1 - 2023-09-14","text":""},{"location":"reference/software/changelog/#added_5","title":"Added","text":"<ul> <li>(System: networking) The PlanktoScope can now also be accessed using the domain name <code>pkscope.local</code> from any web browser where <code>planktoscope.local</code> 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).</li> <li>(System: administration, networking) In operating system's networking configuration files which have lines which are automatically generated based on the PlanktoScope's machine name, those lines now have accompanying code comments which explain the correct files to edit in order to make changes which will persist across device reboots.</li> <li>(System: administration, networking) You can now check the machine name at <code>/home/pi/.local/etc/machine-name</code>. It's updated when the PlanktoScope boots.</li> <li>(System: administration; Application: GUI) The Node-RED dashboard now provides some context on the \"Administration\" page for how to access the logs linked to from that page, and which links to use for providing logs on GitHub or Slack.</li> <li>(System: administration; Application: GUI) The Node-RED dashboard now provides some additional information about the side-effects of selecting a hardware version on the \"Hardware Settings\" page, specifically that the white balance settings will be overwritten.</li> </ul>"},{"location":"reference/software/changelog/#changed_7","title":"Changed","text":"<ul> <li>(Major user-facing change; System: networking) The top-level domain for domain names of format <code>home.planktoscope</code> and <code>{machine-name}.planktoscope</code> (e.g. http://metal-slope-23501.planktoscope) has been changed from <code>planktoscope</code> to <code>pkscope</code>, so that the domain names are now of format <code>home.pkscope</code> and <code>{machine-name}.pkscope</code>. Similarly, the machine-specific mDNS name has been changed from format <code>planktoscope-{machine-name}.local</code> to <code>pkscope-{machine-name}.local</code>.</li> <li>(User-facing change; System: networking) The SSIDs of wifi hotspots generated by the PlanktoScope has been changed from the format <code>PlanktoScope {machine-name}</code> to the format <code>pkscope-{machine-name}</code>. This makes it easier to determine the machine-specific mDNS URL: just add <code>.local</code>, to get <code>pkscope-{machine-name}.local</code> (e.g. <code>pkscope-metal-slope-23501.local</code>).</li> <li>(User-facing change; Application: backend) The Python backend now uses the new machine naming scheme everywhere.</li> <li>(System: networking) The default hostname and SSID (used only in certain unexpected situations when a machine name cannot be determined) have both been shortened from <code>planktoscope</code> to <code>pkscope</code>.</li> <li>(System: networking) The SSID format is now specified in <code>/home/pi/.local/etc/hostapd/ssid.snippet</code>, instead of <code>/home/pi/.local/bin/update-ssid-machine-name.sh</code>.</li> </ul>"},{"location":"reference/software/changelog/#deprecated_3","title":"Deprecated","text":"<ul> <li>(System: networking) The <code>planktoscope.local</code> 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 <code>pkscope.local</code> or the machine-specific mDNS name (of format <code>pkscope-{machine-name}.local</code>) instead.</li> <li>(Application: backend) The Python backend's logs still print machine names in the old naming scheme, to help instrument operators with the naming scheme transition (so that they can identify how each machine was renamed). The machine names in this old naming scheme will be removed in a future release - probably the next release.</li> </ul>"},{"location":"reference/software/changelog/#removed_4","title":"Removed","text":"<ul> <li>(System: administration, networking) The auto-generated <code>/home/pi/.local/etc/cockpit/origins</code> 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.</li> <li>(System: administration, networking) The default <code>/home/pi/.local/etc/hosts</code> file has been removed from the setup files. Instead, it is now automatically generated by the setup scripts.</li> </ul>"},{"location":"reference/software/changelog/#fixed_7","title":"Fixed","text":"<ul> <li>(System: networking) The PlanktoScope no longer generates any machine names or SSIDs which are so long that they prevent the wifi hotspot network from being brought up.</li> <li>(Application: backend) The segmenter no longer crashes and fails to respond immediately after attempting to start segmentation.</li> <li>(Application: preset settings, GUI) The default setting for the pscopehat version of the Node-RED dashboard is now the 300 um capillary, since that version of the hardware is meant to be used with 300 um capillaries. Previously, the default was the 200 um ibidi slide.</li> <li>(Application: preset settings) All default settings for all hardware versions now include a default pixel size calibration of 0.75 um/pixel. Previously, the default settings for v2.1 and v2.3 were missing this setting, which would cause the segmenter to crash when processing datasets generated on PlanktoScopes using the v2.1 or v2.3 hardware settings.</li> <li>(Application: preset settings, GUI) The Node-RED dashboard now correctly lists the selected hardware version in the \"Hardware Settings\" page's \"Hardware Version\" dropdown menu upon startup.</li> <li>(Application: GUI) The Node-RED dashboard now (hopefully) is able to determine the camera type from the Python backend.</li> </ul>"},{"location":"reference/software/changelog/#v202390-beta0-2023-09-02","title":"v2023.9.0-beta.0 - 2023-09-02","text":""},{"location":"reference/software/changelog/#added_6","title":"Added","text":"<ul> <li>(System: networking) Traffic is now routed with Network Address Translation between the Ethernet and Wi-Fi network interfaces. This means that if the PlanktoScope has internet access through an Ethernet connection, it will share that internet access to devices connected to its Wi-Fi hotspot; and if the PlanktoScope has internet access through a Wi-Fi connection, it will share that internet access to devices connected to its Ethernet port.</li> <li>(System: networking) Now both <code>192.168.4.1</code> and <code>192.168.5.1</code> 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.</li> <li>(System: networking) Previously the PlanktoScope could be connected to from <code>192.168.4.1</code> (over Wi-Fi, when running in wireless AP mode), <code>192.168.5.1</code> (over Ethernet), and <code>planktoscope.local</code> (over Wi-Fi or Ethernet, from a client device with mDNS support); this meant that Android devices could only connect to the PlanktoScope at <code>192.168.4.1</code>, as they lack mDNS support. Now, client devices - even those without mDNS support - can connect to the PlanktoScope at <code>home.planktoscope</code>, and/or URLs like <code>clear-field-33719.planktoscope</code> and <code>planktoscope-clear-field-33719.local</code> (where <code>clear-field-33719</code> 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\").</li> <li>(Application: Documentation) An offline copy of the PlanktoScope project documentation is now provided at URL path <code>/ps/docs/</code> (so e.g. it's accessible at http://home.planktoscope/ps/docs/)</li> <li>(Application: GUI) The Node-RED dashboard's \"Hardware Settings\" page now includes a drop-down menu item to select \"PlanktoScope v2.5\" as an allowed hardware version.</li> <li>(Application: GUI, administration) The Node-RED dashboard now generates a notification whenever it restarts the Python backend. This provides visibility for the user when changing the hardware version triggers a restart of the Python backend.</li> <li>(System: administration, troubleshooting, GUI) A Cockpit system administration dashboard is now installed and made accessible at URL path <code>/admin/cockpit/</code> (so e.g. it's accessible at http://home.planktoscope/admin/cockpit/).</li> <li>(System: administration, troubleshooting, GUI) A filebrowser instance, allowing you to manage and edit files anywhere in the Raspberry Pi's SD card, is now installed and made accessible at URL path <code>/admin/fs/</code> (so e.g. it's accessible at http://home.planktoscope/admin/fs/)</li> <li>(System: administration, troubleshooting, GUI) A Portainer administration dashboard for Docker is now installed and made accessible at URL path <code>/admin/portainer/</code> (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.</li> <li>(System: administration) Docker is now installed. We are using it to deliver various applications in a way that will eventually enable safe and easy upgrades.</li> <li>(System: administration, troubleshooting) w3m is now installed, enabling terminal-based interaction with some Wi-Fi network captive portals to obtain internet access on the PlanktoScope. For captive portals which require Javascript, we recommend instead using browsh as a Docker container; we don't provide browsh in the default SD card image because it adds ~250 MB of dependencies to the image.</li> </ul>"},{"location":"reference/software/changelog/#changed_8","title":"Changed","text":"<ul> <li>(User-facing change; System: administration) The file browser on port 80 for viewing datasets has now been moved to path <code>/ps/data/browse/</code> (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.</li> <li>(User-facing change; Application: GUI) If you navigate the PlanktoScope in your web browser on port 80 (or without specifying a port) (e.g. with URLs like <code>http://home.planktoscope</code> or <code>http://planktoscope.local</code>), 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.</li> <li>(User-facing change; Application: GUI) Previously, the Node-RED dashboard was accessed on the path <code>/ui</code> on port 1880, e.g. with URLs like <code>http://planktoscope.local:1880/ui</code> or <code>http://192.168.4.1:1880/ui</code>; now, it should be accessed via a link on the landing page.</li> <li>(User-facing change; System: networking) Previously, PlanktoScope machine names were generated as gibberish words like \"Babaxio-Detuiau\", and the machine names were used as the names of the private Wi-Fi networks generated by the PlanktoScope in wireless AP mode. However, the machine names created by this naming scheme were often difficult to pronounce, remember, and type for people in various languages, and the naming scheme sometimes generated names which sounded like curses or insults in some languages. Now, PlanktoScope machine names are generated as a combination of two words and a number up to five digits long; words are selected from pre-built lists in a language which can be chosen based on localization settings. Currently, word lists are only provided in US English, resulting in names like \"metal-slope-23501\", \"conscious-pocket-1684\", and \"plant-range-10581\"; however, word lists can be added for other languages in the future, and a user interface will eventually be provided for changing localization settings.</li> <li>(User-facing change; Application: GUI) Selecting a hardware version on the \"Hardware Settings\" page of the Node-RED dashboard now causes a default hardware preset for that version to overwrite the entire <code>hardware.json</code> file, and the Node-RED dashboard will reload the settings; this prevents the <code>hardware.json</code> 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.</li> <li>(User-facing change; Application: GUI, troubleshooting) Previously, the Node-RED dashboard's \"Administration\" page merged log entries from every component of the Python backend and the Node-RED dashboard. Now, the Node-RED dashboard instead displays links to separate Cockpit log-viewing pages (which by default are accessed with username <code>pi</code> and password <code>copepode</code>) 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.</li> <li>(User-facing change; System: GUI) Previously, the Node-RED flow editor was accessed directly on port 1880, e.g. with URLs like <code>http://planktoscope.local:1880</code> or <code>http://192.168.4.1:1880</code>; now, it should be accessed via a link on the landing page .</li> <li>(System: networking) Previously, PlanktoScopes all had <code>planktoscope</code> as their hostname. Now, the hostname is of the format <code>planktoscope-&lt;machine-name&gt;</code>, e.g. <code>planktoscope-metal-slope-23501</code> or <code>planktoscope-plant-range-10581</code>.</li> <li>(Likely user-facing change; System: networking) The default Wi-Fi country has been changed from <code>FR</code> (France) to <code>US</code> (USA).</li> <li>(Likely user-facing change; System: networking) Previously the autohotspot script considered receiving an IP address assignment from the connected Wi-Fi network as the criterion for determining whether the Wi-Fi connection was successful. Now the autohotspot script tries to ping <code>google.com</code> 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.</li> <li>(System: networking, troubleshooting) Previously the autohotspot script would print the MAC addresses and SSIDs of all Wi-Fi networks found by scanning. Now it only prints the SSIDs of Wi-Fi networks found by scanning and avoids printing duplicate SSIDs, for more concise service logs.</li> <li>(System: networking, troubleshooting) When the autohotspot script fails to connect to google.com, it will also print some diagnostic information by attempting to ping <code>1.1.1.1</code> (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.</li> <li>(System: networking) Previously the autohotspot script was run every 5 minutes to scan for available Wi-Fi networks. Now it is run every 2 minutes, so that the PlanktoScope will connect more quickly to a Wi-Fi network which has just appeared.</li> <li>(System: networking) Previously the autohotspot script and the dhcpcd service would both try to manage when to start and stop the dnsmasq service. Now, the dnsmasq service always runs. This change was made to simplify the network configuration so that it would be easier to understand, troubleshoot, and maintain.</li> <li>(System: networking) Previously the autohotspot script would use a mixture of dhcpcd and wpa_supplicant as entrypoints for Wi-Fi network connection management. Now, dhcpcd is used to manage wpa_supplicant, and the autohotspot script only interacts with dhcpcd. This change was made to simplify the network configuration so that it would be easier to understand, troubleshoot, and maintain. Note that, in the future, wpa_supplicant and dhcpcd may be replaced with NetworkManager.</li> <li>(System: networking) The autohotspot script has undergone a major refactoring, which may accidentally introduce bugs.</li> <li>(Application: Backend, GUI) The Node-RED dashboard no longer supervises the Python backend; instead, it delegates that work to systemd.</li> <li>(Application: Backend) Log files from the Python backend are no longer saved to <code>/home/pi</code>, but instead to subdirectories for the backend components under <code>/home/pi/device-backend-logs</code>. 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.</li> <li>(System) The <code>/usr/bin/stepper-disable</code> and <code>/usr/bin/autohotspotN</code> scripts have been moved to <code>/home/pi/.local/bin/release-gpio-steppers.sh</code> and <code>/home/pi/.local/bin/autohotspot.sh</code>, respectively.</li> <li>(System) The <code>gpio-init.service</code> systemd service has been renamed to <code>planktoscope-org.init-gpio-steppers.service</code>.</li> <li>(System) Previously the <code>en_DK.UTF-8</code> locale was used for everything. Now it is only used for time, measurements, and paper dimensions, and the <code>en_US.UTF-8</code> locale is the base locale for everything else. In the future we may provide GUI functionality for changing the base locale.</li> <li>(System) The chrony configuration has been simplified, but it may be broken.</li> <li>(System) The default timezone is now officially set to UTC, and we will be using UTC as the standard system time zone for all PlanktoScopes. Previously, the pre-built SD card images provided by this project used UTC as the timezone, but the \"Expert Setup\" instructions for manually setting up the PlanktoScope software did not specify a time zone to use.</li> <li>(System, Dependencies) The base OS is now the 2023-05-03 release of Raspberry Pi OS Bullseye.</li> <li>(Application: Backend, Dependencies) The Python backend and Node-RED dashboard's indirect dependencies are now version-locked to improve the reproducibility of the OS setup script independently of when the script is run.</li> </ul>"},{"location":"reference/software/changelog/#deprecated_4","title":"Deprecated","text":"<ul> <li>(Application: GUI) In a future release (potentially as early as v2023.12.0), the Node-RED editor and Node-RED dashboard will not be accessible at all over port 1880. In this release, you can still access the Node-RED dashboard at path <code>/ps/node-red-v2/ui</code> 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 <code>/admin/ps/node-red-v2</code> 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.</li> <li>(Application: GUI) In a future release (timeline not yet decided), the version of the Node-RED dashboard for the Adafruit HAT will stop receiving new features even as the version of the Node-RED dashboard for the custom PlanktoScope HAT continues receiving new features. However, we will continue to fix bugs in the Node-RED dashboard for the Adafruit HAT, and we will continue to build SD card images for the Adafruit HAT which will also include new features in other software components.</li> </ul>"},{"location":"reference/software/changelog/#removed_5","title":"Removed","text":"<ul> <li>(User-facing removal; Application: GUI) The Node-RED dashboard no longer allows selection of \"PlanktoScope v1.0\" or \"PlanktoScope v2.2 (waveshare HAT)\" as the hardware version. Those hardware versions are no longer supported by the software.</li> <li>(User-facing removal; System: networking) Now <code>planktoscope.local</code> 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. <code>planktoscope.local</code> 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 <code>planktoscope-&lt;machine-name&gt;.local</code>) should be used instead.</li> <li>(System: administration) The Git-based software update system (exposed in the Node-RED dashboard's \"Adminisration\" page) has been removed, since it was reported to behave problematically anyways. In the future, we will use a system based on Docker for safer and easier software updates.</li> </ul>"},{"location":"reference/software/changelog/#fixed_8","title":"Fixed","text":"<ul> <li>(Major fault-tolerance improvement; Application: GUI) When an invalid value is entered for the red or blue white balance gain on the Node-RED dashboard's \"Optic Configuration\" page, that value is now ignored, a notification is displayed about the invalid value, and the white balance gain is reset to the last valid value (loaded from the <code>hardware.json</code> configuration file). This fixes issue #166 by preventing the Node-RED dashboard from saving an invalid value to the <code>hardware.json</code> file, which would crash the Python hardware controller after the next boot (or after the next time the Python hardware controller was restarted).</li> <li>(Major quality-of-life improvement; Backend: dependencies) The <code>adafruit-blinka</code> and <code>adafruit-platformdetect</code> 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.</li> <li>(Application: GUI, troubleshooting) Previously, the Node-RED dashboard would often fail to display the log output from the Python backend. Now, it should always make the logs accessible (either by the links to Cockpit log viewer or by the links to the log file browser).</li> <li>(System: networking) Previously the autohotspot script would not ignore any networks which were commented out in the <code>/etc/wpa_supplicant/wpa_supplicant.conf</code> file when checking if any networks found by scanning matched networks were specified in the <code>wpa_supplicant.conf</code> file; now it ignores them, so that commented-out networks don't incorrectly prevent the autohotspot from going into wireless AP mode.</li> <li>(System: networking) Previously the autohotspot script would always wait 20 seconds after attempting to connect to a Wi-Fi network before checking whether the connection was successful, even if it didn't actually need to wait 20 seconds. Now the autohotspot script repeatedly attempts to ping google.com with a timeout of 2 seconds per attempt and a maximum of 10 attempts, so that the autohotspot script only waits as long as a necessary to determine that a Wi-Fi network connection has succeeded.</li> <li>(System: networking) Previously the autohotspot script could decide that the SSID scan results were available even if no SSIDs were found (despite local Wi-Fi networks being active). Now an empty SSID scan result is treated as a condition where a re-scan is required.</li> <li>(System: networking) Previously the log messages from the autohotspot script had inconsistent capitalization and grammar, and slightly unclear wording. Those have now been made more clear and consistent.</li> </ul>"},{"location":"reference/software/changelog/#v230-2021-12-20","title":"v2.3.0 - 2021-12-20","text":""},{"location":"reference/software/changelog/#added_7","title":"Added","text":"<ul> <li>A basic working image segmenter.</li> <li>Direct connections over Ethernet.</li> <li>A \"Lab culture\" sample type, where location is set to the South Pole, and sample collection time and date are set by default to the current time and date on the Raspberry Pi but can be changed. (#74)</li> <li>A \"Test\" sample type, where location is set to the South Pole, and sample collection time and date are always set to the current time and date on the Raspberry Pi.</li> <li>A selector in the Node-RED dashboard for the machine hardware version (#98)</li> </ul>"},{"location":"reference/software/changelog/#changed_9","title":"Changed","text":"<ul> <li>Various parts of the UI (we do not have a list of specific changes).</li> <li>Node-RED is now upgraded to v2.0 (#97)</li> <li>The base OS is now the 2021-12-03 release of Raspberry Pi OS Buster.</li> </ul>"},{"location":"reference/software/changelog/#fixed_9","title":"Fixed","text":"<ul> <li>Various issues with accessing the Node-RED dashboard via http://planktoscope.local:1880/ui .</li> <li>Various issues with Node-RED (#80, #91, #87, #96)</li> </ul>"},{"location":"reference/software/changelog/#v221-2021-05-10","title":"v2.2.1 - 2021-05-10","text":""},{"location":"reference/software/changelog/#added_8","title":"Added","text":"<ul> <li>The ability for developers to change the PlanktoScope repository to a development branch from the Node-RED dashboard.</li> </ul>"},{"location":"reference/software/changelog/#fixed_10","title":"Fixed","text":"<ul> <li>Various bugs (we do not have a list of specific changes)</li> </ul>"},{"location":"reference/software/changelog/#v220-2021-02-23","title":"v2.2.0 - 2021-02-23","text":""},{"location":"reference/software/changelog/#added_9","title":"Added","text":"<ul> <li>Support for Raspberry Pi HQ cameras.</li> <li>Control of image white balance.</li> <li>A Node-RED dashboard panel to copy all data from <code>/home/pi/data</code> to a USB drive.</li> <li>Integrity check of the generated files (for now only for raw pictures and <code>metadata.json</code> files). A file called <code>integrity.check</code> 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.</li> <li>A file gallery to browse data files in the <code>/home/pi/data</code> directory.</li> <li>A way to update the PlanktoScope software repository on the Raspberry Pi.</li> <li>A Node-RED dashboard panel to choose a wifi network to connect to.</li> <li>A Node-RED tab to enter the configuration of the hardware.</li> </ul>"},{"location":"reference/software/changelog/#changed_10","title":"Changed","text":"<ul> <li>(Breaking change) The UI has been changed (we do not have a list of specific changes)</li> </ul>"},{"location":"reference/software/changelog/#fixed_11","title":"Fixed","text":"<ul> <li>Random camera crash solved: instead of using the python picamera library, we now use a compiled binary, <code>raspimjpeg</code>, controlled through a FIFO pipe</li> </ul>"},{"location":"reference/software/changelog/#v210-2020-10-14","title":"v2.1.0 - 2020-10-14","text":""},{"location":"reference/software/changelog/#added_10","title":"Added","text":"<ul> <li>If the Raspberry Pi is configured (via the <code>/etc/wpa_supplicant/wpa_supplicant.conf</code> 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.</li> <li>If the Raspberry Pi is connected to the internet via its Ethernet port, it will share internet access to devices connected to the Raspberry Pi's wifi hotspot.</li> <li>(Documentation) Information has been added about ribbon cable assembly.</li> <li>(Documentation) Information has been added about how to back up the SD card.</li> </ul>"},{"location":"reference/software/changelog/#changed_11","title":"Changed","text":"<ul> <li>(Breaking change) The OS is now based on Raspberry OS Lite, so there is no graphical desktop.</li> <li>(Breaking change) The wifi network is now named <code>PlanktoScope</code>, and the password to it is now <code>copepode</code>.</li> <li>(Breaking change) The default user is now <code>pi</code>, and the default password is <code>copepode</code> for this user.</li> <li>(Breaking change) All raw and processed data files are now stored in the directory <code>/home/pi/data</code>.</li> <li>The software has undergone a major refactoring, which may accidentally introduce some bugs.</li> </ul>"},{"location":"reference/software/product-specs/","title":"Product Specifications","text":"<p>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.</p>"},{"location":"reference/software/product-specs/#v202400","title":"v2024.0.0","text":"<p>Specs for v2024.0.0 are the same as in v2023.9.0, except for the following sections:</p> <ul> <li>Base operating system: the binary target architecture has changed from 32-bit to 64-bit.</li> <li>System performance: on-board image processing speeds have improved (processing speeds have nearly doubled).</li> </ul>"},{"location":"reference/software/product-specs/#functionalities","title":"Functionalities","text":"<p>Regular operation:</p> <ul> <li>Image acquisition: stop-flow imaging (JPEG image output)</li> <li>On-board image processing: detection and segmentation of objects (batch-processing only)</li> <li>User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer</li> <li>Export of data for uploading to EcoTaxa</li> </ul> <p>Advanced operations:</p> <ul> <li>User interfacing: web browser interfaces for system administration, system monitoring, and troubleshooting</li> <li>Automation: MQTT-based API</li> <li>Application deployment: ability to add software as OCI containers using Docker, optionally via Forklift</li> <li>System configuration: ability to reversibly add, remove, replace, or override OS configuration files via Forklift</li> </ul>"},{"location":"reference/software/product-specs/#base-operating-system","title":"Base operating system","text":"<ul> <li>Distro: Raspberry Pi OS 11 (bullseye)</li> <li>Binary target architecture: 64-bit (aarch64, also known as arm64)</li> </ul>"},{"location":"reference/software/product-specs/#supported-hardware","title":"Supported hardware","text":"<p>Minimum for image acquisition (but not sufficient for on-board image processing):</p> <ul> <li>PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer</li> <li>Memory: 1 GB RAM</li> <li>Storage: 8 GB capacity</li> </ul> <p>Minimum for full functionality, including on-board image processing:</p> <ul> <li>Memory: 4 GB RAM</li> </ul> <p>Recommended:</p> <ul> <li>PlanktoScope: hardware v2.5 or v2.6 with Raspberry Pi 4 Model B computer</li> <li>Storage: 32 GB capacity</li> </ul> <p>Forwards-incompatibilities:</p> <ul> <li>Unable to run on the Raspberry Pi 5 computer.</li> </ul> <p>Backwards-incompatibilities:</p> <ul> <li>Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.</li> </ul>"},{"location":"reference/software/product-specs/#system-performance","title":"System performance","text":"<p>With minimum supported hardware for full functionality:</p> <ul> <li>On-board image processing: a dataset of 400 raw images is processed in approximately 1 hour</li> </ul>"},{"location":"reference/software/product-specs/#v202390","title":"v2023.9.0","text":""},{"location":"reference/software/product-specs/#functionalities_1","title":"Functionalities","text":"<p>Regular operation:</p> <ul> <li>Image acquisition: stop-flow imaging (JPEG image output)</li> <li>On-board image processing: detection and segmentation of objects (batch-processing only)</li> <li>User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer</li> <li>Export of data for uploading to EcoTaxa</li> </ul> <p>Advanced operations:</p> <ul> <li>User interfacing: web browser interfaces for system administration, system monitoring, and troubleshooting</li> <li>Automation: MQTT-based API</li> <li>Application deployment: ability to add software as OCI containers using Docker, optionally via Forklift</li> </ul>"},{"location":"reference/software/product-specs/#base-operating-system_1","title":"Base operating system","text":"<ul> <li>Distro: Raspberry Pi OS 11 (bullseye)</li> <li>Binary target architecture: 32-bit only (armhf, also known as armv7)</li> </ul>"},{"location":"reference/software/product-specs/#supported-hardware_1","title":"Supported hardware","text":"<p>Minimum for image acquisition (but not sufficient for on-board image processing):</p> <ul> <li>PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer</li> <li>Memory: 1 GB RAM</li> <li>Storage: 8 GB capacity</li> </ul> <p>Minimum for full functionality, including on-board image processing:</p> <ul> <li>Memory: 4 GB RAM</li> </ul> <p>Recommended:</p> <ul> <li>PlanktoScope: hardware v2.5 or v2.6 with Raspberry Pi 4 Model B computer</li> <li>Storage: 32 GB capacity</li> </ul> <p>Forwards-incompatibilities:</p> <ul> <li>Unable to run on the Raspberry Pi 5 computer.</li> </ul> <p>Backwards-incompatibilities:</p> <ul> <li>Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.</li> </ul>"},{"location":"reference/software/product-specs/#system-performance_1","title":"System performance","text":"<p>With minimum supported hardware for full functionality:</p> <ul> <li>On-board image processing: a dataset of 400 raw images is processed in approximately 1.5 to 2 hours</li> </ul>"},{"location":"reference/software/product-specs/#v23","title":"v2.3","text":""},{"location":"reference/software/product-specs/#functionalities_2","title":"Functionalities","text":"<p>Regular operation:</p> <ul> <li>Image acquisition: stop-flow imaging (JPEG image output)</li> <li>On-board image processing: detection and segmentation of objects (batch-processing only)</li> <li>User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer</li> <li>Export of data for uploading to EcoTaxa</li> </ul> <p>Advanced operations:</p> <ul> <li>Automation: MQTT-based API</li> </ul>"},{"location":"reference/software/product-specs/#base-operating-system_2","title":"Base operating system","text":"<ul> <li>Distro: Raspberry Pi OS 11 (bullseye)</li> <li>Binary target architecture: 32-bit only (armhf, also known as armv7)</li> </ul>"},{"location":"reference/software/product-specs/#supported-hardware_2","title":"Supported hardware","text":"<p>Minimum for image acquisition (but not sufficient for on-board image processing):</p> <ul> <li>PlanktoScope: hardware v2.1 with Raspberry Pi 3 Model B+ computer</li> <li>Memory: 1 GB RAM</li> <li>Storage: 8 GB capacity</li> </ul> <p>Minimum for full functionality, including on-board image processing:</p> <ul> <li>PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer</li> <li>Memory: 4 GB RAM</li> </ul> <p>Recommended for full functionality:</p> <ul> <li>PlanktoScope: hardware v2.5 or v2.6</li> <li>Storage: 32 GB capacity</li> </ul> <p>Forwards-incompatibilities:</p> <ul> <li>Unable to run on the Raspberry Pi 5 computer.</li> <li>Incompatible with Adafruit Stepper Motor HATs (used in PlanktoScope hardware v2.1) manufactured after mid-2022.</li> </ul>"},{"location":"reference/software/product-specs/#system-performance_2","title":"System performance","text":"<p>With minimum supported hardware for full functionality:</p> <ul> <li>On-board image processing: a dataset of 400 raw images is processed in approximately 1.5 to 2 hours</li> </ul>"},{"location":"reference/software/release-process/","title":"Release Process","text":"<p>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:</p> <ul> <li>Understand what you should do when we publish a new release of the PlanktoScope OS.</li> <li>Interpret the software product specifications and the software changelog.</li> </ul>"},{"location":"reference/software/release-process/#version-numbering","title":"Version numbering","text":"<p>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.</p> <p>We use a calendar-based version numbering system for the PlanktoScope OS, where each version number has the format <code>v(year).(minor).(patch)</code> for stable releases of the software or <code>v(year).(minor).(patch)-(modifier)</code> for testing pre-releases of the software:</p> <ul> <li> <p><code>year</code> 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.</p> </li> <li> <p><code>minor</code> 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 <code>minor</code> 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.</p> </li> <li> <p><code>patch</code> is a number which starts at 0 for each <code>(year).(minor)</code> 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 <code>minor</code> with the next release. For example, we might not publish a v2024.0.1 release, and instead just publish a v2024.1.0 release.</p> </li> <li> <p><code>modifier</code> 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 <code>modifier</code> has the format of either <code>alpha.(index)</code> or <code>beta.(index)</code>, where <code>index</code> is a number which starts at 0 for each <code>(year).(minor).(patch)-alpha</code> or <code>(year).(minor).(patch)-beta</code> 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.</p> </li> </ul>"},{"location":"reference/software/release-process/#release-channels","title":"Release channels","text":"<p>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:</p> <ul> <li>Edge: On the \"Edge\" channel, the PlanktoScope OS is built from the setup scripts on the latest commit of the <code>master</code> 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 <code>master</code> 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.</li> <li>Beta: Once an \"alpha\" pre-release has received sufficient testing for the PlanktoScope software developers to consider it stable enough for all PlanktoScope users to test it out, it will be promoted to a \"beta\" pre-release, and the <code>software/beta</code> branch of the PlanktoScope repository on GitHub will be advanced to the Git commit of the \"beta\" pre-release. At that point, the <code>software/beta</code> branch will only receive patches to fix serious errors. As bugs are fixed on the <code>software/beta</code> branch, more \"beta\" pre-releases may be created on that branch for users to test.</li> <li>Stable: After the latest \"beta\" pre-release has received sufficient testing for the PlanktoScope software developers to consider it stable enough for most (or, ideally, all) PlanktoScope users to rely on it for production use and scientific operations, that \"beta\" pre-release will be promoted to a \"stable\" release, and the <code>software/stable</code> branch of the PlanktoScope repository on GitHub will be advanced to the git commit of the \"stable\" release.</li> </ul>"},{"location":"reference/software/release-process/#release-schedules","title":"Release schedules","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/release-process/#choosing-a-release-channel","title":"Choosing a release channel","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/release-process/#upgrading-to-a-new-release-or-pre-release","title":"Upgrading to a new release or pre-release","text":"<p>In order to use a new release or pre-release of the PlanktoScope OS, you will need to do one of the following:</p> <ul> <li> <p>Download the new SD card image for that release/pre-release, following the standard installation process.</p> </li> <li> <p>Create a new custom SD card image for that release/pre-release, following the non-standard installation process.</p> </li> </ul> <p>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.</p>"},{"location":"reference/software/architecture/os/","title":"Operating System","text":"<p>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:</p> <ul> <li> <p>How the PlanktoScope software abstracts over the PlanktoScope hardware.</p> </li> <li> <p>How the PlanktoScope manages the execution of software programs intended to run on the PlanktoScope.</p> </li> </ul> <p>This information is intended to help you understand:</p> <ul> <li> <p>The overall design of the PlanktoScope OS, including what functionalities it provides and what software it includes, and why we made certain design decisions.</p> </li> <li> <p>How various software functionalities and responsibilities in the PlanktoScope are divided among the various programs in the PlanktoScope OS.</p> </li> <li> <p>How various programs in the PlanktoScope OS support other programs which provide the PlanktoScope's high-level/end-user functionalities.</p> </li> <li> <p>What tools you can use to perform software troubleshooting and system administration tasks with the PlanktoScope.</p> </li> <li> <p>What kinds of new software you can develop and deploy to run on a PlanktoScope.</p> </li> </ul> <p>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:</p> <ul> <li>\"Abstracts hardware to allow execution of other programs.\"</li> <li>\"Defines the liveness of the machine: without it, no program can run.\"</li> <li>Provides some important components including the operating system kernel, libraries, commands, daemons, and other facilities.</li> </ul> <p>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:</p> <ul> <li> <p>A Raspberry Pi computer.</p> </li> <li> <p>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).</p> </li> </ul>"},{"location":"reference/software/architecture/os/#software-deployment-execution","title":"Software deployment &amp; execution","text":"<p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>Most of the PlanktoScope's software is (or eventually will be) executed as Docker containers by the <code>dockerd</code> daemon (which in turn is run by the <code>docker.service</code> 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.</p> </li> </ul> <p>The PlanktoScope OS is a 64-bit operating system.</p>"},{"location":"reference/software/architecture/os/#boot-sequence","title":"Boot sequence","text":"<p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>The systemd system manager's boot behavior, which initializes all necessary filesystems, drivers, and system services.</p> </li> </ul> <p>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 <code>docker.service</code>. The startup ordering relationships between those services are listed in our reference document about services in the startup process.</p>"},{"location":"reference/software/architecture/os/#system-upgrades","title":"System upgrades","text":"<p>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 <code>pip</code>. This causes the following challenges for system administration on the PlanktoScope:</p> <ul> <li> <p>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.</p> </li> <li> <p>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).</p> </li> <li> <p>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.</p> </li> <li> <p>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 <code>pip</code>-managed Python packages which had been installed before the change.</p> </li> </ul> <p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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).</p> </li> <li> <p>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.</p> </li> </ul> <p>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 <code>pip</code>; instead, we use a (partially-implemented) tool called <code>forklift</code> 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:</p> <ul> <li>All software which we run using Docker.</li> <li>PlanktoScope-specific systemd services.</li> <li>PlanktoScope-specific OS configuration files.</li> </ul> <p>Everything managed by <code>forklift</code> is version-controlled in a Git repository, enabling easy backup and restoration of <code>forklift</code>-managed configurations even if the PlanktoScope's SD card is wiped and re-flashed.</p>"},{"location":"reference/software/architecture/os/#package-management-with-forklift","title":"Package management with <code>forklift</code>","text":"<p>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 <code>pip</code> 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.). <code>forklift</code> 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 (<code>forklift pallet switch</code>, described below in the Applying published customizations subsection).</p> <p><code>forklift</code> 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 <code>forklift</code>, you instead edit configuration files which declare the desired state of your system (though some step-by-step commands are also provided by <code>forklift</code> to make editing of files easier), and then you ask <code>forklift</code> 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 <code>forklift</code>'s design were inspired by Terraform.</p>"},{"location":"reference/software/architecture/os/#dependency-management","title":"Dependency management","text":"<p><code>forklift</code> 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 <code>forklift</code> 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.</p> <p>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. <code>forklift</code> 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.</p>"},{"location":"reference/software/architecture/os/#making-publishing-customizations","title":"Making &amp; publishing customizations","text":"<p>The workflow with <code>forklift</code> 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:</p> <ul> <li> <p>Initialize a custom pallet based on (i.e. layered over) an existing pallet, using the <code>forklift pallet init</code> command (e.g. <code>forklift pallet init --from github.com/PlanktoScope/pallet-standard@stable --as github.com/ethanjli/custom-pallet</code> 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 <code>github.com/ethanjli/custom-pallet</code>). (Note: the <code>forklift pallet init</code> 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.)</p> </li> <li> <p>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.</p> </li> <li> <p>Optionally, add published Forklift repositories to the pallet with the <code>forklift pallet add-repo</code> command (e.g. <code>forklift pallet add-repo github.com/ethanjli/pallet-example-minimal@main</code>), 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 <code>forklift pallet add-repo</code> command is also used to upgrade or downgrade the version of the Forklift repository used by the pallet.</p> </li> <li> <p>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.)</p> </li> <li> <p>Stage the pallet to be applied on the next boot of the PlanktoScope OS, with the <code>forklift pallet stage</code> command; when Forklift applies a pallet, it makes the PlanktoScope OS match the configuration of Forklift package deployments specified by the pallet.</p> </li> <li> <p>Use <code>git</code> to commit changes and (ideally) push them to GitHub, in order to publish your customizations for other people to try out.</p> </li> </ul> <p>(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)</p>"},{"location":"reference/software/architecture/os/#applying-published-customizations","title":"Applying published customizations","text":"<p>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:</p> <ul> <li> <p>Stage the customized pallet to be applied on the next boot of the PlanktoScope OS, using the <code>forklift pallet switch</code> command (e.g. <code>forklift pallet switch github.com/PlanktoScope/pallet-segmenter@edge</code> to use the latest development/unstable version of the github.com/PlanktoScope/pallet-segmenter pallet). </p> </li> <li> <p>Reboot the Raspberry Pi computer to apply the staged pallet. If the staged pallet cannot be successfully applied during boot, on subsequent boots <code>forklift</code> 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.)</p> </li> </ul> <p>(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)</p> <p>Note: currently all of <code>forklift</code>'s functionality is only exposed through a command-line interface, but after the <code>forklift</code> tool stabilizes we plan to add a web browser-based graphical interface for use by a general audience.</p>"},{"location":"reference/software/architecture/os/#planktoscope-specific-hardware-abstraction","title":"PlanktoScope-specific hardware abstraction","text":"<p>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):</p> <ul> <li> <p><code>gpsd</code>: for providing an abstraction for the PlanktoScope's GPS receiver.</p> </li> <li> <p><code>chronyd</code>: 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.</p> </li> <li> <p>The PlanktoScope hardware controller: for controlling PlanktoScope-specific hardware modules and abstracting them into high-level network APIs for other programs to interact with.</p> </li> </ul>"},{"location":"reference/software/architecture/os/#user-interface","title":"User interface","text":"<p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul> <p>The PlanktoScope OS adds the following network services which provide web browser-based graphical user interfaces to help users operate the PlanktoScope:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>device-portal: a landing page with links for end-users to quickly access the various web browser-based interfaces mentioned above.</p> </li> </ul> <p>Note: we will probably simplify things by consolidating some of these components together into the PlanktoScope's Node-RED dashboard.</p> <p>The PlanktoScope OS also provides various tools with web browser-based interfaces to aid with system administration and troubleshooting:</p> <ul> <li> <p>Cockpit: for performing system-administration tasks such as monitoring system resources, managing system services, viewing system logs, and executing commands in a terminal.</p> </li> <li> <p>A system file browser for viewing, managing, editing, uploading, and downloading any file on the PlanktoScope.</p> </li> <li> <p>A log file browser for viewing, downloading, and deleting log files files generated by the PlanktoScope hardware controller.</p> </li> <li> <p>Dozzle: for viewing and monitoring logs of Docker containers.</p> </li> <li> <p>Grafana: for monitoring and exploring metrics stored in Prometheus.</p> </li> </ul> <p>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:</p> <ul> <li> <p><code>vim</code>: for editing text files.</p> </li> <li> <p><code>byobu</code>: for running processes persistently across ephemeral terminal sessions.</p> </li> <li> <p><code>git</code>: for interacting with Git repositories.</p> </li> <li> <p><code>w3m</code> and <code>lynx</code>: for interacting with web pages (such as Wi-Fi network captive portals) from the PlanktoScope.</p> </li> <li> <p><code>docker</code>: for managing and inspecting Docker containers.</p> </li> </ul>"},{"location":"reference/software/architecture/os/#networking","title":"Networking","text":"<p>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.</p> <p>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.</p> <p>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. <code>home.pkscope</code>), 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. <code>pkscope.local</code>) 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).</p> <p>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.</p> <p>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:</p> <ul> <li> <p><code>autohotspot</code> (which in turn launches <code>hostapd</code>): 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.</p> </li> <li> <p><code>enable-interface-forwarding</code>: 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.</p> </li> <li> <p><code>dnsmasq</code>: for allowing computers connected to the PlanktoScope over a network to access the PlanktoScope using domain names defined on the PlanktoScope.</p> </li> <li> <p><code>firewalld</code>: a network firewall (currently disabled by default).</p> </li> </ul> <p>The standard PlanktoScope OS also adds the following systemd services for dynamically updating the system's network configuration during boot:</p> <ul> <li> <p><code>generate-machine-name</code>: generates a human-readable machine name  at <code>/run/machine-name</code> from the Raspberry Pi's serial number (or, if that's missing, from <code>/etc/machine-d</code>).</p> </li> <li> <p><code>generate-hostname-templated</code>: generates a temporary hostname file (which is used by a symlink at <code>/etc/hostname</code>) from <code>/etc/hostname-template</code>, which can include the machine name from <code>/run/machine-name</code>.</p> </li> <li> <p><code>update-hostname</code>: updates <code>systemd-hostnamed</code> so that the hostname matches what is specified by <code>/etc/hostname</code>.</p> </li> <li> <p><code>assemble-dnsmasq-config-templated</code>: generates a temporary dnsmasq drop-in config file (which is used by a symlink at <code>/etc/dnsmasq.d/40-generated-templated-config</code>) from drop-in config file templates at <code>/etc/dnsmasq-templates.d</code>. </p> </li> <li> <p><code>assemble-hostapd-config-templated</code>: generates a temporary hostapd drop-in config file (which is used by a symlink at <code>/etc/hostapd/hostapd.conf.d/60-generated-templated.conf</code>) from drop-in config file templates at <code>/etc/hostapd/hostapd.conf-templates.d</code>.</p> </li> <li> <p><code>assemble-hostapd-config</code>: generates a temporary hostapd config file (which is used by a symlink at <code>/etc/hostapd/hostapd.conf</code>) from drop-in config files at <code>/etc/hostapd/hostapd.conf.d</code>.</p> </li> <li> <p><code>assemble-hosts-templated</code>: generates a temporary hosts drop-in snippet (which is used by a symlink at <code>/etc/hosts.d/50-generated-templated</code>) from drop-in hosts snippet templates at <code>/etc/hosts-templates.d</code>.</p> </li> <li> <p><code>assemble-hosts</code> generates a temporary hosts file (which is used by a symlink at <code>/etc/hosts</code>) from drop-in snippets at <code>/etc/hosts-templates.d</code>.</p> </li> </ul> <p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul>"},{"location":"reference/software/architecture/os/#filesystem","title":"Filesystem","text":"<p>The PlanktoScope OS's filesystem makes some changes from the default Debian/Raspberry Pi OS filesystem structure so that <code>/etc</code> and <code>/usr</code> 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:</p> <ul> <li> <p>Make a read-only mount (via the <code>overlay-sysroot</code> systemd service) of the initial root filesystem, at <code>/sysroot</code>.</p> </li> <li> <p>Make a read-only mount of the next Forklift pallet to be applied (via the <code>bindro-run-forklift-stages-current.service</code>) from a subdirectory within <code>/var/lib/forklift/stages</code> to <code>/run/forklift/stages/current</code>.</p> </li> <li> <p>Remount <code>/usr</code> (via the <code>overlay-usr</code> systemd service) as a writable overlay with a Forklift-managed intermediate layer (in a subdirectory within <code>/var/lib/forklift/stages</code> which can also be accessed at <code>/run/forklift/stages/current/exports/overlays/usr</code>) and <code>/sysroot/usr</code> as a base layer; any changes made by the system administrator to files in <code>/usr</code> will be transparently stored by the overlay in <code>/var/lib/overlays/overrides/usr</code>. This allows Forklift to provide extra files in <code>/usr</code> in an atomic way, while overrides made by the system administrator are stored separately.</p> </li> <li> <p>Remount <code>/etc</code> (via the <code>overlay-etc</code> systemd service) as a writable overlay with a Forklift-managed intermediate layer (in a subdirectory within <code>/var/lib/forklift/stages</code> which can also be accessed at <code>/run/forklift/stages/current/exports/overlays/etc</code>) and <code>/sysroot/etc</code> as a base layer; any changes made by the system administrator to files in <code>/etc</code> will be transparently stored by the overlay in <code>/var/lib/overlays/overrides/etc</code>. This allows Forklift to provide extra files in <code>/etc</code> in an atomic way, while overrides made by the system administrator are stored separately.</p> </li> <li> <p>Make a writable mount of <code>/var/lib/forklift/stages</code> to <code>/home/pi/.local/share/forklift/stages</code> (via the <code>bind-.local-share-forklift-stages@home-pi</code> systemd service) so that, when the <code>pi</code> user runs <code>forklift</code> commands like <code>forklift pallet switch</code>, those commands will update <code>/var/lib/forklift/stages</code> - and without requiring the use of <code>sudo</code>.</p> </li> <li> <p>Update systemd (via the <code>start-overlaid-units</code> systemd service) with any new systemd units provided via Forklift, so that they will run during boot.</p> </li> </ul> <p>Beyond what is required by the Linux Filesystem Hierarchy Standard, the PlanktoScope OS sets the following conventions related to filesystem paths:</p> <ul> <li> <p>Scripts which are provided by Forklift and only used as part of systemd services should be provided in <code>/usr/libexec</code>, Forklift packages should export those scripts to <code>overlays/usr/libexec</code> (so, for example, they will be accessible in <code>/run/forklift/stages/current/exports/overlays/usr/libexec</code>).</p> </li> <li> <p>Systemd units provided by Forklift should be provided in <code>/usr/lib/systemd/system</code>, and Forklift packages should export those units to <code>overlays/usr/lib/systemd/system</code>. Symlinks to enable those units should be provided in <code>/etc/systemd/system</code>, and Forklift packages should export those scripts to <code>overlays/etc/systemd/system</code>.</p> </li> <li> <p>Forklift-provided systemd services which dynamically generate temporary files meant to be used in <code>/etc</code> should generate those temporary files at stable paths in <code>/run/overlays/generated/etc</code>. Forklift packages which provide such systemd services should also provide relative symlinks into those temporary files in <code>/run/overlays/generated/etc</code> to be exported into <code>overlays/etc</code> as overlays for the corresponding paths in <code>/etc</code>. For example, if a package provides a service to dynamically generate a hosts file meant to be used as <code>/etc/hosts</code>, that service should generate the file in <code>/run/overlays/generated/etc/hosts</code> and the package should export a symlink at <code>overlays/etc/hosts</code> which points to <code>../../run/overlays/generated/etc/hosts</code>, so that <code>/etc/hosts</code> will be a symlink pointing to <code>/run/overlays/generated/etc/hosts</code>.</p> </li> </ul>"},{"location":"reference/software/architecture/os/#observability-telemetry","title":"Observability &amp; telemetry","text":"<p>Although it is not a high priority yet, we would like to enable operators of large (&gt;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:</p> <ul> <li> <p>Prometheus: a server for collecting and storing metrics and for exposing metrics over an HTTP API.</p> </li> <li> <p>Prometheus node exporter: for measuring computer hardware and OS monitoring metrics and exposing them over a Prometheus-compatible HTTP API.</p> </li> </ul> <p>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.</p>"},{"location":"reference/software/architecture/os/#data-processing","title":"Data processing","text":"<p>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:</p> <ul> <li>The PlanktoScope segmenter: for processing raw image datasets acquired by the PlanktoScope hardware controller to detect and extract particles from raw images.</li> </ul> <p>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.</p>"},{"location":"reference/software/architecture/os/#security","title":"Security","text":"<p>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:</p> <ul> <li> <p>Changing the password of the <code>pi</code> user away from the default of <code>copepode</code>.</p> </li> <li> <p>Password-protecting the Node-RED dashboard editor, which can be used to execute arbitrary commands with root permissions.</p> </li> <li> <p>Setting firewall rules.</p> </li> <li> <p>Changing the password of the Wi-Fi hotspot away from the default of <code>copepode</code>, or disabling Wi-Fi hotspot functionality.</p> </li> </ul> <p>Other risk mitigations will require deeper changes to the PlanktoScope OS, such as:</p> <ul> <li> <p>Limiting the permissions and capabilities made available to various system services which currently run with root permissions</p> </li> <li> <p>Password-protecting web browser-based user interfaces</p> </li> <li> <p>Password-protecting network APIs.</p> </li> </ul> <p>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!</p>"},{"location":"reference/software/functionalities/camera-settings/","title":"Camera Settings","text":"<p>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.</p> <p>The following camera settings can be adjusted via the Node-RED dashboard:</p> <ul> <li> <p>\"ISO\" &amp; \"Shutter Speed\" control the brightness of images captured by the camera.</p> </li> <li> <p>\"Auto White Balance\", \"WB: Red\", and \"WB: Blue\" control the color balance of images captured by the camera.</p> </li> </ul>"},{"location":"reference/software/functionalities/camera-settings/#image-brightness","title":"Image brightness","text":"<p>The Node-RED dashboard's \"Shutter Speed\" setting, which is specified in units of microseconds (\u03bcs), is used to set the <code>ExposureTime</code> 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\".</p> <p>The Node-RED dashboard's \"ISO\" setting is divided by 100 and used to set the <code>AnalogueGain</code> 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 <code>AnalogueGain</code> control and the <code>DigitalGain</code> property.</p>"},{"location":"reference/software/functionalities/camera-settings/#image-color-balance","title":"Image color balance","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/functionalities/sample-imaging/","title":"Sample Imaging","text":"<p>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.</p> <p>Currently, the PlanktoScope software only has one sample-imaging mode, which we call \"stop-flow imaging\":</p>"},{"location":"reference/software/functionalities/sample-imaging/#stop-flow-imaging","title":"Stop-flow imaging","text":"<p>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.</p> <p>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:</p> <ol> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>The PlanktoScope will capture and save an image of its entire field-of-view.</p> </li> </ol>"},{"location":"reference/software/functionalities/segmentation/","title":"Image Segmentation","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>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.</p>"},{"location":"reference/software/functionalities/segmentation/#median-calculation-step","title":"Median-calculation step","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/functionalities/segmentation/#image-correction-step","title":"Image-correction step","text":"<p>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.</p>"},{"location":"reference/software/functionalities/segmentation/#mask-calculation-step","title":"Mask-calculation step","text":"<p>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:</p> <ol> <li> <p>\"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.</p> </li> <li> <p>\"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.</p> </li> <li> <p>\"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.</p> </li> <li> <p>\"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.</p> </li> <li> <p>\"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.</p> </li> <li> <p>\"Erode2\": this operation erodes the mask with an 8-pixel-diameter circular kernel, inverting the effect of the previous \"dilate\" operation.</p> </li> </ol> <p>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.</p>"},{"location":"reference/software/functionalities/segmentation/#object-extraction-step","title":"Object-extraction step","text":"<p>The object-extraction step takes the following inputs:</p> <ul> <li> <p>A median-corrected image</p> </li> <li> <p>A segmentation mask</p> </li> <li> <p>The following sample metadata fields:</p> </li> <li> <p><code>acq_minimum_mesh</code>: 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\".</p> </li> <li> <p><code>process_pixel</code>: the pixel size calibration of the PlanktoScope, in units of \u00b5m per pixel; then the area (in units of \u00b5m<sup>2</sup>) per pixel is <code>process_pixel * process_pixel</code>. This value is set on the \"Hardware Settings\" page of the PlanktoScope's Node-RED dashboard as the \"Pixel size calibration: um per pixel\".</p> </li> </ul> <p>First, the object-extraction step calculates a minimum-area threshold for objects to extract using the input segmentation mask: the threshold (in units of pixel<sup>2</sup>) is calculated as <code>(2 * acq_minimum_mesh / process_pixel) ^ 2</code>.</p> <p>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 (<code>area_bbox</code> in scikit-image) is less than the minimum-area threshold.</p>"},{"location":"reference/software/functionalities/segmentation/#metadata-calculation","title":"Metadata calculation","text":"<p>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:</p> <ul> <li> <p><code>MeanHue</code>: the mean of the hue channel of the image in a hue-saturation-value (HSV) representation of the image</p> </li> <li> <p><code>StdHue</code>: the standard deviation of the hue channel of the image in an HSV representation of the image</p> </li> <li> <p><code>MeanSaturation</code>: the standard deviation of the saturation channel of the image in an HSV representation of the image</p> </li> <li> <p><code>StdSaturation</code>: the standard deviation of the saturation channel of the image in an HSV representation of the image</p> </li> <li> <p><code>MeanValue</code>: the standard deviation of the value channel of the image in an HSV representation of the image</p> </li> <li> <p><code>StdValue</code>: the standard deviation of the value channel of the image in an HSV representation of the image</p> </li> </ul> <p>Additionally, some metadata for the object is calculated from the region properties calculated by scikit-image for that object's region:</p> <ul> <li> <p><code>label</code>: The identifier of the object's region, as assigned by scikit-image. This corresponds to the <code>label</code> region property in scikit-image.</p> </li> <li> <p>Basic area properties:</p> </li> <li> <p><code>area_exc</code>: Number of pixels in the region (excluding pixels in any holes). This corresponds to the <code>area</code> region property in scikit-image.</p> </li> <li> <p><code>area</code>: Number of pixels of the region with all holes filled in (i.e. including pixels in any holes). This corresponds to the <code>area_filled</code> region property in scikit-image. Yes, it's somewhat confusing that the PlanktoScope segmenter renames scikit-image's <code>area</code> region property to <code>area_exc</code> and renames scikit-image's <code>area_filled</code> region property to <code>area</code>.</p> </li> <li> <p><code>%area</code>: 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 <code>1 - area_exc / area</code>. In other words, this represents the proportion of the region which consists of holes. Yes, <code>%area</code> is a misleading name both because of the <code>%</code> in the name and because of the <code>area</code> in the name.</p> </li> <li> <p>Equivalent-circle properties:</p> </li> <li> <p><code>equivalent_diameter</code>: 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 <code>equivalent_diameter_area</code> property in scikit-image.</p> </li> <li>Equivalent-ellipse properties:</li> <li> <p><code>eccentricity</code>: 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 <code>eccentricity</code> property in scikit-image.</p> </li> <li> <p><code>major</code>: The length (in pixels) of the major axis of region's equivalent ellipse. This corresponds to the <code>axis_major_length</code> property in scikit-image.</p> </li> <li> <p><code>minor</code>: The length (in pixels) of the minor axis of the region's equivalent ellipse. This corresponds to the <code>axis_minor_length</code> property in scikit-image.</p> </li> <li> <p><code>elongation</code>: The ratio between <code>major</code> and <code>minor</code>.</p> </li> <li> <p><code>angle</code>: 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 <code>orientation</code> property in scikit-image.</p> </li> <li> <p>Equivalent-object perimeter properties:</p> </li> <li> <p><code>perim.</code>: 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 <code>perimeter</code> property in scikit-image.</p> </li> <li> <p><code>perimareaexc</code>: Ratio between the perimeter and the number of pixels in the region (excluding pixels in any holes). Calculated as <code>perim. / area_exc</code>.</p> </li> <li> <p><code>perimmajor</code>: Ratio between the perimeter and the length of the major axis of the region's equivalent ellipse. Calculated as <code>perim. / major</code>.</p> </li> <li> <p><code>circ.</code>: The roundness of the region's equivalent object, including pixels in any holes. Calculated as <code>4 * \u03c0 * area / (perim. * perim.)</code>. Ranges from 1 for a perfect circle to 0 for highly non-circular shapes.</p> </li> <li> <p><code>circex</code>: The roundness of the region's equivalent object, excluding pixels in any holes. Calculated as <code>4 * \u03c0 * area_exc / (perim. * perim.)</code>. Ranges from 1 for a perfect circle to 0 for highly non-circular shapes or shapes with many large holes.</p> </li> <li> <p>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:</p> </li> <li> <p><code>bx</code>: 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 <code>bbox</code> property in scikit-image.</p> </li> <li> <p><code>by</code>: 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 <code>bbox</code> property in scikit-image.</p> </li> <li> <p><code>width</code>: Width (in number of pixels) of the region's bounding box. This is calculated from the elements of the <code>bbox</code> property in scikit-image.</p> </li> <li> <p><code>height</code>: Height (in number of pixels) of the region's bounding box. This is calculated from the elements of the <code>bbox</code> property in scikit-image.</p> </li> <li> <p><code>bounding_box_area</code>: Number of pixels in the region's bounding box; equivalent to <code>width * height</code>. This corresponds to the <code>area_bbox</code> region property in scikit-image.</p> </li> <li> <p><code>extent</code>: 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 <code>area_exc / bounding_box_area</code>. This corresponds to the <code>extent</code> region property in scikit-image.</p> </li> <li> <p>Convex hull (the smallest convex polygon which encloses the region) properties:</p> </li> <li> <p><code>convex_area</code>: Number of pixels in the convex hull of the region. This corresponds to the <code>area_convex</code> region property in scikit-image.</p> </li> <li> <p><code>solidity</code>: 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 <code>area_exc / convex_area</code>. This corresponds to the <code>solidity</code> region property in scikit-image.</p> </li> <li> <p>Unweighted centroid properties:</p> </li> <li> <p><code>x</code>: 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 <code>centroid</code> region property in scikit-image.</p> </li> <li> <p><code>y</code>: 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 <code>centroid</code> region property in scikit-image.</p> </li> <li> <p><code>local_centroid_col</code>: x-position (in pixels) of the centroid of the object, relative to the top-left corner of the region's bounding box; equivalent to <code>x - bx</code>. This corresponds to the second element of the <code>centroid_local</code> region property in scikit-image.</p> </li> <li> <p><code>local_centroid_row</code>: y-position (in pixels) of the centroid of the object, relative to the top-left corner of the region's bounding box; equivalent to <code>y - by</code>. This corresponds to the first element of the <code>centroid_local</code> region property in scikit-image.</p> </li> <li> <p>Topological properties:</p> </li> <li> <p><code>euler_number</code>: 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 <code>euler_number</code> property in scikit-image.</p> </li> </ul>"},{"location":"reference/software/functionalities/segmentation/#output-image-cropping","title":"Output image cropping","text":"<p>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).</p> <p>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.</p>"},{"location":"reference/software/interfaces/exported-metadata/","title":"Exported Metadata","text":"<p>TODO</p>"},{"location":"reference/software/interfaces/mqtt/","title":"Planktoscope MQTT API Reference","text":"<p>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:</p> <pre><code>flowchart TD\n    API[API Client] --&gt;|Command| Broker[MQTT Broker]\n    Broker --&gt;|Command| Backend[Python Backend]\n    Backend --&gt;|Status Update| Broker[MQTT Broker]\n    Broker --&gt;|Status Update| API</code></pre> <p>Most 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:</p> <ul> <li>API clients send commands to the Python backend (via the MQTT broker), and receive status updates from the Python backend (also via the MQTT broker). The PlanktoScope's Node-RED dashboard is an API client, but other programs are also allowed to act as API clients.</li> <li>The MQTT broker passes commands and status updates between the API client(s) and the Python backend. The MQTT broker runs on the PlanktoScope and accepts connections from API clients on port 1883.</li> <li>The Python backend handles commands, takes actions (e.g. changing the state of hardware actuators), and publishes status updates both in response to commands and in response to changes in internal state. Currently, parts of the Python backend also act as MQTT API clients to other parts of the Python backend.</li> </ul> <p>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. <code>actuator/pump</code>). Every MQTT message in the PlanktoScope's MQTT API carries a payload, which is a JSON object serialized as a string:</p> <ul> <li>Messages which are commands usually specify the type of command in an <code>action</code> field of the payload object; other fields of the payload object are parameters of the command.</li> <li>Messages which are status updates have a single field in the payload object, <code>status</code>, which is a string containing a status or error message.</li> </ul> <p>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:</p>"},{"location":"reference/software/interfaces/mqtt/#pump","title":"Pump","text":"<p>The Pump API controls the movement of fluid through the PlanktoScope:</p> <ul> <li>MQTT topics for commands: <code>actuator/pump</code></li> <li>MQTT topics for status updates: <code>status/pump</code></li> <li>Commands: <code>move</code>, <code>stop</code></li> </ul>"},{"location":"reference/software/interfaces/mqtt/#move-command","title":"<code>move</code> command","text":"<p>The <code>move</code> 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:</p> <pre><code>{\n  \"action\": \"move\",\n  \"direction\": \"FORWARD\",\n  \"volume\": 10,\n  \"flowrate\": 1\n}\n</code></pre> <p>The <code>move</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>move</code> command. string <code>move</code> <code>direction</code> Direction to run the pump. string <code>FORWARD</code>, <code>BACKWARD</code> <code>volume</code> Total volume of sample to pump before stopping automatically (mL). float 0 &lt; <code>volume</code> <code>flowrate</code> Speed of pumping (mL/min). float 0 &lt; <code>flowrate</code> \u2264 45 mL/min"},{"location":"reference/software/interfaces/mqtt/#move-command-responses","title":"<code>move</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/pump</code> topic, in response to the <code>move</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Started</code> The pump has started moving in response to a valid <code>move</code> command. <code>Error, the message is missing an argument</code> One or more required parameters (<code>direction</code>, <code>volume</code>, <code>flowrate</code>) are missing in the <code>move</code> command. <code>Error, The flowrate should not be == 0</code> An invalid value (0) was provided for the <code>flowrate</code> field. <code>Done</code> The pump has successfully stopped after fully pumping the specified volume of sample. <p>Note: the MQTT API does not yet completely specify error messages in response to invalid values for the <code>direction</code>, <code>volume</code>, and <code>flowrate</code> parameters.</p>"},{"location":"reference/software/interfaces/mqtt/#stop-command","title":"<code>stop</code> command","text":"<p>The <code>stop</code> command interrupts any ongoing movement of fluid through the PlanktoScope and cuts off power to the PlanktoScope pump's stepper motor:</p> <pre><code>{\n  \"action\": \"stop\"\n}\n</code></pre> <p>The <code>stop</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>stop</code> command. string <code>stop</code>"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses","title":"<code>stop</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/pump</code> topic, in response to the <code>stop</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Interrupted</code> The pump has stopped moving in response to a valid <code>stop</code> command, interrupting any ongoing <code>move</code> command.Sent in response to any Pump <code>stop</code> command, and any Imager <code>stop</code> command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/pump</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Ready</code> The backend has become ready to respond to Pump commands. <code>Dead</code> The backend will no longer respond to Pump commands."},{"location":"reference/software/interfaces/mqtt/#focus","title":"Focus","text":"<p>The Focus API controls the movement of the sample stage focusing motors in the PlanktoScope:</p> <ul> <li>MQTT topics for commands: <code>actuator/focus</code></li> <li>MQTT topics for status updates: <code>status/focus</code></li> <li>Commands: <code>move</code>, <code>stop</code></li> </ul>"},{"location":"reference/software/interfaces/mqtt/#move-command_1","title":"<code>move</code> command","text":"<p>The <code>move</code> 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:</p> <pre><code>{\n  \"action\": \"move\",\n  \"direction\": \"UP\",\n  \"distance\": 0.26,\n  \"speed\": 1\n}\n</code></pre> <p>The <code>move</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>move</code> command. string <code>move</code> <code>direction</code> Direction to move the sample stage. string <code>UP</code>, <code>DOWN</code> <code>distance</code> Total distance to move the stage before stopping automatically (in mm). float 0 &lt; <code>distance</code> \u2264 45.0 <code>speed</code> Speed of movement (in mm/s).Defaults to 5. float 0 &lt; <code>speed</code> \u2264 5.0 (optional)"},{"location":"reference/software/interfaces/mqtt/#move-command-responses_1","title":"<code>move</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/focus</code> topic in response to the <code>move</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Started</code> The focusing motors have started moving in response to a valid <code>move</code> command. <code>Error</code> The <code>move</code> command is missing the <code>distance</code> and/or <code>direction</code> fields. <code>Done</code> The focusing motors have successfully stopped after moving the specified distance."},{"location":"reference/software/interfaces/mqtt/#stop-command_1","title":"<code>stop</code> command","text":"<p>The <code>stop</code> command interrupts any ongoing movement of the focusing stage and cuts off power to the focusing motors:</p> <pre><code>{\n  \"action\": \"stop\"\n}\n</code></pre> <p>The <code>stop</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>stop</code> command. string <code>stop</code>"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_1","title":"<code>stop</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/focus</code> topic, in response to the <code>stop</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Interrupted</code> The focusing motors have stopped moving in response to a valid <code>stop</code> command, interrupting any ongoing <code>stop</code> command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_1","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/focus</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Ready</code> The backend has become ready to respond to Focus commands. <code>Dead</code> The backend will no longer respond to Focus commands."},{"location":"reference/software/interfaces/mqtt/#light","title":"Light","text":"<p>The Light API controls the state of the LED lighting system in the PlanktoScope:</p> <ul> <li>MQTT topics for commands: <code>actuator/light</code></li> <li>MQTT topics for status updates: <code>status/light</code></li> <li>Commands: <code>on</code>, <code>off</code></li> </ul>"},{"location":"reference/software/interfaces/mqtt/#on-command","title":"<code>on</code> command","text":"<p>The <code>on</code> command turns on the sample illumination LED. For example:</p> <pre><code>{\n  \"action\": \"on\"\n  \"led\": \"1\"\n}\n</code></pre> <p>The <code>on</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>on</code> command. string <code>on</code> <code>led</code> Specifies the LED to turn on.Defaults to <code>1</code>. integer <code>1</code>\u00a0(optional)"},{"location":"reference/software/interfaces/mqtt/#on-command-responses","title":"<code>on</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/light</code> topic in response to the <code>on</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Led 1: On</code> The LED turned on successfully. <code>Error with LED number</code> An invalid value was provided for the <code>led</code> field of the command."},{"location":"reference/software/interfaces/mqtt/#off-command","title":"<code>off</code> command","text":"<p>The <code>off</code> command turns off the sample illumination LED. For example:</p> <pre><code>{\n  \"action\": \"off\"\n}\n</code></pre> <p>The <code>off</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>off</code> command. string <code>off</code> <code>led</code> Specifies the LED to turn on.Defaults to <code>1</code> integer <code>1</code>"},{"location":"reference/software/interfaces/mqtt/#off-command-responses","title":"<code>off</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/light</code> topic in response to the <code>off</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Led 1: Off</code> The LED turned off successfully. <code>Error with LED number</code> An invalid value was provided for the <code>led</code> field of the command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_2","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/light</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Ready</code> The backend has become ready to respond to Light commands. <code>Dead</code> The backend will no longer respond to Light commands."},{"location":"reference/software/interfaces/mqtt/#imager","title":"Imager","text":"<p>The Imager API controls image acquisition with the PlanktoScope's hardware, as well as the PlanktoScope's camera:</p> <ul> <li>MQTT topics for commands: <code>imager/image</code></li> <li>MQTT topics for status updates: <code>status/imager</code></li> <li>Commands: <code>settings</code>, <code>update_config</code>, <code>image</code>, <code>stop</code></li> </ul> <p>For details on how images are acquired, refer to our technical reference on sample imaging in the PlanktoScope.</p> <p>Generally, commands should be sent in the following order:</p> <ol> <li><code>settings</code> command: Configure the camera settings.</li> <li><code>update_config</code> command: Update the dataset metadata for the next image acquisition.</li> <li><code>image</code> command: Initiate image acquisition.</li> <li><code>stop</code> command: Stop any in-progress image acquisition.</li> </ol>"},{"location":"reference/software/interfaces/mqtt/#settings-command","title":"<code>settings</code> command","text":"<p>The <code>settings</code> command changes the camera settings. The fields <code>iso</code>, <code>shutter_speed</code>, <code>white_balance_gain</code> and <code>white_balance</code> 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:</p> <pre><code>{\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}\n</code></pre> <p>The <code>settings</code> command has the following parameters:</p> Parameter Description Type Accepted Values <code>action</code> Specifies the <code>settings</code> command. string <code>settings</code> <code>iso</code> Simulated ISO image sensitivity. int 0 &lt; <code>iso</code> \u2264 650 (higher values may be accepted for certain cameras) (optional) <code>shutter_speed</code> Exposure time (in \u03bcs). int 125 \u2264 <code>shutter_speed</code>\u00a0(optional) <code>white_balance_gain.red</code> White balance red gain. float 0.0 \u2264 <code>white_balance_gain.red</code>\u00a0\u2264 32.0 (optional) <code>white_balance_gain.blue</code> White balance blue gain. float 0.0\u00a0\u2264\u00a0<code>white_balance_gain.blue</code>\u00a0\u2264 32.0 (optional) <code>white_balance</code> White balance mode. (<code>off</code>\u00a0specifies the use of manual white balance gains) string <code>auto</code>, <code>off</code>\u00a0(optional)"},{"location":"reference/software/interfaces/mqtt/#settings-command-responses","title":"<code>settings</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic in response to the <code>settings</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Camera settings updated</code> The camera settings have been successfully updated. <code>Camera settings error</code> The settings command is missing required parameters. <code>Iso number not valid</code> The provided <code>iso</code>\u00a0value is not allowed. <code>Shutter speed not valid</code> The provided <code>shutter_speed</code>\u00a0value is not allowed. <code>White balance gain not valid</code> The provided <code>white_balance_gain</code>\u00a0object is not valid or has an invalid value. <code>White balance mode {white_balance} not valid</code> The provided <code>white_balance</code>\u00a0value is not allowed."},{"location":"reference/software/interfaces/mqtt/#update_config-command","title":"<code>update_config</code> command","text":"<p>The <code>update_config</code> command sets/changes the metadata which will be saved with the dataset which to be acquired by the next <code>image</code> command. For example:</p> <pre><code>{\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}\n</code></pre> <p>The 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 <code>update_config</code> command has the following parameters:</p> <p>Sample information:</p> Field Description Type <code>sample_project</code> Project name. string <code>sample_id</code> Sample identifier. integer <code>sample_uuid</code> Sample UUID. string <code>sample_ship</code> Ship name. string <code>sample_operator</code> Operator name. string <code>sample_sampling_gear</code> Sampling gear description. string <code>sample_concentrated_sample_volume</code> Concentrated sample volume. float <code>sample_total_volume</code> Total volume. float <code>sample_dilution_factor</code> Dilution factor. float <code>sample_speed_through_water</code> Speed through water. float <p>Acquisition information:</p> Field Description Type <code>acq_id</code> Acquisition identifier. integer <code>acq_instrument</code> Acquisition instrument. string <code>acq_magnification</code> Magnification level. string <code>acq_camera_id</code> Camera identifier. integer <code>acq_camera_lens</code> Camera lens. string <code>acq_software</code> Acquisition software. string <code>acq_volume</code> Acquisition volume. float <code>acq_imaged_volume</code> Imaged volume. float <code>acq_minimum_mesh</code> Minimum mesh size. float <code>acq_maximum_mesh</code> Maximum mesh size. float <code>acq_min_esd</code> Minimum equivalent spherical diameter. float <code>acq_max_esd</code> Maximum equivalent spherical diameter. float <code>acq_camera_name</code> Camera name. string <code>acq_nb_frame</code> Number of frames captured. integer <code>acq_local_datetime</code> Local date and time of acquisition. string <code>acq_camera_resolution</code> Camera resolution. string <code>acq_camera_iso</code> Camera ISO setting. float <code>acq_camera_shutter_speed</code> Camera shutter speed. float <p>Object information:</p> Field Description Type <code>object_date</code> Date of the object recording. string <code>object_time</code> Time of the object recording. string <code>object_lat</code> Latitude of the sample location. float <code>object_lon</code> Longitude of the sample location. float <code>object_depth_min</code> Minimum depth of the sample location. float <code>object_depth_max</code> Maximum depth of the sample location. float <code>object_date_end</code> End date of the object recording. string <code>object_time_end</code> End time of the object recording. string <code>object_lat_end</code> End latitude of the sample location. float <code>object_lon_end</code> End longitude of the sample location. float <p>Processing information:</p> Field Description Type <code>process_pixel</code> Pixel processing method. string <code>process_datetime</code> Date and time of processing. string <code>process_id</code> Processing identifier. integer <code>process_uuid</code> Processing UUID. string <code>process_source</code> Source of processing software or method. string <code>process_commit</code> Commit hash of the software used. string"},{"location":"reference/software/interfaces/mqtt/#update_config-command-responses","title":"<code>update_config</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic in response to the <code>update_config</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Config updated</code> The metadata has been successfully updated. <code>Configuration message error</code> The command is missing the required\u00a0<code>config</code> field. <code>Busy</code> Image acquisition is already in progress, so dataset metadata cannot be changed."},{"location":"reference/software/interfaces/mqtt/#image-command","title":"<code>image</code> command","text":"<p>The <code>image</code> 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:</p> <pre><code>{\n  \"action\": \"image\",\n  \"pump_direction\": \"FORWARD\",\n  \"volume\": 1,\n  \"nb_frame\": 200,\n  \"sleep\": 0.1\n}\n</code></pre> <p>A valid <code>update_config</code> command with a unique <code>(object_date, sample_id, acq_id)</code> combination must be sent some time before each <code>image</code> command. If an <code>update_config</code> command has not been sent before the <code>image</code> command, the <code>image</code> 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).</p> <p>The <code>image</code> command has the following parameters:</p> Parameter Description Type Accepted Values <code>pump_direction</code> Direction of sample pumping. string <code>FORWARD</code>, <code>BACKWARD</code>. <code>volume</code> Volume (in mL) of sample to pump between each captured image. float 0 &lt; <code>volume</code> <code>nb_frame</code> Number of frames to capture. integer 0 &lt; <code>nb_frame</code> <code>sleep</code> 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 &lt; <code>sleep</code>"},{"location":"reference/software/interfaces/mqtt/#image-command-responses","title":"<code>image</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic, in response to the <code>image</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Started</code> The image capture process has started successfully. <code>Error</code> At least one field of the\u00a0<code>image</code>\u00a0command is missing or has an invalid value. <code>Error: missing camera</code> No camera is available to use for image acquisition. <code>Configuration update error: object_date is missing!</code> The last time the <code>update_config</code>\u00a0command was sent, it did not have an <code>object_date</code>\u00a0parameter. <code>Configuration update error: Chosen id are already in use!</code> The\u00a0<code>(object_date, sample_id, acq_id)</code>\u00a0combination for the dataset (set by the last <code>update_config</code>\u00a0command) is already used by a previous dataset. <code>Image {index}/{nb_frame} saved to {filename}</code> An image has been successfully captured and saved. <code>Image {index}/{nb_frame} WAS NOT CAPTURED! STOPPING THE PROCESS!</code> An error occurred during image capture; the ongoing image acquisition has finished with failure, resulting in an incomplete dataset. <code>Done</code> The image acquisition finished successfully, resulting in a complete dataset."},{"location":"reference/software/interfaces/mqtt/#stop-command_2","title":"<code>stop</code> command","text":"<p>This message interrupts any in-progress image acquisition routine and stops any ongoing sample pumping.</p> <pre><code>{\n  \"action\": \"stop\"\n}\n</code></pre> <p>The <code>stop</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>stop</code>\u00a0command. string <code>stop</code>"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_2","title":"<code>stop</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic, in response to the <code>stop</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error message Description <code>Interrupted</code> The image capture process was stopped successfully."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_3","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Starting up</code> The backend will soon attempt to initialize the camera. <code>Error: missing camera</code> A camera was not detected. <code>Ready</code> The camera is now operational, and the backend has become ready to respond to Imager commands. <code>Dead</code> The backend will no longer respond to Imager commands."},{"location":"reference/software/interfaces/mqtt/#segmenter","title":"Segmenter","text":"<p>The Segmenter API controls the processing of acquired images:</p> <ul> <li>MQTT topics for commands: <code>segmenter/segment</code></li> <li>MQTT topics for status updates: <code>status/segmenter</code>, <code>status/segmenter/object_id</code>, <code>status/segmenter/metric</code></li> <li>Commands: <code>segment</code></li> </ul> <p>For details on how images are processed, refer to our technical reference on image segmentation in the PlanktoScope.</p>"},{"location":"reference/software/interfaces/mqtt/#segment-command","title":"<code>segment</code> command","text":"<p>The <code>segment</code> command initiates processing of images stored in the specified path, optionally exporting the results to an EcoTaxa-compatible archive. The various <code>settings</code> parameters of this command provide control over the behavior of image processing. For example, this command initiates processing of all images in the <code>/path/to/segment</code> directory:</p> <pre><code>{\n  \"action\": \"segment\",\n  \"path\": \"/path/to/segment\",\n  \"settings\": {\n    \"force\": false,\n    \"recursive\": true,\n    \"ecotaxa\": true,\n    \"keep\": true\n  }\n}\n</code></pre> <p>The <code>segment</code> command has the following parameters:</p> Parameter Description Type Accepted Values <code>path</code> Path to the directory of images to process.Defaults to <code>/home/pi/data/img</code>. file path (string) any subdirectory of\u00a0<code>/home/pi/data/img</code> (optional) <code>settings</code>.<code>force</code> Force re-segmentation of already-processed directories, ignoring the existence of\u00a0<code>done</code>\u00a0files which otherwise prevent already-segmented directories from being processed again.Defaults to <code>false</code>. boolean <code>true</code>, <code>false</code> (optional) <code>settings</code>.<code>recursive</code> Process datasets in all subdirectories of\u00a0<code>path</code>.Defaults to <code>true</code>. boolean <code>true</code>, <code>false</code> (optional) <code>settings</code>.<code>ecotaxa</code> Export an EcoTaxa-compatible archive.Defaults to <code>true</code>. boolean <code>true</code>, <code>false</code> (optional) <code>settings.keep</code> Keep ROI files generated when exporting an EcoTaxa-compatible archive. It has no effect if <code>settings.ecotaxa</code>\u00a0is <code>false</code>.Defaults to <code>true</code>. boolean <code>true</code>, <code>false</code> (optional)"},{"location":"reference/software/interfaces/mqtt/#segment-command-responses","title":"<code>segment</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/segmenter</code> topic, in response to the <code>segment</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error message Description <code>Started</code> The segmentation process has begun. <code>Busy</code> The segmenter is currently running and cannot update configurations. <code>Calculating flat</code> The frame background is being calculated. <code>Segmenting image %s, image %d/%d</code> Segmentation of a specific image is in progress. <code>An exception was raised during the segmentation: %s.</code> An error occurred during segmentation. <code>Done</code> Processing has finished for the specified datasets. <p>As the Python backend performs segmentation, it will repeatedly send additional status updates on the <code>status/segmenter/object_id</code> topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:</p> Field Description Type <code>object_id</code> A scikit-image region label. integer <p>As the Python backend performs segmentation, it will repeatedly send additional status updates on the <code>status/segmenter/metric</code> topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:</p> Field Description Type <code>name</code> 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 <code>status/segmenter/object_id</code>. string <code>metadata</code> Metadata for the object. struct <p>The <code>metadata</code> field of status updates sent on the <code>status/segmenter/metric</code> topic is an object with the following fields:</p> Field Description Type <code>label</code> Label of the object. integer <code>width</code> Width of the smallest rectangle enclosing the object. integer <code>height</code> Height of the smallest rectangle enclosing the object. integer <code>bx</code> X coordinate of the top left point of the smallest rectangle enclosing the object. integer <code>by</code> Y coordinate of the top left point of the smallest rectangle enclosing the object. integer <code>circ</code> Circularity: (4 \u2217 \u03c0 \u2217 Area) / Perimeter^2. A value of 1 indicates a perfect circle, approaching 0 indicates an elongated polygon. float <code>area_exc</code> Surface area of the object excluding holes, in square pixels. integer <code>area</code> Surface area of the object in square pixels. integer <code>%area</code> Percentage of object\u2019s surface area that is comprised of holes. float <code>major</code> Primary axis of the best fitting ellipse for the object. float <code>minor</code> Secondary axis of the best fitting ellipse for the object. float <code>y</code> Y position of the center of gravity of the object. float <code>x</code> X position of the center of gravity of the object. float <code>convex_area</code> The area of the smallest polygon within which all points in the object fit. integer <code>perim</code> The length of the outside boundary of the object. float <code>elongation</code> The result of dividing the <code>major</code> parameter by the <code>minor</code> parameter. float <code>perimareaexc</code> The result of dividing the <code>perim</code> parameter by the <code>area_exc</code> parameter. float <code>perimmajor</code> The result of dividing the <code>perim</code> parameter by the <code>major</code> parameter. float <code>circex</code> (4 \u2217 \u03c0 \u2217 area_exc) / perim^2. float <code>angle</code> Angle between the primary axis and a line parallel to the x-axis of the image. float <code>bounding_box_area</code> Area of the bounding box enclosing the object. integer <code>eccentricity</code> Eccentricity of the object. float <code>equivalent_diameter</code> Diameter of a circle with the same area as the object. float <code>euler_number</code> Euler number of the object. integer <code>extent</code> Ratio of object area to bounding box area. float <code>local_centroid_col</code> Column position of the local centroid. float <code>local_centroid_row</code> Row position of the local centroid. float <code>solidity</code> Ratio of object area to convex area. float <code>MeanHue</code> Mean hue value of the object. float <code>MeanSaturation</code> Mean saturation value of the object. float <code>MeanValue</code> Mean value (brightness) of the object. float <code>StdHue</code> Standard deviation of the hue value of the object. float <code>StdSaturation</code> Standard deviation of the saturation value of the object. float <code>StdValue</code> Standard deviation of the value (brightness) of the object. float"},{"location":"reference/software/interfaces/mqtt/#stop-command_3","title":"<code>stop</code> command","text":"<p>The <code>stop</code> command interrupts any ongoing image processing. For example:</p> <pre><code>{\n  \"action\": \"stop\"\n}\n</code></pre> <p>The <code>stop</code> command has the following parameters:</p> Parameter Type Accepted Values Description <code>action</code> string \"stop\" Specifies the action to stop segmentation. <p>Warning</p> <p>The functionality for this command has not yet been implemented. Currently an <code>Interrupted</code> status is sent as a response on the <code>segmenter/segment</code> topic even though no interruption will actual happen.</p>"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_3","title":"<code>stop</code> command responses","text":"<p>The Python backend can send status updates on the <code>segmenter/segment</code> topic, in response to the <code>stop</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error message Description <code>Interrupted</code> The segmentation process was interrupted."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_4","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/segmenter</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Ready</code> The backend has become ready to respond to Segmenter commands. <code>Dead</code> The backend will no longer respond to Segmenter commands."},{"location":"reference/software/subsystems/installation/","title":"Installation","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/subsystems/installation/#installation-bootstrap-script","title":"Installation bootstrap script","text":"<p>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 <code>stable</code> 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:</p> <ol> <li> <p>The script loads some parameters (set by environment variables and/or corresponding command-line arguments) which set the behavior of the script.</p> </li> <li> <p>The script installs <code>git</code>, if it was not already installed (as is the case on the \"Lite\" image of the Raspberry Pi OS); if the <code>yes</code> parameter was not set and <code>git</code> was not already installed, the script will first ask the user to confirm that they wish to install <code>git</code> before the script continues. <code>git</code> 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.</p> </li> <li> <p>The script clones a minimal \"mirror\" copy of the specified repository (set by the <code>repo</code> parameter) of distro setup scripts to a temporary directory (i.e. a directory created in <code>/tmp</code>). This \"mirror\" copy is used to:</p> <ul> <li> <p>Resolve the version query parameters (<code>version-query</code>, <code>query-type</code>, and - when <code>query-type</code> is <code>tag</code> - <code>tag-prefix</code>) into a specific commit hash for the repository.</p> </li> <li> <p>Determine a (pseudo-)version string for the resolved commit based on the last release tag (whose name is prefixed with the <code>tag-prefix</code> parameter) ancestral to that commit.</p> </li> </ul> </li> <li> <p>The script clones a copy of the specified repository (set by the <code>repo</code> parameter) to a temporary directory and checks out the specific commit which was resolved by the previous step; if the <code>yes</code> 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.</p> </li> <li> <p>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 <code>yes</code> 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.</p> </li> <li> <p>The script runs the specified script (set by the <code>setup-entrypoint</code> parameter) within the downloaded copy of the specified repository; if the <code>yes</code> 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.</p> </li> </ol>"},{"location":"reference/software/subsystems/installation/#script-parameters","title":"Script parameters","text":"Command-Line Flags Environment Variable Name Description <code>-r</code><code>--repo</code> <code>REPO</code> 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:\u00a0<code>github.com/PlanktoScope/PlanktoScope</code> <code>-v</code><code>--version-query</code> <code>VERSION_QUERY</code> The version of the repository to download. The version query is interpreted differently depending on the query type set by the\u00a0<code>query-type</code>\u00a0parameter:<ul><li>Query type\u00a0\u00a0<code>branch</code>: query should be a branch name (e.g. <code>software/beta</code>).</li><li>Query type\u00a0<code>tag</code>: query should be a Git tag name, excluding the tag prefix specified by the <code>tag-prefix</code>\u00a0parameter (e.g. <code>v2024.0.0</code>\u00a0if <code>tag-prefix</code>\u00a0is <code>software</code>\u00a0and the Git tag is\u00a0<code>software/v2024.0.0</code>).</li><li>Query type\u00a0<code>hash</code>: query should be a commit hash and may be abbreviated (e.g. <code>2d6928e</code>).</li></ul>Default value: <code>software/stable</code> <code>-t</code><code>--query-type</code> <code>QUERY_TYPE</code> The type of version query set by the <code>version-query</code>\u00a0parameter.Allowed values: <code>branch</code>, <code>tag</code>, <code>hash</code>.Default value: <code>branch</code> <code>-H</code><code>--hardware</code> <code>HARDWARE</code> The hardware configuration, passed as the first argument to the entrypoint of the distro setup scripts. The distro setup scripts in the\u00a0<code>github.com/PlanktoScope/PlanktoScope</code>\u00a0repo currently expect either <code>none</code>, <code>segmenter-only</code>,\u00a0<code>adafruithat</code>,\u00a0<code>planktoscopehat</code>, or <code>fairscope-latest</code>.Default value: <code>planktoscopehat</code> <code>--tag-prefix</code> <code>TAG_PREFIX</code> The prefix for Git version tags when resolving the version query (with query type\u00a0<code>tag</code>) and when resolving tags (for pseudoversion strings).\u00a0Default value: <code>software/</code> <code>--setup-entrypoint</code> <code>SETUP_ENTRYPOINT</code> 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 <code>repo</code>\u00a0parameter) which will be downloaded at the specified commit (set by the <code>version-query</code>\u00a0and <code>query-type</code>\u00a0parameters and - when <code>query-type</code>\u00a0is <code>tag</code>\u00a0- by the <code>tag-prefix</code>\u00a0parameter) to obtain the distro setup scripts.Default value: <code>software/distro/setup/setup.sh</code> <code>-y</code><code>-f</code><code>--yes</code><code>--force</code> <code>FORCE</code> Whether to automatically confirm all user confirmation prompts:<ul><li><code>FORCE=1</code>\u00a0(or including the command-line flag) automatically confirms all prompts.</li><li>Not setting <code>FORCE</code> (or not including the command-line flag) requires user input for confirmation on all prompts.</li></ul>Default: User input required <code>-V</code><code>--verbose</code> <code>VERBOSE</code> Whether to display additional (verbose) output:<ul><li><code>VERBOSE=1</code>\u00a0(or including the command-line flag) enables verbose output.</li><li>Not setting <code>VERBOSE</code> (or not including the command-line flag) disables verbose output.</li></ul>Default: Don't display verbose output <code>-h</code><code>--help</code> 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. <p>Example combinations of command-line arguments using the above parameters:</p> <ul> <li> <p><code>-v software/stable -H planktoscopehat</code> or <code>-H planktoscopehat</code>: install the latest stable release of the standard PlanktoScope OS (i.e. from the <code>software/stable</code> branch) for a PlanktoScope with the PlanktoScope HAT.</p> </li> <li> <p><code>-v software/beta -H adafruithat</code>: install the latest beta pre-release or stable release of the standard PlanktoScope OS (i.e. from the <code>software/beta</code> branch) for a PlanktoScope with the Adafruit HAT.</p> </li> <li> <p><code>-v master -H planktoscopehat</code>: install the latest development version of the standard PlanktoScope OS (i.e. from the <code>master</code> branch) for a PlanktoScope with the PlanktoScope HAT.</p> </li> <li> <p><code>-t tag -v v2024.0.0-alpha.1 -H adafruithat</code>: install the v2024.0.0-alpha.1 pre-release of the standard PlanktoScope OS (i.e. from the <code>software/v2024.0.0-alpha.1</code> tag) for a PlanktoScope with the Adafruit HAT.</p> </li> <li> <p><code>-t hash -v 2d6928e -H planktoscopehat</code>: install <code>2d6928e</code> commit of the standard PlanktoScope OS for a PlanktoScope with the PlanktoScope HAT.</p> </li> <li> <p><code>-v master -r github.com/LaurentPV/PlanktoScope -H adafruithat</code>: install the latest development commit of <code>master</code> branch of the <code>github.com/LaurentPV/PlanktoScope</code> fork of the PlanktoScope OS for a PlanktoScope with the Adafruit HAT.</p> </li> </ul>"},{"location":"reference/software/subsystems/installation/#recorded-versioning-information","title":"Recorded versioning information","text":"<p>Currently the installer script creates two YAML files, both in the <code>/usr/share/planktoscope</code> directory.</p> <p><code>/usr/share/planktoscope/installer-config.yml</code> records the values of the parameters with which the installer script was invoked:</p> YAML Field Name Corresponding Script Parameter Example Value <code>repo</code> <code>repo</code> <code>\"github.com/PlanktoScope/PlanktoScope\"</code> <code>version-query</code> <code>version-query</code> <code>\"v2024.0.0-alpha.1\"</code> <code>query-type</code> <code>query-type</code> <code>\"tag\"</code> <code>hardware</code> <code>hardware</code> <code>\"adafruithat\"</code> <code>tag-prefix</code> <code>tag-prefix</code> <code>\"software/\"</code> <code>setup-entrypoint</code> <code>setup-entrypoint</code> <code>\"software/distro/setup/setup.sh\"</code> <p><code>/usr/share/planktoscope/installer-versioning.yml</code> records information about the version of the PlanktoScope OS's distro setup scripts which was used to install the PlanktoScope OS:</p> Field Name Description <code>repo</code> The path of the Git repository which provided the distro setup scripts, with any leading protocol string (e.g. <code>https://</code>) removed.Example Values: <ol><li><code>\"github.com/PlanktoScope/PlanktoScope\"</code></li><li><code>\"github.com/PlanktoScope/PlanktoScope\"</code></li></ol> <code>commit</code> The full hash of the exact commit which provided the distro setup scripts.Example Values: <ol><li><code>\"2d6928e596b28f0c4c268fecb588c85215b1027e\"</code>\u00a0(for commit <code>2d6928e</code>)</li><li><code>\"4d8b882616a8374918730bc1c6d300edfd7a523a\"</code>\u00a0(for commit <code>4d8b882</code>)</li></ol> <code>tag</code> The full name of the Git tag (whose name starts with the prefix set by the <code>tag-prefix</code>\u00a0script parameter) at the exact commit which provided the distro setup scripts, if such a tag exists; otherwise, the empty string (<code>\"\"</code>).Example Values: <ol><li><code>\"software/v2024.0.0-alpha.1\"</code>\u00a0(so commit <code>2d6928e</code>\u00a0has Git tag <code>software/v2024.0.0-alpha.1</code>)</li><li><code>\"\"</code>\u00a0(so commit <code>4d8b882</code>\u00a0has no Git tag)</li></ol> <code>version</code> 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 <code>tag-prefix</code>\u00a0script parameter) exists at that commit, this is a version string which just the name of that tag, but with the <code>tag-prefix</code>\u00a0stripped from the name. Otherwise, this is a pseudo-version string with format <code>\"{tag}-{distance}-g{commit}\"</code>, where:<ul><li><code>{tag}</code>\u00a0is the name of the most recent ancestral tag (with a name starting with the prefix set by the <code>tag-prefix</code>\u00a0script parameter) reachable from the commit, but with the <code>tag-prefix</code>\u00a0stripped from the name.<li><code>{distance}</code>\u00a0distance (in number of commits) between the commit and the most recent ancestral tag.</li><li><code>{commit}</code>\u00a0consists of the first seven characters of the hash of the commit.</li>Example Values: <ol><li><code>\"v2024.0.0-alpha.1\"</code>\u00a0(so commit <code>2d6928e</code>\u00a0has Git tag <code>software/v2024.0.0-alpha.1</code>)</li><li><code>\"v2024.0.0-alpha.1-4-g4d8b882\"</code>\u00a0(so commit <code>4d8b882</code>\u00a0is 4 commits above the commit with Git tag <code>software/v2024.0.0-alpha.1</code>, which was the last tag in the ancestry of the commit)</li></ol>"},{"location":"reference/software/subsystems/installation/#distro-setup-scripts","title":"Distro setup scripts","text":"<p>Currently, the entrypoint of the distro setup scripts, at <code>software/distro/setup/setup.sh</code>, takes exactly one command-line argument which must be one of the following values:</p> <ul> <li> <p><code>adafruithat</code>: 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.</p> </li> <li> <p><code>planktoscopehat</code>: 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.</p> </li> </ul> <p>Currently, the distro setup scripts must be run by a user named <code>pi</code>. The scripts should not be run with <code>sudo</code>!</p> <p>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 <code>forklift</code>), we may consolidate these two phases into a single phase.</p>"},{"location":"reference/software/subsystems/installation/#base-system-setup","title":"Base system setup","text":"<p>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:</p> <ul> <li> <p>Installation of base tools: Docker, Cockpit, and various command-line tools are installed.</p> </li> <li> <p>Installation of <code>forklift</code> and a Forklift pallet: a hard-coded version of <code>forklift</code> is downloaded to <code>/usr/bin/forklift</code> , a hard-coded version of a hard-coded pallet (namely, github.com/PlanktoScope/pallet-standard) is downloaded and prepared for deployment, and the <code>forklift-apply.service</code> 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.)</p> </li> <li> <p>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.</p> </li> <li> <p>Configuration of the system locale: the system's language is changed to <code>en_US.UTF-8</code>, but the time and measurement formats are changed to <code>en_DK.UTF-8</code> so that the date format is <code>yyyy-mm-dd</code> and units are metric. The system timezone is set to UTC.</p> </li> <li> <p>Partial configuration of networking: various system services are installed and configured, namely <code>dhcpcd</code>, <code>dnsmasq</code>, <code>hostapd</code>, and <code>firewalld</code>. The <code>enable-interface-forwarding.service</code> and <code>autohotspot.service</code> systemd services are created and enabled. The Raspberry Pi's Wi-Fi country is set to the US.</p> </li> <li> <p>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.</p> </li> </ul>"},{"location":"reference/software/subsystems/installation/#planktoscope-application-environment-setup","title":"PlanktoScope application environment setup","text":"<p>This phase performs steps specific to the PlanktoScope's hardware:</p> <ul> <li> <p>Remaining configuration of networking: a hard-coded version of <code>machine-name</code> is downloaded to <code>/usr/bin/machine-name</code>, <code>avahi-utils</code> 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 <code>machine-name</code> 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, <code>pkscope.local</code> and <code>planktoscope.local</code>).</p> </li> <li> <p>Setup of the PlanktoScope hardware controller: various Python tools (<code>pip</code>, <code>venv</code>, and <code>poetry</code>) 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 <code>planktoscope-org.device-backend.controller-adafruithat.service</code> and <code>planktoscope-org.device-backend.controller-planktoscopehat.service</code> 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.)</p> </li> <li> <p>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.)</p> </li> <li> <p>Setup of the PlanktoScope Node-RED dashboard: Node-RED is installed, as well as a Python package required by the <code>adafruithat</code> 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, <code>npm</code> 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.)</p> </li> <li> <p>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.)</p> </li> <li> <p>Setup of hardware support for the PlanktoScope's GPS receiver: <code>gpsd</code> and <code>chrony</code> are installed and configured. (Note: currently the configurations may be incorrect.)</p> </li> <li> <p>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.)</p> </li> <li> <p>Cleanup: unnecessary APT and <code>pip</code> files are removed.</p> </li> </ul>"},{"location":"reference/software/subsystems/startup/","title":"Startup","text":"<p>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.</p>"},{"location":"reference/software/subsystems/startup/#services","title":"Services","text":"<p>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:</p>"},{"location":"reference/software/subsystems/startup/#software-deployment-execution","title":"Software deployment &amp; execution","text":"<p>In general:</p> <ul> <li> <p><code>dockerd</code> (managed by <code>docker.service</code>) can start before network connectivity has been established; this is not the default behavior for <code>dockerd</code>.</p> </li> <li> <p>All daemons &amp; 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.</p> </li> </ul> <p>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:</p> <ul> <li> <p><code>overlay-sysroot.service</code> runs after <code>-.mount</code> and <code>systemd-remount-fs.service</code>.</p> </li> <li> <p><code>bindro-run-forklift-stages-current.service</code> runs after <code>-mount</code> and <code>systemd-remount-fs.service</code> and before <code>overlay-fs.target</code>.</p> </li> <li> <p><code>overlay-usr.service</code> runs after <code>overlay-sysroot.service</code> and before <code>overlay-fs.target</code>.</p> </li> <li> <p><code>overlay-etc.service</code> runs after <code>overlay-sysroot.service</code> and  <code>systemd-machine-id-commit.service</code> , and before <code>systemd-sysctl.service</code> and <code>overlay-fs.target</code>.</p> </li> <li> <p><code>start-overlaid-units.service</code> runs after <code>overlay-fs.target</code> and <code>basic.target</code>.</p> </li> <li> <p><code>bind-.local-share-forklift-stages@home-pi.service</code> runs after <code>-.mount</code>, <code>home.mount</code>, and <code>basic.target</code>.</p> </li> <li> <p><code>forklift-apply.service</code>, which uses the <code>forklift</code> tool to start all Docker Compose applications, runs after <code>docker.service</code> has started. Docker Compose applications managed with <code>forklift</code> are sequenced by <code>forklift-apply.service</code> according to the resource dependency relationships declared by the Forklift packages which provide those applications.</p> </li> </ul>"},{"location":"reference/software/subsystems/startup/#networking","title":"Networking","text":"<p>For descriptions of the various targets (e.g. <code>sysinit.target</code>, <code>network-pre.target</code>) referred to below, see systemd's bootup process and systemd's special targets:</p> <ul> <li> <p><code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> runs before <code>sysinit.target</code>.</p> </li> <li> <p><code>update-hostname.service</code> runs after <code>generate-hostname-templated.service</code> and <code>systemd-hostnamed.service</code> but before <code>network-pre.target</code>.</p> </li> <li> <p><code>assemble-dnsmasq-config-templated.service</code> runs after <code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> but before <code>dnsmasq.service</code>.</p> </li> <li> <p><code>assemble-hosts-templated.service</code> and <code>assemble-hosts.service</code> run after <code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> but before <code>dnsmasq.service</code> and <code>network-pre.target</code>.</p> </li> <li> <p><code>enable-interface-forwarding.service</code> runs before <code>network-online.target</code>.</p> </li> <li> <p><code>assemble-hostapd-config-templated.service</code> and <code>assemble-hostapd-config.service</code> run after <code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> but before <code>hostapd.service</code>.</p> </li> <li> <p>The <code>hostapd</code> daemon is manually started and stopped by <code>autohotspot.service</code>.</p> </li> <li> <p><code>autohotspot.service</code> runs after <code>forklift-apply.service</code> and <code>enable-interface-forwarding.service</code> 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 <code>autohotspot.timer</code>.</p> </li> <li> <p><code>planktoscope-mdns-alias@pkscope.service</code> and <code>planktoscopemdns-alias@planktoscope.service</code> configure the Avahi daemon (provided by the Raspberry Pi OS) to also resolve mDNS names <code>pkscope.local</code> and <code>planktoscope.local</code>, 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.</p> </li> </ul>"},{"location":"reference/software/subsystems/startup/#user-interface","title":"User interface","text":"<ul> <li> <p><code>assemble-cockpit-config.service</code>, <code>assemble-cockpit-origins.service</code>, and <code>assemble-cockpit-origins-templated.service</code> update Cockpit's configuration file  from drop-in config file fragments in <code>/etc/cockpit/cockpit.conf.d</code>, <code>/etc/cockpit/origins.d</code>, and <code>/etc/cockpit/origins-templates.d</code>, respectively. They run after <code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> and before <code>cockpit.service</code>.</p> </li> <li> <p><code>ensure-ssh-host-keys.service</code> regenerates the SSH server's host keys if the keys are missing, and runs before <code>ssh.service</code>.</p> </li> <li> <p>The PlanktoScope Node-RED dashboard (managed by <code>nodered.service</code>) starts after <code>planktoscope-org.update-machine-name.service</code> 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 <code>forklift</code>.)</p> </li> </ul>"},{"location":"reference/software/subsystems/startup/#planktoscope-specific-hardware-abstraction","title":"PlanktoScope-specific hardware abstraction","text":"<ul> <li>The PlanktoScope hardware controller (managed by <code>planktoscope-org.device-backend.controller-{adafruithat or planktoscopehat}.service</code>) starts after <code>forklift-apply.service</code> (which manages Mosquitto) and <code>nodered.service</code> 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 <code>forklift</code>.)</li> </ul>"},{"location":"setup/","title":"Setup","text":"<p>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:</p> <ul> <li>\"I have a product from FairScope\": you probably received either a fully-assembled Planktoscope or a PlanktoScope do-it-yourself assembly kit. For more information, see the FairScope product section of this page.</li> <li>\"I have a fully assembled PlanktoScope, and it was not assembled by FairScope\": you will need to ensure that you have the latest version of the PlanktoScope software installed on the PlanktoScope, and that the PlanktoScope hardware works. For more information, see the Fully-assembled PlanktoScope section of this page.</li> <li>\"I have a kit of hardware parts to assemble into a PlanktoScope, and it was not provided by FairScope\": you will need to assemble your PlanktoScope hardware and then set up the software on it. For more information, see the DIY kit section of this page.</li> <li>\"I don't have any of the hardware for the PlanktoScope\": you have several options for getting the PlanktoScope hardware. For more information, see the No hardware yet section of this page.</li> </ul>"},{"location":"setup/#fairscope-product","title":"FairScope product","text":"<p>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:</p> <ul> <li>If you purchased a fully-assembled PlanktoScope, it is ready for you to use! You should go to our operation guide to learn how to operate your PlanktoScope.</li> <li>If you purchased a do-it-yourself assembly kit from FairScope, you should go to our hardware setup guide to learn how to assemble your kit into a working PlanktoScope. The software will already have been set up for you, so after you finish setting up the hardware you can proceed to our operation guide to learn how to operate your PlanktoScope.</li> </ul>"},{"location":"setup/#fully-assembled-planktoscope","title":"Fully-assembled PlanktoScope","text":"<p>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:</p> <ul> <li>Depending on what software is pre-installed on your PlanktoScope, and how old the software is, our software setup guide may be useful to help you update the software. You should always ensure that you are running the most recent available version of the PlanktoScope software.</li> <li>Depending on what software configuration your PlanktoScope is running, our operation guide may be useful to help you operate your PlanktoScope.</li> </ul>"},{"location":"setup/#diy-kit","title":"DIY kit","text":"<p>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:</p> <ul> <li>Depending on what is included in your DIY kit, our hardware setup guide may be useful to assemble a PlanktoScope from your kit.</li> <li>Depending on what is on the micro-SD card included with your DIY kit (if it includes a micro-SD card), our software setup guide may be useful to help you update the software. You should always ensure that you are running the most recent available version of the PlanktoScope software.</li> <li>Depending on what software configuration your PlanktoScope is running, our operation guide may be useful to help you operate your PlanktoScope.</li> </ul>"},{"location":"setup/#no-hardware-yet","title":"No hardware yet","text":"<p>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:</p> <ol> <li>Purchase a fully pre-assembled PlanktoScope.</li> <li>Purchase a DIY kit of parts to assemble into a PlanktoScope.</li> <li>Both make your own kit of parts and assemble it into a PlanktoScope.</li> </ol>"},{"location":"setup/#buy-a-pre-assembled-planktoscope","title":"Buy a pre-assembled PlanktoScope","text":"<p>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.</p> <p>We recommend this approach for:</p> <ul> <li>Anyone who wants a PlanktoScope which \"just works\" out-of-the-box.</li> <li>Scientists who just want to collect data and don't want to become engineers.</li> <li>Anyone who just wants to use the PlanktoScope as a tool, rather than tinkering with their PlanktoScope as a project.</li> </ul>"},{"location":"setup/#buy-a-diy-kit","title":"Buy a DIY kit","text":"<p>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.</p> <p>We recommend this approach for:</p> <ul> <li>Anyone who wants a standard PlanktoScope but is on a limited budget, and has some interest in building things and troubleshooting problems.</li> <li>Anyone who wants to approach the PlanktoScope as a project and not just a tool, but who has a limited tolerance of technical complexity.</li> <li>Anyone who wants a do-it-yourself experience but does not have access to a laser cutter or CNC mill.</li> <li>Anyone who wants a standard set of parts as the foundation for customizing their PlanktoScope.</li> <li>Engineers and makers who don't want to worry about figuring out suppliers and making their own one-time supply chain in order to obtain all the hardware parts needed to build a single PlanktoScope.</li> </ul>"},{"location":"setup/#make-a-kit-and-assemble-it","title":"Make a kit and assemble it","text":"<p>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.</p> <p>We recommend this approach for:</p> <ul> <li>Anyone who is on an extremely limited budget but has lots of time and some hardware engineering experience.</li> <li>Makers who are already familiar with laser cutting or CNC milling, and with soldering or PCB assembly (the necessary skills will depend on the version of PlanktoScope hardware being built).</li> <li>Hobbyists and students who are primarily interested in the PlanktoScope as an engineering project and want to figure out everything by themselves.</li> <li>Anyone who wants to design and build an extremely non-standard PlanktoScope, whether for fun or to use it for unconventional purposes.</li> </ul>"},{"location":"setup/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"location":"setup/hardware/","title":"PlanktoScope Hardware","text":"<p>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.</p> <p>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.</p> <p>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.</p>"},{"location":"setup/hardware/#hardware-versions","title":"Hardware versions","text":"<p>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.</p>"},{"location":"setup/hardware/#hardware-v21","title":"Hardware v2.1","text":"<p>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.</p> <p>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.</p>"},{"location":"setup/hardware/#hardware-v25","title":"Hardware v2.5","text":"<p>This version includes many design improvements to solve various problems with the v2.1 hardware design, including:</p> <ul> <li> <p>Replacing the ibidi flowcell with a simpler glass capillary flowcell.</p> </li> <li> <p>Replacing the Adafruit Stepper Motor HAT with a HAT designed specifically for the PlanktoScope (the PlanktoScope HAT).</p> </li> <li> <p>Replacing the linear actuators for sample focusing with a more mechanically robust pair of linear actuators.</p> </li> <li> <p>Replacing the peristaltic pump with a more accurate pump which is commercially available.</p> </li> <li> <p>Making the Raspberry Pi's micro-SD card accessible without requiring disassembly of the PlanktoScope.</p> </li> </ul> <p>The mechanical structure of this design uses CNC-milled parts rather than laser-cut parts.</p> <p>Our documentation site provides manufacturing documentation to make assembly kits for this hardware version, and to assemble kits for this version into PlanktoScopes.</p>"},{"location":"setup/hardware/#choosing-a-version","title":"Choosing a version","text":"<p>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:</p> <ul> <li> <p>You do not have access to a CNC mill, or to a commercial fabrication service with a CNC mill.</p> </li> <li> <p>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.</p> </li> </ul>"},{"location":"setup/hardware/#building-a-planktoscope","title":"Building a PlanktoScope","text":"<p>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.</p> <p>Once you have figured out what hardware version of the PlanktoScope you will build, you can proceed to our version-specific hardware setup guides:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul>"},{"location":"setup/hardware/#next-steps","title":"Next steps","text":"<p>After making an assembly kit (if necessary) and building a PlanktoScope from your assembly kit, you should proceed to our software setup guide.</p>"},{"location":"setup/hardware/index-noguides/","title":"PlanktoScope Hardware","text":"<p>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.</p>"},{"location":"setup/hardware/v2.1/","title":"Hardware v2.1","text":"<p>This page will help you to build the v2.1 hardware for a PlanktoScope.</p>"},{"location":"setup/hardware/v2.1/#make-an-assembly-kit","title":"Make an assembly kit","text":"<p>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.</p> <p>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.</p>"},{"location":"setup/hardware/v2.1/#assemble-a-planktoscope-from-a-kit","title":"Assemble a PlanktoScope from a kit","text":"<p>Once you have an assembly kit, you will need to assemble it into a PlanktoScope.</p>"},{"location":"setup/hardware/v2.1/#next-steps","title":"Next steps","text":"<p>Once you have assembled your PlanktoScope, you can proceed to our operation guide\u00a0to learn how to operate your PlanktoScope.</p>"},{"location":"setup/hardware/v2.1/assembly/","title":"Assembly guide of the PlanktoScope","text":"<p>You can also use CAD renders and photos from the following links as a supplementary material for this assembly guide:</p> <ul> <li>CAD renders for the assembly guide</li> <li>Photos for the assembly guide</li> </ul> <p>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:</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-1-gather-everything-you-need","title":"Step 1: Gather everything you need","text":"<p>For the full list of all required tools and parts, please refer to the v2.1 hardware kit production guide.</p> <ul> <li>Laser cut structure</li> <li>M12 lenses</li> <li>Peristaltic pump and tubing</li> <li>Raspberry Pi, motor driver board, GPIO connectors</li> <li>Flashed SD card</li> <li>Stepper motors</li> <li>PiCam and flex cable</li> <li>GPIO ribbon connector, headers, HATs, LED</li> <li>DC Power terminal</li> <li>Magnets</li> <li>Super glue</li> <li>Standoffs (M2.5), M3 screws and nuts</li> </ul> <p>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.</p> <p>If you are not familiar with any process, such as soldering, tapping, or wiring, try and familiarize yourself with the topics first.</p> <p>Soldering deals with high heat and potentially toxic materials, so make sure to use the proper precautions.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-2-standoff-installation","title":"Step 2: Standoff installation","text":"<p>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.</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-3-motor-hat-preparation","title":"Step 3: Motor HAT preparation","text":"<p>Insert and solder the terminal blocks and headers onto the motor driver PCB. </p> <p></p> <p>Place the motor driver PCB on to the indicated standoffs.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-4-magnets-setup","title":"Step 4: Magnets setup","text":"<p>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.</p> <p></p> <p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-5-sample-stage-assembly","title":"Step 5: Sample stage assembly","text":"<p>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.</p> <p></p> <p>You should now have a sample stage and motor assembly that looks like this.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-6-lenses-tapping-and-mounting","title":"Step 6: Lenses tapping and mounting","text":"<p>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).</p> <p> </p> <p></p> <p>You can now screw the objective lens (the 25mm one) in part D. </p>"},{"location":"setup/hardware/v2.1/assembly/#step-7-camera-preparation","title":"Step 7: Camera preparation","text":"<p>You can now unscrew the lens from the Pi camera, being careful not to disturb the sensor below.  </p>"},{"location":"setup/hardware/v2.1/assembly/#step-8-camera-mount","title":"Step 8: Camera mount","text":"<p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-9-led-preparation","title":"Step 9: LED preparation","text":"<p>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.</p> <p>Warning</p> <p></p> <p>This picture shows the correct wiring for the LED. Please make sure the red wire is on the long pin of the LED.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-10-vertical-slices-assembly","title":"Step 10: Vertical slices assembly","text":"<p>You can now start placing the motor mount/LED assembly- B, </p> <p>C, </p> <p>D, </p> <p>E, </p> <p>F, </p> <p>and G into the base A.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-11-pump-setup","title":"Step 11: Pump setup","text":"<p>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. </p> <p>Fix the pump in place. </p>"},{"location":"setup/hardware/v2.1/assembly/#step-12-pump-mounting","title":"Step 12: Pump mounting","text":"<p>You can now mount the pump on base A. </p> <p>Your setup should look like this. Don't worry about the wiring, we'll have a look at it in the next step!</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-13-motor-hat-wiring","title":"Step 13: Motor HAT wiring","text":"<p>You will now want to wire the steppers and pump to the terminals on the motor driver board.</p> <p>Info</p> <p>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.</p> <p>You can find more information about stepper motors and how they work in this document.</p> <p>Tip</p> <p>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.</p> <p>Tip</p> <p>Make sure the wires are properly connected by pulling on them a little. They should not come loose.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-14-raspberry-pi-setup-and-installation","title":"Step 14: Raspberry Pi setup and installation","text":"<p>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.</p> <p></p> <p>Mount the Raspberry Pi containing the flashed SD card on the standoffs attached to the laser cut base A.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-15-standoffs","title":"Step 15: Standoffs","text":"<p>Add 8 standoffs (M2.5 15mm) to fix the motor driver board and the Raspberry Pi to the base. </p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-16-camera-flex-cable","title":"Step 16: Camera flex cable","text":"<p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-17-power-supply-wiring","title":"Step 17: Power supply wiring","text":"<p>The power wires can be wired into place on the motor driver board.</p> <p>Tip</p> <p>Make sure the wires are properly connected by pulling on them a little. They should not come loose.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-18-prepare-the-gps-hat","title":"Step 18: Prepare the GPS HAT","text":"<p>Tip</p> <p>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.</p> <p></p> <p>Insert the battery to power the GPS HAT and solder the terminal mounts in place.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-19-install-the-gps-hat","title":"Step 19: Install the GPS HAT","text":"<p>Mount the GPS HAT over the motor driver PCB using the standoffs attached to the laser cut base A.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-20-install-the-fan-hat","title":"Step 20: Install the Fan HAT","text":"<p>Place the cooling fan HAT above the Raspberry Pi by mounting it to the standoffs on base A.</p> <p>Warning</p> <p>Be careful to slide the camera flat cable in the slot in the HAT above the connector.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-21-secure-the-hats","title":"Step 21: Secure the HATS","text":"<p>Secure the cooling fan HAT and GPS HAT by tightening the 8 screws to the standoffs on base A</p>"},{"location":"setup/hardware/v2.1/assembly/#step-22-install-back-panel","title":"Step 22: Install back panel","text":"<p>Insert the laser cut border I into base A.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-23-gps-output-connector","title":"Step 23: GPS output connector","text":"<p>Insert the power and GPS connectors into side plate J.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-24-install-side-panel","title":"Step 24: Install side panel","text":"<p>Place the side plate J into the designated slots on the base. You can connect the GPS cable to its connector on the board.</p> <p>Warning</p> <p>The GPS connector is quite fragile, make sure to align it properly before inserting it.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-25-install-the-other-side-panel","title":"Step 25: Install the other side panel","text":"<p>Mount the side plate K on base A using the assigned slots.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-26-secure-the-sides-together","title":"Step 26: Secure the sides together","text":"<p>Secure the laser cut sides with the screws and nuts.</p>"},{"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":"<p>Secure the laser cut sides to the base plate A with the screws and nuts.</p> <p>Warning</p> <p>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.</p>"},{"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":"<p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-29-assemble-the-gpio-ribbon-cable","title":"Step 29: Assemble the GPIO ribbon cable","text":"<p>If you didn't get an already assembled ribbon cable, you need to build it yourself.</p> <p>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.</p> <p>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.</p> <p>Warning</p> <p>Once assembled, the ribbon should NOT look like this: </p> <p>It should rather look like this: </p>"},{"location":"setup/hardware/v2.1/assembly/#step-30-insert-the-ribbon-cable","title":"Step 30: Insert the ribbon cable","text":"<p>Attach the GPIO ribbon to connect the cooling fan HAT to the GPS HAT.</p> <p>Tip</p> <p>You can try to route the flat ribbon from the camera under the ribbon cable you are connecting now. </p>"},{"location":"setup/hardware/v2.1/assembly/#step-31-fluidic-assembly","title":"Step 31: Fluidic assembly","text":"<p>Feed in the tubing from syringe 1 to form the fluidic path as shown.</p> <p></p> <p>Feed in the tubing from syringe 2 to form the fluidic path as shown</p> <p></p> <p>Feed in a length of tubing as shown through motor mount H and illumination mount FE</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-32-close-your-planktoscope","title":"Step 32: Close your PlanktoScope","text":"<p>Warning</p> <p>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.</p> <p></p> <p>Place the top L into the slots on the PlanktoScope body. Secure it in place with screws and nuts.</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-33-enjoy","title":"Step 33: Enjoy!","text":"<p>Congratulations on a job well done. You can have some rest, get a tea and some biscuits!</p> <p></p> <p>Warning</p> <p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#next-steps","title":"Next steps","text":"<p>Once your PlanktoScope fully works, you can proceed to our operation guide\u00a0to learn how to operate your PlanktoScope.</p>"},{"location":"setup/hardware/v2.1/kit/","title":"Kit Production","text":""},{"location":"setup/hardware/v2.1/kit/#required-tools","title":"Required Tools","text":"<p>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.</p>"},{"location":"setup/hardware/v2.1/kit/#soldering-station","title":"Soldering Station","text":"<p> A soldering station with flux, or flux core solder, is necessary for making a few electrical connections. Purchase here.</p>"},{"location":"setup/hardware/v2.1/kit/#tap-wrench","title":"Tap Wrench","text":"<p> Any tap wrench compatible with the M12x0.5 tap will work. Purchase here.</p>"},{"location":"setup/hardware/v2.1/kit/#m12-x-05-tap","title":"M12 x 0.5 Tap","text":"<p> An M12x0.5 tap is required to secure the objective and tube lenses. Purchase here.</p>"},{"location":"setup/hardware/v2.1/kit/#screwdriver-kit","title":"Screwdriver Kit","text":"<p> A screwdriver kit with multiple drivers simplifies many assembly operations. Purchase here.</p>"},{"location":"setup/hardware/v2.1/kit/#required-components","title":"Required Components","text":"<p>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.</p>"},{"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 &amp; 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":"<p>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.</p>"},{"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":"<p>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:</p> <ul> <li>5 mm thickness: SVG file (recommended), DXF file</li> <li>1/4 inch thickness: DXF file</li> </ul> <p>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:</p> <p></p> <p>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.</p>"},{"location":"setup/hardware/v2.5/","title":"Hardware v2.5","text":"<p>This page will help you to build the v2.5 hardware for a PlanktoScope.</p>"},{"location":"setup/hardware/v2.5/#make-an-assembly-kit","title":"Make an assembly kit","text":"<p>If you do not already have an assembly kit, you will need to make a kit for yourself.</p>"},{"location":"setup/hardware/v2.5/#assemble-a-planktoscope-from-a-kit","title":"Assemble a PlanktoScope from a kit","text":"<p>Once you have an assembly kit, you will need to assemble it into a PlanktoScope.</p>"},{"location":"setup/hardware/v2.5/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"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":"<p>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.</p> <p></p> Bag Content A Scews B Tools C Adhesive Pads D Tubing, Glass Cuvettes E Bubbler Pump F Peristaltic Pump G Linear Stepper Motor H Raspberry PI Chip cooler I Raspberry HAT J Camera Lens K MicroSD Card, DC Power Jack Socket L DC Power Supply and Cable M Syringe and Falcon Tube X1 Raspberry PI 4 X2 Pipet X3 Cable ties X4 Raspberry PI HQ Camera Modul X5 Sandpaper <p>If any bags are missing, please go back to the BOM (Bill of Materials) and reorder the required components.</p>"},{"location":"setup/hardware/v2.5/assembly/#about-this-document","title":"About this document","text":"<p>To read this document, follow these guidelines:</p>"},{"location":"setup/hardware/v2.5/assembly/#color-codes","title":"Color codes","text":"<ul> <li>\ud83d\udd34\u00a0Look to the color red</li> <li>\ud83d\udfe0\u00a0Look to the color orange</li> <li>\ud83d\udfe1\u00a0Look to the color yellow</li> <li>\ud83d\udfe2\u00a0Look to the color green</li> <li>\ud83d\udd35\u00a0Look to the color blue</li> <li>\ud83d\udfe3\u00a0Look to the color purple</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#icons","title":"Icons","text":"<ul> <li>\ud83d\udc41\u00a0Pay attention to this</li> <li>\u26a0\u00a0Be careful with this</li> <li>\ud83d\udcdc\u00a0The book says</li> <li>\ud83c\udfac\u00a0Action !</li> <li>\u274c\u00a0Don't focus on that location</li> </ul> <p>As you read through the document, be sure to pay attention to these visual cues to guide you through the build process.</p>"},{"location":"setup/hardware/v2.5/assembly/#requirements","title":"Requirements","text":""},{"location":"setup/hardware/v2.5/assembly/#tools","title":"Tools","text":"<p>Content of\u00a0Bag B:</p> <ul> <li>\ud83d\udd34\u00a0B1. Small flat screwdriver 2mm</li> <li>\ud83d\udfe0\u00a0B2. Razor blade</li> <li>\ud83d\udfe1\u00a0B3. Allen key 2mm</li> <li>\ud83d\udfe2 B4. Wrenches for standoffs</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#components","title":"Components","text":"<p>Content of\u00a0Bag A:</p> <ul> <li>\ud83d\udfe2\u00a0A1. Standoff M2.5 - 6mm - Brass</li> <li>\ud83d\udd35\u00a0A2. Standoff M2.5 - 15mm - \u00a0Brass</li> <li>\ud83d\udfe3\u00a0A3. Standoff M2.5 - 16mm - SS</li> <li>\ud83d\udfe0\u00a0A4. Screw M2.5x5mm CHC - SS</li> <li>\ud83d\udfe1\u00a0A5. Screw M2.5x10mm CHC - SS</li> <li>\ud83d\udd34\u00a0A6. Screw M3x12mm BHC - SS</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#chapter-1-detach-the-parts-from-panels-by-cutting-the-tabs","title":"Chapter 1: Detach the Parts from panels by cutting the tabs","text":"<p> \ud83d\udc41 Locate the panel S1 and discover the 5 differents Parts F, P, K, J and I.</p> <p> \ud83c\udfac Flip your panel S1.</p> <p> \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.</p> <p> Gather all the necessary tools. You will need the B2 \ud83d\udfe0 Razor blade to cut the tabs.</p> <p></p> <ul> <li>\ud83d\udfe3 Use the razor blade to cut the outer tabs located on the edges of the different Parts</li> <li>\u274c Do not cut the inner tabs present inside the different Parts for now and focus on the outer tabs attaching the Parts to the main panel.</li> </ul> <p></p> <ul> <li>Position your razor blade on the tab as close to the piece as possible to avoid residual tab after cutting.</li> <li>Press firmly on the razor blade, being very careful with your finger, to cut your first tab.</li> <li>Make sure you don't damage your table by placing a flat, rigid support under the S1 panel.</li> <li>Keep going with the other tabs of this piece F.</li> </ul> <p>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.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <p>Once you have removed your Part from the main panel by cutting off all the tabs holding it, inspect it for potential residual tabs.</p> <ul> <li>\ud83d\udfe3 Here is a residual tab that will need to be removed.</li> <li>\ud83d\udfe0 Here there is no residual tab which is perfect.</li> </ul> <p></p> <p>\ud83d\udfe3 Place your razor blade flat on the edge of your piece being very careful with your fingers and cut the residual tab.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <p>Repeat the cutting of the tabs on all the Parts F, P, K, J and I present on the panel S1.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <p>\ud83d\udd34 Locate the inner tabs on the edges of the different Parts.</p> <p></p> <p>Cut out the tabs inside of all the Parts F, P, K, J and I detached from the panel S1.</p> <p>Dispose of the cut tabs and any other debris that may have been created during the detachment process.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <ul> <li>\u2705 Good way of cutting inner tabs</li> <li>\u274c Wrong way of cutting inner tabs</li> </ul> <p></p> <p>Repeat the process on the panel S2.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <p>Discover the 11 differents Parts.</p> <p></p> <p>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.</p>"},{"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":"<p> To secure the PlanktoScope on slippery grounds using the adhesive pads, follow these steps. Gather all the necessary materials. You will need:</p> <ul> <li>Time: 1 min</li> <li>\ud83d\udc41 and Take the Part I</li> <li>\ud83d\udfe0 Take the four adhesive pads present in the bag A.</li> <li>\ud83d\udfe3 Locate the four pockets that will receive the four adhesive pads.</li> </ul> <p></p> <ul> <li>Clean the bottom of the case part I. Make sure the surface is free of dirt, debris, and any other substances that may prevent the adhesive pads from sticking properly.</li> <li>Remove the paper and place the four adhesive pads in the pockets by pressing firmly on them, sticky-side down.</li> <li>Test the stability of the PlanktoScope by gently shaking or tilting it. If it feels secure and does not slip or slide, the adhesive pads have been successfully installed.</li> </ul> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"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":"<p>Now it's time to assemble the ground plate for the Raspberry Pi as the PlanktoScope main processing unit.</p> <ul> <li>Time: 5 min</li> </ul> <p></p> <ul> <li>\ud83d\udc41 Grab the Part A.</li> <li>\ud83d\udfe3 Locate the four holes on Part A.</li> </ul> <p></p> <p>\ud83d\udfe2 A1. Standoff M2.5 - 6mm- Brass</p> <p></p> <p>\ud83d\udfe2 B4. Wrenches for standoffs</p> <p></p> <ul> <li>\ud83d\udfe3 Place the Standoff M2.5 - 6mm in the small side of the wrenches for   standoffs B4.</li> <li>\ud83d\udfe0 Do not use the big side of the wrenches for standoffs since the standoff will be loose in it.</li> </ul> <p></p> <ul> <li>Place the standoff in the hole and start rotating by hand in a clockwise direction until secure.</li> <li>Then tighten with the wrench.</li> </ul> <p></p> <ul> <li>\u2705 Make sure to screw until the standoff is properly inserted in the hole.</li> <li>\u274c Do not stop screwing before.</li> </ul> <p></p> <p>Keep going for each of the four holes.</p>"},{"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":"<ul> <li>Time: 2 min</li> </ul> <p>Locate the Raspberry Pi 4 Model B packaging.</p> <p>Warning</p> <p>Be careful removing it from its packaging.</p> <p></p> <p>Place the four Heat Sinks next to your Raspberry Pi and mark the locations of the Heat Sinks on the Raspberry Pi.</p> <ul> <li>\ud83d\udfe0 &amp; \ud83d\udd35 Small Heat Sinks</li> <li>\ud83d\udfe2 Medium Heat Sink</li> <li>\ud83d\udfe3 Big Heat Sink</li> </ul> <p></p> <p>Remove the protective labels under a Heat Sink and place the Heat Sink on the slot of the Raspberry Pi.</p> <p></p> <p>Remove the protective labels under all the Heat Sinks and place all the Heat Sinks on the slots of the Raspberry Pi.</p>"},{"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":"<ul> <li>Locate the SD card adapter in the bag K.</li> <li>The micro SD card is inserted in the SD card adapter.</li> <li>\ud83d\udfe3 Remove the micro SD card from the SD card adapter.</li> </ul> <ul> <li>Flip your Raspberry Pi.</li> <li>\ud83d\udfe0 Locate the micro SD port.</li> <li>\ud83d\udfe3 Insert the micro SD card in the Raspberry Pi.</li> </ul> <p>Push the micro SD card in the Raspberry Pi port to a point of resistance.</p> <p>Note</p> <p>If you notice that the micro SD card protrudes about 2mm from its slot, this is normal.</p>"},{"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":"<ul> <li>Time: 1 min</li> </ul> <ul> <li>\u2705 Make sure to position the Raspberry Pi properly on the four standoffs screwed on the Part A.</li> <li>\u274c Do not invert the position of the Raspberry Pi on the four standoffs screwed on the Part A.</li> </ul> <p>\ud83d\udfe3 A3. Standoff M2.5 - 16mm - SS</p> <p></p> <p>Screw by hand a Standoff M2.5 - 16mm on the Raspberry Pi.</p> <p></p> <ul> <li>Screw by hand all Standoffs M2.5 - 16mm on the Raspberry Pi.</li> <li>Make sure you insert all four standoffs by hand and tighten slightly.</li> </ul> <p></p> <p>\ud83d\udfe2 B4. Wrenches for standoffs</p> <p></p> <ul> <li>\ud83d\udfe0 Secure the Standoff M2.5 - 16 mm - SS A3 in the big side of the wrenches for standoffs B4.</li> <li>\ud83d\udfe3 Do not use the small side of the wrenches for standoffs since the standoff won\u2019t fit in it.</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#chapter-7-attach-the-ribbon-cable-to-the-raspberry-pi","title":"Chapter 7: Attach the Ribbon Cable to the Raspberry Pi","text":"<ul> <li>Time: 2 min</li> </ul> <p>Locate the Raspberry Pi Camera HQ packaging.</p> <p>Warning</p> <p>Be careful removing it from its packaging.</p> <p></p> <p>Lay your Raspberry Pi Camera face down on a suitable surface.</p> <p>\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.</p> <p>Warning</p> <p>Be careful with this, this part is delicate. Lift the black connector gently</p> <p></p> <p>Once the connector has been disengaged from the Raspberry Pi camera board, the cable will simply slide out!</p> <ul> <li>\ud83d\udfe3 Put aside Camera the Raspberry Pi</li> <li>\ud83d\udfe2 Keep the Ribbon Cable for next step.</li> </ul> <p></p> <p>\ud83d\udd34 Locate the black connector present on the Raspberry Pi.</p> <p></p> <p>\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.</p> <p>Warning</p> <p>Be careful, this part is delicate. Gently prise the black connector with nail or fingertip and thumb.</p> <p></p> <p>Insert the Ribbon Cable you just detached from the Raspberry Pi Camera in the Raspberry Pi.</p> <ul> <li>Make sure to insert in as much as you can.</li> <li>Blue rectangle on Ribbon Cable should face the same direction as the arrow below.</li> </ul> <p></p> <p>\ud83d\udd34 Secure the Ribbon Cable in the Raspberry Pi by pressing firmly on the black connector.</p>"},{"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":"<ul> <li>Time: 2 min</li> </ul> <p>Locate the PlanktoScope HAT present in bag I.</p> <p></p> <p>\ud83d\udd34 Thread the Ribbon cable through the PlanktoScope HAT slot from the underside.</p> <p>Warning</p> <p>Make sure the two \ud83d\udfe3 black connectors are aligned before threading through the ribbon.</p> <p></p> <p>\ud83d\udd34 Plug the PlanktoScope HAT into the Raspberry Pi.</p> <p>Warning</p> <p>Make sure the two black connectors are aligned before attaching them together.</p> <p></p> <p>Press the PlanktoScope HAT against the Raspberry Pi until it is no longer possible to move them closer together.</p> <p>Warning</p> <p>Continue to feed through the Ribbon Cable and do not crush it while pressing the PlanktoScope HAT against the standoffs.</p> <p></p> <p>\ud83d\udfe0 A4. Screw M2.5X5mm CHC - SS</p> <p></p> <p>\ud83d\udfe3 Locate the 4 holes on the top of the PlanktoScope HAT and insert the four M2.5X5mm</p> <p></p> <p>\ud83d\udfe1 B3. Allen key 2mm</p> <p></p> <p>Screw the four A4 screws through the PlanktoScope HAT onto the Standoff M2.5 - 16mm.</p> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"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":"<ul> <li>Time: 2 min</li> <li>Locate the DC Power Jack from the Bag K.</li> <li>Remove the Lock Ring from the DC Power Jack</li> </ul> <ul> <li>\ud83d\udd34 Lay the Part M down and make sure the pockets in these holes are facing upwards.</li> <li>\ud83d\udfe3 Locate the Power Socket hole on Part M.</li> </ul> <p>\ud83d\udd34 Insert the cable inside of the hole by being sure of the orientation of the Part M.</p> <p></p> <p>\ud83d\udfe3 Flip the Part M and secure the DC Power Jack by hand on the Part M by screwing the Lock Ring.</p> <p>Warning</p> <p>Make sure the Lock Ring doesn\u2019t spin on itself.</p> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"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":"<ul> <li>Time: 2 min</li> </ul> <p>\ud83d\udfe3 Locate the 4 holes on the top of the Part B.</p> <p></p> <p>\ud83d\udd35 A2. Standoff M2.5 - 15mm - Brass</p> <p></p> <p>Insert the four Standoff M2.5 - 15mm.</p> <p></p> <p>The result should be similar to the picture.</p> <p></p> <p>\ud83d\udfe2 B4. Wrenches for standoffs</p> <p></p> <p>Using the small side of the Standoff Wrench, secure the 4 M2.5 - 15mm Standoffs</p> <p></p> <ul> <li>\u2705 Make sure to screw until the Standoff is properly tightened into the hole.</li> <li>\u274c Do not stop screwing before.</li> </ul> <p></p> <p>Locate the Raspberry Pi Camera HQ</p> <p></p> <p>Remove the lens cap Raspberry Pi Camera HQ.</p> <p></p> <p>Warning</p> <p>Make sure your camera lens is clean. If it is not, gently wipe using cotton swab for this task.</p> <p></p> <p>Place the Raspberry Pi Camera HQ on top of the four Standoffs installed on Part B.</p> <p>\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</p> <p></p> <p>\ud83d\udfe0 A4. Screw M2.5X5mm CHC - SS</p> <p></p> <p>\ud83d\udfe1 B3. Allen key 2mm</p> <p></p> <p>Use the allen key and tighten the Raspberry Pi Camera to the Standoffs.</p> <p></p> <p>The result should be similar to the picture.</p> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"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":"<p>Locate the Stepper Motors</p> <p>Warning</p> <p>Avoid touching the metal rods on the Stepper Motors</p> <p>Info</p> <p>You can touch the \ud83d\udfe3 gold stands</p> <p></p> <p></p> <p>\ud83d\udfe1 A5. Screw M2.5X10mm CHC - SS</p> <p></p> <p>\ud83d\udfe1 B3. Allen key 2mm</p> <p></p> <ul> <li>\ud83d\udd34 Lay the Part E down and make sure the pockets in these holes are   facing upwards.</li> <li>\ud83d\udfe3 Locate the four holes on Part E and place four M2 Screws in the holes.</li> </ul> <p></p> <p>Attach the stepper motors to the screws we have just placed with the \ud83d\udd34 pockets positioned on opposite to the cabling.</p> <p>The result should be similar to the picture.</p> <p></p> <p>Use the 2mm allen key to fix the Stepper Motors.</p> <p>The result should be similar to that picture.</p> <p></p> <p>The result should be similar to the picture.</p> <p></p> <p>Repeat the process on the other side with the other Stepper Motor.</p> <p></p> <p>Repeat the process on the other side with the other Stepper Motor.</p> <p></p> <p>The result should be similar to the picture.</p> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"location":"setup/hardware/v2.5/assembly/#chapter-12-mount-the-led-on-part-g","title":"Chapter 12: Mount the\u00a0LED\u00a0on\u00a0Part G","text":"<ul> <li>Locate the\u00a0LED\u00a0and\u00a0LED cable\u00a0in Bag K.</li> <li>\ud83d\udfe3\u00a0The LED will go on the end where\u00a0the white plastic connector is\u00a0smallest.</li> </ul> <p>Insert the\u00a0LED into the LED cable.</p> <p></p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p></p> <p>Locate part\u00a0G.</p> <p></p> <p>\ud83d\udfe3\u00a0Locate the LED hole on\u00a0Part G.</p> <p></p> <p>We\u00a0will\u00a0now\u00a0place\u00a0the\u00a0LED\u00a0into\u00a0the\u00a0slot\u00a0on part\u00a0G.</p> <p></p> <p>Warning</p> <p>Gently push the LED into the LED\u00a0hole located on Part\u00a0G. It should be a snug fit.</p> <p></p> <p>The result should be similar to the\u00a0picture.</p> <p>Info</p> <p>\ud83c\udfac\u00a0Store this assembly for later.</p>"},{"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":"<ul> <li>Locate the\u00a0Kamoer Peristaltic pump\u00a0from the\u00a0Bag F.</li> <li>\ud83d\udfe3\u00a0Put aside the\u00a0tubing contained in\u00a0the little bag.</li> </ul> <p>\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.</p> <p>Warning</p> <p>\ud83d\udc41 Ensure the correct orientation of\u00a0Part O\u00a0and the\u00a0Peristaltic Pump</p> <p></p> <p>\ud83d\udfe1\u00a0A5. Screw\u00a0M2.5X10mm\u00a0CHC - SS</p> <p></p> <p>\ud83d\udfe1\u00a0B3. Allen key 2mm B3</p> <p></p> <p>\ud83d\udfe2\u00a0Insert the two\u00a0M2.5X10mm\u00a0in the\u00a0two holes.</p> <p></p> <p>Screw the two\u00a0M2.5X10mm\u00a0into the\u00a0two holes.</p> <p></p> <p></p> <p>\ud83d\udd34\u00a0Lay\u00a0the\u00a0Part\u00a0L\u00a0down and make\u00a0sure the pockets in these holes are\u00a0facing upwards.</p> <p></p> <ul> <li>Place\u00a0the\u00a0Peristaltic Pump underneath part L, ensuring the\u00a0correct orientation of these two parts.</li> <li>\ud83d\udd34 Insert the Peristaltic Pump into\u00a0the allocated slot in\u00a0Part L.</li> </ul> <p></p> <p>Insert the\u00a0Peristaltic Pump\u00a0into the\u00a0allocated slot in\u00a0Part L.</p> <p></p> <p>Insert the\u00a0Peristaltic Pump\u00a0into the\u00a0allocated slot in\u00a0Part L.</p> <p></p> <ul> <li>Lay the assembly down.</li> <li>\ud83d\udd34\u00a0Locate the\u00a0four different holes.</li> </ul> <p></p> <p>\ud83d\udfe1\u00a0A5.Screw\u00a0M2.5X10mm\u00a0CHC - SS</p> <p></p> <p>\ud83d\udfe1\u00a0B3.Allen key 2mm</p> <p></p> <p>Screw the four M2.5X10mm in the\u00a0located\u00a0holes\u00a0attaching\u00a0the\u00a0Part\u00a0O\u00a0to\u00a0the\u00a0Part L Peristaltic Pump.</p> <p> The result should be similar to the\u00a0picture.</p> <p>Info</p> <p>We will use this part in the next step.</p>"},{"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":"<ul> <li>Locate the LED and housing, along\u00a0with the pump and housing.</li> <li>\ud83d\udfe3\u00a0Locate the\u00a0spiral wrap\u00a0from\u00a0bag K.</li> </ul> <ul> <li>Spiral wrap both sets of cables\u00a0together.</li> <li>There should be 4 cm (1.5 inches)\u00a0between\u00a0the\u00a0connectors\u00a0and\u00a0the\u00a0start\u00a0of the spiral wrap.</li> </ul> <p>Continue wrapping around the\u00a0cables until you have used all of the\u00a0spiral wrap, leaving small or no gaps.</p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p>Note</p> <p>\ud83c\udfac\u00a0Store this assembly for later.</p>"},{"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":"<p>Locate the Stepper Motors with\u00a0mount, and the Raspberry Pi\u00a0Camera.</p> <p> Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.</p> <p>Warning</p> <p>Make sure the orientation is\u00a0correct and matches the picture.</p> <p> Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.</p> <p>Warning</p> <p>Make sure the orientation is\u00a0correct and matches the picture.</p> <p>Then\u00a0insert\u00a0the\u00a0cylindrical\u00a0parts\u00a0of\u00a0the\u00a0Stepper Motor into the slots.</p> <p></p> <p>Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.</p> <p>Warning</p> <p>Make sure the orientation is\u00a0correct and matches the picture.</p> <p>Then\u00a0insert\u00a0the\u00a0cylindrical\u00a0parts\u00a0of\u00a0the\u00a0Stepper Motor into the slots.</p> <p>Note</p> <p>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</p>"},{"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":"<ul> <li>We will need the\u00a0Raspberry Pi HAT with housing and Ribbon Cable along\u00a0\\   with the\u00a0Raspberry Pi Camera with\u00a0Stepper Motors and housing.</li> <li>We will be connecting the\u00a0\ud83d\udfe2Ribbon\u00a0Cableto the\u00a0\ud83d\udfe1black\u00a0Raspberry Pi Camera\u00a0connector\u00a0that we removed\u00a0it from earlier.</li> </ul> <p>Gently feed the\u00a0Ribbon Cable\u00a0into the\u00a0port of the\u00a0Camera.</p> <p>Warning</p> <p>\ud83d\udc41 Ensure the correct orientation of\u00a0the\u00a0Ribbon Cable\u00a0with the blue end\u00a0facing upwards.</p> <p> \ud83d\udd34\u00a0Press down on the black\u00a0connector on the Raspberry Pi\u00a0camera board once the Ribbon\u00a0Cable is in position.</p> <p> \ud83d\udd34\u00a0B1.Small flat screwdriver 2mm</p> <p></p> <ul> <li>Now we will plug in the\u00a0Stepper\u00a0Mounts to the\u00a0HAT.</li> <li>\ud83d\udd34The cables for the\u00a0Stepper Mounts\u00a0will be plugged into the\u00a0HAT\u00a0\ud83d\udfe3here.</li> </ul> <p>Warning</p> <p>Hold tight, a specific order is\u00a0required.</p> <p></p> <p>Starting with the\u00a0red cable, insert the\u00a0cable in the far left port and tighten\u00a0the screw situated above the port.</p> <p>Note</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>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.</p>"},{"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":"<p>We will now be connecting the LED\u00a0and Peristaltic Pump with the\u00a0Raspberry Pi HAT\u00a0and\u00a0Camera.</p> <p></p> <p>Place the LED housing onto the\u00a0Stepper Mounts.</p> <p>Warning</p> <p>\ud83d\udc41 Ensure correct orientation of both\u00a0\ud83d\udfe3 parts by looking at the\u00a0precut holes.</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>Now we will plug in the\u00a0LED and\u00a0Stepper Mount\u00a0cables to the\u00a0Raspberry Pi.</p> <p></p> <p>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.</p> <p></p> <p>We will now plug the cables into the\u00a0correct ports.</p> <p></p> <p>\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.</p> <p></p> <p>\ud83d\udd34 The two wires (LED) enter on the\u00a0port on top of the Raspberry Pi HAT.</p> <p></p> <p>The result should be similar to the\u00a0picture.</p> <p>Note</p> <p>We will use this assembly in the next\u00a0step.</p>"},{"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":"<ul> <li>\ud83d\udfe2\u00a0Locate the\u00a0DC Power Jack</li> <li>We will plug the DC Power Jack\u00a0into the Raspberry Pi via the \ud83d\udd35 blue port.</li> </ul> <p>\ud83d\udd34\u00a0B1.Small flat screwdriver 2mm</p> <p></p> <ul> <li>Insert the \ud83d\udd34 red cable of the DC\u00a0Power Jack into the left side of the\u00a0blue port.</li> <li>Tighten the screw above.</li> </ul> <p></p> <ul> <li>Insert the \u26ab black cable of the DC\u00a0Power\u00a0Jack\u00a0into\u00a0the\u00a0right\u00a0side\u00a0of\u00a0the\u00a0blue port.</li> <li>Tighten the screw above.</li> </ul> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p>Note</p> <p>We will use this assembly in the next\u00a0step.</p>"},{"location":"setup/hardware/v2.5/assembly/#chapter-19-your-planktoscope-starts-to-take-shape","title":"Chapter 19: Your PlanktoScope starts to take shape","text":"<p>Locate Part I\u00a0and\u00a0Part H.</p> <p></p> <ul> <li>Slot\u00a0Part H\u00a0into\u00a0Part I.</li> <li>\ud83d\udfe3\u00a0Note the orientation.\u00a0Part H\u00a0goes\u00a0into\u00a0Part Iat the end with the\u00a0rectangular slot (as opposed to the\u00a0rectangle with bulbous hole).</li> <li>\ud83d\udfe1\u00a0Also, the deeper slots on\u00a0part H\u00a0should be on the upper side.</li> </ul> <p></p> <p>\ud83d\udd34 Slot the\u00a0Peristaltic Pump\u00a0above\u00a0the\u00a0LED.</p> <p></p> <p>Note</p> <p>The result should be the same as the\u00a0picture.</p> <p></p> <p>Warning</p> <p>\ud83d\udc41 Ensure the correct orientation of\u00a0the housing and the\u00a0Peristaltic Pump.</p> <p></p> <p>At the other end, slot the\u00a0DC Power\u00a0Jack\u00a0housing adjacent to the\u00a0Raspberry Pi.</p> <p> </p> <p>Rotate so that the DC Power Jack is\u00a0facing upwards. We will now slot the Raspberry Pi onto\u00a0the rest of the housing.</p> <p></p> <p>Info</p> <p>The result should be similar to that\u00a0picture.</p> <p>Note</p> <p>\ud83c\udfac\u00a0Store this assembly for later.</p>"},{"location":"setup/hardware/v2.5/assembly/#chapter-20-inserting-screws","title":"Chapter 20: Inserting screws","text":"<p>\ud83d\udfe3 We\u00a0will\u00a0now\u00a0insert\u00a0eight\u00a0M3\u00a0screws\u00a0to fasten the housing together.</p> <p>Note</p> <p>\ud83c\udfac\u00a0Store this assembly for later.</p> <p></p> <p>\ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS</p> <p></p> <p>\ud83d\udfe1\u00a0B3. Allen key 2mm</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>We will now turn over the\u00a0PlanktoScope\u00a0and\u00a0repeat\u00a0the\u00a0process\u00a0for the underside.</p> <p></p> <p>\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0underside.</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>Now turn the PlanktoScope on its side.</p> <p></p> <p></p> <p>Warning</p> <p>\ud83d\udc41 Ensure the orientation of your\u00a0PlanktoScope and\u00a0Part K\u00a0matches\u00a0the picture.</p> <p></p> <p>Slot\u00a0Part K\u00a0onto the rest of the\u00a0PlanktoScope.</p> <p>Warning</p> <p>\ud83d\udfe2\u00a0Ensure the correct orientation. The\u00a0result should look the same at the\u00a0picture.</p> <p></p> <p>Content of\u00a0Bag A: \ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS</p> <p></p> <p>Content of\u00a0Bag B: \ud83d\udfe1\u00a0B3. Allen key 2mm</p> <p></p> <p>\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0side to hold\u00a0Part K\u00a0in place.</p> <p></p> <p></p> <p>We will now place\u00a0Part J\u00a0into position\u00a0as the housing for the side.</p> <p>Warning</p> <p>\ud83d\udc41 Ensure your PlanktoScope matches\u00a0the orientation in the picture.</p> <p></p> <p>\ud83d\udfe2 Place\u00a0Part K\u00a0onto the rest of the\u00a0PlanktoScope and note the position\u00a0of the cutout.</p> <p></p> <p>Content of\u00a0Bag A: \ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS</p> <p></p> <p>Content of\u00a0Bag B: \ud83d\udfe1\u00a0B3. Allen key 2mm</p> <p></p> <p>\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0underside</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p></p> <p>Content of\u00a0Bag A: \ud83d\udfe1\u00a0A5. Screw M2.5X10mm CHC - SS</p> <p></p> <p>Place\u00a0the\u00a0M2.5\u00a0screw\u00a0through\u00a0Part\u00a0N. It\u00a0will\u00a0act\u00a0as\u00a0a\u00a0cover\u00a0for\u00a0the\u00a0electrical\u00a0inputs.</p> <p></p> <ul> <li>Place the\u00a0cover\u00a0over the electrical\u00a0inputs on the PlanktoScope.</li> <li>\ud83d\udfe3 The screw will enter the hole\u00a0located here.</li> </ul> <p></p> <p>Using the allen key, tighten the screw\u00a0so that it is possible to move the\u00a0cover with light force.</p> <p></p> <p>Info</p> <p>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</p>"},{"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":"<ul> <li>Orientate\u00a0your\u00a0PlanktoScope\u00a0so\u00a0that\u00a0it\u00a0matches the picture.</li> <li>Twist off the orange top of the\u00a0Peristaltic\u00a0pump\u00a0in\u00a0an\u00a0anti-clockwise\u00a0direction.</li> </ul> <p>You can now remove the Peristaltic\u00a0Pump housing and\u00a0\ud83d\udfe2 Rotor.</p> <p></p> <p>You can now remove the Peristaltic\u00a0Pump housing and\u00a0\ud83d\udfe2 Rotor.</p> <p></p> <p>\ud83d\udd34 Locate the\u00a0Tube\u00a0for the Peristaltic\u00a0Pump in\u00a0Bag F\u00a0and remove it from the\u00a0bag.</p> <p>Warning</p> <p>The tips of the Tubing that are\u00a0covered by black rubber are very\u00a0delicate and easily broken.</p> <p></p> <p>Insert the first plastic arch of the\u00a0Tube\u00a0into the slot on the Peristaltic Pump\u00a0\\ housing.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p> </p> <p>Insert the\u00a0Rotor\u00a0into the housing\u00a0ensuring the correct orientation. The\u00a0hole in the centre should be visible on\u00a0the underside.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>Insert the\u00a0Rotor\u00a0into the housing.\u00a0Then, thread the\u00a0Tube\u00a0around the\u00a0Rotor\u00a0and insert the other plastic\u00a0arch into the second slot.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <ul> <li>Thread the\u00a0Tube\u00a0around around the\u00a0Rotor\u00a0and insert the other plastic\u00a0arch into the second slot.</li> <li>This will require stretching the\u00a0Tube\u00a0slightly.</li> </ul> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>Place the Peristaltic Pump housing\u00a0back onto the PlanktoScope.</p> <p></p> <p>Achieve the angle shown in the\u00a0picture between the Peristaltic Pump\u00a0housing and PlanktoScope main\u00a0body. Then, press and twist in a\u00a0clockwise direction.</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <ul> <li>\ud83d\udfe3\u00a0Gently remove the black rubber\u00a0covers for the Peristaltic Pump\u00a0connectors by pinching the very tip\u00a0and pulling away.</li> <li>Once complete, locate\u00a0Bag D\u00a0which\u00a0contains tubing.</li> </ul> <p></p> <p>Push the small piece of tubing from\u00a0Bag D\u00a0over the left-side connector of\u00a0the\u00a0Peristaltic Pump.</p> <p></p> <p>Place the long piece of tubing from\u00a0Bag D\u00a0over the right-side connector\u00a0of the\u00a0Peristaltic Pump.</p> <p></p> <p>Insert the connector from\u00a0Bag D\u00a0into\u00a0the other end of the\u00a0small piece of\u00a0tubing.</p> <p></p> <p></p> <p>Orientate\u00a0Part P\u00a0so that the magnets\u00a0are face-down on the left-hand side.</p> <p></p> <p>Place Part P over the magnets\u00a0adjacent to the\u00a0Peristaltic Pump.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>\ud83d\udd34 From\u00a0Bag M, Place the\u00a0light blue Test Tube in the hole adjacent to the\u00a0Peristaltic Pump.</p> <p></p> <p>Place the\u00a0\ud83d\udd35 dark blue Test Tube\u00a0into\u00a0the hole situated outside of the\u00a0PlanktoScope.</p> <p></p> <p>\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.</p> <p></p> <p> </p> <ul> <li>Locate Part\u00a0C</li> <li>Locate\u00a025\u00a0mm\u00a0camera\u00a0lens\u00a0and\u00a0Lock Ring\u00a0from\u00a0Bag J.</li> <li>25MM is printed on the lens.</li> </ul> <p> </p> <ul> <li>Remove the plastic lens cap.</li> <li>Slot\u00a0the\u00a025\u00a0mm\u00a0camera\u00a0lens into\u00a0Part C.</li> </ul> <p>Info</p> <p>The magnets are raised on the\u00a0side where the lens lays flat.</p> <p>Warning</p> <p>Try not to touch the lens</p> <p>Screw the\u00a0Lock Ring\u00a0onto the lens,\u00a0flat-side down.</p> <p> </p> <ul> <li>Locate Part\u00a0D.</li> <li>Locate\u00a016\u00a0mm\u00a0camera\u00a0lens\u00a0and\u00a0Lock\u00a0Ring\u00a0from\u00a0Bag J.</li> <li>16MM is printed on the lens.</li> </ul> <p> </p> <ul> <li>Remove the plastic lens cap.</li> <li>Slot\u00a0the\u00a016\u00a0mm\u00a0camera\u00a0lens into Part\u00a0D.</li> </ul> <p>Info</p> <p>The\u00a0magnets\u00a0are\u00a0indented\u00a0on\u00a0the\u00a0side that the lens lays flat.</p> <p>Warning</p> <p>Try not to touch the lens</p> <p>Screw the\u00a0Lock Ring\u00a0onto the lens,\u00a0flat-side down.</p> <p>The result should be similar to that\u00a0picture.</p> <p> </p> <p>Place\u00a0both\u00a0Lenses (C\u00a0and\u00a0D)\u00a0together\u00a0so that they flat together and both\u00a0lenses are facing each other.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p> </p> <p>Place\u00a0the\u00a0Lenses\u00a0(both\u00a0C\u00a0and\u00a0D)\u00a0into\u00a0position, adjacent to the camera.</p> <p>The orientation of your PlanktoScope\u00a0and Lenses should match the\u00a0pictures.</p> <p></p> <ul> <li>Once\u00a0together,\u00a0place\u00a0the\u00a0lenses\u00a0(both\u00a0C and D) into position, adjacent to\u00a0the camera.</li> <li>Part\u00a0C\u00a0/\u00a025mm\u00a0lens\u00a0should\u00a0be\u00a0furthest\u00a0from the pump (orange piece).</li> </ul> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p></p> <p>Info</p> <p>The Fluidic Path will have a\u00a0cardboard protector.</p> <p>Please take extra precaution while handling\u00a0this\u00a0part\u00a0and\u00a0avoid\u00a0touching\u00a0the glass element of the piece.</p> <p>Warning</p> <p>The Fluidic Path is very delicate.</p> <p></p> <p>Place the Tube Clamp over the long\u00a0piece\u00a0of\u00a0tube\u00a0at\u00a0the\u00a0end\u00a0of\u00a0the\u00a0Fluidic\u00a0Path.</p> <p></p> <p>Place the white clamp over the long\u00a0piece\u00a0of\u00a0tube\u00a0at\u00a0the\u00a0end\u00a0of\u00a0the\u00a0Fluidic Path.</p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>Press down on the Tube Clamp so\u00a0that it clicks into place with just one\u00a0click.</p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>Insert\u00a0a\u00a0small\u00a0plastic\u00a0Connector\u00a0into\u00a0the\u00a0end\u00a0of\u00a0the\u00a0tubing,\u00a0below\u00a0the\u00a0Tube\u00a0Clamp.</p> <p></p> <p>Make sure the tubing is over the\u00a0Connector.</p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>Remove the cardboard protector\u00a0from the\u00a0Fluidic Path.</p> <p></p> <p>Warning</p> <p>A reminder, the glass part of the\u00a0Fluidic\u00a0Path\u00a0is\u00a0very\u00a0delicate.\u00a0Please\u00a0try\u00a0not to touch it.</p> <p></p> <p>Place another Connector at the end\u00a0of the tubing.</p> <p></p> <p>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</p> <p></p> <p>\u26a0 Gently place the Fluidic Path in\u00a0the designated indentation on\u00a0Part F.</p> <p>Warning</p> <p>Do not touch the glass.\u00a0</p> <ul> <li>You may have to slightly stretch the\u00a0tubing to get the Fluidic Path into\u00a0position.</li> <li>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</li> </ul> <p></p> <p>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.</p> <p>Avoid placing tape over the glass.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p> </p> <p>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.</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p> </p> <ul> <li>Place the Fluidic Path into position\u00a0between the mount and the\u00a0Peristaltic Pump.</li> <li>Connect the magnets to face each\u00a0other.</li> </ul> <p></p> <p>The result should look the same as\u00a0the pictures.</p> <p> </p> <ul> <li>\ud83d\udfe2 Connect the Fluidic Path to the\u00a0Peristaltic Pump by twisting the two\u00a0connectors together.</li> <li>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#build-complete","title":"Build complete! \ud83d\udcaf \ud83d\udcab","text":""},{"location":"setup/hardware/v2.5/assembly/#next-steps","title":"Next steps","text":"<p>Next, you will need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi.</p>"},{"location":"setup/hardware/v2.5/kit/","title":"Kit Production","text":""},{"location":"setup/hardware/v2.5/kit/#mechanical-structure","title":"Mechanical Structure","text":"<p>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.</p> <p></p>"},{"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":"<p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>Strength: Valchromat has a high mechanical strength, making it suitable for use in structural applications such as flooring, furniture, and doors.</p> </li> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul> <p></p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul> <p>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.</p> <p>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.</p>"},{"location":"setup/hardware/v2.5/kit/#finishing","title":"Finishing","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>We use Rubio Monocoat Plus as a finishing product for Valchromat.</p>"},{"location":"setup/hardware/v2.5/kit/#cnc-workflow","title":"CNC workflow","text":"<p>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:</p> <ol> <li> <p>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:</p> </li> <li> <p>6mm end mill for straight flats</p> </li> <li>2mm end mill for inner contours</li> <li> <p>1mm end mill for small holes</p> </li> <li> <p>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:</p> </li> <li> <p>1500mm/min for 1-2mm end mills</p> </li> <li>2500mm/min for 3mm end mills</li> <li> <p>3500mm/min for 6mm end mills</p> </li> <li> <p>Load the end mill: Once the appropriate end mill has been selected, it can be loaded onto the spindle of the CNC milling machine.</p> </li> <li> <p>Set the workpiece: The workpiece should be securely clamped onto the table of the CNC milling machine.</p> </li> <li> <p>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.</p> </li> <li> <p>Begin machining: The machining process should be carried out in the following sequence:</p> </li> <li> <p>Mill the screw holes with a 2mm end mill and then with a 3mm end mill</p> </li> <li>Mill the corners with a 2mm end mill</li> <li>Mill everything else with a 3mm end mill</li> </ol> <p>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.</p> <p></p>"},{"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":"<ul> <li>Hammer</li> <li>Air Compressor</li> <li>Rubber gloves</li> <li>Paper carpet pad</li> <li>Clean piece of cotton fabric</li> <li>Support material for drying the parts</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#case-part-parts","title":"Case part parts","text":"<ul> <li>all case parts</li> <li>Rubio Monocoat Oil Plus 2C</li> <li>Rubio Monocoat Accelerator Component B</li> <li>Magnets</li> <li>Square nuts</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#clean","title":"Clean","text":""},{"location":"setup/hardware/v2.5/kit/#stir","title":"Stir","text":""},{"location":"setup/hardware/v2.5/kit/#apply","title":"Apply","text":""},{"location":"setup/hardware/v2.5/kit/#dry","title":"Dry","text":""},{"location":"setup/hardware/v2.5/kit/#inserting-the-screws","title":"Inserting the screws","text":""},{"location":"setup/hardware/v2.5/kit/#inserting-the-magnets","title":"Inserting the magnets","text":""},{"location":"setup/hardware/v2.5/kit/#package-housing-part","title":"Package Housing part","text":""},{"location":"setup/hardware/v2.5/kit/#planktoscope-hat","title":"PlanktoScope Hat","text":"<p>Welcome to the PCB production manual for the PlanktoScope Hat!</p> <p> </p> <p>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.</p> <p>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.</p> <p>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.</p> <p>Note</p> <p>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.</p>"},{"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":"<p>To order a PCB board including assembly, follow these steps:</p> <ul> <li>Select a manufacturing company based on your local availability, budget, delivery dates, and services such as assembly.</li> </ul> <p>Note</p> <p>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.</p> <ul> <li>Create a customer account if you do not already have one. Ensure to specify the correct tax, contact, and delivery information.</li> </ul> <p>Warning</p> <p>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.</p> <ul> <li>Create a project and select the quantity of PCB boards you need for production.</li> <li>Configure the order based on the values specified in this document.</li> <li>Upload the bill of material (BOM) and validate the component availability.</li> </ul> <p>Warning</p> <p>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.</p> <p>Info</p> <p>The component costs will now be calculated, and the price should be displayed.</p> <ul> <li>Upload the gerber files provided as a zip file in the repository under the following link.</li> <li>Upload the assembly instructions provided as a zip file in the repository under the following link.</li> <li>Check that there are no missing references in your order configuration.</li> <li>Place the order based on your delivery requirements.</li> <li>Select a payment method and complete the order process.</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#configuration","title":"Configuration","text":"<p>The following configuration parameters can be used for the production of the PCB.</p> <p>Info</p> <p>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.</p>"},{"location":"setup/hardware/v2.5/kit/#board-dimensions","title":"Board dimensions","text":"<p>65 mm x 100 mm</p>"},{"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 &gt; 0.15 mm Min. drill hole size &gt; 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":"<p>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.</p> <p>Warning</p> <p>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.</p>"},{"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":"<ul> <li>professional Soldering iron</li> <li>solder with flux</li> <li>Helping hand or Breadboard</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#thru-hole-parts","title":"Thru-Hole parts","text":"Files Description Planktoscope-Hat-bom-through-hole.csv The list of used SMD components <p>Warning</p> <p>When you solder this for the first time, take special care not to damage the board.</p> <p>Info</p> <p>To learn how to solder we recommend you the awesome Comic \"Soldering is easy\" by Mitch Altmal, Andie Nordgren and Jeff Keyzer</p>"},{"location":"setup/hardware/v2.5/kit/#soldering-of-the-stepper-motor-driver","title":"Soldering of the stepper motor driver","text":"<p>Unpack the motor driver and the connector strips and take the breadboard aside.</p> <p></p> <p>Plug the connectors with the appropriate distance to the breadboard.</p> <p>Info</p> <p>The breadboard supports you during soldering to ensure the spacing and angle of the connectors, alternatively you can also use a third hand.</p> <p></p> <p>Now position the motor driver on the connector strips of the beadboard.</p> <p>Warning</p> <p>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.</p> <p></p> <p>Now solder all pins of the connector strip.</p> <p>Info</p> <p>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.</p> <p>Tip</p> <p>You can also solder one pin on one side and then the opposite one to fix your workpiece, this ensures that nothing accidentally moves.</p>"},{"location":"setup/hardware/v2.5/kit/#soldering-of-the-motor-driver-sockets","title":"Soldering of the motor driver sockets","text":"<p>Now take the PlanktoScope Hat board and the female connector of the stepper motor driver and position them as shown in the picture.</p> <p></p> <p>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.</p> <p></p> <p>Now solder all pins of the connector strip.</p> <p>Info</p> <p>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.</p> <p>Tip</p> <p>You can also solder one pin on one side and then the opposite one to fix your workpiece, this ensures that nothing accidentally moves.</p> <p></p> <p>Repeat the procedure with the second motor driver. The end result should look like this.</p>"},{"location":"setup/hardware/v2.5/kit/#soldering-the-connection-sockets","title":"Soldering the connection sockets","text":"<p>Now solder the motor driver sockets, inserting the connector into the holes as shown.</p> <p></p> <p>Turn the board over and hold the loose connector while soldering it. Repeat the procedure with the second motor connector.</p> <p>Info</p> <p>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.</p> <p></p> <p>Repeat the procedure with the power connector. The end result should look like this.</p> <p></p> <p>Repeat the procedure with the led connector. The end result should look like this.</p>"},{"location":"setup/hardware/v2.5/kit/#soldering-the-raspberry-pi-connector","title":"Soldering the Raspberry Pi connector","text":"<p>Now solder the Raspberry Pi header connector with all 20 pins.</p> <p>Warning</p> <p>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.</p>"},{"location":"setup/hardware/v2.5/kit/#install-and-solder-the-cooling-fan","title":"Install and solder the cooling fan","text":"<p>Install the fan with the four screws and nuts.</p> <p>Warning</p> <p>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.</p> <p>Cut off the excess cable of the fan and leave about 6 cm.</p> <p></p> <p>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.</p> <p></p> <p>Solder the fan cables according to the marking and color codes \u26ab GND, \ud83d\udd34 VCC, \ud83d\udfe1 RPM, \ud83d\udd35 PWM.</p> <p>Note</p> <p>If your fan doesn't have a \ud83d\udd35 PWM connector, then that's not a problem, you can just leave it out.</p>"},{"location":"setup/hardware/v2.5/kit/#solder-the-display-connector","title":"Solder the display connector","text":"<p>Insert the pin headers into the holes provided, hold them in place, carefully turn the board over and solder the connector.</p> <p>Note</p> <p>If you do not use an OLED display, you do not need to solder the connector.</p>"},{"location":"setup/hardware/v2.5/kit/#solder-the-configuration-option-jumpers","title":"Solder the configuration option jumpers","text":"<p>Insert the pin headers into the holes provided, hold them in place, carefully turn the board over and solder the connector.</p> <p>Note</p> <p>If you do not use an OLED display, you do not need to solder the connector.</p>"},{"location":"setup/hardware/v2.5/kit/#you-have-finished-soldering-the-components","title":"You have finished soldering the components","text":"<p>The assembly of the thru-hole components for the planktoscope hat is now complete. The end result should look like this.</p>"},{"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":"<ul> <li>double sided adhesive tape</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#hard-case-parts","title":"Hard case parts","text":"<ul> <li>Hard case</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#foam-preparation","title":"Foam preparation","text":"<p>Cut the foam block at the outer edge by gently tearing it apart with your fingers.</p> <p>Warning</p> <p>Be careful the foam tears easily and can not be repaired.</p> <p>Tip</p> <p>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.</p> <p></p> <p>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.</p> <p></p> <p>Now insert the foam edge in to the case and glue it to the outer wall.</p> <p>Note</p> <p>Before you fix the foam, position it completely and check that it is placed flush with the edge of the case.</p>"},{"location":"setup/hardware/v2.5/kit/#kit-composition","title":"Kit composition","text":"<p>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!</p>"},{"location":"setup/software/","title":"PlanktoScope Software","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>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.</p>"},{"location":"setup/software/#choosing-an-sd-card-image","title":"Choosing an SD card image","text":"<p>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 <code>planktoscope-v2024.0.0+planktoscopehat.img.gz</code> 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. <code>planktoscopehat</code>).</p>"},{"location":"setup/software/#planktoscope-os-versions","title":"PlanktoScope OS versions","text":"<p>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.</p> <p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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 <code>9</code> should not be interpreted as having any special meaning.</p> </li> <li> <p>v2024.0.0: this version is the first release of the PlanktoScope OS in 2024.</p> </li> <li> <p>v2024.1.0: this version will be the second release of the PlanktoScope OS in 2024.</p> </li> </ul>"},{"location":"setup/software/#hardware-configurations","title":"Hardware configurations","text":"<p>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:</p> <ul> <li> <p><code>adafruithat</code>: this configuration of the PlanktoScope OS is compatible with v2.1 of the PlanktoScope hardware, which uses the Adafruit Stepper Motor HAT.</p> </li> <li> <p><code>planktoscopehat</code>: 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.</p> </li> <li> <p><code>fairscope-latest</code>: this configuration of the PlanktoScope OS is identical to the <code>planktoscopehat</code> 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.</p> </li> </ul> <p>If you have a PlanktoScope from FairScope, you should probably use the <code>fairscope-latest</code> SD card image; otherwise, if you have a non-FairScope PlanktoScope with hardware version v2.3 or later, you should probably use the <code>planktoscopehat</code> SD card image; otherwise, if you have a v2.1 PlanktoScope, you should probably use an <code>adafruithat</code> SD card image.</p>"},{"location":"setup/software/#installation","title":"Installation","text":"<p>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.</p>"},{"location":"setup/software/#post-installation-configuration","title":"Post-installation configuration","text":"<p>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.</p>"},{"location":"setup/software/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"location":"setup/software/config/","title":"Post-Installation Configuration","text":"<p>After installing the PlanktoScope software onto your PlanktoScope, you will need to configure the software to match your PlanktoScope hardware and your operational requirements.</p> <p>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.</p>"},{"location":"setup/software/config/#hardware-version","title":"Hardware Version","text":"<p>Info</p> <p>This step is only required if you are using a <code>planktoscopehat</code> SD card image; it is not needed on the <code>adafruithat</code> and <code>fairscope-latest</code> SD card images.</p> <p>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.</p>"},{"location":"setup/software/config/#next-steps","title":"Next steps","text":"<p>Now that you have configured the PlanktoScope software, you can proceed to our guide on how to operate your PlanktoScope.</p>"},{"location":"setup/software/nonstandard-install/","title":"Non-Standard Installation","text":"<p>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.</p>"},{"location":"setup/software/nonstandard-install/#prerequisites","title":"Prerequisites","text":"<p>This guide assumes that:</p> <ol> <li>You have previous experience with using the command-line terminal on the Raspberry Pi OS or another Linux distribution.</li> <li>You have already confirmed that your PlanktoScope works without any problems with software installed by the standard PlanktoScope software setup process.</li> <li>You already know how to use the PlanktoScope software.</li> </ol> <p>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.</p> <p>In order to complete the non-standard setup process, you will need all of the following:</p> <ol> <li>A Raspberry Pi computer. We only test to ensure that the PlanktoScope software works on the Raspberry Pi 4; it may or may not work on the Raspberry Pi 3, and it does not yet work on the Raspberry Pi 5.</li> <li>A keyboard connected to your Raspberry Pi.</li> <li>A display connected to your Raspberry Pi.</li> <li>A micro-SD card for your Raspberry Pi.</li> <li>A way to provide internet access to your Raspberry Pi.</li> <li>A separate computer which can flash SD card images to your micro-SD card.</li> </ol>"},{"location":"setup/software/nonstandard-install/#install-and-set-up-raspberry-pi-os-on-your-raspberry-pi","title":"Install and set up Raspberry Pi OS on your Raspberry Pi","text":""},{"location":"setup/software/nonstandard-install/#download-a-raspberry-pi-os-sd-card-image","title":"Download a Raspberry Pi OS SD card image","text":"<p>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:</p> <ul> <li>\"Raspberry Pi OS with desktop\"</li> <li>\"Raspberry Pi OS with desktop and recommended software\"</li> <li>\"Raspberry Pi OS Lite\"</li> </ul> <p>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.</p> <p>Warning</p> <p>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.</p>"},{"location":"setup/software/nonstandard-install/#write-the-os-image-to-an-sd-card","title":"Write the OS image to an SD card","text":"<p>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.</p> <p>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 <code>.img</code>, <code>.img.gz</code>, or <code>.img.xz</code> 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.</p> <p>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 <code>ddrescue</code> on a Debian-based system, e.g. as follows:</p> <pre><code>gunzip planktoscope-v2.3-final.img.gz\nsudo ddrescue planktoscope-v2.3-final.img /dev/mmcblk0 --force\n</code></pre> <p>Warning: 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.</p>"},{"location":"setup/software/nonstandard-install/#configure-your-raspberry-pi","title":"Configure your Raspberry Pi","text":"<p>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.</p> <p>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.</p> <p>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 <code>en_US.UTF-8</code> 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 <code>pi</code> as the username, and you should choose a password you can remember. By default, the standard PlanktoScope SD card images use <code>copepode</code> 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.</p> <p>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.</p>"},{"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":"<p>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 <code>planktoscopehat</code> with the word <code>adafruithat</code> in any of the commands below.</p> <p>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):</p> StableBetaEdge <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- -v software/stable -H planktoscopehat\n</code></pre> <p>This 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.</p> <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- -v software/beta -H planktoscopehat\n</code></pre> <p>This 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.</p> <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- -v master -H planktoscopehat\n</code></pre> <p>This will install the current unstable development version of the PlanktoScope OS. This version is likely to be broken in various ways.</p> <p>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:</p> <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- -t tag -v v2024.0.0-alpha.1 -H planktoscopehat\n</code></pre> <p>You can also choose to install the PlanktoScope software from some other repository on GitHub instead of github.com/PlanktoScope/PlanktoScope, by using the <code>-r</code> 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:</p> <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- --help\n</code></pre>"},{"location":"setup/software/nonstandard-install/#wait-for-installation-to-finish","title":"Wait for installation to finish","text":"<p>The 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.</p> <p>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.</p>"},{"location":"setup/software/nonstandard-install/#connect-to-the-planktoscope","title":"Connect to the PlanktoScope","text":"<p>Next, you will need to restart the Raspberry Pi, e.g. with the following command:</p> <pre><code>sudo reboot now\n</code></pre> <p>This step is necessary to finish the PlanktoScope software setup process.</p> <p>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 <code>pkscope</code> followed by the unique randomly-generated name of your PlanktoScope, and whose password is <code>copepode</code>.</p> <p>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):</p> <ul> <li>http://planktoscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)</li> <li>http://pkscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)</li> <li>http://home.pkscope (this should work unless your web browser is configured to use a Private DNS provider)</li> <li>http://192.168.4.1 (this should always work)</li> <li>http://192.168.5.1 (this should always work)</li> </ul> <p>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 <code>pkscope-chain-list-27764 login:</code>, then the PlanktoScope is named <code>pkscope-chain-list-27764</code>).</p> <p>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.</p>"},{"location":"setup/software/nonstandard-install/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"location":"setup/software/standard-install/","title":"Standard Installation","text":"<p>This page provides instructions for installing the most recent standard version of the PlanktoScope OS on a PlanktoScope.</p>"},{"location":"setup/software/standard-install/#set-up-the-sd-card","title":"Set up the SD card","text":"<p>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.</p>"},{"location":"setup/software/standard-install/#prerequisites","title":"Prerequisites","text":"<p>In order to complete this step, you will need all of the following:</p> <ol> <li>A microSD card for your Raspberry Pi.</li> <li>A separate computer which can flash SD card images to your microSD card.</li> </ol>"},{"location":"setup/software/standard-install/#download-the-planktoscope-software-sd-card-image","title":"Download the PlanktoScope software SD card image","text":"<p>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.</p>"},{"location":"setup/software/standard-install/#write-the-image-to-the-sd-card","title":"Write the image to the SD card","text":"<p>To write the image file to your microSD card:</p> <ol> <li>Download, install, and start the latest version of the Raspberry Pi Imager.</li> <li>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.</li> <li>Press the \"Choose Device\" button. Select \"No filtering\" from the menu. It actually doesn't matter what you select here.</li> <li>Press the \"Choose OS\" button. Select \"Use custom\" from the menu (this is why it doesn't matter what you selected in the \"Choose Device\" menu). In the file dialog, open the PlanktoScope SD card image file you downloaded in the previous section of this setup guide.</li> <li>Press the \"Choose Storage\" button. Select your SD card from the menu.</li> <li>Press the \"Next\" button. A pop-up dialog should appear asking if you would like to customize the OS. You should probably press the \"No\" button unless you are already experienced with the PlanktoScope software, because most of the settings inside don't matter to typical users of the PlanktoScope software, and because it's possible to break the software with incorrect settings.</li> <li>A pop-up dialog should appear asking you to confirm whether you selected the correct SD card and want to wipe all data on the SD card in order to write the PlanktoScope SD card image to your SD card. If you are ready, press the \"Yes\" button.</li> <li>The Raspberry Pi Imager will begin overwriting your SD card with the PlanktoScope SD card image. This will take a while to finish.</li> </ol> <p>Once flashing is complete, unmount the SD card and remove it from the computer.</p>"},{"location":"setup/software/standard-install/#insert-the-sd-card-into-the-planktoscope","title":"Insert the SD card into the PlanktoScope","text":"<p>Insert the microSD card into the Raspberry Pi computer installed in your PlanktoScope.</p>"},{"location":"setup/software/standard-install/#connect-to-the-planktoscope","title":"Connect to the PlanktoScope","text":"<p>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 <code>pkscope</code> followed by the unique randomly-generated name of your PlanktoScope. The password of this Wi-Fi network is <code>copepode</code>.</p> <p>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.</p> <p>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):</p> <ul> <li>http://planktoscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)</li> <li>http://pkscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)</li> <li>http://home.pkscope (this should work unless your web browser is configured to use a Private DNS provider)</li> <li>http://192.168.4.1 (this should always work)</li> <li>http://192.168.5.1 (this should always work)</li> </ul> <p>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.</p>"},{"location":"setup/software/standard-install/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"location":"troubleshooting/","title":"Troubleshooting","text":"<p>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 <code>#3-start-testing</code> channel on Slack.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"PlanktoScope Documentation","text":"<p>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:</p> <ol> <li>\"I want to get a PlanktoScope!\"</li> <li>\"I want to learn how to operate a PlanktoScope!\"</li> <li>\"I want to fix something which isn't working on my PlanktoScope!\"</li> <li>\"I want to get involved in the PlanktoScope community!\"</li> <li>\"I want to study the design of the PlanktoScope!\"</li> </ol>"},{"location":"#what-is-planktoscope","title":"What is PlanktoScope?","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p></p>"},{"location":"#what-is-the-planktoscope-project","title":"What is the PlanktoScope project?","text":"<p>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.</p>"},{"location":"#who-are-planktoscopes-for","title":"Who are PlanktoScopes for?","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>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!</p>"},{"location":"faq/","title":"Frequently Asked Questions","text":"<p>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!</p>"},{"location":"faq/#can-i-purchase-a-planktoscope","title":"Can I purchase a PlanktoScope?","text":"<p>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.</p>"},{"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":"<p>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.</p> <p>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.</p>"},{"location":"community/","title":"The PlanktoScope Community","text":"<p>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.</p> <p>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.</p>"},{"location":"community/#engage-on-github","title":"Engage on GitHub","text":"<p>Feel free to visit the GitHub and engage if you want.</p> <p></p> <p>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.</p> <p>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.</p>"},{"location":"community/#chat-on-slack","title":"Chat on Slack","text":"<p>The community is using Slack to communicate.</p> <p></p> <p>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.</p> <p>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.</p>"},{"location":"community/#classify-on-ecotaxa","title":"Classify on EcoTaxa","text":"<p>To join EcoTaxa, you just need to create an account.</p> <p></p> <p>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.</p> <p>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.</p>"},{"location":"community/code-of-conduct/","title":"Contributor Covenant Code of Conduct","text":""},{"location":"community/code-of-conduct/#our-pledge","title":"Our Pledge","text":"<p>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.</p> <p>We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.</p>"},{"location":"community/code-of-conduct/#our-standards","title":"Our Standards","text":"<p>Examples of behavior that contributes to a positive environment for our community include:</p> <ul> <li>Demonstrating empathy and kindness toward other people</li> <li>Being respectful of differing opinions, viewpoints, and experiences</li> <li>Giving and gracefully accepting constructive feedback</li> <li>Accepting responsibility and apologizing to those affected by our mistakes,   and learning from the experience</li> <li>Focusing on what is best not just for us as individuals, but for the overall   community</li> </ul> <p>Examples of unacceptable behavior include:</p> <ul> <li>The use of sexualized language or imagery, and sexual attention or advances of   any kind</li> <li>Trolling, insulting or derogatory comments, and personal or political attacks</li> <li>Public or private harassment</li> <li>Publishing others' private information, such as a physical or email address,   without their explicit permission</li> <li>Other conduct which could reasonably be considered inappropriate in a   professional setting</li> </ul>"},{"location":"community/code-of-conduct/#enforcement-responsibilities","title":"Enforcement Responsibilities","text":"<p>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.</p> <p>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.</p>"},{"location":"community/code-of-conduct/#scope","title":"Scope","text":"<p>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.</p>"},{"location":"community/code-of-conduct/#enforcement","title":"Enforcement","text":"<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at &lt; thibaut at fairscope.com &gt; . All complaints will be reviewed and investigated promptly and fairly.</p> <p>All community leaders are obligated to respect the privacy and security of the reporter of any incident.</p>"},{"location":"community/code-of-conduct/#enforcement-guidelines","title":"Enforcement Guidelines","text":"<p>Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:</p>"},{"location":"community/code-of-conduct/#1-correction","title":"1. Correction","text":"<p>Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.</p> <p>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.</p>"},{"location":"community/code-of-conduct/#2-warning","title":"2. Warning","text":"<p>Community Impact: A violation through a single incident or series of actions.</p> <p>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.</p>"},{"location":"community/code-of-conduct/#3-temporary-ban","title":"3. Temporary Ban","text":"<p>Community Impact: A serious violation of community standards, including sustained inappropriate behavior.</p> <p>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.</p>"},{"location":"community/code-of-conduct/#4-permanent-ban","title":"4. Permanent Ban","text":"<p>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.</p> <p>Consequence: A permanent ban from any sort of public interaction within the community.</p>"},{"location":"community/code-of-conduct/#attribution","title":"Attribution","text":"<p>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.</p> <p>Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.</p> <p>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.</p>"},{"location":"community/license/","title":"Our work is fully open source","text":"<p>That's the headline, yes.</p>"},{"location":"community/license/#hardware-files","title":"Hardware files","text":"<p>We released our hardware files (everything in the <code>hardware</code> directory) under a CERN OHL-S license.</p>"},{"location":"community/license/#software-source","title":"Software source","text":"<p>Our source code (everything in the directories <code>flows</code> and <code>scripts</code>) is released under a GPL-3.0 license.</p>"},{"location":"community/license/#everything-else-documentation-pictures-etc","title":"Everything else (documentation, pictures, etc...)","text":"<p>Everything else is released under a Creative Commons CC-BY-SA license.</p>"},{"location":"community/trainings/","title":"Trainings","text":"<p>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.</p>"},{"location":"community/trainings/#the-train-the-trainer-program","title":"The Train the trainer program","text":"<p>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.</p> <p>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.</p>"},{"location":"community/trainings/#event-types","title":"Event types","text":""},{"location":"community/trainings/#build-workshop","title":"Build workshop","text":"<p>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.</p>"},{"location":"community/trainings/#selecting-the-production-site","title":"Selecting the production site","text":"<p>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:</p> <ol> <li>Check the Manufacturing and Assembly Guides: Before choosing a production site, make sure to review the PlanktoScope Kit Manufacturing Guide and the Device Assembly Guide. These guides will provide detailed information on the necessary tools and equipment required for the production of the PlanktoScope Kits.</li> <li>Visit Fablab and Hackspaces: Consider visiting Fablabs or Hackspaces in your region. These organizations often have a culture of openness and may be willing to support you with your project. They may have the necessary tools and equipment to produce the PlanktoScope Kits, as well as the knowledge and expertise to guide you through the production process.</li> <li>Commercial Manufacturing: Look for a facility that has the capability to handle small scale production runs, a good quality control process and a logistic plan to ship the product to the final destination. Many</li> </ol> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#material-procurement","title":"Material procurement","text":"<p>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:</p> <ol> <li>Prepare the order list: Use the bill of materials (BOM) as a starting point to create a comprehensive list of all materials needed for the workshop. Expand it with additional columns for suppliers, delivery dates, prices, shipping costs, and import taxes.</li> <li>Plan for packaging: Plan for extra packaging so you can assemble the parts as shown in the instructions. Try to minimize plastic as much as possible.</li> <li>Research suppliers: Research suppliers and see if there are local options, if you can consolidate orders to save costs and ensure timely delivery.</li> <li>Compare prices: Compare the prices of different suppliers to minimize the total cost.</li> <li>Plan for spare parts: Plan for spare parts in case something is broken or lost.</li> <li>Check your Budget: Check your budget and ensure that you have enough funds to cover the cost of all materials, shipping, and any additional expenses before placing your orders.</li> <li>Place orders: Once you have identified the best suppliers, place orders for all of the materials that you need. Be sure to factor in lead time when placing orders to ensure that the materials will arrive in time for the workshop.</li> <li>Track orders: Keep track of your orders and expected delivery dates, mark a component when it arrives. Contact suppliers if there are any delays or problems with delivery.</li> <li>Communicate: Communicate with participants if there are issues with timely delivery. It may make sense to postpone the workshop if there is not enough time to prepare and test everything. The participants will be grateful and will understand if it helps to ensure that everything runs smoothly.</li> </ol> <p>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.</p> <p>Note</p> <p>If you have difficulty finding the components you need, contact us and we will be happy to help you find the right alternative.</p> <p>Warning</p> <p>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.</p> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#prepare-the-kit","title":"Prepare the Kit","text":"<p>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:</p> <ol> <li>Review the Bill of Materials (BOM): Review the Bill of Materials (BOM) for the PlanktoScope to ensure that you have all the necessary parts and materials for the workshop. The parts list can be found in the Device Assembly Guide and lists all components and quantities needed to build a microscope.</li> <li>Divide the kit components according to the BOM: Once the materials have been received, divide the kit components from the orders according to the Bill of Materials (BOM) of the PlanktoScope. This will ensure that each participant receives the correct components and that there are no missing parts.</li> <li>Have extra components: Have extra components on hand in case of any missing or damaged parts during the workshop.</li> <li>Package the kits: Package the kits in a way that makes it easy for the participants to find and use the components during the workshop.</li> <li>Label materials: Label the packages as described in Device Assembly Guide so that they are easy to find and distribute during the workshop.</li> <li>Preparation of the housing parts: Prepare the housing parts by applying the surface sealant and insert the nuts to screw the housing as described in the Kit Manufacturing Guide.</li> <li>Cutting and soldering of electronic cables: Cut and solder the electronic cables for the PlanktoScope. This will save time during the workshop and ensure that the participants have all the necessary cables to complete the assembly.</li> <li>Setting up the embedded development environment: Set up the embedded development environment and flash the eeprom of the PlanktoScope hat. This will ensure that the PlanktoScope hat is ready to be used during the workshop.</li> <li>Download the Raspberry Pi image: Download the Raspberry Pi image and flash it to the SD card. This will ensure that the participants have a ready to use image for the PlanktoScope.</li> <li>Test the kits: Test the kits before the workshop to ensure that all components are working correctly and that the instructions are clear and easy to follow. This will help to ensure that the participants have a positive and productive experience during the workshop.</li> </ol> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#conducting-the-workshop","title":"Conducting the workshop","text":"<p>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!</p> <ol> <li>Prepare the presentation: Prepare the presentation device and start your slides.</li> <li>Check-In: Once the Participants arrive, complete the check-in, share the agenda and set expectations for the workshop.</li> <li>Venue: Provide information about the venue, including where to find restrooms and where to buy food.</li> <li>Digital tools: Provide information about the digital tools that will be used during the workshop, such as the platform for collaboration, the survey tool and the chat channel, and how to access them.</li> <li>Data privacy: Inform about the privacy policy and the forms that need to be signed by the participants if you want to take photos.</li> <li>Introduction round: Begin with a round of introductions and give everyone a chance to introduce themselves, their background, and their interest in the project.</li> <li>Provide an overview: Provide details about the project, including the general mode of operation, the working materials such as the kit, the documentation and the git repository.</li> <li>Provide the Kits and Tools: Provide the Kit and Tools to each participant with a kit and the necessary tools.</li> <li>Follow the build instructions: Depending on the format you have chosen, start implementing by following the Kit Manufacturing guide or Device Assembly guide</li> <li>Follow the operation instructions: Now that you have successfully assembled the PlanktoScope, you can proceed to operation of the PlanktoScope by following the Getting started and User interface instructions.</li> <li>Final Test: For a final test you can use for example pure cultures or a sample taken with a Plankton net from a surrounding waters.</li> </ol>"},{"location":"community/trainings/#field-trip","title":"Field trip","text":"<p>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!</p>"},{"location":"community/trainings/#hackathon","title":"Hackathon","text":"<p>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!</p>"},{"location":"community/trainings/#general-planning-methods","title":"General planning methods","text":"<p>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.</p> <p>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.</p>"},{"location":"community/trainings/#building-a-team","title":"Building a team","text":"<p>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.</p> <ol> <li>Identify the roles and responsibilities: Determine the key areas that need to be covered during the workshop and assign specific roles to team members. For example, one team member may be responsible for organizing logistics, while another may be responsible for creating the agenda.</li> <li>Assemble the team: Once the roles and responsibilities have been identified, begin assembling the team. Consider individuals with relevant skills and experiences, as well as those who have a passion for the topic of the workshop. It is also important to have a mix of team members from different departments or backgrounds to bring a variety of perspectives to the planning process.</li> <li>Communicate effectively: Establish clear lines of communication within the team to ensure that everyone is on the same page. This can be done through regular meetings, email, or a team collaboration platform.</li> <li>Encourage participation: Encourage team members to actively participate in the planning process by sharing their ideas and feedback. This will help to ensure that everyone feels invested in the success of the workshop.</li> <li>Appoint a leader: Appoint a leader for the team who will be responsible for coordinating the planning process and ensuring that the team stays on track. The leader should be someone who is organized, a good communicator, and able to delegate tasks effectively.</li> </ol>"},{"location":"community/trainings/#communication-channels","title":"Communication channels","text":"<p>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.</p> <ol> <li>Choose the right channels: Once the needs have been identified, choose the communication channels that will best serve those needs. Email, chat, and video conferencing are all popular options. If the group is small, a group chat or email chain may be sufficient. If the group is larger or more dispersed, a video conferencing platform may be more appropriate.</li> <li>Make sure they are accessible: Ensure that the communication channels you choose are accessible to all participants. This may include providing training or support for those who are less familiar with the tools you are using.</li> <li>Communicate expectations: Clearly communicate the expectations for using the communication channels to the participants. This includes guidelines for how often and when to check the channels, as well as how to respond to messages.</li> <li>Continuity: Make sure that you have continuity in the communication channels after the workshop. This will help to build a fluent community and to keep the participants connected and engaged. Use the same channels to share updates and resources, or to organize follow-up events or activities.</li> </ol> <p>Note</p> <p>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.</p> <p>Note</p> <p>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.</p> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#selecting-digital-tools","title":"Selecting digital tools","text":"<p>The right tools can help to facilitate communication, collaboration, and organization, making the workshop experience more productive and enjoyable for everyone.</p> <ol> <li>Use web-based tools: Whenever possible, use web-based tools that can be accessed from any device with an internet connection. This will make it easier for participants to access and use the tools, regardless of their location or device.</li> <li>Use collaborative note-taking tools: You might use web-based tools like HedgeDoc that allow participants to collaboratively collect notes during the workshop. This can help to ensure that everyone has access to the same information, and can help to make the workshop experience more productive and enjoyable for everyone.</li> <li>Use survey tools: You might use survey tools like LimeSurvey to gather information about the participants' needs and expectations for the workshop. This can help to ensure that the workshop is relevant, valuable, and effective for them.</li> <li>Use ticketing tools: You might use tools like Pretix to manage ticketing for the workshop. This can help to simplify the registration process, and can also provide valuable information about the attendees.</li> </ol>"},{"location":"community/trainings/#find-your-audience","title":"Find your audience","text":"<p>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.</p> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#determining-the-need","title":"Determining the need","text":"<p>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:</p> <ol> <li>Surveys and questionnaires: Use surveys and questionnaires to gather information about the participants' needs and expectations for the workshop. This can include their level of experience and knowledge, their specific interests and goals, and any challenges or concerns they may have.</li> <li>Pre-workshop consultation: Schedule pre-workshop consultations with the participants to discuss their needs and expectations in more detail. This can help to identify any specific areas of interest or concern, and can also provide an opportunity to address any questions or concerns the participants may have.</li> <li>Audience analysis: Analyze the characteristics of the audience, such as their profession, level of education and experience, and any other relevant details. This will give you a better idea of the type of content that will be most relevant and useful for the participants.</li> <li>Feedback: Ask for feedback from participants after the workshop and take it into account when planning future workshops. This feedback can be used to improve the overall experience and to tailor the workshop to better meet the needs of the participants.</li> </ol>"},{"location":"community/trainings/#defining-the-goals","title":"Defining the goals","text":"<p>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.</p> <ol> <li>Number of participants: The workshop should be designed for a specific number of participants. Depending on the available resources, the number of participants can range from small groups of 4-8 people to larger groups of 8-12 people.</li> <li>Number of microscopes: The goal of the workshop is to build a specific number of PlanktoScope Microscopes. It is important to have the necessary materials and tools for each participant to build their own microscope.</li> <li>Content: The workshop will include both theoretical and practical content. The theoretical content will cover the principles of open-source hardware and software and the specific design of the PlanktoScope Microscope. The practical content will focus on the assembly and usage of the microscope, including hands-on experience with soldering and other techniques.</li> </ol> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#financial-planning","title":"Financial planning","text":"<p>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:</p> <ol> <li>Decide on the cost of the kits: One of the first things to consider is whether you want to offer the kits for sale to the participants or if you want them to purchase the kits themselves. If you choose to offer the kits for sale, you will need to factor in the cost of materials and other expenses, such as shipping and handling. If you choose to have the participants purchase the kits themselves, you will need to provide them with information on where to purchase the kits and the estimated cost.</li> <li>Check for funding opportunities: There may be organizations or foundations that would be willing to support your workshop financially. It's a good idea to research potential sources of funding such as grants, sponsorships, and crowdfunding campaigns. Additionally, look for local or regional organizations that are working in the same field as your workshop, they might be interested in supporting your initiative.</li> <li>Reach out to potential sponsors: Once you have identified potential sources of funding, reach out to them to inquire about their funding opportunities. Be prepared to provide them with information about the workshop, including the goals, objectives, and expected outcomes. Be sure to include information about the open-source nature of the project, as this may make it more attractive to organizations with an interest in open-source technology.</li> <li>Look for cost-saving options: In addition to securing funding, there are also ways to save money on expenses. Consider renting equipment or space rather than purchasing it. Reach out to local universities or community organizations to see if they have equipment or space that you can use for the workshop at a reduced cost or for free.</li> </ol> <p>Tip</p> <p>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.</p>"},{"location":"community/trainings/#creating-a-timetable","title":"Creating a timetable","text":"<p>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:</p> <ol> <li>Plan for more than just a day: A workshop may take more than one day to complete, so be sure to plan accordingly. Consider the amount of time required to cover all the topics, and allocate enough time for each one.</li> <li>Assign an expected duration to each item on the schedule: Assign an expected duration to each item on the schedule so that participants know how much time they should expect to spend on each topic. This will also help you to ensure that you have allocated enough time for each topic.</li> <li>Allocate time for breaks and activities: Make sure to allocate time for breaks, meals and other activities such as group discussions, teamwork, or hands-on activities. This will help to keep the participants engaged and energized throughout the workshop.</li> <li>Plan for contingencies: Include some flexibility in the schedule to allow for unexpected events or delays. This will help to ensure that the workshop stays on track even if things don't go exactly as planned.</li> </ol>"},{"location":"community/trainings/#venue-selection","title":"Venue selection","text":"<p>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:</p> <ol> <li>Reach out to Universities, research institutions, Fablabs, Hackspaces or non-profit organizations: Reach out to organizations that might have an interest in the PlanktoScope, and a community that might support you with free access to their location.</li> <li>Check the equipment: Make sure the location is equipped with the necessary resources such as a whiteboard, projector/TV, and other equipment that may be required for the workshop.</li> <li>Check the accessibility: Check the accessibility of the location with the public transport system and parking availability.</li> <li>Check for food provision: Consider if there is a possibility to go shopping or how to provide food for the course participants during the workshop.</li> <li>Check the environment: Consider the environment of the location, make sure it is comfortable, has enough space and is well-ventilated for the workshop.</li> </ol>"},{"location":"community/trainings/#announcing-the-event","title":"Announcing the event","text":"<p>When announcing the event, it is important to include the following information:</p> <ol> <li>Date: Provide a specific date, start and end time for the workshop, and ensure there is enough lead time for preparation, including ordering or manufacturing materials and coordinating with suppliers. Allow ample time between announcing the workshop and the actual event.</li> <li>Goal: Clearly communicate the specific goal of the workshop, such as to build a fully functional planktoscope and learn how to use it.</li> <li>What attendees will learn in the workshop: Clearly outline the specific skills or knowledge that will be covered in the workshop, such as how to assemble the kit, soldering the through-hole components of the controller, and working with the software.</li> <li>Instructor's background: Provide some notes about the instructor's qualifications or experience that make them well-suited to lead the workshop, such as experience working with planktoscope.</li> <li>Target audience: Clearly indicate the target group of the workshop, such as researchers, engineers or designers.</li> <li>Previous knowledge: Specify any previous knowledge required for the workshop, such as soldering skills or experience working with open-source hardware and software.</li> <li>Implementation method: Describe the form of the workshop, such as a step-by-step guide.</li> <li>Documentation: Consider sharing the documentation beforehand, so they can familiarize themselves with the process.</li> <li>Cost: Clearly communicate the cost of the workshop.</li> <li>Schedule: Provide a clear and detailed schedule of the workshop, including the duration of the workshop, for example, one day of building and one day of using the plankoscope.</li> <li>Location: Provide the location of the workshop, including information on how to get there with public transportation or Arrival by car and parking. Also, provide a link to a map service</li> <li>Registration: Details of the registration process, including information on where to obtain a ticket and any deadlines for registration.</li> <li>Contact details: Additionally, it may be helpful to include contact information for any questions.</li> <li>Images: Include some visually appealing images, such as from a previous workshop or field trip, to show what attendees can expect from the event. This can additionally be a great way to build anticipation and excitement, thus motivating more people to attend the workshop.</li> <li>Media: Post your offer on a website or social media platform that is relevant to the workshop topic and your target audience. This way you can increase visibility and reach a wider audience, which increases the chances of getting more attendees.</li> </ol> <p>Tip</p> <p>If you already have a group of interested people, send a link to the announcement via email or chat and invite them personally.</p>"},{"location":"community/trainings/#preparing-a-presentation","title":"Preparing a presentation","text":"<p>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.</p> <ol> <li>Gather resources: Gather resources such as images, videos, and diagrams that can be used to support the presentation. These resources can be found on the Planktoscope website or other sources.</li> <li>Outline the main topics: Outline the main topics that will be covered during the workshop, such as the components of the microscope, the assembly process, and the use of the microscope.</li> <li>Prepare a handout: Prepare a handout or a guide that the participants can use during the workshop to follow the steps, and have it ready to be printed or shared digitally</li> <li>Practice the presentation: Practice the presentation several times before the workshop to ensure that it runs smoothly and that you are comfortable with the material.</li> <li>Be ready to adapt: Be ready to adapt the presentation during the workshop to fit the needs of the participants.</li> </ol> <p>Here are some topics that should be covered in a presentation:</p> <ol> <li>Event: Provide an overview of the event, including the goal of the workshop.</li> <li>Schedule: Provide an timetable for the event, including breaks, start and end times, and any planned activities for the next day.</li> <li>Venue: Provide information about the venue, including where to find restrooms and where to buy food.</li> <li>Instructor: Provide information about the instructor, including his or her background, and how to get in touch with him or her</li> <li>Digital tools: Provide information about the digital tools that will be used during the workshop, such as the platform for collaboration, the survey tool and the chat channel, and how to access them</li> <li>Data privacy: Provide information about the data privacy policy and the forms that need to be signed by the participants.</li> <li>Follow-ups: Point out follow-up actions such as the survey and that participation can be very helpful in improving the offer.</li> <li>Communication: Inform about the communication channels that will be used during the workshop and complete the onboarding.</li> <li>Introduction round: A round of introductions at the beginning of a workshop helps to create a sense of community and connection among the participants, allows the instructor to tailor the workshop to the group's needs, addresses potential language barriers, creates a sense of accountability, and helps participants to be more focused and relaxed.</li> <li>About the project: Provide details about the project, including the working materials such as the kit, the documentation, and the git repository.</li> </ol>"},{"location":"community/trainings/#send-an-final-reminder","title":"Send an final Reminder","text":"<p>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.</p> <ol> <li>Schedule for the event: Include a detailed schedule for the event, including breaks, start and end times, and any planned activities for the next day. This will help participants to plan their time and make the most of the workshop.</li> <li>About the venue: Provide detailed information about the venue, including the address, public transportation options, and parking situation. Make sure to include any specific instructions or requirements for accessing the venue.</li> <li>About the documentation: Provide a link to the documentation, such as the assembly and manufacturing guide, that the participants can familiarize themselves with before the workshop. This will help them to be better prepared and make the most of the workshop.</li> <li>Cancellation policy: Remind the participants that now is the last opportunity to cancel their registration. This will allow other individuals on the waiting list to attend the workshop.</li> <li>Final Instructions: Provide any final instructions or important information that the participants should be aware of before the workshop.</li> </ol>"},{"location":"community/trainings/#documenting-the-event","title":"Documenting the event","text":"<p>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.</p> <ol> <li>Equipment: Make sure you have the necessary equipment to document the event, including a camera (DSLR or mirrorless camera), lenses, memory cards, and batteries.</li> <li>Backup: Always make sure to have a backup plan for your equipment and photos, such as bringing extra memory cards and batteries.</li> <li>Lighting: Take into account the lighting conditions and make sure to have the right settings for your camera to capture the best possible images.</li> <li>Planning: Plan out the photos you want to take, taking into account the theme, location and schedule of the event.</li> <li>Composition: Pay attention to the composition of your photos and make sure to use techniques such as the rule of thirds and leading lines to create visually appealing images.</li> <li>Capturing candid moments: In addition to capturing posed shots, make sure to capture candid moments that capture the atmosphere and emotions of the event.</li> <li>Post-processing: Once the event is over, review and edit your photos to make them look their best.</li> <li>Data Privacy and Opt-Out: Pay attention to the privacy policy and get participants' consent before taking photos of them. Offer an opt-out option for participants who do not want to have photos taken. Clearly communicate what the photos will be used for and by whom, for example, to enhance this documentation.</li> <li>License: If your participants have agreed to share and use the photos, choose an appropriate license under which to license the photos. We recommend the Creative Commons license. For more information, see the project's license terms page.</li> <li>Sharing on Social Media: Share the photos on social media platforms to create a visual memory of the event and increase the visibility of the event.</li> </ol> <p>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.</p>"},{"location":"community/trainings/#follow-up","title":"Follow-up","text":"<p>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:</p> <ol> <li>Follow-up with participants: Send out a survey or contact participants individually to gather feedback on their experience during the workshop. This feedback can be used to improve future workshops and address any issues that may have arisen.</li> <li>Share resources and information: Share any relevant resources such as presentations, handouts, or any other materials that will help the participants continue their learning after the workshop.</li> <li>Build a community: Encourage participants to connect and share their experiences with each other. This can be done through online forums, social media groups, or other platforms. Building a community of enthusiasts and collaborators will help to ensure that the workshop's goals and objectives are met and that the participants leave the workshop with a sense of accomplishment.</li> <li>Continual learning: Provide additional training opportunities or resources for participants to continue their learning after the workshop. This could be through follow-up workshops, webinars, or online tutorials.</li> <li>Track progress: Keep track of the progress of the participants, check if they are applying what they learned during the workshop and give feedback to help them improve.</li> </ol>"},{"location":"community/trainings/#improve-this-training-program","title":"Improve this training program","text":"<p>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.</p> <p>Here are a few ways to improve this training program:</p> <ol> <li>Gather feedback: Regularly gather feedback from attendees, instructors and other stakeholders to understand how the program is being received and identify areas for improvement.</li> <li>Review and revise content: Review the content of the program and make changes as necessary to ensure that it is up-to-date, accurate, and relevant to the attendees.</li> <li>Continuously update the material: Continuously update the material, adding new information and best practices as it becomes available.</li> <li>Use different learning methods: Use different learning methods to accommodate different learning styles, such as hands-on activities, group discussions, and online resources.</li> <li>Encourage participation: Encourage participation and collaboration among attendees, creating an interactive and dynamic learning experience.</li> <li>Use modern technologies: Use modern technologies to enhance the learning experience, such as virtual reality, gamification, and AI-based learning.</li> <li>Assess the impact: Assess the impact of the program on the attendees and make changes as necessary to ensure that the program is achieving its intended goals.</li> </ol> <p>For more information on how to contribute to this document and improve this training program, please see the contribute section on Writing Documentation.</p>"},{"location":"community/contribute/documentation/","title":"Writing Documentation","text":"<p>The source files are in the main github repository, in the <code>docs</code> folder.</p> <p>They are simple Markdown files, that you can edit in any text editor of your choice.</p> <p>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.</p> <pre><code>hatch run docs:serve\n</code></pre> <p>After installing mkdocs, you can use <code>mkdocs serve</code> in the main folder of this repository to start the development server.</p> <p>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 <code>expert_setup.md</code>, please put all the related pictures in the <code>docs/expert_setup/</code> 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.</p> <p>Contributions should be made by creating pull requests on Github directly.</p>"},{"location":"community/contribute/documentation/#extensions-available","title":"Extensions available","text":"<p>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.</p> <ul> <li>SmartyPants: Converts ASCII dashes, quotes and ellipses to their HTML entity equivalents.</li> <li>Sane Lists: Alters the behavior of the Markdown List syntax to be less surprising.</li> <li>Admonition: Adds rST-style admonitions to Markdown documents.</li> <li>Table of contents: Generates a Table of Contents from a Markdown document and adds it into the resulting HTML document.</li> <li>Metadata: Adds a syntax for defining meta-data about a document.</li> <li>Tables: Adds the ability to create tables in Markdown documents.</li> <li>Fenced Code Blocks: Adds a secondary way to define code blocks.</li> </ul>"},{"location":"community/contribute/github/","title":"Contributing","text":"<p>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.</p> <p>There are several ways to join the development effort, share your progress with your build or just ask for help.</p> <p>We are using slack as a communication platform between interested parties. You can request to join by filling this form.</p> <p>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.</p>"},{"location":"community/contribute/github/#assumptions","title":"Assumptions","text":"<ol> <li>You're familiar with git and the Merge Request(PR) workflow.</li> <li>**You've read the PlanktoScope documentation.</li> <li>You know about the PlanktoScope community on Slack. Please use this for help.</li> </ol>"},{"location":"community/contribute/github/#how-to-contribute","title":"How to Contribute","text":"<ol> <li>Make sure that the contribution you want to make is explained or detailed in a GitHub issue! Find an existing issue or open a new one.</li> <li>Once done, fork the PlanktoScope repository in your Github account. Ask a mastertainer if you want your issue to be checked before making a PR.</li> <li>Create a new Git branch.</li> <li>Review the Development Workflow section that describes the steps to mastertain the repository.</li> <li>Make the changes on your branch.</li> <li>Submit the branch as a PR pointing to the <code>master</code> 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.</li> </ol>"},{"location":"community/contribute/github/#git-guidelines","title":"Git Guidelines","text":""},{"location":"community/contribute/github/#git-branches","title":"Git Branches","text":"<p>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.</p>"},{"location":"community/contribute/github/#git-commits","title":"Git Commits","text":"<p>As minimal requirements, your commit message should:</p> <ul> <li>be capitalized</li> <li>not finish by a dot or any other punctuation character (!,?)</li> <li>start with a verb so that we can read your commit message this way: \"This commit will ...\", where \"...\" is the commit message.   e.g.: \"Fix the home page button\" or \"Add more tests for create_index method\"</li> </ul> <p>We don't follow any other convention, but if you want to use one, we recommend this one.</p>"},{"location":"community/contribute/github/#pull-requests","title":"Pull Requests","text":"<p>Some notes on PRs:</p> <ul> <li>Convert your PR as a draft if your changes are a work in progress: no one will review it until you pass your PR as ready for review.   The draft PR can be very useful if you want to show that you are working on something and make your work visible.</li> <li>The branch related to the PR must be up-to-date with <code>master</code> before merging. Fortunately, this project integrates a bot to automatically enforce this requirement without the PR author having to do it manually.</li> <li>All PRs must be reviewed and approved by at least one mastertainer.</li> <li>The PR title should be accurate and descriptive of the changes. The title of the PR will be indeed automatically added to the next release changelogs.</li> </ul>"},{"location":"community/contribute/github/#release-process-for-internal-team-only","title":"Release Process (for internal team only)","text":"<p>PlanktoScope tools follow the Semantic Versioning Convention.</p>"},{"location":"community/contribute/github/#automation-to-rebase-and-merge-the-prs","title":"Automation to Rebase and Merge the PRs","text":"<p>This project integrates a bot that helps us manage pull requests merging. Read more about this.</p>"},{"location":"community/contribute/github/#how-to-publish-the-release","title":"How to Publish the Release","text":"<p>\u26a0\ufe0f Before doing anything, make sure you got through the guide about Releasing an Integration.</p> <p>\u26a0\ufe0f Every PR that is merged to <code>master</code> introducing changes to the PlanktoScope needs to modify the file ``, by increasing the version of the chart accordingly.</p> <p>Every PR that is merged to <code>master</code> 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.</p> <p>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</p>"},{"location":"community/contribute/hardware/","title":"Hardware Development","text":""},{"location":"community/contribute/hardware/#planktoscope-case","title":"PlanktoScope Case","text":"<p>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.</p> <p>To get started with the project, you will need to install a development environment on your computer. Here are the steps to follow:</p> <ul> <li>Download and install Fusion 360 from the Autodesk website.</li> <li>Create a free Autodesk account and log in to Fusion 360.</li> <li>Join the PlanktoScope Case team in Fusion 360. This will give you access to all of the project files and allow you to collaborate with other team members.</li> <li>Familiarize yourself with the Fusion 360 interface and tools. There are many resources available online, including tutorials and user guides, to help you get up to speed.</li> <li>Start designing and testing your case components in Fusion 360. You can use the software to create 3D models, run simulations and stress tests, and collaborate with other team members in real-time.</li> </ul> <p>By following these steps, you will be able to successfully install a development environment and participate in the PlanktoScope Case using Autodesk Fusion 360.</p>"},{"location":"community/contribute/hardware/#planktoscope-hat","title":"PlanktoScope Hat","text":"<p>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).</p> <p>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:</p> <ul> <li>Download and install Autodesk Eagle from the official website. Make sure to select the appropriate version for your operating system (Windows, Mac, or Linux).</li> <li>Follow the instructions provided by Autodesk to complete the installation process. This may involve entering a license key or activating the software through your Autodesk account.</li> <li>Once Autodesk Eagle is installed, you may need to install additional libraries or tools depending on the specific requirements of the PlanktoScope Hat. These may include libraries for communicating with specific hardware components, or tools for debugging and testing your designs.</li> <li>Once you have installed all the necessary tools and libraries, you should be ready to start working on the PlanktoScope Hat using Autodesk Eagle. You can begin by opening the project files and familiarizing yourself with the existing design, or by creating new designs as needed.</li> </ul> <p>By following these steps, you can set up a development environment that allows you to contribute to the PlanktoScope Hat using Autodesk Eagle.</p>"},{"location":"community/contribute/software/","title":"How to help development for the PlanktoScope code","text":"<p>We are using the Github Flow approach for our development efforts.</p> <p>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.</p> <p>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!)</p>"},{"location":"community/contribute/software/#node-red","title":"Node-Red","text":"<p>Node-Red is our main process. We use the flow to manage our user interface through a dashboard instance.</p> <p></p> <p>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.</p> <p>To set up a Node-RED development environment on a Debian operating system, you will need to follow these steps:</p> <ol> <li>Install Node.js: Node-RED requires Node.js to be installed on your system. You can install Node.js using the package manager by running the following command: <code>sudo apt-get install nodejs</code></li> <li>Install npm (Node Package Manager): npm is a package manager for Node.js that is used to install and manage Node-RED and its dependencies. You can install npm by running the following command: <code>sudo apt-get install npm</code></li> <li>Install Node-RED: Once Node.js and npm are installed, you can install Node-RED by running the following command: <code>sudo npm install -g --unsafe-perm node-red</code></li> <li>Start the Node-RED server: You can start the Node-RED server by running the following command: <code>node-red</code></li> <li>Access the Node-RED editor: You can access the Node-RED editor by opening a web browser and going to the URL http://localhost:1880.</li> </ol> <p>By following these steps, you will be able to set up a Node-RED development environment on your Debian operating system and start building applications with the visual, drag-and-drop interface.</p>"},{"location":"community/contribute/software/#python","title":"Python","text":"<p>The python code is separated in four main processes, each with a specific set of responsibilities:</p> <ul> <li>The main process controls all the others, starts everything up and cleans up on shutdown</li> <li>The stepper process manages the stepper movements.</li> <li>The imager process controls the camera and the streaming server via a state machine.</li> <li>The segmenter process manages the segmentation and its outputs.</li> </ul> <p>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.</p> <p>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.</p>"},{"location":"operation/","title":"Operation","text":"<p>This page provides basic instructions for operating your PlanktoScope.</p> <p></p>"},{"location":"operation/#connect-directly-to-your-planktoscope","title":"Connect directly to your PlanktoScope","text":"<p>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.</p>"},{"location":"operation/#connect-with-an-ethernet-cable","title":"Connect with an Ethernet cable","text":"<p>You can connect your computer to the PlanktoScope by plugging an Ethernet cable between your computer and your PlanktoScope's Raspberry Pi.</p>"},{"location":"operation/#connect-with-the-planktoscopes-isolated-wi-fi-network","title":"Connect with the PlanktoScope's isolated Wi-Fi network","text":"<p>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.</p> <p></p> <p>As you can see, the name of your PlanktoScope's Wi-Fi network will be of the format <code>pkscope-{random word}-{random word}-{random number}</code>. 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 <code>{random-word}-{random-word}-{random number}</code>, which is just the name of the Wi-Fi network but without the <code>pkscope-</code> prefix (e.g. <code>chain-list-27764</code>). You should connect to the Wi-Fi network specific to your PlanktoScope.</p> <p>Unless you have changed the password of your PlanktoScope's Wi-Fi network, the password should be <code>copepode</code>.</p>"},{"location":"operation/#access-your-planktoscopes-software","title":"Access your PlanktoScope's software","text":"<p>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):</p> <ul> <li>http://planktoscope.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)</li> <li>http://pkscope.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)</li> <li>http://home.pkscope\u00a0(this should work unless your web browser is configured to use a Private DNS provider)</li> <li>http://192.168.4.1\u00a0(this should always work)</li> <li>http://192.168.5.1\u00a0(this should always work)</li> </ul> <p>Tip</p> <p>If you know the machine name of your PlanktoScope (which has format <code>{random-word}-{random-word}-{random number}</code>, e.g. <code>chain-list-27764</code>, you can also try the following URLs after replacing <code>{machine-name}</code> with the actual machine name of your PlanktoScope:</p> <p><code>http://pkscope-{machine-name}.local</code>\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)</p> <p><code>http://{machine-name}.pkscope</code>\u00a0(this should work unless your web browser is configured to use a Private DNS provider)</p> <p>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.</p> <p>Warning</p> <p>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.</p> <p>One of the above URLs should work, and your web browser should show a landing page with a list of links:</p> <p></p> <p>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.</p>"},{"location":"operation/#how-to-image-plankton","title":"How to image plankton","text":"<p>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).</p> <p>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.</p> <p>You can then do an acquisition run. This is the best way to learn about the machine and this process!</p> <p>Warning</p> <p>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.</p> <p>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.</p> <p>For quantitative imaging of water samples, refer to the following protocols published by members of the PlanktoScope community:</p> <ul> <li>\"Planktoscope protocol for plankton imaging V.2\" for software v2.3+ and hardware v2.5. A PDF copy of this protocol is also available for offline use.</li> <li>\"Planktoscope protocol for plankton imaging V.1\" for software v2.3 and hardware v2.1-2.3. A PDF copy of this protocol is also available for offline use.</li> </ul>"},{"location":"operation/clone-sd/","title":"Clone your SD card","text":"<p>If you want to create an SD card image from your PlanktoScope to use on other PlanktoScopes, you can follow the following steps.</p>"},{"location":"operation/clone-sd/#prepare-the-sd-card-for-cloning","title":"Prepare the SD card for cloning","text":"<p>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.</p>"},{"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":"<p>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 <code>/usr/libexec/prepare-custom-image</code> 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:</p> <pre><code>sudo /usr/libexec/prepare-custom-image\n</code></pre> <p>Once this script finishes running, it will shut down your PlanktoScope's Raspberry Pi.</p> <p>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 <code>rootfs</code> partition to delete any other sensitive files which were not removed by the <code>/usr/libexec/prepare-custom-image</code> script. For example, you may also want to delete or edit some or all of the following files from the <code>rootfs</code> partition in order to remove any sensitive or machine-specific information:</p> <ul> <li><code>etc/wpa_supplicant/wpa_supplicant.conf</code>: Wi-Fi configuration and network secrets.</li> <li><code>home/pi/.ssh/authorized_keys</code>: SSH public keys of devices authorized to remotely connect to the PlanktoScope.</li> <li><code>home/pi/data/</code>: 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.</li> <li><code>home/pi/.bash_history</code>: Bash command history.</li> <li><code>home/pi/.python_history</code>: Python command history.</li> <li><code>home/pi/.gitconfig</code>: Git configuration, which may contain user-specific details.</li> </ul> <p>Info</p> <p>You can also delete the files listed above before running the <code>/usr/libexec/prepare-custom-image</code> 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.</p> <p>Next, proceed to the Make an SD card image section of this guide.</p>"},{"location":"operation/clone-sd/#prepare-an-exact-backup","title":"Prepare an exact backup","text":"<p>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 <code>/usr/libexec/prepare-custom-image</code> script: that script will delete some files which you probably want to keep. Instead, you should edit the <code>/boot/cmdline.txt</code> file to add the string <code>init=/usr/lib/raspberrypi-sys-mods/firstboot</code> to the end of the file, for example resulting in a file which looks something like:</p> <pre><code>console=tty1 root=PARTUUID=someuniqueidhere rootfstype=ext4 fsck.repair=yes rootwait init=/usr/lib/raspberrypi-sys-mods/firstboot\n</code></pre> <p>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. Then proceed to the Make an SD card image section of this guide.</p> <p>Warning</p> <p>After you have finished cloning the SD card to an SD card image, you should edit the <code>/boot/cmdline.txt</code> file to remove the <code>init=/usr/lib/raspberrypi-sys-mods/firstboot</code> 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.</p>"},{"location":"operation/clone-sd/#make-an-sd-card-image","title":"Make an SD card image","text":""},{"location":"operation/clone-sd/#locate-the-sd-card","title":"Locate the SD card","text":"<p>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 <code>/dev/mmcblk0</code>, <code>/dev/sda</code>, or <code>/dev/sdb</code>; it should always be some file in <code>/dev</code>. To identify the device file for your SD card, run the command <code>sudo fdisk -l</code> in your terminal. The output may look something like:</p> <pre><code>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\n</code></pre> <p>To 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 <code>/dev/mmcblk0</code>.</p> <p>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 <code>umount</code> command. For example, if your device is <code>/dev/mmcblk0</code>, you will need to run:</p> <pre><code>sudo umount /dev/mmcblk0p1\nsudo umount /dev/mmcblk0p2\n</code></pre> <p>If the devices were already not mounted, you should expect to see (and you can safely ignore) error messages which look like:</p> <pre><code>umount: /dev/mmcblk0p1: not mounted.\numount: /dev/mmcblk0p2: not mounted.\n</code></pre>"},{"location":"operation/clone-sd/#clone-the-sd-card-to-an-image","title":"Clone the SD card to an image","text":"<p>To 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 <code>/dev/mmcblk0</code>, you could run the following command (replacing file paths and names accordingly):</p> <pre><code>sudo dd bs=4M if=/dev/mmcblk0 of=/some/path/here/image-name-here.img status=progress\n</code></pre> <p>This will create a <code>.img</code> file (at <code>/some/path/here/image-name-here.img</code>) 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.</p>"},{"location":"operation/clone-sd/#shrink-the-sd-card-image","title":"Shrink the SD card image","text":"<p>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):</p> <pre><code>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\n</code></pre> <p>If you had set up the PlanktoScope software on a Raspberry Pi OS Lite image, you should get a <code>image-name-here.img.gz</code> file which is at least 2 GB in size.</p>"},{"location":"operation/clone-sd/#use-the-sd-card-image","title":"Use the SD card image","text":"<p>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.</p>"},{"location":"operation/maintenance/","title":"Maintenance and Repair","text":"<p>Instructions for maintaining and repairing the PlanktoScope.</p>"},{"location":"operation/maintenance/#cleaning-the-optics","title":"Cleaning the optics","text":"<ul> <li>Begin by turning off the microscope and unplugging it from any power source.   Gently remove any dust or debris using a soft, dry cloth.</li> <li>To clean the lenses and other optics, use a lens cleaning solution and a lens cleaning tissue or cloth. Gently wipe the optics in a circular motion, starting from the center and working outward. Avoid applying too much pressure or using a rough cloth, as this can scratch or damage the optics.</li> <li>Once you have finished cleaning the optics, use a dry cloth to remove any excess moisture or cleaning solution.</li> </ul>"},{"location":"operation/maintenance/#software-updates","title":"Software updates","text":"<p>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.</p> <p>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.</p>"},{"location":"operation/sample-collection/","title":"Sample collection","text":"<p>The most common way to collect samples for the PlanktoScope is to use a plankton net.</p>"},{"location":"operation/sample-collection/#plankton-net","title":"Plankton Net","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p></p> <p>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.</p> <p>Plankton nets can be made easily with a good sewind machine and some hardware.</p>"},{"location":"operation/user-interface/","title":"User interface guide","text":"<p>This guide will help you understand how to use the Node-RED dashboard, which is the primary user interface for operating the PlanktoScope.</p> <p></p>"},{"location":"operation/user-interface/#home","title":"Home","text":"<p>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.</p> <p>From here, you can quickly access any of the available tabs. The buttons are only the most used functionnalities of the machine. Three others tabs are accessible only through the hamburger menu on the top left of the screen (the three horizontal lines):</p> <ul> <li>Wifi</li> <li>Administration</li> <li>Hardware Config</li> </ul> <p></p> <p>Tip</p> <p>This list is also available from any other tab and allows you to quickly navigate between tabs.</p>"},{"location":"operation/user-interface/#machine-shutdown","title":"Machine shutdown","text":"<p>From this page, you can also shutdown the machine when you are done.</p> <p>Warning</p> <p>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!</p> <p>To shutdown the machine, first unlock the shutdown button by clicking on \"Unlock Button\".</p> <p></p> <p>You can then click on \"Shutdown\". The machine will ask for a final confirmation and will then shut itself down.</p> <p></p>"},{"location":"operation/user-interface/#sample-tab","title":"Sample Tab","text":"<p>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.</p> <p></p> <p>Depending on the device you choose, the page will change to reflect the needed information.</p> <p>There is a mechanism of validation of the submitted data. Please be careful to use the format given in example for each input field.</p> <p></p> <p>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.</p> <p></p> <p>Once all the fields are completed, you can go to the next tab by clicking the -&gt; arrow. This will make sure all the inserted data is valid.</p>"},{"location":"operation/user-interface/#optic-configuration","title":"Optic Configuration","text":"<p>This page allows you to control the optical setup of the acquisition.</p> <p></p> <p>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.</p> <p>Warning</p> <p>For now, the characteristics shown here are not true values (except if you use the 25mm/16mm lens couple).</p> <p>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.</p> <p>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.</p> <p>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.</p> <p>As with all the tabs, once you are satisfied with your focus and your image settings, you can click on \"Continue\".</p>"},{"location":"operation/user-interface/#fluidic-acquisition","title":"Fluidic Acquisition","text":"<p>Finally, this is where the magic happens! You will be able to chose the final parameters of your capture.</p> <p></p> <p>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.</p> <p>Warning</p> <p>Make sure the Total pumped volume is lower than the volume of your sample.</p>"},{"location":"operation/user-interface/#gallery","title":"Gallery","text":"<p>This simple page will allow you to preview and download the captured data.</p>"},{"location":"operation/user-interface/#system-monitoring","title":"System Monitoring","text":"<p>This tab allows you to monitor the physical characteristics of the machine and follow the processor load, CPU temperature, memory use and disk usage.</p> <p></p> <p>You also can find information about the software version you are using, the machine name and its camera.</p>"},{"location":"operation/user-interface/#wifi","title":"Wifi","text":"<p>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.</p> <p>Start by doing a network scan by clicking on the <code>Scan</code> 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 <code>Add the network</code> 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.</p> <p>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).</p> <p>Clicking on the button <code>Reset wifi networks</code> 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.</p> <p>Info</p> <p>For now, only WPA/WPA2 Personal security is supported; Wi-Fi networks without passwords are not supported.</p> <p>Warning</p> <p>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.</p>"},{"location":"operation/user-interface/#administration","title":"Administration","text":"<p>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.</p>"},{"location":"operation/user-interface/#hardware-settings","title":"Hardware Settings","text":"<p>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.</p>"},{"location":"reference/","title":"Technical Reference","text":"<p>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.</p>"},{"location":"reference/#key-features","title":"Key Features","text":"<p>Here are some key features of the PlanktoScope:</p> <ol> <li>Low cost: The PlanktoScope is designed to be affordable, with parts costing under $1000.</li> <li>Modular: The PlanktoScope is modular, meaning it can be easily reconfigured to meet the changing needs of users.</li> <li>Open-source: The PlanktoScope is based on open-source hardware and software, making it accessible to a wide community of engineers, researchers, and citizens.</li> <li>Versatility: The PlanktoScope is versatile, and can be used to study a variety of plankton types, including laboratory cultures and natural micro-plankton communities.</li> <li>High-throughput: The PlanktoScope is capable of high-throughput quantitative imaging, allowing users to analyze large numbers of samples quickly and efficiently.</li> <li>WiFi-enabled: The PlanktoScope can be controlled from any WiFi-enabled device, making it easy to use and deploy in a variety of settings.</li> <li>Portable: The PlanktoScope is small and portable, making it easy to transport and use in the field.</li> <li>Ease of use: The PlanktoScope is designed to be easy to use, with instructions for assembly and use available on the PlanktoScope website.</li> </ol>"},{"location":"reference/hardware/changelog/","title":"Changelog","text":"<p>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:</p>"},{"location":"reference/hardware/changelog/#v26","title":"v2.6","text":"<p>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.</p>"},{"location":"reference/hardware/changelog/#v25","title":"v2.5","text":"<p>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.</p>"},{"location":"reference/hardware/changelog/#v24","title":"v2.4","text":"<p>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.</p> <p>This version was only an internal prototype for the PlanktoScope development team.</p>"},{"location":"reference/hardware/changelog/#v23","title":"v2.3","text":"<p>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.</p> <p>This version was only an internal prototype for the PlanktoScope development team.</p>"},{"location":"reference/hardware/changelog/#v22","title":"v2.2","text":"<p>This was a prototype version of the hardware which replaced the Adafruit Stepper Motor HAT with a Waveshare Stepper Motor HAT.</p> <p>This version was only an internal prototype for the PlanktoScope development team.</p>"},{"location":"reference/hardware/changelog/#v21","title":"v2.1","text":"<p>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.</p>"},{"location":"reference/hardware/changelog/#v10","title":"v1.0","text":"<p>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.</p> <p>This design was complicated to assemble, and it suffered from unreliable electronic communication between the modules, so it was never publicly released.</p>"},{"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":"<p>Address 0x52 Configured through a kernel driver.</p>"},{"location":"reference/hardware/hat/#oled-display","title":"OLED Display","text":"<p>Address 0x3c</p>"},{"location":"reference/hardware/hat/#led-control-lm36011","title":"LED control: LM36011","text":"<p>Address 0x64 Control through specific software, current range from 0 to 376mA in normal mode, up to 1.5A in flash mode.</p>"},{"location":"reference/hardware/hat/#spi0-bus","title":"SPI0 Bus","text":""},{"location":"reference/hardware/hat/#motor-controller-0-tmc5160","title":"Motor Controller 0: TMC5160","text":"<p>Chip Enable: SPI0_CE0 Motor Enable: GPIO23</p> <p>Diagnostic output: GPIO16 for Error output GPIO20 for Stall output</p>"},{"location":"reference/hardware/hat/#motor-controller-1-tmc5160","title":"Motor Controller 1: TMC5160","text":"<p>Chip Enable: SPI0_CE1 Motor Enable: GPIO5</p> <p>Diagnostic output: GPIO16 for Error output GPIO20 for Stall output</p>"},{"location":"reference/hardware/hat/#gpio","title":"GPIO","text":""},{"location":"reference/hardware/hat/#fan-control","title":"Fan control","text":"<p>PWM1 control through GPIO13</p>"},{"location":"reference/hardware/hat/#led-output-selection","title":"LED Output selection","text":"<p>GPIO18: high for LED1, low for LED2</p>"},{"location":"reference/hardware/hat/#led-strobe","title":"LED Strobe","text":"<p>GPIO22 for pulse</p>"},{"location":"reference/hardware/hat/#i2c0-bus","title":"I2C0 Bus","text":""},{"location":"reference/hardware/hat/#eeprom-m24c32","title":"EEPROM M24C32","text":"<p>Address 0x50 For HAT information only.</p>"},{"location":"reference/hardware/product-specs/","title":"Product Specifications","text":"<p>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.</p>"},{"location":"reference/hardware/product-specs/#v26","title":"v2.6","text":"<p>Overview:</p> <ul> <li>Weight: 3.5 kg</li> <li> <p>Enclosure:</p> <ul> <li>Dimensions: 27.5 cm (length) x 12.5 cm (width) x 10.5 cm (height)</li> <li>Material: bamboo plywood</li> <li>Fabrication process: CNC milling</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#functionalities","title":"Functionalities","text":"<ul> <li>Automated image acquisition, with a motorized pump and an embedded computer</li> <li>Precise focus adjustment, with motorized linear actuators</li> <li>Continuous mixing of input sample to prevent sedimentation of heavier particles, with a USB-powered bubbler</li> <li>On-board image processing, with the embedded computer</li> <li>Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer</li> <li>Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer</li> </ul>"},{"location":"reference/hardware/product-specs/#subsystems","title":"Subsystems","text":"<p>Optics:</p> <ul> <li> <p>Imaging characteristics:</p> <ul> <li>Optical magnification: 1.33</li> <li>Field of view: 3062 \u00b5m x 2295 \u00b5m</li> <li>Optical pixel size: 0.75 \u00b5m</li> <li>Depth of field: 95 \u00b5m</li> </ul> </li> <li> <p>Internal camera: Raspberry Pi High Quality Camera</p> <ul> <li>Sensor: Sony IMX477R</li> <li>Resolution: 12.3 Megapixels (4056 x 3040 pixels)</li> </ul> </li> <li> <p>Lenses:</p> <ul> <li>Objective lens: 12 mm focal length, M12</li> <li>Tube lens: 25 mm focal length, M12</li> <li>Lens mount: M12x0.5</li> </ul> </li> <li> <p>Illumination: white LED</p> </li> </ul> <p>Fluidics:</p> <ul> <li> <p>Flow cell: capillary with rectangular cross-section</p> <ul> <li>Thickness: 300 \u00b5m</li> <li>Material: glass</li> </ul> </li> <li> <p>Internal tubing:</p> <ul> <li>Material: Tygon S3 (contains no BPA or phthalates)</li> <li>Dimensions: 1.6 mm (1/16\") inner diameter, 3.2 mm (1/8\") outer diameter</li> <li>Connectors: Luer lock</li> </ul> </li> <li> <p>Peristaltic pump</p> </li> <li>Sample intake capacity: 20 mL</li> </ul> <p>Other internal electronics:</p> <ul> <li> <p>Embedded computer: Raspberry Pi 4 Model B</p> <ul> <li>Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz</li> <li>Memory: 4 GB RAM</li> <li>Storage: 128 GB capacity (micro-SD card, UHS speed class 3)</li> </ul> </li> <li> <p>Control board: PlanktoScope HAT v1.2</p> </li> </ul> <p>External interfaces &amp; connectivity:</p> <ul> <li>Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports</li> <li>Wired networking: Gigabit Ethernet</li> <li>Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi</li> <li>Power input: 12 V DC, up to 4 A of current draw (5.1 x 2.2 mm DC barrel jack, center positive)</li> <li>Latching push-button switch to toggle power</li> </ul> <p>External AC-to-DC power adapter:</p> <ul> <li>Input: 100-240 V AC, 50-60 Hz (IEC 60320 C8 socket)</li> <li>Output: 12 V DC, up to 4 A of current output (5.1 x 2.2 mm DC barrel jack, center positive)</li> <li>Dimensions: 126 mm (length) x 52 mm (width) x 35.5 mm (height)</li> <li>Weight: 0.25 kg</li> </ul>"},{"location":"reference/hardware/product-specs/#system-performance","title":"System performance","text":"<p>Image acquisition throughput:</p> <ul> <li>Volume of sample measured: 2.1 \u00b5L per acquired image</li> <li>Volume of sample pumped: ~15 \u00b5L per acquired image</li> <li>Maximum image acquisition rate: ~60 images/min</li> </ul> <p>Samples:</p> <ul> <li> <p>Object size range:</p> <ul> <li>Minimum for taxonomy: ~20 \u00b5m diameter for round objects</li> <li>Maximum: ~200 \u00b5m diameter for round objects (larger objects will clog the flow cell)</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#v25","title":"v2.5","text":"<p>Overview:</p> <ul> <li> <p>Enclosure:</p> <ul> <li>Dimensions: 27.5 cm (length) x 12.5 cm (width) x 10.5 cm (height)</li> <li>Material: bamboo plywood</li> <li>Fabrication process: CNC milling</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#functionalities_1","title":"Functionalities","text":"<ul> <li>Automated image acquisition, with a motorized pump and an embedded computer</li> <li>Precise focus adjustment, with motorized linear actuators</li> <li>Continuous mixing of input sample to prevent sedimentation of heavier particles, with a USB-powered bubbler</li> <li>On-board image processing, with the embedded computer</li> <li>Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer</li> <li>Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer</li> </ul>"},{"location":"reference/hardware/product-specs/#subsystems_1","title":"Subsystems","text":"<p>Optics:</p> <ul> <li> <p>Imaging characteristics:</p> <ul> <li>Field of view: 3670 \u00b5m x 2675 \u00b5m</li> <li>Optical pixel size: 0.88 \u00b5m</li> </ul> </li> <li> <p>Internal camera: Raspberry Pi High Quality Camera</p> <ul> <li>Sensor: Sony IMX477R</li> <li>Resolution: 12.3 Megapixels (4056 x 3040 pixels)</li> </ul> </li> <li> <p>Lenses:</p> <ul> <li>Objective lens: 16 mm focal length, M12</li> <li>Tube lens: 25 mm focal length, M12</li> <li>Lens mount: M12x0.5</li> </ul> </li> <li> <p>Illumination: white LED</p> </li> </ul> <p>Fluidics:</p> <ul> <li> <p>Flow cell: capillary with rectangular cross-section</p> <ul> <li>Thickness: 300 \u00b5m</li> <li>Material: glass</li> </ul> </li> <li> <p>Internal tubing:</p> <ul> <li>Material: Tygon S3 (contains no BPA or phthalates)</li> <li>Dimensions: 1.6 mm (1/16\") inner diameter, 3.2 mm (1/8\") outer diameter</li> <li>Connectors: Luer lock</li> </ul> </li> <li> <p>Peristaltic pump</p> </li> <li>Sample intake capacity: 20 mL</li> </ul> <p>Other internal electronics:</p> <ul> <li> <p>Embedded computer: Raspberry Pi 4 Model B</p> <ul> <li>Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz</li> <li>Memory: 4 GB RAM</li> <li>Storage: 128 GB capacity (micro-SD card, UHS speed class 3)</li> </ul> </li> <li> <p>Control board: PlanktoScope HAT v1.2</p> </li> </ul> <p>External interfaces &amp; connectivity:</p> <ul> <li>Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports</li> <li>Wired networking: Gigabit Ethernet</li> <li>Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi</li> <li>Power input: 12 V DC, up to 4 A of current draw (5.1 x 2.2 mm DC barrel jack, center positive)</li> <li>Latching push-button switch to toggle power</li> </ul> <p>External AC-to-DC power adapter:</p> <ul> <li>Input: 100-240 V AC, 50-60 Hz (IEC 60320 C8 socket)</li> <li>Output: 12 V DC, up to 4 A of current output (5.1 x 2.2 mm DC barrel jack, center positive)</li> <li>Dimensions: 126 mm (length) x 52 mm (width) x 35.5 mm (height)</li> <li>Weight: 0.25 kg</li> </ul>"},{"location":"reference/hardware/product-specs/#system-performance_1","title":"System performance","text":"<p>Image acquisition throughput:</p> <ul> <li>Volume of sample pumped: ~15 \u00b5L per acquired image</li> <li>Maximum image acquisition rate: ~60 images/min</li> </ul> <p>Samples:</p> <ul> <li> <p>Object size range:</p> <ul> <li>Maximum: ~200 \u00b5m diameter for round objects (larger objects will clog the flow cell)</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#v21","title":"v2.1","text":"<p>Overview:</p> <ul> <li> <p>Enclosure:</p> <ul> <li>Dimensions: ~32 cm (length) x ~5.5 cm (width) x ~15 cm (height)</li> <li>Material: acrylic, plywood, or fiberboard</li> <li>Fabrication process: laser cutting</li> </ul> </li> </ul>"},{"location":"reference/hardware/product-specs/#functionalities_2","title":"Functionalities","text":"<ul> <li>Automated image acquisition, with a motorized pump and an embedded computer</li> <li>Precise focus adjustment, with motorized linear actuators</li> <li>On-board image processing, with the embedded computer</li> <li>Local Wi-Fi network hotspot for local operation from a connected phone, tablet or laptop, with the embedded computer</li> <li>Internet connectivity via Wi-Fi or Ethernet for remote operation, with the embedded computer</li> </ul>"},{"location":"reference/hardware/product-specs/#subsystems_2","title":"Subsystems","text":"<p>Optics:</p> <ul> <li> <p>Imaging characteristics:</p> <ul> <li>Field of view: 2300 \u00b5m x 1730 \u00b5m</li> <li>Optical pixel size: 0.75 \u00b5m</li> </ul> </li> <li> <p>Internal camera: Raspberry Pi Camera Module 2</p> <ul> <li>Sensor: Sony IMX219</li> <li>Resolution: 8 Megapixels (3280 x 2464 pixels)</li> </ul> </li> <li> <p>Lenses:</p> <ul> <li>Objective lens: 12 mm focal length, M12</li> <li>Tube lens: 25 mm focal length, M12</li> <li>Lens mount: M12x0.5</li> </ul> </li> <li> <p>Illumination: white LED</p> </li> </ul> <p>Fluidics:</p> <ul> <li> <p>Flow cell: ibidi \u00b5-Slide I Luer channel slide</p> <ul> <li>Thickness: 200 \u00b5m, 400 \u00b5m, 600 \u00b5m, or 800 \u00b5m</li> <li>Material: Plastic (no surface modification)</li> </ul> </li> <li> <p>Internal tubing:</p> <ul> <li>Material: Tygon S3 (contains no BPA or phthalates)</li> <li>Dimensions: 1.6 mm (1/16\") inner diameter, 3.2 mm (1/8\") outer diameter</li> <li>Connectors: Luer lock</li> </ul> </li> <li> <p>Peristaltic pump</p> </li> <li>Sample intake capacity: 20 mL</li> </ul> <p>Other internal electronics:</p> <ul> <li> <p>Embedded computer: Raspberry Pi 4 Model B</p> <ul> <li>Processor: Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.8 GHz</li> <li>Memory: 4 GB RAM</li> </ul> </li> <li> <p>Control boards:</p> <ul> <li> <p>Adafruit Stepper Motor HAT</p> <ul> <li>Input voltage: 5 - 12 V DC</li> <li>Output voltage: 4.5 - 13.5 V DC</li> <li>Output current: up to 1.2 A continuous, 3 A peak</li> </ul> </li> <li> <p>Adafruit Ultimate GPS HAT</p> </li> </ul> </li> </ul> <p>External interfaces &amp; connectivity:</p> <ul> <li>Expansion: 2 USB 3.0 ports, 2 USB 2.0 ports, 2 micro-HDMI ports</li> <li>Wired networking: Gigabit Ethernet</li> <li>Wireless networking: 2.4 GHz and 5.0 GHz 802.11ac Wi-Fi</li> <li>Power input for embedded computer: 5 V DC, up to 3 A of current draw (USB-C)</li> <li>Power input for motors: 5 - 12 V DC, depending on pump motor (5.1 x 2.2 mm DC barrel jack, center positive)</li> </ul>"},{"location":"reference/software/changelog/","title":"Changelog","text":"<p>All notable changes to the PlanktoScope's software will be documented in this file.</p> <p>The format is based on Keep a Changelog, and this project uses Calendar Versioning with a <code>YYYY.minor.patch</code> scheme for all releases after <code>v2.3.0</code>. All dates in this file are given in the UTC time zone.</p>"},{"location":"reference/software/changelog/#v202400-beta2-2024-09-19","title":"v2024.0.0-beta.2 - 2024-09-19","text":""},{"location":"reference/software/changelog/#added","title":"Added","text":"<ul> <li>(System: administration) Added a Forklift-deployed script <code>/usr/libexec/prepare-custom-image</code> (which must be invoked with <code>sudo</code>) 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.</li> </ul>"},{"location":"reference/software/changelog/#changed","title":"Changed","text":"<ul> <li>(Application: GUI) Changed the default ISO value from 100 to 150.</li> </ul>"},{"location":"reference/software/changelog/#fixed","title":"Fixed","text":"<ul> <li>(Application: backend) Changed the hardware controller's libcamera-based camera controller to initialize its default image gain based on camera sensor type in order to match the GUI's default ISO value of 150, instead of initializing default image gain to 1.0 regardless of camera sensor type.</li> <li>(Breaking change; Application: backend) Changed the segmenter to include the acquisition ID in the filename of the metadata TSV file included with the EcoTaxa export ZIP archive; this is necessary to allow efficient bulk importing of such ZIP archives into EcoTaxa, which was previously prevented by the use of the same <code>ecotaxa_export.tsv</code> filename for all metadata TSV files.</li> <li>(Application: GUI) The Grafana server's CPU allowance should now be limited to one core, in an attempt to prevent it from starving other programs of CPU time shortly after booting up under certain situations.</li> </ul>"},{"location":"reference/software/changelog/#v202400-beta1-2024-06-24","title":"v2024.0.0-beta.1 - 2024-06-24","text":""},{"location":"reference/software/changelog/#added_1","title":"Added","text":"<ul> <li>(Application: GUI) On the <code>planktoscopehat</code> 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.</li> <li>(Release) A <code>fairscope-latest</code> SD card image is now provided which is identical to the <code>planktoscopehat</code> 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).</li> <li>(System: administration) The Forklift pallet provided by default as the SD card image is now named (and pinned as) the <code>factory-reset</code> staged pallet bundle.</li> <li>(System: networking) The <code>planktoscope.local</code> 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 <code>pkscope.local</code> or the machine-specific mDNS name (of format <code>pkscope-{machine-name}.local</code>) instead of <code>planktoscope.local</code>.</li> </ul>"},{"location":"reference/software/changelog/#changed_1","title":"Changed","text":"<ul> <li>(Breaking change; Application: GUI) The default settings configuration file for the <code>planktoscopehat</code> 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.</li> <li>(Release) SD card images are now released with xz compression (as <code>.img.xz</code> files) rather than gzip compression (as <code>.img.gz</code> files).</li> </ul>"},{"location":"reference/software/changelog/#removed","title":"Removed","text":"<ul> <li>(Application: GUI) On the <code>planktoscopehat</code> SD card image, a hardware version is no longer set in the default <code>config.json</code> 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.</li> <li>(Application: GUI) The Node-RED dashboard's Administration page's \"Dashboard Errors\" panel has been removed, because it doesn't show any useful messages.</li> <li>(System) <code>gcc</code> has been removed from the SD card image, to help reduce SD card image size.</li> </ul>"},{"location":"reference/software/changelog/#fixed_1","title":"Fixed","text":"<ul> <li>(Application: GUI) The flowcell setting from the <code>config.json</code> file should now be properly displayed as the default selection on the Node-RED dashboard's \"Fluidic Acquisition\" page.</li> </ul>"},{"location":"reference/software/changelog/#v202400-beta0-2024-06-07","title":"v2024.0.0-beta.0 - 2024-06-07","text":""},{"location":"reference/software/changelog/#changed_2","title":"Changed","text":"<ul> <li>(Application: GUI) The ISO selector in the \"Optic Configuration\" page has been changed from a button group to a slider (with an increment of 50), to enable somewhat finer adjustment of the ISO setting.</li> <li>(Breaking change; System) The official SD card images of PlanktoScope OS are now based on the 64-bit (arm64) version of the 2024-03-12 build of Raspberry Pi OS 11 (bullseye), instead of the 32-bit (armhf) version of the 2023-05-03 build of Raspberry Pi OS 11 (bullseye). This increases the performance of the Python segmenter, potentially by a factor of 2. This is expected to break compatibility with the raspimjpeg-based imaging module. If you need a 32-bit version of PlanktoScope OS, you will need to run the OS setup scripts following the PlanktoScope project's documentation's \"Non-standard installation\" guide for software setup.</li> <li>(System: administration) The <code>machine-name</code> 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) &amp; removeability/replaceability (by switching to a different pallet which provides a different version of - or does not provide - the <code>machine-name</code>).</li> </ul>"},{"location":"reference/software/changelog/#deprecated","title":"Deprecated","text":"<ul> <li>(System: networking)</li> <li>(System) 32-bit versions of PlanktoScope OS (which can be set up on a 32-bit version of Raspberry Pi OS using the OS setup scripts) are no longer officially supported by the project, but they will continue to work for v2024.0.0 of PlanktoScope OS.</li> </ul>"},{"location":"reference/software/changelog/#removed_1","title":"Removed","text":"<ul> <li>(Application: GUI) The landing page's links to Portainer have been removed, as part of the deprecation in v2024.0.0-alpha.2 of the inclusion of Portainer by default in the PlanktoScope OS's SD card images.</li> </ul>"},{"location":"reference/software/changelog/#fixed_2","title":"Fixed","text":"<ul> <li>(Application: GUI) The landing page's links to offline PDF copies of the protocols.io protocols for PlanktoScope operation are no longer broken.</li> <li>(Application: GUI) The maximum allowed value in the ISO selector in the \"Optic Configuration\" page has been reduced from 800 to 650, but only for the planktoscopehat version of the Node-RED dashboard; maximum allowed value is still 800 in the adafruithat version of the Node-RED dashboard. This change is because v2024.0.0-alpha.2's change to the scaling factor for converting between ISO settings and camera gains in the picamera2 library has meant that ISO values above 650 were converted to image gain values which were silently rejected for the Raspberry Pi HQ Camera used PlanktoScopes with hardware version at or above v2.3; this, this change prevents users from setting ISO values which would be silently rejected by the Python hardware controller.</li> </ul>"},{"location":"reference/software/changelog/#v202400-alpha2-2024-04-25","title":"v2024.0.0-alpha.2 - 2024-04-25","text":""},{"location":"reference/software/changelog/#added_2","title":"Added","text":"<ul> <li>(System: administration) The hostname can now be customized by modifying the hostname template (with string interpolation for the machine name) in <code>/etc/hostname-template</code>.</li> <li>(System: administration) The Cockpit configuration can now be customized by adding configuration snippets as drop-in files in <code>/etc/cockpit/cockpit.conf.d</code>, and adding origins to allow in <code>/etc/cockpit/origins.d</code>, and adding templated origins (with string interpolation for the machine name, the hostname, and the custom domain) to allow in <code>/etc/cockpit/origins-templates.d</code>.</li> <li>(System: administration) The dnsmasq configuration can now be customized by adding templated drop-in configuration files (with string interpolation for the machine name, the hostname, and the custom domain) in <code>/etc/dnsmasq-templates.d</code>, and by modifying the custom domain (which defaults to <code>pkscope</code>) in <code>/etc/custom-domain</code>.</li> <li>(System: administration) The hostapd configuration can now be customized by adding configuration snippets as drop-in files in <code>/etc/hostapd/hostapd.conf.d</code>, and adding templated drop-in files (with string interpolation for the machine name, the hostname, and the custom domain) in <code>/etc/hostapd/hostapd.conf-templates.d</code>.</li> <li>(System: administration) The hosts file can now be customized can now be customized by adding snippets as drop-in files at <code>/etc/hosts.d</code>, and and adding templated snippets (with string interpolation for the machine name, the hostname, and the custom domain) in <code>/etc/hosts-templates.d</code>.</li> <li>(System: administration) SSH host keys for the SSH server are now automatically generated (if deleted or otherwise missing) during every boot, not just during the first boot.</li> </ul>"},{"location":"reference/software/changelog/#changed_3","title":"Changed","text":"<ul> <li>(Breaking change; Application: backend) Previously, the segmenter's default behavior was to subtract consecutive masks to try to mitigate image-processing issues with objects which get stuck to the flowcell during imaging. However, when different objects occupied the same space in consecutive frames, the subtraction behavior would subtract one object's mask from the mask of the other object in the following frame, which would produce clearly incorrect masks. This behavior is no longer enabled by default; in order to re-enable it, you should enable the <code>pipeline-subtract-consecutive-masks</code> feature flag in the <code>apps/ps/backend/proc-segmenter</code> package deployment of the local Forklift pallet and re-apply the pallet.</li> <li>(Application: backend, GUI) The image quality of frames in the camera preview stream is increased, and frames also have greater width and height.</li> <li>(Breaking change; Application: GUI) The default settings configuration file for the <code>planktoscopehat</code> SD card image is now for the v2.6 PlanktoScope hardware; previously, it was still for the v2.5 hardware.</li> <li>(Breaking change; System: administration) The minimum supported Forklift version for Forklift pallets has increased from v0.4.0 to v0.7.0, due to new integration between Forklift and the filesystem.</li> <li>(System: administration) Forklift has been upgraded to v0.7.0, so that pallets are staged before being applied (and with automatic fallback to the last successfully-applied staged pallet), and so that systemd services, <code>/etc</code> config files, and some scripts in <code>/usr</code> are now managed by Forklift.</li> <li>(System: administration) <code>/etc</code> is now a overlay filesystem with all manually-edited files saved at <code>/var/lib/overlays/overrides/etc</code>.</li> <li>(System: administration) <code>/usr</code> is now a overlay filesystem with all manually-edited files saved at <code>/var/lib/overlays/overrides/usr</code>.</li> </ul>"},{"location":"reference/software/changelog/#deprecated_1","title":"Deprecated","text":"<ul> <li>(System: administration, troubleshooting; Application: GUI) Portainer will no longer be installed/provided by default after v2024.0.0. This is because it requires inclusion of a relatively large Docker container image in the PlanktoScope OS's SD card image (which is constrained to be up to 2 GB in size so that it can be attached as an upload to GitHub Releases), and because it has an annoying first-time user experience (i.e. that a password must be set within a few minutes of boot, or else the Portainer container must be restarted), and because Dozzle already provides all the basic functionalities needed by most users, and because Portainer has never actually been used for troubleshooting within the past year of the project, and because Portainer has a nontrivial impact on the sizes of the PlanktoScope OS SD card images (which are limited to 2 GB).</li> <li>(System: administration; Application: GUI) The \"USB backup\" functionality of the Node-RED dashboard will be removed in v2024.1.0 (the next release after v2024.0.0). Instead, you should use the datasets file browser for backing up and deleting dataset files on your PlanktoScope.</li> <li>(Application: backend) The raspimjpeg-based imaging module in the Python hardware controller has not yet been deleted so that you can change the Python hardware controller code to switch back from the new picamera2-based imaging module if picamera2 ends up causing big problems for you. However, we are deprecating the raspimjpeg-based imaging module, and we will fully delete it in a future release (perhaps v2024.1.0, or perhaps later).</li> </ul>"},{"location":"reference/software/changelog/#fixed_3","title":"Fixed","text":"<ul> <li>(Application: GUI) The white balance input validation, which previously only allowed gains between 1.0 and 8.0, now allows gains in the full range allowed by the camera (i.e. between 0.0 and 32.0).</li> <li>(Application: backend, GUI) The incorrect scaling factor for converting between ISO settings (in the Node-RED dashboard) and image gains in the new picamera2-based imager is fixed.</li> <li>(System: networking) Some uncommon edge cases for packet forwarding (e.g. accessing a one of the PlanktoScope's static IP addresses on a network interface not associated with that static IP address) should work now.</li> </ul>"},{"location":"reference/software/changelog/#v202400-alpha1-2024-03-26","title":"v2024.0.0-alpha.1 - 2024-03-26","text":""},{"location":"reference/software/changelog/#changed_4","title":"Changed","text":"<ul> <li>(Breaking change; System: setup) The word <code>pscopehat</code> has been replaced with <code>planktoscopehat</code> everywhere. This means that any distro setup scripts/commands you previously used with <code>pscopehat</code> should be changed.</li> <li>(Breaking change; Application: hardware controller) The hardware controller now uses <code>picamera2</code> instead of <code>raspimjpeg</code> 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.</li> </ul>"},{"location":"reference/software/changelog/#deprecated_2","title":"Deprecated","text":"<ul> <li>(Application: GUI) The current Node-RED dashboard (both the version for the Adafruit HAT and the version for the PlanktoScope HAT) is transitioning to maintenance mode: no new features will be added, and any bugs will be only be fixed if someone volunteers to fix them. The current Node-RED dashboard will be completely replaced by a fully-rewritten Node-RED dashboard, though there is no timeline for completion of that new dashboard. Currently, our plan for deprecating and eventually removing the current Node-RED dashboard is as follows: maintenance mode (no new features, only some bugfixes), then deprecation (no maintenance; not enabled by default, but still installed), then removal (not installed by default, but anyone is free to install it and see if it still works); deprecation will not occur before the rewritten Node-RED dashboard is stable for general-purpose usage. If you have concerns, please share your feedback on GitHub, in an email, or on the PlanktoScope Slack.</li> </ul>"},{"location":"reference/software/changelog/#fixed_4","title":"Fixed","text":"<ul> <li>(Breaking change; Application: backend) The default hardware configuration file for the <code>planktoscopehat</code> 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.</li> <li>(Application: hardware controller) The camera no longer overexposes captured images compared to the camera preview stream, and it no longer produces camera timeout errors.</li> <li>(Application: backend) The segmenter should no longer have file permissions errors when trying to read or write files in directories created by Docker or by the Python hardware controller.</li> </ul>"},{"location":"reference/software/changelog/#v202400-alpha0-2024-02-06","title":"v2024.0.0-alpha.0 - 2024-02-06","text":""},{"location":"reference/software/changelog/#added_3","title":"Added","text":"<ul> <li>(System: networking) Added support to share internet access and browser application access over additional network interfaces: a second Wi-Fi module, an additional Ethernet adapter, and a USB networking interface (made by plugging a phone to the Raspberry Pi in USB tethering mode).</li> <li>(Application: GUI) The \"System Monitoring\" page now shows the current system time on the Raspberry Pi and the current time in the web browser of the client device.</li> <li>(Application: GUI) The \"System Monitoring\" page now detects when the Raspberry Pi's system time is very different from the web browser's time, and shows a message and a buttom to change the Raspberry Pi's system time to match the web browser's time.</li> <li>(Application: GUI) The \"System Monitoring\" page's system metrics panel is now collapsible, and it now includes an expandable \"Detailed History\" subsection to view additional information.</li> <li>(System: administration) Added Dozzle as a viewer for Docker container logs.</li> <li>(System: networking) Added <code>lynx</code> as an alternative terminal web browser to <code>w3m</code> for trying to work through captive portals on the Cockpit terminal.</li> <li>(System: administration) Added Prometheus as a metrics collection &amp; storage system.</li> <li>(System: administration) Added Grafana as a metrics visualization &amp; alerting system.</li> </ul>"},{"location":"reference/software/changelog/#changed_5","title":"Changed","text":"<ul> <li>(Application: GUI) The \"System Monitoring\" page now uses a Grafana dashboard to display metrics.</li> <li>(Application: GUI) The \"Fluidic Acquisition\" page now uses a numeric text input instead of a slider for adjusting the \"Pumped volume\" setting, to make it easier to change the setting to a different exact value.</li> <li>(Application: GUI) On the \"Sample\" page, the input fields of the \"Sample Location\"/\"Net Throw Location\"/\"Net Retrieval Location\"/\"Culture Date and Time\" panels no longer get cleared when pressing the \"Validate\" button.</li> <li>(System: administration) Docker commands can now be run without <code>sudo</code>.</li> <li>(System: security) <code>ufw</code> has been replaced with <code>firewalld</code>. However, <code>firewalld</code> has not yet been properly configured.</li> <li>(System) The PlanktoScope's machine name is now saved to <code>/var/lib/planktoscope/machine-name</code> instead of <code>/home/pi/.local/etc/machine-name</code>, and it's now saved without a trailing newline.</li> </ul>"},{"location":"reference/software/changelog/#removed_2","title":"Removed","text":"<ul> <li>(Application: GUI) The \"System Monitoring\" page no longer displays a gauge for the CPU usage, since that information does not need to be monitored to ensure system stability &amp; usability. Instead, a CPU usage history graph can be found in the new \"Detailed History\" subsection.</li> <li>(System: administration) Removed <code>cockpit-storaged</code>, which was not useful enough to justify the number (and size of) unneeded dependencies it pulled in for the PlanktoScope software SD card image.</li> <li>(System: setup) Removed some unnecessary <code>apt-get update</code> commands for a very minor speed-up in the distro setup process.</li> </ul>"},{"location":"reference/software/changelog/#fixed_5","title":"Fixed","text":"<ul> <li>(Application: GUI) The \"Filtered volume\" field (on the \"Sample\" page) is now saved as the <code>sample_total_volume</code> metadata field for all sample types, not just horizontal Plankton tows (corresponding to the \"Plankton net\", \"High Speed Net\", and \"Tara decknet\" sample types).</li> <li>(System) Boot time has been made faster by approximately 1 minute.</li> <li>(Application: GUI) On Mozilla Firefox, the embedded file browser in the Node-RED dashboard's \"Gallery\" page should now consistently load with the correct height, instead of sometimes loading with an absurdly small height.</li> <li>(System: networking) The Raspberry Pi now correctly detects a phone connected in USB tethering mode to share internet access regardless of when the phone was connected, instead of only detecting that phone if USB tethering mode was enabled early in startup (specifically, before the <code>dhcpcd</code> service had started).</li> <li>(System: networking) Functionality for automatically updating the <code>/etc/hosts</code> file and the hostname based on the machine name has now been split into two separate system services, <code>planktoscope-org.update-hosts-machine-name.service</code> and <code>planktoscope-org.update-hostname-machine-name.service</code>.</li> </ul>"},{"location":"reference/software/changelog/#v202390-2023-12-30","title":"v2023.9.0 - 2023-12-30","text":"<p>(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)</p>"},{"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":"<ul> <li>(Application) A hardware configuration file for PlanktoScope hardware v2.6, which was previously missing, has been added. It is now the default hardware configuration file for <code>pscopehat</code> builds of the PlanktoScope distro.</li> </ul>"},{"location":"reference/software/changelog/#changed_6","title":"Changed","text":"<ul> <li>(System: infrastructure) Forklift has been upgraded from v0.3.1 to v0.4.0, which includes breaking changes to the schema of Forklift repositories and pallets.</li> </ul>"},{"location":"reference/software/changelog/#removed_3","title":"Removed","text":"<ul> <li>(Application: documentation) The offline documentation included on the PlanktoScope now omits the hardware setup guides.</li> </ul>"},{"location":"reference/software/changelog/#fixed_6","title":"Fixed","text":"<ul> <li>(Application: GUI) The white balance gains are now only validated and sent to the backend after the user changes focus away from the input field, instead of being validated and sent 300 ms after the user pauses while editing the value in the input field. This prevents the input validation from being run while the user is still editing the value.</li> <li>(Application) The default brightness of the illumination LED for the pscopehat version of the backend (for the custom PlanktoScope HAT) has been reduced; this a temporary workaround to a bug with raspimjpeg where saved images are overexposed even on the default brightness settings with minimum shutter speed and ISO, despite the brightness of raspimjpeg's camera preview looking reasonable (see https://github.com/PlanktoScope/PlanktoScope/issues/259 for details).</li> <li>(Application: GUI) In the \"Sample\" page, when the minimal &amp; maximal fraction size fields and min &amp; max sampling depth fields are both displayed simultaneously, now the adafruithat version of the Node-RED dashboard shows the fraction size fields on one row and the sampling depth fields on another row, rather than showing them in adjacent columns. This way, the adafruithat version of the Node-RED dashboard now matches the layout in the pscopehat version of the Node-RED dashboard.</li> <li>(Application: GUI) The \"System Monitoring\" page now correctly displays the PlanktoScope hardware version in the \"Information\" panel's \"Instrument Type\" field.</li> <li>(Application: GUI) The \"System Monitoring\" and \"Fluidic Acquisition\" pages now display a software version string which is either a tagged version (e.g. <code>v2023.9.0-beta.1</code>) when the version is tagged, or else a pseudoversion (e.g. <code>v2023.9.0-beta.1-36-gf276e84</code>) 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 <code>acq_software</code> metadata field.</li> <li>(Application: GUI) The <code>process_commit</code> 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.</li> <li>(Application: GUI) The <code>process_source</code> 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.</li> <li>(System: infrastructure) The SD card setup scripts now apply the Forklift pallet in order to create the Docker Compose services and resources ahead-of-time (rather than waiting for the first boot to do that work), so that the first boot of the SD card image will be much faster.</li> <li>(System: infrastructure) The distro setup scripts now work even if they are run from a repository downloaded to some path other than <code>/home/pi/PlanktoScope</code>.</li> <li>(Application: GUI) The landing page now links to the new project documentation site for online documentation, instead of the old project documentation site.</li> </ul>"},{"location":"reference/software/changelog/#v202390-beta1-2023-09-14","title":"v2023.9.0-beta.1 - 2023-09-14","text":""},{"location":"reference/software/changelog/#added_5","title":"Added","text":"<ul> <li>(System: networking) The PlanktoScope can now also be accessed using the domain name <code>pkscope.local</code> from any web browser where <code>planktoscope.local</code> 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).</li> <li>(System: administration, networking) In operating system's networking configuration files which have lines which are automatically generated based on the PlanktoScope's machine name, those lines now have accompanying code comments which explain the correct files to edit in order to make changes which will persist across device reboots.</li> <li>(System: administration, networking) You can now check the machine name at <code>/home/pi/.local/etc/machine-name</code>. It's updated when the PlanktoScope boots.</li> <li>(System: administration; Application: GUI) The Node-RED dashboard now provides some context on the \"Administration\" page for how to access the logs linked to from that page, and which links to use for providing logs on GitHub or Slack.</li> <li>(System: administration; Application: GUI) The Node-RED dashboard now provides some additional information about the side-effects of selecting a hardware version on the \"Hardware Settings\" page, specifically that the white balance settings will be overwritten.</li> </ul>"},{"location":"reference/software/changelog/#changed_7","title":"Changed","text":"<ul> <li>(Major user-facing change; System: networking) The top-level domain for domain names of format <code>home.planktoscope</code> and <code>{machine-name}.planktoscope</code> (e.g. http://metal-slope-23501.planktoscope) has been changed from <code>planktoscope</code> to <code>pkscope</code>, so that the domain names are now of format <code>home.pkscope</code> and <code>{machine-name}.pkscope</code>. Similarly, the machine-specific mDNS name has been changed from format <code>planktoscope-{machine-name}.local</code> to <code>pkscope-{machine-name}.local</code>.</li> <li>(User-facing change; System: networking) The SSIDs of wifi hotspots generated by the PlanktoScope has been changed from the format <code>PlanktoScope {machine-name}</code> to the format <code>pkscope-{machine-name}</code>. This makes it easier to determine the machine-specific mDNS URL: just add <code>.local</code>, to get <code>pkscope-{machine-name}.local</code> (e.g. <code>pkscope-metal-slope-23501.local</code>).</li> <li>(User-facing change; Application: backend) The Python backend now uses the new machine naming scheme everywhere.</li> <li>(System: networking) The default hostname and SSID (used only in certain unexpected situations when a machine name cannot be determined) have both been shortened from <code>planktoscope</code> to <code>pkscope</code>.</li> <li>(System: networking) The SSID format is now specified in <code>/home/pi/.local/etc/hostapd/ssid.snippet</code>, instead of <code>/home/pi/.local/bin/update-ssid-machine-name.sh</code>.</li> </ul>"},{"location":"reference/software/changelog/#deprecated_3","title":"Deprecated","text":"<ul> <li>(System: networking) The <code>planktoscope.local</code> 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 <code>pkscope.local</code> or the machine-specific mDNS name (of format <code>pkscope-{machine-name}.local</code>) instead.</li> <li>(Application: backend) The Python backend's logs still print machine names in the old naming scheme, to help instrument operators with the naming scheme transition (so that they can identify how each machine was renamed). The machine names in this old naming scheme will be removed in a future release - probably the next release.</li> </ul>"},{"location":"reference/software/changelog/#removed_4","title":"Removed","text":"<ul> <li>(System: administration, networking) The auto-generated <code>/home/pi/.local/etc/cockpit/origins</code> 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.</li> <li>(System: administration, networking) The default <code>/home/pi/.local/etc/hosts</code> file has been removed from the setup files. Instead, it is now automatically generated by the setup scripts.</li> </ul>"},{"location":"reference/software/changelog/#fixed_7","title":"Fixed","text":"<ul> <li>(System: networking) The PlanktoScope no longer generates any machine names or SSIDs which are so long that they prevent the wifi hotspot network from being brought up.</li> <li>(Application: backend) The segmenter no longer crashes and fails to respond immediately after attempting to start segmentation.</li> <li>(Application: preset settings, GUI) The default setting for the pscopehat version of the Node-RED dashboard is now the 300 um capillary, since that version of the hardware is meant to be used with 300 um capillaries. Previously, the default was the 200 um ibidi slide.</li> <li>(Application: preset settings) All default settings for all hardware versions now include a default pixel size calibration of 0.75 um/pixel. Previously, the default settings for v2.1 and v2.3 were missing this setting, which would cause the segmenter to crash when processing datasets generated on PlanktoScopes using the v2.1 or v2.3 hardware settings.</li> <li>(Application: preset settings, GUI) The Node-RED dashboard now correctly lists the selected hardware version in the \"Hardware Settings\" page's \"Hardware Version\" dropdown menu upon startup.</li> <li>(Application: GUI) The Node-RED dashboard now (hopefully) is able to determine the camera type from the Python backend.</li> </ul>"},{"location":"reference/software/changelog/#v202390-beta0-2023-09-02","title":"v2023.9.0-beta.0 - 2023-09-02","text":""},{"location":"reference/software/changelog/#added_6","title":"Added","text":"<ul> <li>(System: networking) Traffic is now routed with Network Address Translation between the Ethernet and Wi-Fi network interfaces. This means that if the PlanktoScope has internet access through an Ethernet connection, it will share that internet access to devices connected to its Wi-Fi hotspot; and if the PlanktoScope has internet access through a Wi-Fi connection, it will share that internet access to devices connected to its Ethernet port.</li> <li>(System: networking) Now both <code>192.168.4.1</code> and <code>192.168.5.1</code> 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.</li> <li>(System: networking) Previously the PlanktoScope could be connected to from <code>192.168.4.1</code> (over Wi-Fi, when running in wireless AP mode), <code>192.168.5.1</code> (over Ethernet), and <code>planktoscope.local</code> (over Wi-Fi or Ethernet, from a client device with mDNS support); this meant that Android devices could only connect to the PlanktoScope at <code>192.168.4.1</code>, as they lack mDNS support. Now, client devices - even those without mDNS support - can connect to the PlanktoScope at <code>home.planktoscope</code>, and/or URLs like <code>clear-field-33719.planktoscope</code> and <code>planktoscope-clear-field-33719.local</code> (where <code>clear-field-33719</code> 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\").</li> <li>(Application: Documentation) An offline copy of the PlanktoScope project documentation is now provided at URL path <code>/ps/docs/</code> (so e.g. it's accessible at http://home.planktoscope/ps/docs/)</li> <li>(Application: GUI) The Node-RED dashboard's \"Hardware Settings\" page now includes a drop-down menu item to select \"PlanktoScope v2.5\" as an allowed hardware version.</li> <li>(Application: GUI, administration) The Node-RED dashboard now generates a notification whenever it restarts the Python backend. This provides visibility for the user when changing the hardware version triggers a restart of the Python backend.</li> <li>(System: administration, troubleshooting, GUI) A Cockpit system administration dashboard is now installed and made accessible at URL path <code>/admin/cockpit/</code> (so e.g. it's accessible at http://home.planktoscope/admin/cockpit/).</li> <li>(System: administration, troubleshooting, GUI) A filebrowser instance, allowing you to manage and edit files anywhere in the Raspberry Pi's SD card, is now installed and made accessible at URL path <code>/admin/fs/</code> (so e.g. it's accessible at http://home.planktoscope/admin/fs/)</li> <li>(System: administration, troubleshooting, GUI) A Portainer administration dashboard for Docker is now installed and made accessible at URL path <code>/admin/portainer/</code> (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.</li> <li>(System: administration) Docker is now installed. We are using it to deliver various applications in a way that will eventually enable safe and easy upgrades.</li> <li>(System: administration, troubleshooting) w3m is now installed, enabling terminal-based interaction with some Wi-Fi network captive portals to obtain internet access on the PlanktoScope. For captive portals which require Javascript, we recommend instead using browsh as a Docker container; we don't provide browsh in the default SD card image because it adds ~250 MB of dependencies to the image.</li> </ul>"},{"location":"reference/software/changelog/#changed_8","title":"Changed","text":"<ul> <li>(User-facing change; System: administration) The file browser on port 80 for viewing datasets has now been moved to path <code>/ps/data/browse/</code> (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.</li> <li>(User-facing change; Application: GUI) If you navigate the PlanktoScope in your web browser on port 80 (or without specifying a port) (e.g. with URLs like <code>http://home.planktoscope</code> or <code>http://planktoscope.local</code>), 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.</li> <li>(User-facing change; Application: GUI) Previously, the Node-RED dashboard was accessed on the path <code>/ui</code> on port 1880, e.g. with URLs like <code>http://planktoscope.local:1880/ui</code> or <code>http://192.168.4.1:1880/ui</code>; now, it should be accessed via a link on the landing page.</li> <li>(User-facing change; System: networking) Previously, PlanktoScope machine names were generated as gibberish words like \"Babaxio-Detuiau\", and the machine names were used as the names of the private Wi-Fi networks generated by the PlanktoScope in wireless AP mode. However, the machine names created by this naming scheme were often difficult to pronounce, remember, and type for people in various languages, and the naming scheme sometimes generated names which sounded like curses or insults in some languages. Now, PlanktoScope machine names are generated as a combination of two words and a number up to five digits long; words are selected from pre-built lists in a language which can be chosen based on localization settings. Currently, word lists are only provided in US English, resulting in names like \"metal-slope-23501\", \"conscious-pocket-1684\", and \"plant-range-10581\"; however, word lists can be added for other languages in the future, and a user interface will eventually be provided for changing localization settings.</li> <li>(User-facing change; Application: GUI) Selecting a hardware version on the \"Hardware Settings\" page of the Node-RED dashboard now causes a default hardware preset for that version to overwrite the entire <code>hardware.json</code> file, and the Node-RED dashboard will reload the settings; this prevents the <code>hardware.json</code> 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.</li> <li>(User-facing change; Application: GUI, troubleshooting) Previously, the Node-RED dashboard's \"Administration\" page merged log entries from every component of the Python backend and the Node-RED dashboard. Now, the Node-RED dashboard instead displays links to separate Cockpit log-viewing pages (which by default are accessed with username <code>pi</code> and password <code>copepode</code>) 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.</li> <li>(User-facing change; System: GUI) Previously, the Node-RED flow editor was accessed directly on port 1880, e.g. with URLs like <code>http://planktoscope.local:1880</code> or <code>http://192.168.4.1:1880</code>; now, it should be accessed via a link on the landing page .</li> <li>(System: networking) Previously, PlanktoScopes all had <code>planktoscope</code> as their hostname. Now, the hostname is of the format <code>planktoscope-&lt;machine-name&gt;</code>, e.g. <code>planktoscope-metal-slope-23501</code> or <code>planktoscope-plant-range-10581</code>.</li> <li>(Likely user-facing change; System: networking) The default Wi-Fi country has been changed from <code>FR</code> (France) to <code>US</code> (USA).</li> <li>(Likely user-facing change; System: networking) Previously the autohotspot script considered receiving an IP address assignment from the connected Wi-Fi network as the criterion for determining whether the Wi-Fi connection was successful. Now the autohotspot script tries to ping <code>google.com</code> 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.</li> <li>(System: networking, troubleshooting) Previously the autohotspot script would print the MAC addresses and SSIDs of all Wi-Fi networks found by scanning. Now it only prints the SSIDs of Wi-Fi networks found by scanning and avoids printing duplicate SSIDs, for more concise service logs.</li> <li>(System: networking, troubleshooting) When the autohotspot script fails to connect to google.com, it will also print some diagnostic information by attempting to ping <code>1.1.1.1</code> (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.</li> <li>(System: networking) Previously the autohotspot script was run every 5 minutes to scan for available Wi-Fi networks. Now it is run every 2 minutes, so that the PlanktoScope will connect more quickly to a Wi-Fi network which has just appeared.</li> <li>(System: networking) Previously the autohotspot script and the dhcpcd service would both try to manage when to start and stop the dnsmasq service. Now, the dnsmasq service always runs. This change was made to simplify the network configuration so that it would be easier to understand, troubleshoot, and maintain.</li> <li>(System: networking) Previously the autohotspot script would use a mixture of dhcpcd and wpa_supplicant as entrypoints for Wi-Fi network connection management. Now, dhcpcd is used to manage wpa_supplicant, and the autohotspot script only interacts with dhcpcd. This change was made to simplify the network configuration so that it would be easier to understand, troubleshoot, and maintain. Note that, in the future, wpa_supplicant and dhcpcd may be replaced with NetworkManager.</li> <li>(System: networking) The autohotspot script has undergone a major refactoring, which may accidentally introduce bugs.</li> <li>(Application: Backend, GUI) The Node-RED dashboard no longer supervises the Python backend; instead, it delegates that work to systemd.</li> <li>(Application: Backend) Log files from the Python backend are no longer saved to <code>/home/pi</code>, but instead to subdirectories for the backend components under <code>/home/pi/device-backend-logs</code>. 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.</li> <li>(System) The <code>/usr/bin/stepper-disable</code> and <code>/usr/bin/autohotspotN</code> scripts have been moved to <code>/home/pi/.local/bin/release-gpio-steppers.sh</code> and <code>/home/pi/.local/bin/autohotspot.sh</code>, respectively.</li> <li>(System) The <code>gpio-init.service</code> systemd service has been renamed to <code>planktoscope-org.init-gpio-steppers.service</code>.</li> <li>(System) Previously the <code>en_DK.UTF-8</code> locale was used for everything. Now it is only used for time, measurements, and paper dimensions, and the <code>en_US.UTF-8</code> locale is the base locale for everything else. In the future we may provide GUI functionality for changing the base locale.</li> <li>(System) The chrony configuration has been simplified, but it may be broken.</li> <li>(System) The default timezone is now officially set to UTC, and we will be using UTC as the standard system time zone for all PlanktoScopes. Previously, the pre-built SD card images provided by this project used UTC as the timezone, but the \"Expert Setup\" instructions for manually setting up the PlanktoScope software did not specify a time zone to use.</li> <li>(System, Dependencies) The base OS is now the 2023-05-03 release of Raspberry Pi OS Bullseye.</li> <li>(Application: Backend, Dependencies) The Python backend and Node-RED dashboard's indirect dependencies are now version-locked to improve the reproducibility of the OS setup script independently of when the script is run.</li> </ul>"},{"location":"reference/software/changelog/#deprecated_4","title":"Deprecated","text":"<ul> <li>(Application: GUI) In a future release (potentially as early as v2023.12.0), the Node-RED editor and Node-RED dashboard will not be accessible at all over port 1880. In this release, you can still access the Node-RED dashboard at path <code>/ps/node-red-v2/ui</code> 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 <code>/admin/ps/node-red-v2</code> 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.</li> <li>(Application: GUI) In a future release (timeline not yet decided), the version of the Node-RED dashboard for the Adafruit HAT will stop receiving new features even as the version of the Node-RED dashboard for the custom PlanktoScope HAT continues receiving new features. However, we will continue to fix bugs in the Node-RED dashboard for the Adafruit HAT, and we will continue to build SD card images for the Adafruit HAT which will also include new features in other software components.</li> </ul>"},{"location":"reference/software/changelog/#removed_5","title":"Removed","text":"<ul> <li>(User-facing removal; Application: GUI) The Node-RED dashboard no longer allows selection of \"PlanktoScope v1.0\" or \"PlanktoScope v2.2 (waveshare HAT)\" as the hardware version. Those hardware versions are no longer supported by the software.</li> <li>(User-facing removal; System: networking) Now <code>planktoscope.local</code> 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. <code>planktoscope.local</code> 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 <code>planktoscope-&lt;machine-name&gt;.local</code>) should be used instead.</li> <li>(System: administration) The Git-based software update system (exposed in the Node-RED dashboard's \"Adminisration\" page) has been removed, since it was reported to behave problematically anyways. In the future, we will use a system based on Docker for safer and easier software updates.</li> </ul>"},{"location":"reference/software/changelog/#fixed_8","title":"Fixed","text":"<ul> <li>(Major fault-tolerance improvement; Application: GUI) When an invalid value is entered for the red or blue white balance gain on the Node-RED dashboard's \"Optic Configuration\" page, that value is now ignored, a notification is displayed about the invalid value, and the white balance gain is reset to the last valid value (loaded from the <code>hardware.json</code> configuration file). This fixes issue #166 by preventing the Node-RED dashboard from saving an invalid value to the <code>hardware.json</code> file, which would crash the Python hardware controller after the next boot (or after the next time the Python hardware controller was restarted).</li> <li>(Major quality-of-life improvement; Backend: dependencies) The <code>adafruit-blinka</code> and <code>adafruit-platformdetect</code> 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.</li> <li>(Application: GUI, troubleshooting) Previously, the Node-RED dashboard would often fail to display the log output from the Python backend. Now, it should always make the logs accessible (either by the links to Cockpit log viewer or by the links to the log file browser).</li> <li>(System: networking) Previously the autohotspot script would not ignore any networks which were commented out in the <code>/etc/wpa_supplicant/wpa_supplicant.conf</code> file when checking if any networks found by scanning matched networks were specified in the <code>wpa_supplicant.conf</code> file; now it ignores them, so that commented-out networks don't incorrectly prevent the autohotspot from going into wireless AP mode.</li> <li>(System: networking) Previously the autohotspot script would always wait 20 seconds after attempting to connect to a Wi-Fi network before checking whether the connection was successful, even if it didn't actually need to wait 20 seconds. Now the autohotspot script repeatedly attempts to ping google.com with a timeout of 2 seconds per attempt and a maximum of 10 attempts, so that the autohotspot script only waits as long as a necessary to determine that a Wi-Fi network connection has succeeded.</li> <li>(System: networking) Previously the autohotspot script could decide that the SSID scan results were available even if no SSIDs were found (despite local Wi-Fi networks being active). Now an empty SSID scan result is treated as a condition where a re-scan is required.</li> <li>(System: networking) Previously the log messages from the autohotspot script had inconsistent capitalization and grammar, and slightly unclear wording. Those have now been made more clear and consistent.</li> </ul>"},{"location":"reference/software/changelog/#v230-2021-12-20","title":"v2.3.0 - 2021-12-20","text":""},{"location":"reference/software/changelog/#added_7","title":"Added","text":"<ul> <li>A basic working image segmenter.</li> <li>Direct connections over Ethernet.</li> <li>A \"Lab culture\" sample type, where location is set to the South Pole, and sample collection time and date are set by default to the current time and date on the Raspberry Pi but can be changed. (#74)</li> <li>A \"Test\" sample type, where location is set to the South Pole, and sample collection time and date are always set to the current time and date on the Raspberry Pi.</li> <li>A selector in the Node-RED dashboard for the machine hardware version (#98)</li> </ul>"},{"location":"reference/software/changelog/#changed_9","title":"Changed","text":"<ul> <li>Various parts of the UI (we do not have a list of specific changes).</li> <li>Node-RED is now upgraded to v2.0 (#97)</li> <li>The base OS is now the 2021-12-03 release of Raspberry Pi OS Buster.</li> </ul>"},{"location":"reference/software/changelog/#fixed_9","title":"Fixed","text":"<ul> <li>Various issues with accessing the Node-RED dashboard via http://planktoscope.local:1880/ui .</li> <li>Various issues with Node-RED (#80, #91, #87, #96)</li> </ul>"},{"location":"reference/software/changelog/#v221-2021-05-10","title":"v2.2.1 - 2021-05-10","text":""},{"location":"reference/software/changelog/#added_8","title":"Added","text":"<ul> <li>The ability for developers to change the PlanktoScope repository to a development branch from the Node-RED dashboard.</li> </ul>"},{"location":"reference/software/changelog/#fixed_10","title":"Fixed","text":"<ul> <li>Various bugs (we do not have a list of specific changes)</li> </ul>"},{"location":"reference/software/changelog/#v220-2021-02-23","title":"v2.2.0 - 2021-02-23","text":""},{"location":"reference/software/changelog/#added_9","title":"Added","text":"<ul> <li>Support for Raspberry Pi HQ cameras.</li> <li>Control of image white balance.</li> <li>A Node-RED dashboard panel to copy all data from <code>/home/pi/data</code> to a USB drive.</li> <li>Integrity check of the generated files (for now only for raw pictures and <code>metadata.json</code> files). A file called <code>integrity.check</code> 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.</li> <li>A file gallery to browse data files in the <code>/home/pi/data</code> directory.</li> <li>A way to update the PlanktoScope software repository on the Raspberry Pi.</li> <li>A Node-RED dashboard panel to choose a wifi network to connect to.</li> <li>A Node-RED tab to enter the configuration of the hardware.</li> </ul>"},{"location":"reference/software/changelog/#changed_10","title":"Changed","text":"<ul> <li>(Breaking change) The UI has been changed (we do not have a list of specific changes)</li> </ul>"},{"location":"reference/software/changelog/#fixed_11","title":"Fixed","text":"<ul> <li>Random camera crash solved: instead of using the python picamera library, we now use a compiled binary, <code>raspimjpeg</code>, controlled through a FIFO pipe</li> </ul>"},{"location":"reference/software/changelog/#v210-2020-10-14","title":"v2.1.0 - 2020-10-14","text":""},{"location":"reference/software/changelog/#added_10","title":"Added","text":"<ul> <li>If the Raspberry Pi is configured (via the <code>/etc/wpa_supplicant/wpa_supplicant.conf</code> 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.</li> <li>If the Raspberry Pi is connected to the internet via its Ethernet port, it will share internet access to devices connected to the Raspberry Pi's wifi hotspot.</li> <li>(Documentation) Information has been added about ribbon cable assembly.</li> <li>(Documentation) Information has been added about how to back up the SD card.</li> </ul>"},{"location":"reference/software/changelog/#changed_11","title":"Changed","text":"<ul> <li>(Breaking change) The OS is now based on Raspberry OS Lite, so there is no graphical desktop.</li> <li>(Breaking change) The wifi network is now named <code>PlanktoScope</code>, and the password to it is now <code>copepode</code>.</li> <li>(Breaking change) The default user is now <code>pi</code>, and the default password is <code>copepode</code> for this user.</li> <li>(Breaking change) All raw and processed data files are now stored in the directory <code>/home/pi/data</code>.</li> <li>The software has undergone a major refactoring, which may accidentally introduce some bugs.</li> </ul>"},{"location":"reference/software/product-specs/","title":"Product Specifications","text":"<p>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.</p>"},{"location":"reference/software/product-specs/#v202400","title":"v2024.0.0","text":"<p>Specs for v2024.0.0 are the same as in v2023.9.0, except for the following sections:</p> <ul> <li>Base operating system: the binary target architecture has changed from 32-bit to 64-bit.</li> <li>System performance: on-board image processing speeds have improved (processing speeds have nearly doubled).</li> </ul>"},{"location":"reference/software/product-specs/#functionalities","title":"Functionalities","text":"<p>Regular operation:</p> <ul> <li>Image acquisition: stop-flow imaging (JPEG image output)</li> <li>On-board image processing: detection and segmentation of objects (batch-processing only)</li> <li>User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer</li> <li>Export of data for uploading to EcoTaxa</li> </ul> <p>Advanced operations:</p> <ul> <li>User interfacing: web browser interfaces for system administration, system monitoring, and troubleshooting</li> <li>Automation: MQTT-based API</li> <li>Application deployment: ability to add software as OCI containers using Docker, optionally via Forklift</li> <li>System configuration: ability to reversibly add, remove, replace, or override OS configuration files via Forklift</li> </ul>"},{"location":"reference/software/product-specs/#base-operating-system","title":"Base operating system","text":"<ul> <li>Distro: Raspberry Pi OS 11 (bullseye)</li> <li>Binary target architecture: 64-bit (aarch64, also known as arm64)</li> </ul>"},{"location":"reference/software/product-specs/#supported-hardware","title":"Supported hardware","text":"<p>Minimum for image acquisition (but not sufficient for on-board image processing):</p> <ul> <li>PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer</li> <li>Memory: 1 GB RAM</li> <li>Storage: 8 GB capacity</li> </ul> <p>Minimum for full functionality, including on-board image processing:</p> <ul> <li>Memory: 4 GB RAM</li> </ul> <p>Recommended:</p> <ul> <li>PlanktoScope: hardware v2.5 or v2.6 with Raspberry Pi 4 Model B computer</li> <li>Storage: 32 GB capacity</li> </ul> <p>Forwards-incompatibilities:</p> <ul> <li>Unable to run on the Raspberry Pi 5 computer.</li> </ul> <p>Backwards-incompatibilities:</p> <ul> <li>Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.</li> </ul>"},{"location":"reference/software/product-specs/#system-performance","title":"System performance","text":"<p>With minimum supported hardware for full functionality:</p> <ul> <li>On-board image processing: a dataset of 400 raw images is processed in approximately 1 hour</li> </ul>"},{"location":"reference/software/product-specs/#v202390","title":"v2023.9.0","text":""},{"location":"reference/software/product-specs/#functionalities_1","title":"Functionalities","text":"<p>Regular operation:</p> <ul> <li>Image acquisition: stop-flow imaging (JPEG image output)</li> <li>On-board image processing: detection and segmentation of objects (batch-processing only)</li> <li>User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer</li> <li>Export of data for uploading to EcoTaxa</li> </ul> <p>Advanced operations:</p> <ul> <li>User interfacing: web browser interfaces for system administration, system monitoring, and troubleshooting</li> <li>Automation: MQTT-based API</li> <li>Application deployment: ability to add software as OCI containers using Docker, optionally via Forklift</li> </ul>"},{"location":"reference/software/product-specs/#base-operating-system_1","title":"Base operating system","text":"<ul> <li>Distro: Raspberry Pi OS 11 (bullseye)</li> <li>Binary target architecture: 32-bit only (armhf, also known as armv7)</li> </ul>"},{"location":"reference/software/product-specs/#supported-hardware_1","title":"Supported hardware","text":"<p>Minimum for image acquisition (but not sufficient for on-board image processing):</p> <ul> <li>PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer</li> <li>Memory: 1 GB RAM</li> <li>Storage: 8 GB capacity</li> </ul> <p>Minimum for full functionality, including on-board image processing:</p> <ul> <li>Memory: 4 GB RAM</li> </ul> <p>Recommended:</p> <ul> <li>PlanktoScope: hardware v2.5 or v2.6 with Raspberry Pi 4 Model B computer</li> <li>Storage: 32 GB capacity</li> </ul> <p>Forwards-incompatibilities:</p> <ul> <li>Unable to run on the Raspberry Pi 5 computer.</li> </ul> <p>Backwards-incompatibilities:</p> <ul> <li>Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.</li> </ul>"},{"location":"reference/software/product-specs/#system-performance_1","title":"System performance","text":"<p>With minimum supported hardware for full functionality:</p> <ul> <li>On-board image processing: a dataset of 400 raw images is processed in approximately 1.5 to 2 hours</li> </ul>"},{"location":"reference/software/product-specs/#v23","title":"v2.3","text":""},{"location":"reference/software/product-specs/#functionalities_2","title":"Functionalities","text":"<p>Regular operation:</p> <ul> <li>Image acquisition: stop-flow imaging (JPEG image output)</li> <li>On-board image processing: detection and segmentation of objects (batch-processing only)</li> <li>User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer</li> <li>Export of data for uploading to EcoTaxa</li> </ul> <p>Advanced operations:</p> <ul> <li>Automation: MQTT-based API</li> </ul>"},{"location":"reference/software/product-specs/#base-operating-system_2","title":"Base operating system","text":"<ul> <li>Distro: Raspberry Pi OS 11 (bullseye)</li> <li>Binary target architecture: 32-bit only (armhf, also known as armv7)</li> </ul>"},{"location":"reference/software/product-specs/#supported-hardware_2","title":"Supported hardware","text":"<p>Minimum for image acquisition (but not sufficient for on-board image processing):</p> <ul> <li>PlanktoScope: hardware v2.1 with Raspberry Pi 3 Model B+ computer</li> <li>Memory: 1 GB RAM</li> <li>Storage: 8 GB capacity</li> </ul> <p>Minimum for full functionality, including on-board image processing:</p> <ul> <li>PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer</li> <li>Memory: 4 GB RAM</li> </ul> <p>Recommended for full functionality:</p> <ul> <li>PlanktoScope: hardware v2.5 or v2.6</li> <li>Storage: 32 GB capacity</li> </ul> <p>Forwards-incompatibilities:</p> <ul> <li>Unable to run on the Raspberry Pi 5 computer.</li> <li>Incompatible with Adafruit Stepper Motor HATs (used in PlanktoScope hardware v2.1) manufactured after mid-2022.</li> </ul>"},{"location":"reference/software/product-specs/#system-performance_2","title":"System performance","text":"<p>With minimum supported hardware for full functionality:</p> <ul> <li>On-board image processing: a dataset of 400 raw images is processed in approximately 1.5 to 2 hours</li> </ul>"},{"location":"reference/software/release-process/","title":"Release Process","text":"<p>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:</p> <ul> <li>Understand what you should do when we publish a new release of the PlanktoScope OS.</li> <li>Interpret the software product specifications and the software changelog.</li> </ul>"},{"location":"reference/software/release-process/#version-numbering","title":"Version numbering","text":"<p>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.</p> <p>We use a calendar-based version numbering system for the PlanktoScope OS, where each version number has the format <code>v(year).(minor).(patch)</code> for stable releases of the software or <code>v(year).(minor).(patch)-(modifier)</code> for testing pre-releases of the software:</p> <ul> <li> <p><code>year</code> 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.</p> </li> <li> <p><code>minor</code> 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 <code>minor</code> 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.</p> </li> <li> <p><code>patch</code> is a number which starts at 0 for each <code>(year).(minor)</code> 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 <code>minor</code> with the next release. For example, we might not publish a v2024.0.1 release, and instead just publish a v2024.1.0 release.</p> </li> <li> <p><code>modifier</code> 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 <code>modifier</code> has the format of either <code>alpha.(index)</code> or <code>beta.(index)</code>, where <code>index</code> is a number which starts at 0 for each <code>(year).(minor).(patch)-alpha</code> or <code>(year).(minor).(patch)-beta</code> 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.</p> </li> </ul>"},{"location":"reference/software/release-process/#release-channels","title":"Release channels","text":"<p>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:</p> <ul> <li>Edge: On the \"Edge\" channel, the PlanktoScope OS is built from the setup scripts on the latest commit of the <code>master</code> 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 <code>master</code> 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.</li> <li>Beta: Once an \"alpha\" pre-release has received sufficient testing for the PlanktoScope software developers to consider it stable enough for all PlanktoScope users to test it out, it will be promoted to a \"beta\" pre-release, and the <code>software/beta</code> branch of the PlanktoScope repository on GitHub will be advanced to the Git commit of the \"beta\" pre-release. At that point, the <code>software/beta</code> branch will only receive patches to fix serious errors. As bugs are fixed on the <code>software/beta</code> branch, more \"beta\" pre-releases may be created on that branch for users to test.</li> <li>Stable: After the latest \"beta\" pre-release has received sufficient testing for the PlanktoScope software developers to consider it stable enough for most (or, ideally, all) PlanktoScope users to rely on it for production use and scientific operations, that \"beta\" pre-release will be promoted to a \"stable\" release, and the <code>software/stable</code> branch of the PlanktoScope repository on GitHub will be advanced to the git commit of the \"stable\" release.</li> </ul>"},{"location":"reference/software/release-process/#release-schedules","title":"Release schedules","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/release-process/#choosing-a-release-channel","title":"Choosing a release channel","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/release-process/#upgrading-to-a-new-release-or-pre-release","title":"Upgrading to a new release or pre-release","text":"<p>In order to use a new release or pre-release of the PlanktoScope OS, you will need to do one of the following:</p> <ul> <li> <p>Download the new SD card image for that release/pre-release, following the standard installation process.</p> </li> <li> <p>Create a new custom SD card image for that release/pre-release, following the non-standard installation process.</p> </li> </ul> <p>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.</p>"},{"location":"reference/software/architecture/os/","title":"Operating System","text":"<p>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:</p> <ul> <li> <p>How the PlanktoScope software abstracts over the PlanktoScope hardware.</p> </li> <li> <p>How the PlanktoScope manages the execution of software programs intended to run on the PlanktoScope.</p> </li> </ul> <p>This information is intended to help you understand:</p> <ul> <li> <p>The overall design of the PlanktoScope OS, including what functionalities it provides and what software it includes, and why we made certain design decisions.</p> </li> <li> <p>How various software functionalities and responsibilities in the PlanktoScope are divided among the various programs in the PlanktoScope OS.</p> </li> <li> <p>How various programs in the PlanktoScope OS support other programs which provide the PlanktoScope's high-level/end-user functionalities.</p> </li> <li> <p>What tools you can use to perform software troubleshooting and system administration tasks with the PlanktoScope.</p> </li> <li> <p>What kinds of new software you can develop and deploy to run on a PlanktoScope.</p> </li> </ul> <p>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:</p> <ul> <li>\"Abstracts hardware to allow execution of other programs.\"</li> <li>\"Defines the liveness of the machine: without it, no program can run.\"</li> <li>Provides some important components including the operating system kernel, libraries, commands, daemons, and other facilities.</li> </ul> <p>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:</p> <ul> <li> <p>A Raspberry Pi computer.</p> </li> <li> <p>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).</p> </li> </ul>"},{"location":"reference/software/architecture/os/#software-deployment-execution","title":"Software deployment &amp; execution","text":"<p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>Most of the PlanktoScope's software is (or eventually will be) executed as Docker containers by the <code>dockerd</code> daemon (which in turn is run by the <code>docker.service</code> 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.</p> </li> </ul> <p>The PlanktoScope OS is a 64-bit operating system.</p>"},{"location":"reference/software/architecture/os/#boot-sequence","title":"Boot sequence","text":"<p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>The systemd system manager's boot behavior, which initializes all necessary filesystems, drivers, and system services.</p> </li> </ul> <p>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 <code>docker.service</code>. The startup ordering relationships between those services are listed in our reference document about services in the startup process.</p>"},{"location":"reference/software/architecture/os/#system-upgrades","title":"System upgrades","text":"<p>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 <code>pip</code>. This causes the following challenges for system administration on the PlanktoScope:</p> <ul> <li> <p>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.</p> </li> <li> <p>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).</p> </li> <li> <p>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.</p> </li> <li> <p>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 <code>pip</code>-managed Python packages which had been installed before the change.</p> </li> </ul> <p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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).</p> </li> <li> <p>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.</p> </li> </ul> <p>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 <code>pip</code>; instead, we use a (partially-implemented) tool called <code>forklift</code> 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:</p> <ul> <li>All software which we run using Docker.</li> <li>PlanktoScope-specific systemd services.</li> <li>PlanktoScope-specific OS configuration files.</li> </ul> <p>Everything managed by <code>forklift</code> is version-controlled in a Git repository, enabling easy backup and restoration of <code>forklift</code>-managed configurations even if the PlanktoScope's SD card is wiped and re-flashed.</p>"},{"location":"reference/software/architecture/os/#package-management-with-forklift","title":"Package management with <code>forklift</code>","text":"<p>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 <code>pip</code> 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.). <code>forklift</code> 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 (<code>forklift pallet switch</code>, described below in the Applying published customizations subsection).</p> <p><code>forklift</code> 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 <code>forklift</code>, you instead edit configuration files which declare the desired state of your system (though some step-by-step commands are also provided by <code>forklift</code> to make editing of files easier), and then you ask <code>forklift</code> 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 <code>forklift</code>'s design were inspired by Terraform.</p>"},{"location":"reference/software/architecture/os/#dependency-management","title":"Dependency management","text":"<p><code>forklift</code> 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 <code>forklift</code> 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.</p> <p>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. <code>forklift</code> 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.</p>"},{"location":"reference/software/architecture/os/#making-publishing-customizations","title":"Making &amp; publishing customizations","text":"<p>The workflow with <code>forklift</code> 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:</p> <ul> <li> <p>Initialize a custom pallet based on (i.e. layered over) an existing pallet, using the <code>forklift pallet init</code> command (e.g. <code>forklift pallet init --from github.com/PlanktoScope/pallet-standard@stable --as github.com/ethanjli/custom-pallet</code> 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 <code>github.com/ethanjli/custom-pallet</code>). (Note: the <code>forklift pallet init</code> 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.)</p> </li> <li> <p>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.</p> </li> <li> <p>Optionally, add published Forklift repositories to the pallet with the <code>forklift pallet add-repo</code> command (e.g. <code>forklift pallet add-repo github.com/ethanjli/pallet-example-minimal@main</code>), 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 <code>forklift pallet add-repo</code> command is also used to upgrade or downgrade the version of the Forklift repository used by the pallet.</p> </li> <li> <p>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.)</p> </li> <li> <p>Stage the pallet to be applied on the next boot of the PlanktoScope OS, with the <code>forklift pallet stage</code> command; when Forklift applies a pallet, it makes the PlanktoScope OS match the configuration of Forklift package deployments specified by the pallet.</p> </li> <li> <p>Use <code>git</code> to commit changes and (ideally) push them to GitHub, in order to publish your customizations for other people to try out.</p> </li> </ul> <p>(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)</p>"},{"location":"reference/software/architecture/os/#applying-published-customizations","title":"Applying published customizations","text":"<p>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:</p> <ul> <li> <p>Stage the customized pallet to be applied on the next boot of the PlanktoScope OS, using the <code>forklift pallet switch</code> command (e.g. <code>forklift pallet switch github.com/PlanktoScope/pallet-segmenter@edge</code> to use the latest development/unstable version of the github.com/PlanktoScope/pallet-segmenter pallet). </p> </li> <li> <p>Reboot the Raspberry Pi computer to apply the staged pallet. If the staged pallet cannot be successfully applied during boot, on subsequent boots <code>forklift</code> 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.)</p> </li> </ul> <p>(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)</p> <p>Note: currently all of <code>forklift</code>'s functionality is only exposed through a command-line interface, but after the <code>forklift</code> tool stabilizes we plan to add a web browser-based graphical interface for use by a general audience.</p>"},{"location":"reference/software/architecture/os/#planktoscope-specific-hardware-abstraction","title":"PlanktoScope-specific hardware abstraction","text":"<p>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):</p> <ul> <li> <p><code>gpsd</code>: for providing an abstraction for the PlanktoScope's GPS receiver.</p> </li> <li> <p><code>chronyd</code>: 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.</p> </li> <li> <p>The PlanktoScope hardware controller: for controlling PlanktoScope-specific hardware modules and abstracting them into high-level network APIs for other programs to interact with.</p> </li> </ul>"},{"location":"reference/software/architecture/os/#user-interface","title":"User interface","text":"<p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul> <p>The PlanktoScope OS adds the following network services which provide web browser-based graphical user interfaces to help users operate the PlanktoScope:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>device-portal: a landing page with links for end-users to quickly access the various web browser-based interfaces mentioned above.</p> </li> </ul> <p>Note: we will probably simplify things by consolidating some of these components together into the PlanktoScope's Node-RED dashboard.</p> <p>The PlanktoScope OS also provides various tools with web browser-based interfaces to aid with system administration and troubleshooting:</p> <ul> <li> <p>Cockpit: for performing system-administration tasks such as monitoring system resources, managing system services, viewing system logs, and executing commands in a terminal.</p> </li> <li> <p>A system file browser for viewing, managing, editing, uploading, and downloading any file on the PlanktoScope.</p> </li> <li> <p>A log file browser for viewing, downloading, and deleting log files files generated by the PlanktoScope hardware controller.</p> </li> <li> <p>Dozzle: for viewing and monitoring logs of Docker containers.</p> </li> <li> <p>Grafana: for monitoring and exploring metrics stored in Prometheus.</p> </li> </ul> <p>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:</p> <ul> <li> <p><code>vim</code>: for editing text files.</p> </li> <li> <p><code>byobu</code>: for running processes persistently across ephemeral terminal sessions.</p> </li> <li> <p><code>git</code>: for interacting with Git repositories.</p> </li> <li> <p><code>w3m</code> and <code>lynx</code>: for interacting with web pages (such as Wi-Fi network captive portals) from the PlanktoScope.</p> </li> <li> <p><code>docker</code>: for managing and inspecting Docker containers.</p> </li> </ul>"},{"location":"reference/software/architecture/os/#networking","title":"Networking","text":"<p>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.</p> <p>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.</p> <p>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. <code>home.pkscope</code>), 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. <code>pkscope.local</code>) 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).</p> <p>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.</p> <p>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:</p> <ul> <li> <p><code>autohotspot</code> (which in turn launches <code>hostapd</code>): 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.</p> </li> <li> <p><code>enable-interface-forwarding</code>: 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.</p> </li> <li> <p><code>dnsmasq</code>: for allowing computers connected to the PlanktoScope over a network to access the PlanktoScope using domain names defined on the PlanktoScope.</p> </li> <li> <p><code>firewalld</code>: a network firewall (currently disabled by default).</p> </li> </ul> <p>The standard PlanktoScope OS also adds the following systemd services for dynamically updating the system's network configuration during boot:</p> <ul> <li> <p><code>generate-machine-name</code>: generates a human-readable machine name  at <code>/run/machine-name</code> from the Raspberry Pi's serial number (or, if that's missing, from <code>/etc/machine-d</code>).</p> </li> <li> <p><code>generate-hostname-templated</code>: generates a temporary hostname file (which is used by a symlink at <code>/etc/hostname</code>) from <code>/etc/hostname-template</code>, which can include the machine name from <code>/run/machine-name</code>.</p> </li> <li> <p><code>update-hostname</code>: updates <code>systemd-hostnamed</code> so that the hostname matches what is specified by <code>/etc/hostname</code>.</p> </li> <li> <p><code>assemble-dnsmasq-config-templated</code>: generates a temporary dnsmasq drop-in config file (which is used by a symlink at <code>/etc/dnsmasq.d/40-generated-templated-config</code>) from drop-in config file templates at <code>/etc/dnsmasq-templates.d</code>. </p> </li> <li> <p><code>assemble-hostapd-config-templated</code>: generates a temporary hostapd drop-in config file (which is used by a symlink at <code>/etc/hostapd/hostapd.conf.d/60-generated-templated.conf</code>) from drop-in config file templates at <code>/etc/hostapd/hostapd.conf-templates.d</code>.</p> </li> <li> <p><code>assemble-hostapd-config</code>: generates a temporary hostapd config file (which is used by a symlink at <code>/etc/hostapd/hostapd.conf</code>) from drop-in config files at <code>/etc/hostapd/hostapd.conf.d</code>.</p> </li> <li> <p><code>assemble-hosts-templated</code>: generates a temporary hosts drop-in snippet (which is used by a symlink at <code>/etc/hosts.d/50-generated-templated</code>) from drop-in hosts snippet templates at <code>/etc/hosts-templates.d</code>.</p> </li> <li> <p><code>assemble-hosts</code> generates a temporary hosts file (which is used by a symlink at <code>/etc/hosts</code>) from drop-in snippets at <code>/etc/hosts-templates.d</code>.</p> </li> </ul> <p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul>"},{"location":"reference/software/architecture/os/#filesystem","title":"Filesystem","text":"<p>The PlanktoScope OS's filesystem makes some changes from the default Debian/Raspberry Pi OS filesystem structure so that <code>/etc</code> and <code>/usr</code> 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:</p> <ul> <li> <p>Make a read-only mount (via the <code>overlay-sysroot</code> systemd service) of the initial root filesystem, at <code>/sysroot</code>.</p> </li> <li> <p>Make a read-only mount of the next Forklift pallet to be applied (via the <code>bindro-run-forklift-stages-current.service</code>) from a subdirectory within <code>/var/lib/forklift/stages</code> to <code>/run/forklift/stages/current</code>.</p> </li> <li> <p>Remount <code>/usr</code> (via the <code>overlay-usr</code> systemd service) as a writable overlay with a Forklift-managed intermediate layer (in a subdirectory within <code>/var/lib/forklift/stages</code> which can also be accessed at <code>/run/forklift/stages/current/exports/overlays/usr</code>) and <code>/sysroot/usr</code> as a base layer; any changes made by the system administrator to files in <code>/usr</code> will be transparently stored by the overlay in <code>/var/lib/overlays/overrides/usr</code>. This allows Forklift to provide extra files in <code>/usr</code> in an atomic way, while overrides made by the system administrator are stored separately.</p> </li> <li> <p>Remount <code>/etc</code> (via the <code>overlay-etc</code> systemd service) as a writable overlay with a Forklift-managed intermediate layer (in a subdirectory within <code>/var/lib/forklift/stages</code> which can also be accessed at <code>/run/forklift/stages/current/exports/overlays/etc</code>) and <code>/sysroot/etc</code> as a base layer; any changes made by the system administrator to files in <code>/etc</code> will be transparently stored by the overlay in <code>/var/lib/overlays/overrides/etc</code>. This allows Forklift to provide extra files in <code>/etc</code> in an atomic way, while overrides made by the system administrator are stored separately.</p> </li> <li> <p>Make a writable mount of <code>/var/lib/forklift/stages</code> to <code>/home/pi/.local/share/forklift/stages</code> (via the <code>bind-.local-share-forklift-stages@home-pi</code> systemd service) so that, when the <code>pi</code> user runs <code>forklift</code> commands like <code>forklift pallet switch</code>, those commands will update <code>/var/lib/forklift/stages</code> - and without requiring the use of <code>sudo</code>.</p> </li> <li> <p>Update systemd (via the <code>start-overlaid-units</code> systemd service) with any new systemd units provided via Forklift, so that they will run during boot.</p> </li> </ul> <p>Beyond what is required by the Linux Filesystem Hierarchy Standard, the PlanktoScope OS sets the following conventions related to filesystem paths:</p> <ul> <li> <p>Scripts which are provided by Forklift and only used as part of systemd services should be provided in <code>/usr/libexec</code>, Forklift packages should export those scripts to <code>overlays/usr/libexec</code> (so, for example, they will be accessible in <code>/run/forklift/stages/current/exports/overlays/usr/libexec</code>).</p> </li> <li> <p>Systemd units provided by Forklift should be provided in <code>/usr/lib/systemd/system</code>, and Forklift packages should export those units to <code>overlays/usr/lib/systemd/system</code>. Symlinks to enable those units should be provided in <code>/etc/systemd/system</code>, and Forklift packages should export those scripts to <code>overlays/etc/systemd/system</code>.</p> </li> <li> <p>Forklift-provided systemd services which dynamically generate temporary files meant to be used in <code>/etc</code> should generate those temporary files at stable paths in <code>/run/overlays/generated/etc</code>. Forklift packages which provide such systemd services should also provide relative symlinks into those temporary files in <code>/run/overlays/generated/etc</code> to be exported into <code>overlays/etc</code> as overlays for the corresponding paths in <code>/etc</code>. For example, if a package provides a service to dynamically generate a hosts file meant to be used as <code>/etc/hosts</code>, that service should generate the file in <code>/run/overlays/generated/etc/hosts</code> and the package should export a symlink at <code>overlays/etc/hosts</code> which points to <code>../../run/overlays/generated/etc/hosts</code>, so that <code>/etc/hosts</code> will be a symlink pointing to <code>/run/overlays/generated/etc/hosts</code>.</p> </li> </ul>"},{"location":"reference/software/architecture/os/#observability-telemetry","title":"Observability &amp; telemetry","text":"<p>Although it is not a high priority yet, we would like to enable operators of large (&gt;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:</p> <ul> <li> <p>Prometheus: a server for collecting and storing metrics and for exposing metrics over an HTTP API.</p> </li> <li> <p>Prometheus node exporter: for measuring computer hardware and OS monitoring metrics and exposing them over a Prometheus-compatible HTTP API.</p> </li> </ul> <p>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.</p>"},{"location":"reference/software/architecture/os/#data-processing","title":"Data processing","text":"<p>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:</p> <ul> <li>The PlanktoScope segmenter: for processing raw image datasets acquired by the PlanktoScope hardware controller to detect and extract particles from raw images.</li> </ul> <p>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.</p>"},{"location":"reference/software/architecture/os/#security","title":"Security","text":"<p>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:</p> <ul> <li> <p>Changing the password of the <code>pi</code> user away from the default of <code>copepode</code>.</p> </li> <li> <p>Password-protecting the Node-RED dashboard editor, which can be used to execute arbitrary commands with root permissions.</p> </li> <li> <p>Setting firewall rules.</p> </li> <li> <p>Changing the password of the Wi-Fi hotspot away from the default of <code>copepode</code>, or disabling Wi-Fi hotspot functionality.</p> </li> </ul> <p>Other risk mitigations will require deeper changes to the PlanktoScope OS, such as:</p> <ul> <li> <p>Limiting the permissions and capabilities made available to various system services which currently run with root permissions</p> </li> <li> <p>Password-protecting web browser-based user interfaces</p> </li> <li> <p>Password-protecting network APIs.</p> </li> </ul> <p>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!</p>"},{"location":"reference/software/functionalities/camera-settings/","title":"Camera Settings","text":"<p>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.</p> <p>The following camera settings can be adjusted via the Node-RED dashboard:</p> <ul> <li> <p>\"ISO\" &amp; \"Shutter Speed\" control the brightness of images captured by the camera.</p> </li> <li> <p>\"Auto White Balance\", \"WB: Red\", and \"WB: Blue\" control the color balance of images captured by the camera.</p> </li> </ul>"},{"location":"reference/software/functionalities/camera-settings/#image-brightness","title":"Image brightness","text":"<p>The Node-RED dashboard's \"Shutter Speed\" setting, which is specified in units of microseconds (\u03bcs), is used to set the <code>ExposureTime</code> 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\".</p> <p>The Node-RED dashboard's \"ISO\" setting is divided by 100 and used to set the <code>AnalogueGain</code> 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 <code>AnalogueGain</code> control and the <code>DigitalGain</code> property.</p>"},{"location":"reference/software/functionalities/camera-settings/#image-color-balance","title":"Image color balance","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/functionalities/sample-imaging/","title":"Sample Imaging","text":"<p>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.</p> <p>Currently, the PlanktoScope software only has one sample-imaging mode, which we call \"stop-flow imaging\":</p>"},{"location":"reference/software/functionalities/sample-imaging/#stop-flow-imaging","title":"Stop-flow imaging","text":"<p>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.</p> <p>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:</p> <ol> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>The PlanktoScope will capture and save an image of its entire field-of-view.</p> </li> </ol>"},{"location":"reference/software/functionalities/segmentation/","title":"Image Segmentation","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>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.</p>"},{"location":"reference/software/functionalities/segmentation/#median-calculation-step","title":"Median-calculation step","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/functionalities/segmentation/#image-correction-step","title":"Image-correction step","text":"<p>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.</p>"},{"location":"reference/software/functionalities/segmentation/#mask-calculation-step","title":"Mask-calculation step","text":"<p>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:</p> <ol> <li> <p>\"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.</p> </li> <li> <p>\"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.</p> </li> <li> <p>\"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.</p> </li> <li> <p>\"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.</p> </li> <li> <p>\"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.</p> </li> <li> <p>\"Erode2\": this operation erodes the mask with an 8-pixel-diameter circular kernel, inverting the effect of the previous \"dilate\" operation.</p> </li> </ol> <p>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.</p>"},{"location":"reference/software/functionalities/segmentation/#object-extraction-step","title":"Object-extraction step","text":"<p>The object-extraction step takes the following inputs:</p> <ul> <li> <p>A median-corrected image</p> </li> <li> <p>A segmentation mask</p> </li> <li> <p>The following sample metadata fields:</p> </li> <li> <p><code>acq_minimum_mesh</code>: 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\".</p> </li> <li> <p><code>process_pixel</code>: the pixel size calibration of the PlanktoScope, in units of \u00b5m per pixel; then the area (in units of \u00b5m<sup>2</sup>) per pixel is <code>process_pixel * process_pixel</code>. This value is set on the \"Hardware Settings\" page of the PlanktoScope's Node-RED dashboard as the \"Pixel size calibration: um per pixel\".</p> </li> </ul> <p>First, the object-extraction step calculates a minimum-area threshold for objects to extract using the input segmentation mask: the threshold (in units of pixel<sup>2</sup>) is calculated as <code>(2 * acq_minimum_mesh / process_pixel) ^ 2</code>.</p> <p>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 (<code>area_bbox</code> in scikit-image) is less than the minimum-area threshold.</p>"},{"location":"reference/software/functionalities/segmentation/#metadata-calculation","title":"Metadata calculation","text":"<p>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:</p> <ul> <li> <p><code>MeanHue</code>: the mean of the hue channel of the image in a hue-saturation-value (HSV) representation of the image</p> </li> <li> <p><code>StdHue</code>: the standard deviation of the hue channel of the image in an HSV representation of the image</p> </li> <li> <p><code>MeanSaturation</code>: the standard deviation of the saturation channel of the image in an HSV representation of the image</p> </li> <li> <p><code>StdSaturation</code>: the standard deviation of the saturation channel of the image in an HSV representation of the image</p> </li> <li> <p><code>MeanValue</code>: the standard deviation of the value channel of the image in an HSV representation of the image</p> </li> <li> <p><code>StdValue</code>: the standard deviation of the value channel of the image in an HSV representation of the image</p> </li> </ul> <p>Additionally, some metadata for the object is calculated from the region properties calculated by scikit-image for that object's region:</p> <ul> <li> <p><code>label</code>: The identifier of the object's region, as assigned by scikit-image. This corresponds to the <code>label</code> region property in scikit-image.</p> </li> <li> <p>Basic area properties:</p> </li> <li> <p><code>area_exc</code>: Number of pixels in the region (excluding pixels in any holes). This corresponds to the <code>area</code> region property in scikit-image.</p> </li> <li> <p><code>area</code>: Number of pixels of the region with all holes filled in (i.e. including pixels in any holes). This corresponds to the <code>area_filled</code> region property in scikit-image. Yes, it's somewhat confusing that the PlanktoScope segmenter renames scikit-image's <code>area</code> region property to <code>area_exc</code> and renames scikit-image's <code>area_filled</code> region property to <code>area</code>.</p> </li> <li> <p><code>%area</code>: 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 <code>1 - area_exc / area</code>. In other words, this represents the proportion of the region which consists of holes. Yes, <code>%area</code> is a misleading name both because of the <code>%</code> in the name and because of the <code>area</code> in the name.</p> </li> <li> <p>Equivalent-circle properties:</p> </li> <li> <p><code>equivalent_diameter</code>: 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 <code>equivalent_diameter_area</code> property in scikit-image.</p> </li> <li>Equivalent-ellipse properties:</li> <li> <p><code>eccentricity</code>: 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 <code>eccentricity</code> property in scikit-image.</p> </li> <li> <p><code>major</code>: The length (in pixels) of the major axis of region's equivalent ellipse. This corresponds to the <code>axis_major_length</code> property in scikit-image.</p> </li> <li> <p><code>minor</code>: The length (in pixels) of the minor axis of the region's equivalent ellipse. This corresponds to the <code>axis_minor_length</code> property in scikit-image.</p> </li> <li> <p><code>elongation</code>: The ratio between <code>major</code> and <code>minor</code>.</p> </li> <li> <p><code>angle</code>: 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 <code>orientation</code> property in scikit-image.</p> </li> <li> <p>Equivalent-object perimeter properties:</p> </li> <li> <p><code>perim.</code>: 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 <code>perimeter</code> property in scikit-image.</p> </li> <li> <p><code>perimareaexc</code>: Ratio between the perimeter and the number of pixels in the region (excluding pixels in any holes). Calculated as <code>perim. / area_exc</code>.</p> </li> <li> <p><code>perimmajor</code>: Ratio between the perimeter and the length of the major axis of the region's equivalent ellipse. Calculated as <code>perim. / major</code>.</p> </li> <li> <p><code>circ.</code>: The roundness of the region's equivalent object, including pixels in any holes. Calculated as <code>4 * \u03c0 * area / (perim. * perim.)</code>. Ranges from 1 for a perfect circle to 0 for highly non-circular shapes.</p> </li> <li> <p><code>circex</code>: The roundness of the region's equivalent object, excluding pixels in any holes. Calculated as <code>4 * \u03c0 * area_exc / (perim. * perim.)</code>. Ranges from 1 for a perfect circle to 0 for highly non-circular shapes or shapes with many large holes.</p> </li> <li> <p>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:</p> </li> <li> <p><code>bx</code>: 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 <code>bbox</code> property in scikit-image.</p> </li> <li> <p><code>by</code>: 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 <code>bbox</code> property in scikit-image.</p> </li> <li> <p><code>width</code>: Width (in number of pixels) of the region's bounding box. This is calculated from the elements of the <code>bbox</code> property in scikit-image.</p> </li> <li> <p><code>height</code>: Height (in number of pixels) of the region's bounding box. This is calculated from the elements of the <code>bbox</code> property in scikit-image.</p> </li> <li> <p><code>bounding_box_area</code>: Number of pixels in the region's bounding box; equivalent to <code>width * height</code>. This corresponds to the <code>area_bbox</code> region property in scikit-image.</p> </li> <li> <p><code>extent</code>: 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 <code>area_exc / bounding_box_area</code>. This corresponds to the <code>extent</code> region property in scikit-image.</p> </li> <li> <p>Convex hull (the smallest convex polygon which encloses the region) properties:</p> </li> <li> <p><code>convex_area</code>: Number of pixels in the convex hull of the region. This corresponds to the <code>area_convex</code> region property in scikit-image.</p> </li> <li> <p><code>solidity</code>: 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 <code>area_exc / convex_area</code>. This corresponds to the <code>solidity</code> region property in scikit-image.</p> </li> <li> <p>Unweighted centroid properties:</p> </li> <li> <p><code>x</code>: 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 <code>centroid</code> region property in scikit-image.</p> </li> <li> <p><code>y</code>: 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 <code>centroid</code> region property in scikit-image.</p> </li> <li> <p><code>local_centroid_col</code>: x-position (in pixels) of the centroid of the object, relative to the top-left corner of the region's bounding box; equivalent to <code>x - bx</code>. This corresponds to the second element of the <code>centroid_local</code> region property in scikit-image.</p> </li> <li> <p><code>local_centroid_row</code>: y-position (in pixels) of the centroid of the object, relative to the top-left corner of the region's bounding box; equivalent to <code>y - by</code>. This corresponds to the first element of the <code>centroid_local</code> region property in scikit-image.</p> </li> <li> <p>Topological properties:</p> </li> <li> <p><code>euler_number</code>: 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 <code>euler_number</code> property in scikit-image.</p> </li> </ul>"},{"location":"reference/software/functionalities/segmentation/#output-image-cropping","title":"Output image cropping","text":"<p>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).</p> <p>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.</p>"},{"location":"reference/software/interfaces/exported-metadata/","title":"Exported Metadata","text":"<p>TODO</p>"},{"location":"reference/software/interfaces/mqtt/","title":"Planktoscope MQTT API Reference","text":"<p>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:</p> <pre><code>flowchart TD\n    API[API Client] --&gt;|Command| Broker[MQTT Broker]\n    Broker --&gt;|Command| Backend[Python Backend]\n    Backend --&gt;|Status Update| Broker[MQTT Broker]\n    Broker --&gt;|Status Update| API</code></pre> <p>Most 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:</p> <ul> <li>API clients send commands to the Python backend (via the MQTT broker), and receive status updates from the Python backend (also via the MQTT broker). The PlanktoScope's Node-RED dashboard is an API client, but other programs are also allowed to act as API clients.</li> <li>The MQTT broker passes commands and status updates between the API client(s) and the Python backend. The MQTT broker runs on the PlanktoScope and accepts connections from API clients on port 1883.</li> <li>The Python backend handles commands, takes actions (e.g. changing the state of hardware actuators), and publishes status updates both in response to commands and in response to changes in internal state. Currently, parts of the Python backend also act as MQTT API clients to other parts of the Python backend.</li> </ul> <p>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. <code>actuator/pump</code>). Every MQTT message in the PlanktoScope's MQTT API carries a payload, which is a JSON object serialized as a string:</p> <ul> <li>Messages which are commands usually specify the type of command in an <code>action</code> field of the payload object; other fields of the payload object are parameters of the command.</li> <li>Messages which are status updates have a single field in the payload object, <code>status</code>, which is a string containing a status or error message.</li> </ul> <p>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:</p>"},{"location":"reference/software/interfaces/mqtt/#pump","title":"Pump","text":"<p>The Pump API controls the movement of fluid through the PlanktoScope:</p> <ul> <li>MQTT topics for commands: <code>actuator/pump</code></li> <li>MQTT topics for status updates: <code>status/pump</code></li> <li>Commands: <code>move</code>, <code>stop</code></li> </ul>"},{"location":"reference/software/interfaces/mqtt/#move-command","title":"<code>move</code> command","text":"<p>The <code>move</code> 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:</p> <pre><code>{\n  \"action\": \"move\",\n  \"direction\": \"FORWARD\",\n  \"volume\": 10,\n  \"flowrate\": 1\n}\n</code></pre> <p>The <code>move</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>move</code> command. string <code>move</code> <code>direction</code> Direction to run the pump. string <code>FORWARD</code>, <code>BACKWARD</code> <code>volume</code> Total volume of sample to pump before stopping automatically (mL). float 0 &lt; <code>volume</code> <code>flowrate</code> Speed of pumping (mL/min). float 0 &lt; <code>flowrate</code> \u2264 45 mL/min"},{"location":"reference/software/interfaces/mqtt/#move-command-responses","title":"<code>move</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/pump</code> topic, in response to the <code>move</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Started</code> The pump has started moving in response to a valid <code>move</code> command. <code>Error, the message is missing an argument</code> One or more required parameters (<code>direction</code>, <code>volume</code>, <code>flowrate</code>) are missing in the <code>move</code> command. <code>Error, The flowrate should not be == 0</code> An invalid value (0) was provided for the <code>flowrate</code> field. <code>Done</code> The pump has successfully stopped after fully pumping the specified volume of sample. <p>Note: the MQTT API does not yet completely specify error messages in response to invalid values for the <code>direction</code>, <code>volume</code>, and <code>flowrate</code> parameters.</p>"},{"location":"reference/software/interfaces/mqtt/#stop-command","title":"<code>stop</code> command","text":"<p>The <code>stop</code> command interrupts any ongoing movement of fluid through the PlanktoScope and cuts off power to the PlanktoScope pump's stepper motor:</p> <pre><code>{\n  \"action\": \"stop\"\n}\n</code></pre> <p>The <code>stop</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>stop</code> command. string <code>stop</code>"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses","title":"<code>stop</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/pump</code> topic, in response to the <code>stop</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Interrupted</code> The pump has stopped moving in response to a valid <code>stop</code> command, interrupting any ongoing <code>move</code> command.Sent in response to any Pump <code>stop</code> command, and any Imager <code>stop</code> command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/pump</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Ready</code> The backend has become ready to respond to Pump commands. <code>Dead</code> The backend will no longer respond to Pump commands."},{"location":"reference/software/interfaces/mqtt/#focus","title":"Focus","text":"<p>The Focus API controls the movement of the sample stage focusing motors in the PlanktoScope:</p> <ul> <li>MQTT topics for commands: <code>actuator/focus</code></li> <li>MQTT topics for status updates: <code>status/focus</code></li> <li>Commands: <code>move</code>, <code>stop</code></li> </ul>"},{"location":"reference/software/interfaces/mqtt/#move-command_1","title":"<code>move</code> command","text":"<p>The <code>move</code> 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:</p> <pre><code>{\n  \"action\": \"move\",\n  \"direction\": \"UP\",\n  \"distance\": 0.26,\n  \"speed\": 1\n}\n</code></pre> <p>The <code>move</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>move</code> command. string <code>move</code> <code>direction</code> Direction to move the sample stage. string <code>UP</code>, <code>DOWN</code> <code>distance</code> Total distance to move the stage before stopping automatically (in mm). float 0 &lt; <code>distance</code> \u2264 45.0 <code>speed</code> Speed of movement (in mm/s).Defaults to 5. float 0 &lt; <code>speed</code> \u2264 5.0 (optional)"},{"location":"reference/software/interfaces/mqtt/#move-command-responses_1","title":"<code>move</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/focus</code> topic in response to the <code>move</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Started</code> The focusing motors have started moving in response to a valid <code>move</code> command. <code>Error</code> The <code>move</code> command is missing the <code>distance</code> and/or <code>direction</code> fields. <code>Done</code> The focusing motors have successfully stopped after moving the specified distance."},{"location":"reference/software/interfaces/mqtt/#stop-command_1","title":"<code>stop</code> command","text":"<p>The <code>stop</code> command interrupts any ongoing movement of the focusing stage and cuts off power to the focusing motors:</p> <pre><code>{\n  \"action\": \"stop\"\n}\n</code></pre> <p>The <code>stop</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>stop</code> command. string <code>stop</code>"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_1","title":"<code>stop</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/focus</code> topic, in response to the <code>stop</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Interrupted</code> The focusing motors have stopped moving in response to a valid <code>stop</code> command, interrupting any ongoing <code>stop</code> command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_1","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/focus</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Ready</code> The backend has become ready to respond to Focus commands. <code>Dead</code> The backend will no longer respond to Focus commands."},{"location":"reference/software/interfaces/mqtt/#light","title":"Light","text":"<p>The Light API controls the state of the LED lighting system in the PlanktoScope:</p> <ul> <li>MQTT topics for commands: <code>actuator/light</code></li> <li>MQTT topics for status updates: <code>status/light</code></li> <li>Commands: <code>on</code>, <code>off</code></li> </ul>"},{"location":"reference/software/interfaces/mqtt/#on-command","title":"<code>on</code> command","text":"<p>The <code>on</code> command turns on the sample illumination LED. For example:</p> <pre><code>{\n  \"action\": \"on\"\n  \"led\": \"1\"\n}\n</code></pre> <p>The <code>on</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>on</code> command. string <code>on</code> <code>led</code> Specifies the LED to turn on.Defaults to <code>1</code>. integer <code>1</code>\u00a0(optional)"},{"location":"reference/software/interfaces/mqtt/#on-command-responses","title":"<code>on</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/light</code> topic in response to the <code>on</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Led 1: On</code> The LED turned on successfully. <code>Error with LED number</code> An invalid value was provided for the <code>led</code> field of the command."},{"location":"reference/software/interfaces/mqtt/#off-command","title":"<code>off</code> command","text":"<p>The <code>off</code> command turns off the sample illumination LED. For example:</p> <pre><code>{\n  \"action\": \"off\"\n}\n</code></pre> <p>The <code>off</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>off</code> command. string <code>off</code> <code>led</code> Specifies the LED to turn on.Defaults to <code>1</code> integer <code>1</code>"},{"location":"reference/software/interfaces/mqtt/#off-command-responses","title":"<code>off</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/light</code> topic in response to the <code>off</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Led 1: Off</code> The LED turned off successfully. <code>Error with LED number</code> An invalid value was provided for the <code>led</code> field of the command."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_2","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/light</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Ready</code> The backend has become ready to respond to Light commands. <code>Dead</code> The backend will no longer respond to Light commands."},{"location":"reference/software/interfaces/mqtt/#imager","title":"Imager","text":"<p>The Imager API controls image acquisition with the PlanktoScope's hardware, as well as the PlanktoScope's camera:</p> <ul> <li>MQTT topics for commands: <code>imager/image</code></li> <li>MQTT topics for status updates: <code>status/imager</code></li> <li>Commands: <code>settings</code>, <code>update_config</code>, <code>image</code>, <code>stop</code></li> </ul> <p>For details on how images are acquired, refer to our technical reference on sample imaging in the PlanktoScope.</p> <p>Generally, commands should be sent in the following order:</p> <ol> <li><code>settings</code> command: Configure the camera settings.</li> <li><code>update_config</code> command: Update the dataset metadata for the next image acquisition.</li> <li><code>image</code> command: Initiate image acquisition.</li> <li><code>stop</code> command: Stop any in-progress image acquisition.</li> </ol>"},{"location":"reference/software/interfaces/mqtt/#settings-command","title":"<code>settings</code> command","text":"<p>The <code>settings</code> command changes the camera settings. The fields <code>iso</code>, <code>shutter_speed</code>, <code>white_balance_gain</code> and <code>white_balance</code> 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:</p> <pre><code>{\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}\n</code></pre> <p>The <code>settings</code> command has the following parameters:</p> Parameter Description Type Accepted Values <code>action</code> Specifies the <code>settings</code> command. string <code>settings</code> <code>iso</code> Simulated ISO image sensitivity. int 0 &lt; <code>iso</code> \u2264 650 (higher values may be accepted for certain cameras) (optional) <code>shutter_speed</code> Exposure time (in \u03bcs). int 125 \u2264 <code>shutter_speed</code>\u00a0(optional) <code>white_balance_gain.red</code> White balance red gain. float 0.0 \u2264 <code>white_balance_gain.red</code>\u00a0\u2264 32.0 (optional) <code>white_balance_gain.blue</code> White balance blue gain. float 0.0\u00a0\u2264\u00a0<code>white_balance_gain.blue</code>\u00a0\u2264 32.0 (optional) <code>white_balance</code> White balance mode. (<code>off</code>\u00a0specifies the use of manual white balance gains) string <code>auto</code>, <code>off</code>\u00a0(optional)"},{"location":"reference/software/interfaces/mqtt/#settings-command-responses","title":"<code>settings</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic in response to the <code>settings</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Cause <code>Camera settings updated</code> The camera settings have been successfully updated. <code>Camera settings error</code> The settings command is missing required parameters. <code>Iso number not valid</code> The provided <code>iso</code>\u00a0value is not allowed. <code>Shutter speed not valid</code> The provided <code>shutter_speed</code>\u00a0value is not allowed. <code>White balance gain not valid</code> The provided <code>white_balance_gain</code>\u00a0object is not valid or has an invalid value. <code>White balance mode {white_balance} not valid</code> The provided <code>white_balance</code>\u00a0value is not allowed."},{"location":"reference/software/interfaces/mqtt/#update_config-command","title":"<code>update_config</code> command","text":"<p>The <code>update_config</code> command sets/changes the metadata which will be saved with the dataset which to be acquired by the next <code>image</code> command. For example:</p> <pre><code>{\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}\n</code></pre> <p>The 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 <code>update_config</code> command has the following parameters:</p> <p>Sample information:</p> Field Description Type <code>sample_project</code> Project name. string <code>sample_id</code> Sample identifier. integer <code>sample_uuid</code> Sample UUID. string <code>sample_ship</code> Ship name. string <code>sample_operator</code> Operator name. string <code>sample_sampling_gear</code> Sampling gear description. string <code>sample_concentrated_sample_volume</code> Concentrated sample volume. float <code>sample_total_volume</code> Total volume. float <code>sample_dilution_factor</code> Dilution factor. float <code>sample_speed_through_water</code> Speed through water. float <p>Acquisition information:</p> Field Description Type <code>acq_id</code> Acquisition identifier. integer <code>acq_instrument</code> Acquisition instrument. string <code>acq_magnification</code> Magnification level. string <code>acq_camera_id</code> Camera identifier. integer <code>acq_camera_lens</code> Camera lens. string <code>acq_software</code> Acquisition software. string <code>acq_volume</code> Acquisition volume. float <code>acq_imaged_volume</code> Imaged volume. float <code>acq_minimum_mesh</code> Minimum mesh size. float <code>acq_maximum_mesh</code> Maximum mesh size. float <code>acq_min_esd</code> Minimum equivalent spherical diameter. float <code>acq_max_esd</code> Maximum equivalent spherical diameter. float <code>acq_camera_name</code> Camera name. string <code>acq_nb_frame</code> Number of frames captured. integer <code>acq_local_datetime</code> Local date and time of acquisition. string <code>acq_camera_resolution</code> Camera resolution. string <code>acq_camera_iso</code> Camera ISO setting. float <code>acq_camera_shutter_speed</code> Camera shutter speed. float <p>Object information:</p> Field Description Type <code>object_date</code> Date of the object recording. string <code>object_time</code> Time of the object recording. string <code>object_lat</code> Latitude of the sample location. float <code>object_lon</code> Longitude of the sample location. float <code>object_depth_min</code> Minimum depth of the sample location. float <code>object_depth_max</code> Maximum depth of the sample location. float <code>object_date_end</code> End date of the object recording. string <code>object_time_end</code> End time of the object recording. string <code>object_lat_end</code> End latitude of the sample location. float <code>object_lon_end</code> End longitude of the sample location. float <p>Processing information:</p> Field Description Type <code>process_pixel</code> Pixel processing method. string <code>process_datetime</code> Date and time of processing. string <code>process_id</code> Processing identifier. integer <code>process_uuid</code> Processing UUID. string <code>process_source</code> Source of processing software or method. string <code>process_commit</code> Commit hash of the software used. string"},{"location":"reference/software/interfaces/mqtt/#update_config-command-responses","title":"<code>update_config</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic in response to the <code>update_config</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Config updated</code> The metadata has been successfully updated. <code>Configuration message error</code> The command is missing the required\u00a0<code>config</code> field. <code>Busy</code> Image acquisition is already in progress, so dataset metadata cannot be changed."},{"location":"reference/software/interfaces/mqtt/#image-command","title":"<code>image</code> command","text":"<p>The <code>image</code> 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:</p> <pre><code>{\n  \"action\": \"image\",\n  \"pump_direction\": \"FORWARD\",\n  \"volume\": 1,\n  \"nb_frame\": 200,\n  \"sleep\": 0.1\n}\n</code></pre> <p>A valid <code>update_config</code> command with a unique <code>(object_date, sample_id, acq_id)</code> combination must be sent some time before each <code>image</code> command. If an <code>update_config</code> command has not been sent before the <code>image</code> command, the <code>image</code> 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).</p> <p>The <code>image</code> command has the following parameters:</p> Parameter Description Type Accepted Values <code>pump_direction</code> Direction of sample pumping. string <code>FORWARD</code>, <code>BACKWARD</code>. <code>volume</code> Volume (in mL) of sample to pump between each captured image. float 0 &lt; <code>volume</code> <code>nb_frame</code> Number of frames to capture. integer 0 &lt; <code>nb_frame</code> <code>sleep</code> 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 &lt; <code>sleep</code>"},{"location":"reference/software/interfaces/mqtt/#image-command-responses","title":"<code>image</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic, in response to the <code>image</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Started</code> The image capture process has started successfully. <code>Error</code> At least one field of the\u00a0<code>image</code>\u00a0command is missing or has an invalid value. <code>Error: missing camera</code> No camera is available to use for image acquisition. <code>Configuration update error: object_date is missing!</code> The last time the <code>update_config</code>\u00a0command was sent, it did not have an <code>object_date</code>\u00a0parameter. <code>Configuration update error: Chosen id are already in use!</code> The\u00a0<code>(object_date, sample_id, acq_id)</code>\u00a0combination for the dataset (set by the last <code>update_config</code>\u00a0command) is already used by a previous dataset. <code>Image {index}/{nb_frame} saved to {filename}</code> An image has been successfully captured and saved. <code>Image {index}/{nb_frame} WAS NOT CAPTURED! STOPPING THE PROCESS!</code> An error occurred during image capture; the ongoing image acquisition has finished with failure, resulting in an incomplete dataset. <code>Done</code> The image acquisition finished successfully, resulting in a complete dataset."},{"location":"reference/software/interfaces/mqtt/#stop-command_2","title":"<code>stop</code> command","text":"<p>This message interrupts any in-progress image acquisition routine and stops any ongoing sample pumping.</p> <pre><code>{\n  \"action\": \"stop\"\n}\n</code></pre> <p>The <code>stop</code> command has the following parameters:</p> Field Description Type Accepted Values <code>action</code> Specifies the <code>stop</code>\u00a0command. string <code>stop</code>"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_2","title":"<code>stop</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic, in response to the <code>stop</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error message Description <code>Interrupted</code> The image capture process was stopped successfully."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_3","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/imager</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Starting up</code> The backend will soon attempt to initialize the camera. <code>Error: missing camera</code> A camera was not detected. <code>Ready</code> The camera is now operational, and the backend has become ready to respond to Imager commands. <code>Dead</code> The backend will no longer respond to Imager commands."},{"location":"reference/software/interfaces/mqtt/#segmenter","title":"Segmenter","text":"<p>The Segmenter API controls the processing of acquired images:</p> <ul> <li>MQTT topics for commands: <code>segmenter/segment</code></li> <li>MQTT topics for status updates: <code>status/segmenter</code>, <code>status/segmenter/object_id</code>, <code>status/segmenter/metric</code></li> <li>Commands: <code>segment</code></li> </ul> <p>For details on how images are processed, refer to our technical reference on image segmentation in the PlanktoScope.</p>"},{"location":"reference/software/interfaces/mqtt/#segment-command","title":"<code>segment</code> command","text":"<p>The <code>segment</code> command initiates processing of images stored in the specified path, optionally exporting the results to an EcoTaxa-compatible archive. The various <code>settings</code> parameters of this command provide control over the behavior of image processing. For example, this command initiates processing of all images in the <code>/path/to/segment</code> directory:</p> <pre><code>{\n  \"action\": \"segment\",\n  \"path\": \"/path/to/segment\",\n  \"settings\": {\n    \"force\": false,\n    \"recursive\": true,\n    \"ecotaxa\": true,\n    \"keep\": true\n  }\n}\n</code></pre> <p>The <code>segment</code> command has the following parameters:</p> Parameter Description Type Accepted Values <code>path</code> Path to the directory of images to process.Defaults to <code>/home/pi/data/img</code>. file path (string) any subdirectory of\u00a0<code>/home/pi/data/img</code> (optional) <code>settings</code>.<code>force</code> Force re-segmentation of already-processed directories, ignoring the existence of\u00a0<code>done</code>\u00a0files which otherwise prevent already-segmented directories from being processed again.Defaults to <code>false</code>. boolean <code>true</code>, <code>false</code> (optional) <code>settings</code>.<code>recursive</code> Process datasets in all subdirectories of\u00a0<code>path</code>.Defaults to <code>true</code>. boolean <code>true</code>, <code>false</code> (optional) <code>settings</code>.<code>ecotaxa</code> Export an EcoTaxa-compatible archive.Defaults to <code>true</code>. boolean <code>true</code>, <code>false</code> (optional) <code>settings.keep</code> Keep ROI files generated when exporting an EcoTaxa-compatible archive. It has no effect if <code>settings.ecotaxa</code>\u00a0is <code>false</code>.Defaults to <code>true</code>. boolean <code>true</code>, <code>false</code> (optional)"},{"location":"reference/software/interfaces/mqtt/#segment-command-responses","title":"<code>segment</code> command responses","text":"<p>The Python backend can send status updates on the <code>status/segmenter</code> topic, in response to the <code>segment</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error message Description <code>Started</code> The segmentation process has begun. <code>Busy</code> The segmenter is currently running and cannot update configurations. <code>Calculating flat</code> The frame background is being calculated. <code>Segmenting image %s, image %d/%d</code> Segmentation of a specific image is in progress. <code>An exception was raised during the segmentation: %s.</code> An error occurred during segmentation. <code>Done</code> Processing has finished for the specified datasets. <p>As the Python backend performs segmentation, it will repeatedly send additional status updates on the <code>status/segmenter/object_id</code> topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:</p> Field Description Type <code>object_id</code> A scikit-image region label. integer <p>As the Python backend performs segmentation, it will repeatedly send additional status updates on the <code>status/segmenter/metric</code> topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:</p> Field Description Type <code>name</code> 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 <code>status/segmenter/object_id</code>. string <code>metadata</code> Metadata for the object. struct <p>The <code>metadata</code> field of status updates sent on the <code>status/segmenter/metric</code> topic is an object with the following fields:</p> Field Description Type <code>label</code> Label of the object. integer <code>width</code> Width of the smallest rectangle enclosing the object. integer <code>height</code> Height of the smallest rectangle enclosing the object. integer <code>bx</code> X coordinate of the top left point of the smallest rectangle enclosing the object. integer <code>by</code> Y coordinate of the top left point of the smallest rectangle enclosing the object. integer <code>circ</code> Circularity: (4 \u2217 \u03c0 \u2217 Area) / Perimeter^2. A value of 1 indicates a perfect circle, approaching 0 indicates an elongated polygon. float <code>area_exc</code> Surface area of the object excluding holes, in square pixels. integer <code>area</code> Surface area of the object in square pixels. integer <code>%area</code> Percentage of object\u2019s surface area that is comprised of holes. float <code>major</code> Primary axis of the best fitting ellipse for the object. float <code>minor</code> Secondary axis of the best fitting ellipse for the object. float <code>y</code> Y position of the center of gravity of the object. float <code>x</code> X position of the center of gravity of the object. float <code>convex_area</code> The area of the smallest polygon within which all points in the object fit. integer <code>perim</code> The length of the outside boundary of the object. float <code>elongation</code> The result of dividing the <code>major</code> parameter by the <code>minor</code> parameter. float <code>perimareaexc</code> The result of dividing the <code>perim</code> parameter by the <code>area_exc</code> parameter. float <code>perimmajor</code> The result of dividing the <code>perim</code> parameter by the <code>major</code> parameter. float <code>circex</code> (4 \u2217 \u03c0 \u2217 area_exc) / perim^2. float <code>angle</code> Angle between the primary axis and a line parallel to the x-axis of the image. float <code>bounding_box_area</code> Area of the bounding box enclosing the object. integer <code>eccentricity</code> Eccentricity of the object. float <code>equivalent_diameter</code> Diameter of a circle with the same area as the object. float <code>euler_number</code> Euler number of the object. integer <code>extent</code> Ratio of object area to bounding box area. float <code>local_centroid_col</code> Column position of the local centroid. float <code>local_centroid_row</code> Row position of the local centroid. float <code>solidity</code> Ratio of object area to convex area. float <code>MeanHue</code> Mean hue value of the object. float <code>MeanSaturation</code> Mean saturation value of the object. float <code>MeanValue</code> Mean value (brightness) of the object. float <code>StdHue</code> Standard deviation of the hue value of the object. float <code>StdSaturation</code> Standard deviation of the saturation value of the object. float <code>StdValue</code> Standard deviation of the value (brightness) of the object. float"},{"location":"reference/software/interfaces/mqtt/#stop-command_3","title":"<code>stop</code> command","text":"<p>The <code>stop</code> command interrupts any ongoing image processing. For example:</p> <pre><code>{\n  \"action\": \"stop\"\n}\n</code></pre> <p>The <code>stop</code> command has the following parameters:</p> Parameter Type Accepted Values Description <code>action</code> string \"stop\" Specifies the action to stop segmentation. <p>Warning</p> <p>The functionality for this command has not yet been implemented. Currently an <code>Interrupted</code> status is sent as a response on the <code>segmenter/segment</code> topic even though no interruption will actual happen.</p>"},{"location":"reference/software/interfaces/mqtt/#stop-command-responses_3","title":"<code>stop</code> command responses","text":"<p>The Python backend can send status updates on the <code>segmenter/segment</code> topic, in response to the <code>stop</code> command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error message Description <code>Interrupted</code> The segmentation process was interrupted."},{"location":"reference/software/interfaces/mqtt/#non-response-status-updates_4","title":"Non-response status updates","text":"<p>The Python backend can send status updates on the <code>status/segmenter</code> topic which are not triggered by any command. The <code>status</code> field of such status updates can have any of the following values:</p> Status/Error Description <code>Ready</code> The backend has become ready to respond to Segmenter commands. <code>Dead</code> The backend will no longer respond to Segmenter commands."},{"location":"reference/software/subsystems/installation/","title":"Installation","text":"<p>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.</p> <p>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.</p>"},{"location":"reference/software/subsystems/installation/#installation-bootstrap-script","title":"Installation bootstrap script","text":"<p>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 <code>stable</code> 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:</p> <ol> <li> <p>The script loads some parameters (set by environment variables and/or corresponding command-line arguments) which set the behavior of the script.</p> </li> <li> <p>The script installs <code>git</code>, if it was not already installed (as is the case on the \"Lite\" image of the Raspberry Pi OS); if the <code>yes</code> parameter was not set and <code>git</code> was not already installed, the script will first ask the user to confirm that they wish to install <code>git</code> before the script continues. <code>git</code> 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.</p> </li> <li> <p>The script clones a minimal \"mirror\" copy of the specified repository (set by the <code>repo</code> parameter) of distro setup scripts to a temporary directory (i.e. a directory created in <code>/tmp</code>). This \"mirror\" copy is used to:</p> <ul> <li> <p>Resolve the version query parameters (<code>version-query</code>, <code>query-type</code>, and - when <code>query-type</code> is <code>tag</code> - <code>tag-prefix</code>) into a specific commit hash for the repository.</p> </li> <li> <p>Determine a (pseudo-)version string for the resolved commit based on the last release tag (whose name is prefixed with the <code>tag-prefix</code> parameter) ancestral to that commit.</p> </li> </ul> </li> <li> <p>The script clones a copy of the specified repository (set by the <code>repo</code> parameter) to a temporary directory and checks out the specific commit which was resolved by the previous step; if the <code>yes</code> 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.</p> </li> <li> <p>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 <code>yes</code> 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.</p> </li> <li> <p>The script runs the specified script (set by the <code>setup-entrypoint</code> parameter) within the downloaded copy of the specified repository; if the <code>yes</code> 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.</p> </li> </ol>"},{"location":"reference/software/subsystems/installation/#script-parameters","title":"Script parameters","text":"Command-Line Flags Environment Variable Name Description <code>-r</code><code>--repo</code> <code>REPO</code> 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:\u00a0<code>github.com/PlanktoScope/PlanktoScope</code> <code>-v</code><code>--version-query</code> <code>VERSION_QUERY</code> The version of the repository to download. The version query is interpreted differently depending on the query type set by the\u00a0<code>query-type</code>\u00a0parameter:<ul><li>Query type\u00a0\u00a0<code>branch</code>: query should be a branch name (e.g. <code>software/beta</code>).</li><li>Query type\u00a0<code>tag</code>: query should be a Git tag name, excluding the tag prefix specified by the <code>tag-prefix</code>\u00a0parameter (e.g. <code>v2024.0.0</code>\u00a0if <code>tag-prefix</code>\u00a0is <code>software</code>\u00a0and the Git tag is\u00a0<code>software/v2024.0.0</code>).</li><li>Query type\u00a0<code>hash</code>: query should be a commit hash and may be abbreviated (e.g. <code>2d6928e</code>).</li></ul>Default value: <code>software/stable</code> <code>-t</code><code>--query-type</code> <code>QUERY_TYPE</code> The type of version query set by the <code>version-query</code>\u00a0parameter.Allowed values: <code>branch</code>, <code>tag</code>, <code>hash</code>.Default value: <code>branch</code> <code>-H</code><code>--hardware</code> <code>HARDWARE</code> The hardware configuration, passed as the first argument to the entrypoint of the distro setup scripts. The distro setup scripts in the\u00a0<code>github.com/PlanktoScope/PlanktoScope</code>\u00a0repo currently expect either <code>none</code>, <code>segmenter-only</code>,\u00a0<code>adafruithat</code>,\u00a0<code>planktoscopehat</code>, or <code>fairscope-latest</code>.Default value: <code>planktoscopehat</code> <code>--tag-prefix</code> <code>TAG_PREFIX</code> The prefix for Git version tags when resolving the version query (with query type\u00a0<code>tag</code>) and when resolving tags (for pseudoversion strings).\u00a0Default value: <code>software/</code> <code>--setup-entrypoint</code> <code>SETUP_ENTRYPOINT</code> 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 <code>repo</code>\u00a0parameter) which will be downloaded at the specified commit (set by the <code>version-query</code>\u00a0and <code>query-type</code>\u00a0parameters and - when <code>query-type</code>\u00a0is <code>tag</code>\u00a0- by the <code>tag-prefix</code>\u00a0parameter) to obtain the distro setup scripts.Default value: <code>software/distro/setup/setup.sh</code> <code>-y</code><code>-f</code><code>--yes</code><code>--force</code> <code>FORCE</code> Whether to automatically confirm all user confirmation prompts:<ul><li><code>FORCE=1</code>\u00a0(or including the command-line flag) automatically confirms all prompts.</li><li>Not setting <code>FORCE</code> (or not including the command-line flag) requires user input for confirmation on all prompts.</li></ul>Default: User input required <code>-V</code><code>--verbose</code> <code>VERBOSE</code> Whether to display additional (verbose) output:<ul><li><code>VERBOSE=1</code>\u00a0(or including the command-line flag) enables verbose output.</li><li>Not setting <code>VERBOSE</code> (or not including the command-line flag) disables verbose output.</li></ul>Default: Don't display verbose output <code>-h</code><code>--help</code> 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. <p>Example combinations of command-line arguments using the above parameters:</p> <ul> <li> <p><code>-v software/stable -H planktoscopehat</code> or <code>-H planktoscopehat</code>: install the latest stable release of the standard PlanktoScope OS (i.e. from the <code>software/stable</code> branch) for a PlanktoScope with the PlanktoScope HAT.</p> </li> <li> <p><code>-v software/beta -H adafruithat</code>: install the latest beta pre-release or stable release of the standard PlanktoScope OS (i.e. from the <code>software/beta</code> branch) for a PlanktoScope with the Adafruit HAT.</p> </li> <li> <p><code>-v master -H planktoscopehat</code>: install the latest development version of the standard PlanktoScope OS (i.e. from the <code>master</code> branch) for a PlanktoScope with the PlanktoScope HAT.</p> </li> <li> <p><code>-t tag -v v2024.0.0-alpha.1 -H adafruithat</code>: install the v2024.0.0-alpha.1 pre-release of the standard PlanktoScope OS (i.e. from the <code>software/v2024.0.0-alpha.1</code> tag) for a PlanktoScope with the Adafruit HAT.</p> </li> <li> <p><code>-t hash -v 2d6928e -H planktoscopehat</code>: install <code>2d6928e</code> commit of the standard PlanktoScope OS for a PlanktoScope with the PlanktoScope HAT.</p> </li> <li> <p><code>-v master -r github.com/LaurentPV/PlanktoScope -H adafruithat</code>: install the latest development commit of <code>master</code> branch of the <code>github.com/LaurentPV/PlanktoScope</code> fork of the PlanktoScope OS for a PlanktoScope with the Adafruit HAT.</p> </li> </ul>"},{"location":"reference/software/subsystems/installation/#recorded-versioning-information","title":"Recorded versioning information","text":"<p>Currently the installer script creates two YAML files, both in the <code>/usr/share/planktoscope</code> directory.</p> <p><code>/usr/share/planktoscope/installer-config.yml</code> records the values of the parameters with which the installer script was invoked:</p> YAML Field Name Corresponding Script Parameter Example Value <code>repo</code> <code>repo</code> <code>\"github.com/PlanktoScope/PlanktoScope\"</code> <code>version-query</code> <code>version-query</code> <code>\"v2024.0.0-alpha.1\"</code> <code>query-type</code> <code>query-type</code> <code>\"tag\"</code> <code>hardware</code> <code>hardware</code> <code>\"adafruithat\"</code> <code>tag-prefix</code> <code>tag-prefix</code> <code>\"software/\"</code> <code>setup-entrypoint</code> <code>setup-entrypoint</code> <code>\"software/distro/setup/setup.sh\"</code> <p><code>/usr/share/planktoscope/installer-versioning.yml</code> records information about the version of the PlanktoScope OS's distro setup scripts which was used to install the PlanktoScope OS:</p> Field Name Description <code>repo</code> The path of the Git repository which provided the distro setup scripts, with any leading protocol string (e.g. <code>https://</code>) removed.Example Values: <ol><li><code>\"github.com/PlanktoScope/PlanktoScope\"</code></li><li><code>\"github.com/PlanktoScope/PlanktoScope\"</code></li></ol> <code>commit</code> The full hash of the exact commit which provided the distro setup scripts.Example Values: <ol><li><code>\"2d6928e596b28f0c4c268fecb588c85215b1027e\"</code>\u00a0(for commit <code>2d6928e</code>)</li><li><code>\"4d8b882616a8374918730bc1c6d300edfd7a523a\"</code>\u00a0(for commit <code>4d8b882</code>)</li></ol> <code>tag</code> The full name of the Git tag (whose name starts with the prefix set by the <code>tag-prefix</code>\u00a0script parameter) at the exact commit which provided the distro setup scripts, if such a tag exists; otherwise, the empty string (<code>\"\"</code>).Example Values: <ol><li><code>\"software/v2024.0.0-alpha.1\"</code>\u00a0(so commit <code>2d6928e</code>\u00a0has Git tag <code>software/v2024.0.0-alpha.1</code>)</li><li><code>\"\"</code>\u00a0(so commit <code>4d8b882</code>\u00a0has no Git tag)</li></ol> <code>version</code> 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 <code>tag-prefix</code>\u00a0script parameter) exists at that commit, this is a version string which just the name of that tag, but with the <code>tag-prefix</code>\u00a0stripped from the name. Otherwise, this is a pseudo-version string with format <code>\"{tag}-{distance}-g{commit}\"</code>, where:<ul><li><code>{tag}</code>\u00a0is the name of the most recent ancestral tag (with a name starting with the prefix set by the <code>tag-prefix</code>\u00a0script parameter) reachable from the commit, but with the <code>tag-prefix</code>\u00a0stripped from the name.<li><code>{distance}</code>\u00a0distance (in number of commits) between the commit and the most recent ancestral tag.</li><li><code>{commit}</code>\u00a0consists of the first seven characters of the hash of the commit.</li>Example Values: <ol><li><code>\"v2024.0.0-alpha.1\"</code>\u00a0(so commit <code>2d6928e</code>\u00a0has Git tag <code>software/v2024.0.0-alpha.1</code>)</li><li><code>\"v2024.0.0-alpha.1-4-g4d8b882\"</code>\u00a0(so commit <code>4d8b882</code>\u00a0is 4 commits above the commit with Git tag <code>software/v2024.0.0-alpha.1</code>, which was the last tag in the ancestry of the commit)</li></ol>"},{"location":"reference/software/subsystems/installation/#distro-setup-scripts","title":"Distro setup scripts","text":"<p>Currently, the entrypoint of the distro setup scripts, at <code>software/distro/setup/setup.sh</code>, takes exactly one command-line argument which must be one of the following values:</p> <ul> <li> <p><code>adafruithat</code>: 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.</p> </li> <li> <p><code>planktoscopehat</code>: 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.</p> </li> </ul> <p>Currently, the distro setup scripts must be run by a user named <code>pi</code>. The scripts should not be run with <code>sudo</code>!</p> <p>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 <code>forklift</code>), we may consolidate these two phases into a single phase.</p>"},{"location":"reference/software/subsystems/installation/#base-system-setup","title":"Base system setup","text":"<p>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:</p> <ul> <li> <p>Installation of base tools: Docker, Cockpit, and various command-line tools are installed.</p> </li> <li> <p>Installation of <code>forklift</code> and a Forklift pallet: a hard-coded version of <code>forklift</code> is downloaded to <code>/usr/bin/forklift</code> , a hard-coded version of a hard-coded pallet (namely, github.com/PlanktoScope/pallet-standard) is downloaded and prepared for deployment, and the <code>forklift-apply.service</code> 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.)</p> </li> <li> <p>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.</p> </li> <li> <p>Configuration of the system locale: the system's language is changed to <code>en_US.UTF-8</code>, but the time and measurement formats are changed to <code>en_DK.UTF-8</code> so that the date format is <code>yyyy-mm-dd</code> and units are metric. The system timezone is set to UTC.</p> </li> <li> <p>Partial configuration of networking: various system services are installed and configured, namely <code>dhcpcd</code>, <code>dnsmasq</code>, <code>hostapd</code>, and <code>firewalld</code>. The <code>enable-interface-forwarding.service</code> and <code>autohotspot.service</code> systemd services are created and enabled. The Raspberry Pi's Wi-Fi country is set to the US.</p> </li> <li> <p>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.</p> </li> </ul>"},{"location":"reference/software/subsystems/installation/#planktoscope-application-environment-setup","title":"PlanktoScope application environment setup","text":"<p>This phase performs steps specific to the PlanktoScope's hardware:</p> <ul> <li> <p>Remaining configuration of networking: a hard-coded version of <code>machine-name</code> is downloaded to <code>/usr/bin/machine-name</code>, <code>avahi-utils</code> 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 <code>machine-name</code> 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, <code>pkscope.local</code> and <code>planktoscope.local</code>).</p> </li> <li> <p>Setup of the PlanktoScope hardware controller: various Python tools (<code>pip</code>, <code>venv</code>, and <code>poetry</code>) 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 <code>planktoscope-org.device-backend.controller-adafruithat.service</code> and <code>planktoscope-org.device-backend.controller-planktoscopehat.service</code> 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.)</p> </li> <li> <p>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.)</p> </li> <li> <p>Setup of the PlanktoScope Node-RED dashboard: Node-RED is installed, as well as a Python package required by the <code>adafruithat</code> 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, <code>npm</code> 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.)</p> </li> <li> <p>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.)</p> </li> <li> <p>Setup of hardware support for the PlanktoScope's GPS receiver: <code>gpsd</code> and <code>chrony</code> are installed and configured. (Note: currently the configurations may be incorrect.)</p> </li> <li> <p>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.)</p> </li> <li> <p>Cleanup: unnecessary APT and <code>pip</code> files are removed.</p> </li> </ul>"},{"location":"reference/software/subsystems/startup/","title":"Startup","text":"<p>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.</p>"},{"location":"reference/software/subsystems/startup/#services","title":"Services","text":"<p>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:</p>"},{"location":"reference/software/subsystems/startup/#software-deployment-execution","title":"Software deployment &amp; execution","text":"<p>In general:</p> <ul> <li> <p><code>dockerd</code> (managed by <code>docker.service</code>) can start before network connectivity has been established; this is not the default behavior for <code>dockerd</code>.</p> </li> <li> <p>All daemons &amp; 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.</p> </li> </ul> <p>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:</p> <ul> <li> <p><code>overlay-sysroot.service</code> runs after <code>-.mount</code> and <code>systemd-remount-fs.service</code>.</p> </li> <li> <p><code>bindro-run-forklift-stages-current.service</code> runs after <code>-mount</code> and <code>systemd-remount-fs.service</code> and before <code>overlay-fs.target</code>.</p> </li> <li> <p><code>overlay-usr.service</code> runs after <code>overlay-sysroot.service</code> and before <code>overlay-fs.target</code>.</p> </li> <li> <p><code>overlay-etc.service</code> runs after <code>overlay-sysroot.service</code> and  <code>systemd-machine-id-commit.service</code> , and before <code>systemd-sysctl.service</code> and <code>overlay-fs.target</code>.</p> </li> <li> <p><code>start-overlaid-units.service</code> runs after <code>overlay-fs.target</code> and <code>basic.target</code>.</p> </li> <li> <p><code>bind-.local-share-forklift-stages@home-pi.service</code> runs after <code>-.mount</code>, <code>home.mount</code>, and <code>basic.target</code>.</p> </li> <li> <p><code>forklift-apply.service</code>, which uses the <code>forklift</code> tool to start all Docker Compose applications, runs after <code>docker.service</code> has started. Docker Compose applications managed with <code>forklift</code> are sequenced by <code>forklift-apply.service</code> according to the resource dependency relationships declared by the Forklift packages which provide those applications.</p> </li> </ul>"},{"location":"reference/software/subsystems/startup/#networking","title":"Networking","text":"<p>For descriptions of the various targets (e.g. <code>sysinit.target</code>, <code>network-pre.target</code>) referred to below, see systemd's bootup process and systemd's special targets:</p> <ul> <li> <p><code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> runs before <code>sysinit.target</code>.</p> </li> <li> <p><code>update-hostname.service</code> runs after <code>generate-hostname-templated.service</code> and <code>systemd-hostnamed.service</code> but before <code>network-pre.target</code>.</p> </li> <li> <p><code>assemble-dnsmasq-config-templated.service</code> runs after <code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> but before <code>dnsmasq.service</code>.</p> </li> <li> <p><code>assemble-hosts-templated.service</code> and <code>assemble-hosts.service</code> run after <code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> but before <code>dnsmasq.service</code> and <code>network-pre.target</code>.</p> </li> <li> <p><code>enable-interface-forwarding.service</code> runs before <code>network-online.target</code>.</p> </li> <li> <p><code>assemble-hostapd-config-templated.service</code> and <code>assemble-hostapd-config.service</code> run after <code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> but before <code>hostapd.service</code>.</p> </li> <li> <p>The <code>hostapd</code> daemon is manually started and stopped by <code>autohotspot.service</code>.</p> </li> <li> <p><code>autohotspot.service</code> runs after <code>forklift-apply.service</code> and <code>enable-interface-forwarding.service</code> 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 <code>autohotspot.timer</code>.</p> </li> <li> <p><code>planktoscope-mdns-alias@pkscope.service</code> and <code>planktoscopemdns-alias@planktoscope.service</code> configure the Avahi daemon (provided by the Raspberry Pi OS) to also resolve mDNS names <code>pkscope.local</code> and <code>planktoscope.local</code>, 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.</p> </li> </ul>"},{"location":"reference/software/subsystems/startup/#user-interface","title":"User interface","text":"<ul> <li> <p><code>assemble-cockpit-config.service</code>, <code>assemble-cockpit-origins.service</code>, and <code>assemble-cockpit-origins-templated.service</code> update Cockpit's configuration file  from drop-in config file fragments in <code>/etc/cockpit/cockpit.conf.d</code>, <code>/etc/cockpit/origins.d</code>, and <code>/etc/cockpit/origins-templates.d</code>, respectively. They run after <code>generate-machine-name.service</code> and <code>generate-hostname-templated.service</code> and before <code>cockpit.service</code>.</p> </li> <li> <p><code>ensure-ssh-host-keys.service</code> regenerates the SSH server's host keys if the keys are missing, and runs before <code>ssh.service</code>.</p> </li> <li> <p>The PlanktoScope Node-RED dashboard (managed by <code>nodered.service</code>) starts after <code>planktoscope-org.update-machine-name.service</code> 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 <code>forklift</code>.)</p> </li> </ul>"},{"location":"reference/software/subsystems/startup/#planktoscope-specific-hardware-abstraction","title":"PlanktoScope-specific hardware abstraction","text":"<ul> <li>The PlanktoScope hardware controller (managed by <code>planktoscope-org.device-backend.controller-{adafruithat or planktoscopehat}.service</code>) starts after <code>forklift-apply.service</code> (which manages Mosquitto) and <code>nodered.service</code> 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 <code>forklift</code>.)</li> </ul>"},{"location":"setup/","title":"Setup","text":"<p>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:</p> <ul> <li>\"I have a product from FairScope\": you probably received either a fully-assembled Planktoscope or a PlanktoScope do-it-yourself assembly kit. For more information, see the FairScope product section of this page.</li> <li>\"I have a fully assembled PlanktoScope, and it was not assembled by FairScope\": you will need to ensure that you have the latest version of the PlanktoScope software installed on the PlanktoScope, and that the PlanktoScope hardware works. For more information, see the Fully-assembled PlanktoScope section of this page.</li> <li>\"I have a kit of hardware parts to assemble into a PlanktoScope, and it was not provided by FairScope\": you will need to assemble your PlanktoScope hardware and then set up the software on it. For more information, see the DIY kit section of this page.</li> <li>\"I don't have any of the hardware for the PlanktoScope\": you have several options for getting the PlanktoScope hardware. For more information, see the No hardware yet section of this page.</li> </ul>"},{"location":"setup/#fairscope-product","title":"FairScope product","text":"<p>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:</p> <ul> <li>If you purchased a fully-assembled PlanktoScope, it is ready for you to use! You should go to our operation guide to learn how to operate your PlanktoScope.</li> <li>If you purchased a do-it-yourself assembly kit from FairScope, you should go to our hardware setup guide to learn how to assemble your kit into a working PlanktoScope. The software will already have been set up for you, so after you finish setting up the hardware you can proceed to our operation guide to learn how to operate your PlanktoScope.</li> </ul>"},{"location":"setup/#fully-assembled-planktoscope","title":"Fully-assembled PlanktoScope","text":"<p>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:</p> <ul> <li>Depending on what software is pre-installed on your PlanktoScope, and how old the software is, our software setup guide may be useful to help you update the software. You should always ensure that you are running the most recent available version of the PlanktoScope software.</li> <li>Depending on what software configuration your PlanktoScope is running, our operation guide may be useful to help you operate your PlanktoScope.</li> </ul>"},{"location":"setup/#diy-kit","title":"DIY kit","text":"<p>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:</p> <ul> <li>Depending on what is included in your DIY kit, our hardware setup guide may be useful to assemble a PlanktoScope from your kit.</li> <li>Depending on what is on the micro-SD card included with your DIY kit (if it includes a micro-SD card), our software setup guide may be useful to help you update the software. You should always ensure that you are running the most recent available version of the PlanktoScope software.</li> <li>Depending on what software configuration your PlanktoScope is running, our operation guide may be useful to help you operate your PlanktoScope.</li> </ul>"},{"location":"setup/#no-hardware-yet","title":"No hardware yet","text":"<p>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:</p> <ol> <li>Purchase a fully pre-assembled PlanktoScope.</li> <li>Purchase a DIY kit of parts to assemble into a PlanktoScope.</li> <li>Both make your own kit of parts and assemble it into a PlanktoScope.</li> </ol>"},{"location":"setup/#buy-a-pre-assembled-planktoscope","title":"Buy a pre-assembled PlanktoScope","text":"<p>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.</p> <p>We recommend this approach for:</p> <ul> <li>Anyone who wants a PlanktoScope which \"just works\" out-of-the-box.</li> <li>Scientists who just want to collect data and don't want to become engineers.</li> <li>Anyone who just wants to use the PlanktoScope as a tool, rather than tinkering with their PlanktoScope as a project.</li> </ul>"},{"location":"setup/#buy-a-diy-kit","title":"Buy a DIY kit","text":"<p>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.</p> <p>We recommend this approach for:</p> <ul> <li>Anyone who wants a standard PlanktoScope but is on a limited budget, and has some interest in building things and troubleshooting problems.</li> <li>Anyone who wants to approach the PlanktoScope as a project and not just a tool, but who has a limited tolerance of technical complexity.</li> <li>Anyone who wants a do-it-yourself experience but does not have access to a laser cutter or CNC mill.</li> <li>Anyone who wants a standard set of parts as the foundation for customizing their PlanktoScope.</li> <li>Engineers and makers who don't want to worry about figuring out suppliers and making their own one-time supply chain in order to obtain all the hardware parts needed to build a single PlanktoScope.</li> </ul>"},{"location":"setup/#make-a-kit-and-assemble-it","title":"Make a kit and assemble it","text":"<p>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.</p> <p>We recommend this approach for:</p> <ul> <li>Anyone who is on an extremely limited budget but has lots of time and some hardware engineering experience.</li> <li>Makers who are already familiar with laser cutting or CNC milling, and with soldering or PCB assembly (the necessary skills will depend on the version of PlanktoScope hardware being built).</li> <li>Hobbyists and students who are primarily interested in the PlanktoScope as an engineering project and want to figure out everything by themselves.</li> <li>Anyone who wants to design and build an extremely non-standard PlanktoScope, whether for fun or to use it for unconventional purposes.</li> </ul>"},{"location":"setup/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"location":"setup/hardware/","title":"PlanktoScope Hardware","text":"<p>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.</p> <p>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.</p> <p>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.</p>"},{"location":"setup/hardware/#hardware-versions","title":"Hardware versions","text":"<p>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.</p>"},{"location":"setup/hardware/#hardware-v21","title":"Hardware v2.1","text":"<p>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.</p> <p>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.</p>"},{"location":"setup/hardware/#hardware-v25","title":"Hardware v2.5","text":"<p>This version includes many design improvements to solve various problems with the v2.1 hardware design, including:</p> <ul> <li> <p>Replacing the ibidi flowcell with a simpler glass capillary flowcell.</p> </li> <li> <p>Replacing the Adafruit Stepper Motor HAT with a HAT designed specifically for the PlanktoScope (the PlanktoScope HAT).</p> </li> <li> <p>Replacing the linear actuators for sample focusing with a more mechanically robust pair of linear actuators.</p> </li> <li> <p>Replacing the peristaltic pump with a more accurate pump which is commercially available.</p> </li> <li> <p>Making the Raspberry Pi's micro-SD card accessible without requiring disassembly of the PlanktoScope.</p> </li> </ul> <p>The mechanical structure of this design uses CNC-milled parts rather than laser-cut parts.</p> <p>Our documentation site provides manufacturing documentation to make assembly kits for this hardware version, and to assemble kits for this version into PlanktoScopes.</p>"},{"location":"setup/hardware/#choosing-a-version","title":"Choosing a version","text":"<p>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:</p> <ul> <li> <p>You do not have access to a CNC mill, or to a commercial fabrication service with a CNC mill.</p> </li> <li> <p>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.</p> </li> </ul>"},{"location":"setup/hardware/#building-a-planktoscope","title":"Building a PlanktoScope","text":"<p>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.</p> <p>Once you have figured out what hardware version of the PlanktoScope you will build, you can proceed to our version-specific hardware setup guides:</p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul>"},{"location":"setup/hardware/#next-steps","title":"Next steps","text":"<p>After making an assembly kit (if necessary) and building a PlanktoScope from your assembly kit, you should proceed to our software setup guide.</p>"},{"location":"setup/hardware/index-noguides/","title":"PlanktoScope Hardware","text":"<p>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.</p>"},{"location":"setup/hardware/v2.1/","title":"Hardware v2.1","text":"<p>This page will help you to build the v2.1 hardware for a PlanktoScope.</p>"},{"location":"setup/hardware/v2.1/#make-an-assembly-kit","title":"Make an assembly kit","text":"<p>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.</p> <p>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.</p>"},{"location":"setup/hardware/v2.1/#assemble-a-planktoscope-from-a-kit","title":"Assemble a PlanktoScope from a kit","text":"<p>Once you have an assembly kit, you will need to assemble it into a PlanktoScope.</p>"},{"location":"setup/hardware/v2.1/#next-steps","title":"Next steps","text":"<p>Once you have assembled your PlanktoScope, you can proceed to our operation guide\u00a0to learn how to operate your PlanktoScope.</p>"},{"location":"setup/hardware/v2.1/assembly/","title":"Assembly guide of the PlanktoScope","text":"<p>You can also use CAD renders and photos from the following links as a supplementary material for this assembly guide:</p> <ul> <li>CAD renders for the assembly guide</li> <li>Photos for the assembly guide</li> </ul> <p>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:</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-1-gather-everything-you-need","title":"Step 1: Gather everything you need","text":"<p>For the full list of all required tools and parts, please refer to the v2.1 hardware kit production guide.</p> <ul> <li>Laser cut structure</li> <li>M12 lenses</li> <li>Peristaltic pump and tubing</li> <li>Raspberry Pi, motor driver board, GPIO connectors</li> <li>Flashed SD card</li> <li>Stepper motors</li> <li>PiCam and flex cable</li> <li>GPIO ribbon connector, headers, HATs, LED</li> <li>DC Power terminal</li> <li>Magnets</li> <li>Super glue</li> <li>Standoffs (M2.5), M3 screws and nuts</li> </ul> <p>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.</p> <p>If you are not familiar with any process, such as soldering, tapping, or wiring, try and familiarize yourself with the topics first.</p> <p>Soldering deals with high heat and potentially toxic materials, so make sure to use the proper precautions.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-2-standoff-installation","title":"Step 2: Standoff installation","text":"<p>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.</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-3-motor-hat-preparation","title":"Step 3: Motor HAT preparation","text":"<p>Insert and solder the terminal blocks and headers onto the motor driver PCB. </p> <p></p> <p>Place the motor driver PCB on to the indicated standoffs.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-4-magnets-setup","title":"Step 4: Magnets setup","text":"<p>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.</p> <p></p> <p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-5-sample-stage-assembly","title":"Step 5: Sample stage assembly","text":"<p>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.</p> <p></p> <p>You should now have a sample stage and motor assembly that looks like this.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-6-lenses-tapping-and-mounting","title":"Step 6: Lenses tapping and mounting","text":"<p>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).</p> <p> </p> <p></p> <p>You can now screw the objective lens (the 25mm one) in part D. </p>"},{"location":"setup/hardware/v2.1/assembly/#step-7-camera-preparation","title":"Step 7: Camera preparation","text":"<p>You can now unscrew the lens from the Pi camera, being careful not to disturb the sensor below.  </p>"},{"location":"setup/hardware/v2.1/assembly/#step-8-camera-mount","title":"Step 8: Camera mount","text":"<p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-9-led-preparation","title":"Step 9: LED preparation","text":"<p>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.</p> <p>Warning</p> <p></p> <p>This picture shows the correct wiring for the LED. Please make sure the red wire is on the long pin of the LED.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-10-vertical-slices-assembly","title":"Step 10: Vertical slices assembly","text":"<p>You can now start placing the motor mount/LED assembly- B, </p> <p>C, </p> <p>D, </p> <p>E, </p> <p>F, </p> <p>and G into the base A.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-11-pump-setup","title":"Step 11: Pump setup","text":"<p>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. </p> <p>Fix the pump in place. </p>"},{"location":"setup/hardware/v2.1/assembly/#step-12-pump-mounting","title":"Step 12: Pump mounting","text":"<p>You can now mount the pump on base A. </p> <p>Your setup should look like this. Don't worry about the wiring, we'll have a look at it in the next step!</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-13-motor-hat-wiring","title":"Step 13: Motor HAT wiring","text":"<p>You will now want to wire the steppers and pump to the terminals on the motor driver board.</p> <p>Info</p> <p>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.</p> <p>You can find more information about stepper motors and how they work in this document.</p> <p>Tip</p> <p>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.</p> <p>Tip</p> <p>Make sure the wires are properly connected by pulling on them a little. They should not come loose.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-14-raspberry-pi-setup-and-installation","title":"Step 14: Raspberry Pi setup and installation","text":"<p>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.</p> <p></p> <p>Mount the Raspberry Pi containing the flashed SD card on the standoffs attached to the laser cut base A.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-15-standoffs","title":"Step 15: Standoffs","text":"<p>Add 8 standoffs (M2.5 15mm) to fix the motor driver board and the Raspberry Pi to the base. </p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-16-camera-flex-cable","title":"Step 16: Camera flex cable","text":"<p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-17-power-supply-wiring","title":"Step 17: Power supply wiring","text":"<p>The power wires can be wired into place on the motor driver board.</p> <p>Tip</p> <p>Make sure the wires are properly connected by pulling on them a little. They should not come loose.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-18-prepare-the-gps-hat","title":"Step 18: Prepare the GPS HAT","text":"<p>Tip</p> <p>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.</p> <p></p> <p>Insert the battery to power the GPS HAT and solder the terminal mounts in place.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-19-install-the-gps-hat","title":"Step 19: Install the GPS HAT","text":"<p>Mount the GPS HAT over the motor driver PCB using the standoffs attached to the laser cut base A.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-20-install-the-fan-hat","title":"Step 20: Install the Fan HAT","text":"<p>Place the cooling fan HAT above the Raspberry Pi by mounting it to the standoffs on base A.</p> <p>Warning</p> <p>Be careful to slide the camera flat cable in the slot in the HAT above the connector.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-21-secure-the-hats","title":"Step 21: Secure the HATS","text":"<p>Secure the cooling fan HAT and GPS HAT by tightening the 8 screws to the standoffs on base A</p>"},{"location":"setup/hardware/v2.1/assembly/#step-22-install-back-panel","title":"Step 22: Install back panel","text":"<p>Insert the laser cut border I into base A.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-23-gps-output-connector","title":"Step 23: GPS output connector","text":"<p>Insert the power and GPS connectors into side plate J.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-24-install-side-panel","title":"Step 24: Install side panel","text":"<p>Place the side plate J into the designated slots on the base. You can connect the GPS cable to its connector on the board.</p> <p>Warning</p> <p>The GPS connector is quite fragile, make sure to align it properly before inserting it.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-25-install-the-other-side-panel","title":"Step 25: Install the other side panel","text":"<p>Mount the side plate K on base A using the assigned slots.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-26-secure-the-sides-together","title":"Step 26: Secure the sides together","text":"<p>Secure the laser cut sides with the screws and nuts.</p>"},{"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":"<p>Secure the laser cut sides to the base plate A with the screws and nuts.</p> <p>Warning</p> <p>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.</p>"},{"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":"<p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#step-29-assemble-the-gpio-ribbon-cable","title":"Step 29: Assemble the GPIO ribbon cable","text":"<p>If you didn't get an already assembled ribbon cable, you need to build it yourself.</p> <p>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.</p> <p>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.</p> <p>Warning</p> <p>Once assembled, the ribbon should NOT look like this: </p> <p>It should rather look like this: </p>"},{"location":"setup/hardware/v2.1/assembly/#step-30-insert-the-ribbon-cable","title":"Step 30: Insert the ribbon cable","text":"<p>Attach the GPIO ribbon to connect the cooling fan HAT to the GPS HAT.</p> <p>Tip</p> <p>You can try to route the flat ribbon from the camera under the ribbon cable you are connecting now. </p>"},{"location":"setup/hardware/v2.1/assembly/#step-31-fluidic-assembly","title":"Step 31: Fluidic assembly","text":"<p>Feed in the tubing from syringe 1 to form the fluidic path as shown.</p> <p></p> <p>Feed in the tubing from syringe 2 to form the fluidic path as shown</p> <p></p> <p>Feed in a length of tubing as shown through motor mount H and illumination mount FE</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-32-close-your-planktoscope","title":"Step 32: Close your PlanktoScope","text":"<p>Warning</p> <p>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.</p> <p></p> <p>Place the top L into the slots on the PlanktoScope body. Secure it in place with screws and nuts.</p> <p></p>"},{"location":"setup/hardware/v2.1/assembly/#step-33-enjoy","title":"Step 33: Enjoy!","text":"<p>Congratulations on a job well done. You can have some rest, get a tea and some biscuits!</p> <p></p> <p>Warning</p> <p>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.</p>"},{"location":"setup/hardware/v2.1/assembly/#next-steps","title":"Next steps","text":"<p>Once your PlanktoScope fully works, you can proceed to our operation guide\u00a0to learn how to operate your PlanktoScope.</p>"},{"location":"setup/hardware/v2.1/kit/","title":"Kit Production","text":""},{"location":"setup/hardware/v2.1/kit/#required-tools","title":"Required Tools","text":"<p>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.</p>"},{"location":"setup/hardware/v2.1/kit/#soldering-station","title":"Soldering Station","text":"<p> A soldering station with flux, or flux core solder, is necessary for making a few electrical connections. Purchase here.</p>"},{"location":"setup/hardware/v2.1/kit/#tap-wrench","title":"Tap Wrench","text":"<p> Any tap wrench compatible with the M12x0.5 tap will work. Purchase here.</p>"},{"location":"setup/hardware/v2.1/kit/#m12-x-05-tap","title":"M12 x 0.5 Tap","text":"<p> An M12x0.5 tap is required to secure the objective and tube lenses. Purchase here.</p>"},{"location":"setup/hardware/v2.1/kit/#screwdriver-kit","title":"Screwdriver Kit","text":"<p> A screwdriver kit with multiple drivers simplifies many assembly operations. Purchase here.</p>"},{"location":"setup/hardware/v2.1/kit/#required-components","title":"Required Components","text":"<p>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.</p>"},{"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 &amp; 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":"<p>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.</p>"},{"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":"<p>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:</p> <ul> <li>5 mm thickness: SVG file (recommended), DXF file</li> <li>1/4 inch thickness: DXF file</li> </ul> <p>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:</p> <p></p> <p>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.</p>"},{"location":"setup/hardware/v2.5/","title":"Hardware v2.5","text":"<p>This page will help you to build the v2.5 hardware for a PlanktoScope.</p>"},{"location":"setup/hardware/v2.5/#make-an-assembly-kit","title":"Make an assembly kit","text":"<p>If you do not already have an assembly kit, you will need to make a kit for yourself.</p>"},{"location":"setup/hardware/v2.5/#assemble-a-planktoscope-from-a-kit","title":"Assemble a PlanktoScope from a kit","text":"<p>Once you have an assembly kit, you will need to assemble it into a PlanktoScope.</p>"},{"location":"setup/hardware/v2.5/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"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":"<p>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.</p> <p></p> Bag Content A Scews B Tools C Adhesive Pads D Tubing, Glass Cuvettes E Bubbler Pump F Peristaltic Pump G Linear Stepper Motor H Raspberry PI Chip cooler I Raspberry HAT J Camera Lens K MicroSD Card, DC Power Jack Socket L DC Power Supply and Cable M Syringe and Falcon Tube X1 Raspberry PI 4 X2 Pipet X3 Cable ties X4 Raspberry PI HQ Camera Modul X5 Sandpaper <p>If any bags are missing, please go back to the BOM (Bill of Materials) and reorder the required components.</p>"},{"location":"setup/hardware/v2.5/assembly/#about-this-document","title":"About this document","text":"<p>To read this document, follow these guidelines:</p>"},{"location":"setup/hardware/v2.5/assembly/#color-codes","title":"Color codes","text":"<ul> <li>\ud83d\udd34\u00a0Look to the color red</li> <li>\ud83d\udfe0\u00a0Look to the color orange</li> <li>\ud83d\udfe1\u00a0Look to the color yellow</li> <li>\ud83d\udfe2\u00a0Look to the color green</li> <li>\ud83d\udd35\u00a0Look to the color blue</li> <li>\ud83d\udfe3\u00a0Look to the color purple</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#icons","title":"Icons","text":"<ul> <li>\ud83d\udc41\u00a0Pay attention to this</li> <li>\u26a0\u00a0Be careful with this</li> <li>\ud83d\udcdc\u00a0The book says</li> <li>\ud83c\udfac\u00a0Action !</li> <li>\u274c\u00a0Don't focus on that location</li> </ul> <p>As you read through the document, be sure to pay attention to these visual cues to guide you through the build process.</p>"},{"location":"setup/hardware/v2.5/assembly/#requirements","title":"Requirements","text":""},{"location":"setup/hardware/v2.5/assembly/#tools","title":"Tools","text":"<p>Content of\u00a0Bag B:</p> <ul> <li>\ud83d\udd34\u00a0B1. Small flat screwdriver 2mm</li> <li>\ud83d\udfe0\u00a0B2. Razor blade</li> <li>\ud83d\udfe1\u00a0B3. Allen key 2mm</li> <li>\ud83d\udfe2 B4. Wrenches for standoffs</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#components","title":"Components","text":"<p>Content of\u00a0Bag A:</p> <ul> <li>\ud83d\udfe2\u00a0A1. Standoff M2.5 - 6mm - Brass</li> <li>\ud83d\udd35\u00a0A2. Standoff M2.5 - 15mm - \u00a0Brass</li> <li>\ud83d\udfe3\u00a0A3. Standoff M2.5 - 16mm - SS</li> <li>\ud83d\udfe0\u00a0A4. Screw M2.5x5mm CHC - SS</li> <li>\ud83d\udfe1\u00a0A5. Screw M2.5x10mm CHC - SS</li> <li>\ud83d\udd34\u00a0A6. Screw M3x12mm BHC - SS</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#chapter-1-detach-the-parts-from-panels-by-cutting-the-tabs","title":"Chapter 1: Detach the Parts from panels by cutting the tabs","text":"<p> \ud83d\udc41 Locate the panel S1 and discover the 5 differents Parts F, P, K, J and I.</p> <p> \ud83c\udfac Flip your panel S1.</p> <p> \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.</p> <p> Gather all the necessary tools. You will need the B2 \ud83d\udfe0 Razor blade to cut the tabs.</p> <p></p> <ul> <li>\ud83d\udfe3 Use the razor blade to cut the outer tabs located on the edges of the different Parts</li> <li>\u274c Do not cut the inner tabs present inside the different Parts for now and focus on the outer tabs attaching the Parts to the main panel.</li> </ul> <p></p> <ul> <li>Position your razor blade on the tab as close to the piece as possible to avoid residual tab after cutting.</li> <li>Press firmly on the razor blade, being very careful with your finger, to cut your first tab.</li> <li>Make sure you don't damage your table by placing a flat, rigid support under the S1 panel.</li> <li>Keep going with the other tabs of this piece F.</li> </ul> <p>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.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <p>Once you have removed your Part from the main panel by cutting off all the tabs holding it, inspect it for potential residual tabs.</p> <ul> <li>\ud83d\udfe3 Here is a residual tab that will need to be removed.</li> <li>\ud83d\udfe0 Here there is no residual tab which is perfect.</li> </ul> <p></p> <p>\ud83d\udfe3 Place your razor blade flat on the edge of your piece being very careful with your fingers and cut the residual tab.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <p>Repeat the cutting of the tabs on all the Parts F, P, K, J and I present on the panel S1.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <p>\ud83d\udd34 Locate the inner tabs on the edges of the different Parts.</p> <p></p> <p>Cut out the tabs inside of all the Parts F, P, K, J and I detached from the panel S1.</p> <p>Dispose of the cut tabs and any other debris that may have been created during the detachment process.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <ul> <li>\u2705 Good way of cutting inner tabs</li> <li>\u274c Wrong way of cutting inner tabs</li> </ul> <p></p> <p>Repeat the process on the panel S2.</p> <p>Warning</p> <p>Be extremely careful because this is very sharp.</p> <p></p> <p>Discover the 11 differents Parts.</p> <p></p> <p>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.</p>"},{"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":"<p> To secure the PlanktoScope on slippery grounds using the adhesive pads, follow these steps. Gather all the necessary materials. You will need:</p> <ul> <li>Time: 1 min</li> <li>\ud83d\udc41 and Take the Part I</li> <li>\ud83d\udfe0 Take the four adhesive pads present in the bag A.</li> <li>\ud83d\udfe3 Locate the four pockets that will receive the four adhesive pads.</li> </ul> <p></p> <ul> <li>Clean the bottom of the case part I. Make sure the surface is free of dirt, debris, and any other substances that may prevent the adhesive pads from sticking properly.</li> <li>Remove the paper and place the four adhesive pads in the pockets by pressing firmly on them, sticky-side down.</li> <li>Test the stability of the PlanktoScope by gently shaking or tilting it. If it feels secure and does not slip or slide, the adhesive pads have been successfully installed.</li> </ul> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"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":"<p>Now it's time to assemble the ground plate for the Raspberry Pi as the PlanktoScope main processing unit.</p> <ul> <li>Time: 5 min</li> </ul> <p></p> <ul> <li>\ud83d\udc41 Grab the Part A.</li> <li>\ud83d\udfe3 Locate the four holes on Part A.</li> </ul> <p></p> <p>\ud83d\udfe2 A1. Standoff M2.5 - 6mm- Brass</p> <p></p> <p>\ud83d\udfe2 B4. Wrenches for standoffs</p> <p></p> <ul> <li>\ud83d\udfe3 Place the Standoff M2.5 - 6mm in the small side of the wrenches for   standoffs B4.</li> <li>\ud83d\udfe0 Do not use the big side of the wrenches for standoffs since the standoff will be loose in it.</li> </ul> <p></p> <ul> <li>Place the standoff in the hole and start rotating by hand in a clockwise direction until secure.</li> <li>Then tighten with the wrench.</li> </ul> <p></p> <ul> <li>\u2705 Make sure to screw until the standoff is properly inserted in the hole.</li> <li>\u274c Do not stop screwing before.</li> </ul> <p></p> <p>Keep going for each of the four holes.</p>"},{"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":"<ul> <li>Time: 2 min</li> </ul> <p>Locate the Raspberry Pi 4 Model B packaging.</p> <p>Warning</p> <p>Be careful removing it from its packaging.</p> <p></p> <p>Place the four Heat Sinks next to your Raspberry Pi and mark the locations of the Heat Sinks on the Raspberry Pi.</p> <ul> <li>\ud83d\udfe0 &amp; \ud83d\udd35 Small Heat Sinks</li> <li>\ud83d\udfe2 Medium Heat Sink</li> <li>\ud83d\udfe3 Big Heat Sink</li> </ul> <p></p> <p>Remove the protective labels under a Heat Sink and place the Heat Sink on the slot of the Raspberry Pi.</p> <p></p> <p>Remove the protective labels under all the Heat Sinks and place all the Heat Sinks on the slots of the Raspberry Pi.</p>"},{"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":"<ul> <li>Locate the SD card adapter in the bag K.</li> <li>The micro SD card is inserted in the SD card adapter.</li> <li>\ud83d\udfe3 Remove the micro SD card from the SD card adapter.</li> </ul> <ul> <li>Flip your Raspberry Pi.</li> <li>\ud83d\udfe0 Locate the micro SD port.</li> <li>\ud83d\udfe3 Insert the micro SD card in the Raspberry Pi.</li> </ul> <p>Push the micro SD card in the Raspberry Pi port to a point of resistance.</p> <p>Note</p> <p>If you notice that the micro SD card protrudes about 2mm from its slot, this is normal.</p>"},{"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":"<ul> <li>Time: 1 min</li> </ul> <ul> <li>\u2705 Make sure to position the Raspberry Pi properly on the four standoffs screwed on the Part A.</li> <li>\u274c Do not invert the position of the Raspberry Pi on the four standoffs screwed on the Part A.</li> </ul> <p>\ud83d\udfe3 A3. Standoff M2.5 - 16mm - SS</p> <p></p> <p>Screw by hand a Standoff M2.5 - 16mm on the Raspberry Pi.</p> <p></p> <ul> <li>Screw by hand all Standoffs M2.5 - 16mm on the Raspberry Pi.</li> <li>Make sure you insert all four standoffs by hand and tighten slightly.</li> </ul> <p></p> <p>\ud83d\udfe2 B4. Wrenches for standoffs</p> <p></p> <ul> <li>\ud83d\udfe0 Secure the Standoff M2.5 - 16 mm - SS A3 in the big side of the wrenches for standoffs B4.</li> <li>\ud83d\udfe3 Do not use the small side of the wrenches for standoffs since the standoff won\u2019t fit in it.</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#chapter-7-attach-the-ribbon-cable-to-the-raspberry-pi","title":"Chapter 7: Attach the Ribbon Cable to the Raspberry Pi","text":"<ul> <li>Time: 2 min</li> </ul> <p>Locate the Raspberry Pi Camera HQ packaging.</p> <p>Warning</p> <p>Be careful removing it from its packaging.</p> <p></p> <p>Lay your Raspberry Pi Camera face down on a suitable surface.</p> <p>\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.</p> <p>Warning</p> <p>Be careful with this, this part is delicate. Lift the black connector gently</p> <p></p> <p>Once the connector has been disengaged from the Raspberry Pi camera board, the cable will simply slide out!</p> <ul> <li>\ud83d\udfe3 Put aside Camera the Raspberry Pi</li> <li>\ud83d\udfe2 Keep the Ribbon Cable for next step.</li> </ul> <p></p> <p>\ud83d\udd34 Locate the black connector present on the Raspberry Pi.</p> <p></p> <p>\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.</p> <p>Warning</p> <p>Be careful, this part is delicate. Gently prise the black connector with nail or fingertip and thumb.</p> <p></p> <p>Insert the Ribbon Cable you just detached from the Raspberry Pi Camera in the Raspberry Pi.</p> <ul> <li>Make sure to insert in as much as you can.</li> <li>Blue rectangle on Ribbon Cable should face the same direction as the arrow below.</li> </ul> <p></p> <p>\ud83d\udd34 Secure the Ribbon Cable in the Raspberry Pi by pressing firmly on the black connector.</p>"},{"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":"<ul> <li>Time: 2 min</li> </ul> <p>Locate the PlanktoScope HAT present in bag I.</p> <p></p> <p>\ud83d\udd34 Thread the Ribbon cable through the PlanktoScope HAT slot from the underside.</p> <p>Warning</p> <p>Make sure the two \ud83d\udfe3 black connectors are aligned before threading through the ribbon.</p> <p></p> <p>\ud83d\udd34 Plug the PlanktoScope HAT into the Raspberry Pi.</p> <p>Warning</p> <p>Make sure the two black connectors are aligned before attaching them together.</p> <p></p> <p>Press the PlanktoScope HAT against the Raspberry Pi until it is no longer possible to move them closer together.</p> <p>Warning</p> <p>Continue to feed through the Ribbon Cable and do not crush it while pressing the PlanktoScope HAT against the standoffs.</p> <p></p> <p>\ud83d\udfe0 A4. Screw M2.5X5mm CHC - SS</p> <p></p> <p>\ud83d\udfe3 Locate the 4 holes on the top of the PlanktoScope HAT and insert the four M2.5X5mm</p> <p></p> <p>\ud83d\udfe1 B3. Allen key 2mm</p> <p></p> <p>Screw the four A4 screws through the PlanktoScope HAT onto the Standoff M2.5 - 16mm.</p> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"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":"<ul> <li>Time: 2 min</li> <li>Locate the DC Power Jack from the Bag K.</li> <li>Remove the Lock Ring from the DC Power Jack</li> </ul> <ul> <li>\ud83d\udd34 Lay the Part M down and make sure the pockets in these holes are facing upwards.</li> <li>\ud83d\udfe3 Locate the Power Socket hole on Part M.</li> </ul> <p>\ud83d\udd34 Insert the cable inside of the hole by being sure of the orientation of the Part M.</p> <p></p> <p>\ud83d\udfe3 Flip the Part M and secure the DC Power Jack by hand on the Part M by screwing the Lock Ring.</p> <p>Warning</p> <p>Make sure the Lock Ring doesn\u2019t spin on itself.</p> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"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":"<ul> <li>Time: 2 min</li> </ul> <p>\ud83d\udfe3 Locate the 4 holes on the top of the Part B.</p> <p></p> <p>\ud83d\udd35 A2. Standoff M2.5 - 15mm - Brass</p> <p></p> <p>Insert the four Standoff M2.5 - 15mm.</p> <p></p> <p>The result should be similar to the picture.</p> <p></p> <p>\ud83d\udfe2 B4. Wrenches for standoffs</p> <p></p> <p>Using the small side of the Standoff Wrench, secure the 4 M2.5 - 15mm Standoffs</p> <p></p> <ul> <li>\u2705 Make sure to screw until the Standoff is properly tightened into the hole.</li> <li>\u274c Do not stop screwing before.</li> </ul> <p></p> <p>Locate the Raspberry Pi Camera HQ</p> <p></p> <p>Remove the lens cap Raspberry Pi Camera HQ.</p> <p></p> <p>Warning</p> <p>Make sure your camera lens is clean. If it is not, gently wipe using cotton swab for this task.</p> <p></p> <p>Place the Raspberry Pi Camera HQ on top of the four Standoffs installed on Part B.</p> <p>\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</p> <p></p> <p>\ud83d\udfe0 A4. Screw M2.5X5mm CHC - SS</p> <p></p> <p>\ud83d\udfe1 B3. Allen key 2mm</p> <p></p> <p>Use the allen key and tighten the Raspberry Pi Camera to the Standoffs.</p> <p></p> <p>The result should be similar to the picture.</p> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"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":"<p>Locate the Stepper Motors</p> <p>Warning</p> <p>Avoid touching the metal rods on the Stepper Motors</p> <p>Info</p> <p>You can touch the \ud83d\udfe3 gold stands</p> <p></p> <p></p> <p>\ud83d\udfe1 A5. Screw M2.5X10mm CHC - SS</p> <p></p> <p>\ud83d\udfe1 B3. Allen key 2mm</p> <p></p> <ul> <li>\ud83d\udd34 Lay the Part E down and make sure the pockets in these holes are   facing upwards.</li> <li>\ud83d\udfe3 Locate the four holes on Part E and place four M2 Screws in the holes.</li> </ul> <p></p> <p>Attach the stepper motors to the screws we have just placed with the \ud83d\udd34 pockets positioned on opposite to the cabling.</p> <p>The result should be similar to the picture.</p> <p></p> <p>Use the 2mm allen key to fix the Stepper Motors.</p> <p>The result should be similar to that picture.</p> <p></p> <p>The result should be similar to the picture.</p> <p></p> <p>Repeat the process on the other side with the other Stepper Motor.</p> <p></p> <p>Repeat the process on the other side with the other Stepper Motor.</p> <p></p> <p>The result should be similar to the picture.</p> <p>Note</p> <p>\ud83c\udfac Store this assembly for later.</p>"},{"location":"setup/hardware/v2.5/assembly/#chapter-12-mount-the-led-on-part-g","title":"Chapter 12: Mount the\u00a0LED\u00a0on\u00a0Part G","text":"<ul> <li>Locate the\u00a0LED\u00a0and\u00a0LED cable\u00a0in Bag K.</li> <li>\ud83d\udfe3\u00a0The LED will go on the end where\u00a0the white plastic connector is\u00a0smallest.</li> </ul> <p>Insert the\u00a0LED into the LED cable.</p> <p></p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p></p> <p>Locate part\u00a0G.</p> <p></p> <p>\ud83d\udfe3\u00a0Locate the LED hole on\u00a0Part G.</p> <p></p> <p>We\u00a0will\u00a0now\u00a0place\u00a0the\u00a0LED\u00a0into\u00a0the\u00a0slot\u00a0on part\u00a0G.</p> <p></p> <p>Warning</p> <p>Gently push the LED into the LED\u00a0hole located on Part\u00a0G. It should be a snug fit.</p> <p></p> <p>The result should be similar to the\u00a0picture.</p> <p>Info</p> <p>\ud83c\udfac\u00a0Store this assembly for later.</p>"},{"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":"<ul> <li>Locate the\u00a0Kamoer Peristaltic pump\u00a0from the\u00a0Bag F.</li> <li>\ud83d\udfe3\u00a0Put aside the\u00a0tubing contained in\u00a0the little bag.</li> </ul> <p>\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.</p> <p>Warning</p> <p>\ud83d\udc41 Ensure the correct orientation of\u00a0Part O\u00a0and the\u00a0Peristaltic Pump</p> <p></p> <p>\ud83d\udfe1\u00a0A5. Screw\u00a0M2.5X10mm\u00a0CHC - SS</p> <p></p> <p>\ud83d\udfe1\u00a0B3. Allen key 2mm B3</p> <p></p> <p>\ud83d\udfe2\u00a0Insert the two\u00a0M2.5X10mm\u00a0in the\u00a0two holes.</p> <p></p> <p>Screw the two\u00a0M2.5X10mm\u00a0into the\u00a0two holes.</p> <p></p> <p></p> <p>\ud83d\udd34\u00a0Lay\u00a0the\u00a0Part\u00a0L\u00a0down and make\u00a0sure the pockets in these holes are\u00a0facing upwards.</p> <p></p> <ul> <li>Place\u00a0the\u00a0Peristaltic Pump underneath part L, ensuring the\u00a0correct orientation of these two parts.</li> <li>\ud83d\udd34 Insert the Peristaltic Pump into\u00a0the allocated slot in\u00a0Part L.</li> </ul> <p></p> <p>Insert the\u00a0Peristaltic Pump\u00a0into the\u00a0allocated slot in\u00a0Part L.</p> <p></p> <p>Insert the\u00a0Peristaltic Pump\u00a0into the\u00a0allocated slot in\u00a0Part L.</p> <p></p> <ul> <li>Lay the assembly down.</li> <li>\ud83d\udd34\u00a0Locate the\u00a0four different holes.</li> </ul> <p></p> <p>\ud83d\udfe1\u00a0A5.Screw\u00a0M2.5X10mm\u00a0CHC - SS</p> <p></p> <p>\ud83d\udfe1\u00a0B3.Allen key 2mm</p> <p></p> <p>Screw the four M2.5X10mm in the\u00a0located\u00a0holes\u00a0attaching\u00a0the\u00a0Part\u00a0O\u00a0to\u00a0the\u00a0Part L Peristaltic Pump.</p> <p> The result should be similar to the\u00a0picture.</p> <p>Info</p> <p>We will use this part in the next step.</p>"},{"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":"<ul> <li>Locate the LED and housing, along\u00a0with the pump and housing.</li> <li>\ud83d\udfe3\u00a0Locate the\u00a0spiral wrap\u00a0from\u00a0bag K.</li> </ul> <ul> <li>Spiral wrap both sets of cables\u00a0together.</li> <li>There should be 4 cm (1.5 inches)\u00a0between\u00a0the\u00a0connectors\u00a0and\u00a0the\u00a0start\u00a0of the spiral wrap.</li> </ul> <p>Continue wrapping around the\u00a0cables until you have used all of the\u00a0spiral wrap, leaving small or no gaps.</p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p>Note</p> <p>\ud83c\udfac\u00a0Store this assembly for later.</p>"},{"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":"<p>Locate the Stepper Motors with\u00a0mount, and the Raspberry Pi\u00a0Camera.</p> <p> Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.</p> <p>Warning</p> <p>Make sure the orientation is\u00a0correct and matches the picture.</p> <p> Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.</p> <p>Warning</p> <p>Make sure the orientation is\u00a0correct and matches the picture.</p> <p>Then\u00a0insert\u00a0the\u00a0cylindrical\u00a0parts\u00a0of\u00a0the\u00a0Stepper Motor into the slots.</p> <p></p> <p>Feed the Stepper Motor cables into\u00a0the\u00a0slots\u00a0either\u00a0side\u00a0of\u00a0the\u00a0Raspberry\u00a0Pi Camera.</p> <p>Warning</p> <p>Make sure the orientation is\u00a0correct and matches the picture.</p> <p>Then\u00a0insert\u00a0the\u00a0cylindrical\u00a0parts\u00a0of\u00a0the\u00a0Stepper Motor into the slots.</p> <p>Note</p> <p>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</p>"},{"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":"<ul> <li>We will need the\u00a0Raspberry Pi HAT with housing and Ribbon Cable along\u00a0\\   with the\u00a0Raspberry Pi Camera with\u00a0Stepper Motors and housing.</li> <li>We will be connecting the\u00a0\ud83d\udfe2Ribbon\u00a0Cableto the\u00a0\ud83d\udfe1black\u00a0Raspberry Pi Camera\u00a0connector\u00a0that we removed\u00a0it from earlier.</li> </ul> <p>Gently feed the\u00a0Ribbon Cable\u00a0into the\u00a0port of the\u00a0Camera.</p> <p>Warning</p> <p>\ud83d\udc41 Ensure the correct orientation of\u00a0the\u00a0Ribbon Cable\u00a0with the blue end\u00a0facing upwards.</p> <p> \ud83d\udd34\u00a0Press down on the black\u00a0connector on the Raspberry Pi\u00a0camera board once the Ribbon\u00a0Cable is in position.</p> <p> \ud83d\udd34\u00a0B1.Small flat screwdriver 2mm</p> <p></p> <ul> <li>Now we will plug in the\u00a0Stepper\u00a0Mounts to the\u00a0HAT.</li> <li>\ud83d\udd34The cables for the\u00a0Stepper Mounts\u00a0will be plugged into the\u00a0HAT\u00a0\ud83d\udfe3here.</li> </ul> <p>Warning</p> <p>Hold tight, a specific order is\u00a0required.</p> <p></p> <p>Starting with the\u00a0red cable, insert the\u00a0cable in the far left port and tighten\u00a0the screw situated above the port.</p> <p>Note</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>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.</p>"},{"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":"<p>We will now be connecting the LED\u00a0and Peristaltic Pump with the\u00a0Raspberry Pi HAT\u00a0and\u00a0Camera.</p> <p></p> <p>Place the LED housing onto the\u00a0Stepper Mounts.</p> <p>Warning</p> <p>\ud83d\udc41 Ensure correct orientation of both\u00a0\ud83d\udfe3 parts by looking at the\u00a0precut holes.</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>Now we will plug in the\u00a0LED and\u00a0Stepper Mount\u00a0cables to the\u00a0Raspberry Pi.</p> <p></p> <p>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.</p> <p></p> <p>We will now plug the cables into the\u00a0correct ports.</p> <p></p> <p>\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.</p> <p></p> <p>\ud83d\udd34 The two wires (LED) enter on the\u00a0port on top of the Raspberry Pi HAT.</p> <p></p> <p>The result should be similar to the\u00a0picture.</p> <p>Note</p> <p>We will use this assembly in the next\u00a0step.</p>"},{"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":"<ul> <li>\ud83d\udfe2\u00a0Locate the\u00a0DC Power Jack</li> <li>We will plug the DC Power Jack\u00a0into the Raspberry Pi via the \ud83d\udd35 blue port.</li> </ul> <p>\ud83d\udd34\u00a0B1.Small flat screwdriver 2mm</p> <p></p> <ul> <li>Insert the \ud83d\udd34 red cable of the DC\u00a0Power Jack into the left side of the\u00a0blue port.</li> <li>Tighten the screw above.</li> </ul> <p></p> <ul> <li>Insert the \u26ab black cable of the DC\u00a0Power\u00a0Jack\u00a0into\u00a0the\u00a0right\u00a0side\u00a0of\u00a0the\u00a0blue port.</li> <li>Tighten the screw above.</li> </ul> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p>Note</p> <p>We will use this assembly in the next\u00a0step.</p>"},{"location":"setup/hardware/v2.5/assembly/#chapter-19-your-planktoscope-starts-to-take-shape","title":"Chapter 19: Your PlanktoScope starts to take shape","text":"<p>Locate Part I\u00a0and\u00a0Part H.</p> <p></p> <ul> <li>Slot\u00a0Part H\u00a0into\u00a0Part I.</li> <li>\ud83d\udfe3\u00a0Note the orientation.\u00a0Part H\u00a0goes\u00a0into\u00a0Part Iat the end with the\u00a0rectangular slot (as opposed to the\u00a0rectangle with bulbous hole).</li> <li>\ud83d\udfe1\u00a0Also, the deeper slots on\u00a0part H\u00a0should be on the upper side.</li> </ul> <p></p> <p>\ud83d\udd34 Slot the\u00a0Peristaltic Pump\u00a0above\u00a0the\u00a0LED.</p> <p></p> <p>Note</p> <p>The result should be the same as the\u00a0picture.</p> <p></p> <p>Warning</p> <p>\ud83d\udc41 Ensure the correct orientation of\u00a0the housing and the\u00a0Peristaltic Pump.</p> <p></p> <p>At the other end, slot the\u00a0DC Power\u00a0Jack\u00a0housing adjacent to the\u00a0Raspberry Pi.</p> <p> </p> <p>Rotate so that the DC Power Jack is\u00a0facing upwards. We will now slot the Raspberry Pi onto\u00a0the rest of the housing.</p> <p></p> <p>Info</p> <p>The result should be similar to that\u00a0picture.</p> <p>Note</p> <p>\ud83c\udfac\u00a0Store this assembly for later.</p>"},{"location":"setup/hardware/v2.5/assembly/#chapter-20-inserting-screws","title":"Chapter 20: Inserting screws","text":"<p>\ud83d\udfe3 We\u00a0will\u00a0now\u00a0insert\u00a0eight\u00a0M3\u00a0screws\u00a0to fasten the housing together.</p> <p>Note</p> <p>\ud83c\udfac\u00a0Store this assembly for later.</p> <p></p> <p>\ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS</p> <p></p> <p>\ud83d\udfe1\u00a0B3. Allen key 2mm</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>We will now turn over the\u00a0PlanktoScope\u00a0and\u00a0repeat\u00a0the\u00a0process\u00a0for the underside.</p> <p></p> <p>\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0underside.</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>Now turn the PlanktoScope on its side.</p> <p></p> <p></p> <p>Warning</p> <p>\ud83d\udc41 Ensure the orientation of your\u00a0PlanktoScope and\u00a0Part K\u00a0matches\u00a0the picture.</p> <p></p> <p>Slot\u00a0Part K\u00a0onto the rest of the\u00a0PlanktoScope.</p> <p>Warning</p> <p>\ud83d\udfe2\u00a0Ensure the correct orientation. The\u00a0result should look the same at the\u00a0picture.</p> <p></p> <p>Content of\u00a0Bag A: \ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS</p> <p></p> <p>Content of\u00a0Bag B: \ud83d\udfe1\u00a0B3. Allen key 2mm</p> <p></p> <p>\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0side to hold\u00a0Part K\u00a0in place.</p> <p></p> <p></p> <p>We will now place\u00a0Part J\u00a0into position\u00a0as the housing for the side.</p> <p>Warning</p> <p>\ud83d\udc41 Ensure your PlanktoScope matches\u00a0the orientation in the picture.</p> <p></p> <p>\ud83d\udfe2 Place\u00a0Part K\u00a0onto the rest of the\u00a0PlanktoScope and note the position\u00a0of the cutout.</p> <p></p> <p>Content of\u00a0Bag A: \ud83d\udd34\u00a0A6. Screw M3X12mm BHC - SS</p> <p></p> <p>Content of\u00a0Bag B: \ud83d\udfe1\u00a0B3. Allen key 2mm</p> <p></p> <p>\ud83d\udfe3\u00a0Insert eight more M3 screws on the\u00a0underside</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p></p> <p>Content of\u00a0Bag A: \ud83d\udfe1\u00a0A5. Screw M2.5X10mm CHC - SS</p> <p></p> <p>Place\u00a0the\u00a0M2.5\u00a0screw\u00a0through\u00a0Part\u00a0N. It\u00a0will\u00a0act\u00a0as\u00a0a\u00a0cover\u00a0for\u00a0the\u00a0electrical\u00a0inputs.</p> <p></p> <ul> <li>Place the\u00a0cover\u00a0over the electrical\u00a0inputs on the PlanktoScope.</li> <li>\ud83d\udfe3 The screw will enter the hole\u00a0located here.</li> </ul> <p></p> <p>Using the allen key, tighten the screw\u00a0so that it is possible to move the\u00a0cover with light force.</p> <p></p> <p>Info</p> <p>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</p>"},{"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":"<ul> <li>Orientate\u00a0your\u00a0PlanktoScope\u00a0so\u00a0that\u00a0it\u00a0matches the picture.</li> <li>Twist off the orange top of the\u00a0Peristaltic\u00a0pump\u00a0in\u00a0an\u00a0anti-clockwise\u00a0direction.</li> </ul> <p>You can now remove the Peristaltic\u00a0Pump housing and\u00a0\ud83d\udfe2 Rotor.</p> <p></p> <p>You can now remove the Peristaltic\u00a0Pump housing and\u00a0\ud83d\udfe2 Rotor.</p> <p></p> <p>\ud83d\udd34 Locate the\u00a0Tube\u00a0for the Peristaltic\u00a0Pump in\u00a0Bag F\u00a0and remove it from the\u00a0bag.</p> <p>Warning</p> <p>The tips of the Tubing that are\u00a0covered by black rubber are very\u00a0delicate and easily broken.</p> <p></p> <p>Insert the first plastic arch of the\u00a0Tube\u00a0into the slot on the Peristaltic Pump\u00a0\\ housing.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p> </p> <p>Insert the\u00a0Rotor\u00a0into the housing\u00a0ensuring the correct orientation. The\u00a0hole in the centre should be visible on\u00a0the underside.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>Insert the\u00a0Rotor\u00a0into the housing.\u00a0Then, thread the\u00a0Tube\u00a0around the\u00a0Rotor\u00a0and insert the other plastic\u00a0arch into the second slot.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <ul> <li>Thread the\u00a0Tube\u00a0around around the\u00a0Rotor\u00a0and insert the other plastic\u00a0arch into the second slot.</li> <li>This will require stretching the\u00a0Tube\u00a0slightly.</li> </ul> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>Place the Peristaltic Pump housing\u00a0back onto the PlanktoScope.</p> <p></p> <p>Achieve the angle shown in the\u00a0picture between the Peristaltic Pump\u00a0housing and PlanktoScope main\u00a0body. Then, press and twist in a\u00a0clockwise direction.</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <ul> <li>\ud83d\udfe3\u00a0Gently remove the black rubber\u00a0covers for the Peristaltic Pump\u00a0connectors by pinching the very tip\u00a0and pulling away.</li> <li>Once complete, locate\u00a0Bag D\u00a0which\u00a0contains tubing.</li> </ul> <p></p> <p>Push the small piece of tubing from\u00a0Bag D\u00a0over the left-side connector of\u00a0the\u00a0Peristaltic Pump.</p> <p></p> <p>Place the long piece of tubing from\u00a0Bag D\u00a0over the right-side connector\u00a0of the\u00a0Peristaltic Pump.</p> <p></p> <p>Insert the connector from\u00a0Bag D\u00a0into\u00a0the other end of the\u00a0small piece of\u00a0tubing.</p> <p></p> <p></p> <p>Orientate\u00a0Part P\u00a0so that the magnets\u00a0are face-down on the left-hand side.</p> <p></p> <p>Place Part P over the magnets\u00a0adjacent to the\u00a0Peristaltic Pump.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p>\ud83d\udd34 From\u00a0Bag M, Place the\u00a0light blue Test Tube in the hole adjacent to the\u00a0Peristaltic Pump.</p> <p></p> <p>Place the\u00a0\ud83d\udd35 dark blue Test Tube\u00a0into\u00a0the hole situated outside of the\u00a0PlanktoScope.</p> <p></p> <p>\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.</p> <p></p> <p> </p> <ul> <li>Locate Part\u00a0C</li> <li>Locate\u00a025\u00a0mm\u00a0camera\u00a0lens\u00a0and\u00a0Lock Ring\u00a0from\u00a0Bag J.</li> <li>25MM is printed on the lens.</li> </ul> <p> </p> <ul> <li>Remove the plastic lens cap.</li> <li>Slot\u00a0the\u00a025\u00a0mm\u00a0camera\u00a0lens into\u00a0Part C.</li> </ul> <p>Info</p> <p>The magnets are raised on the\u00a0side where the lens lays flat.</p> <p>Warning</p> <p>Try not to touch the lens</p> <p>Screw the\u00a0Lock Ring\u00a0onto the lens,\u00a0flat-side down.</p> <p> </p> <ul> <li>Locate Part\u00a0D.</li> <li>Locate\u00a016\u00a0mm\u00a0camera\u00a0lens\u00a0and\u00a0Lock\u00a0Ring\u00a0from\u00a0Bag J.</li> <li>16MM is printed on the lens.</li> </ul> <p> </p> <ul> <li>Remove the plastic lens cap.</li> <li>Slot\u00a0the\u00a016\u00a0mm\u00a0camera\u00a0lens into Part\u00a0D.</li> </ul> <p>Info</p> <p>The\u00a0magnets\u00a0are\u00a0indented\u00a0on\u00a0the\u00a0side that the lens lays flat.</p> <p>Warning</p> <p>Try not to touch the lens</p> <p>Screw the\u00a0Lock Ring\u00a0onto the lens,\u00a0flat-side down.</p> <p>The result should be similar to that\u00a0picture.</p> <p> </p> <p>Place\u00a0both\u00a0Lenses (C\u00a0and\u00a0D)\u00a0together\u00a0so that they flat together and both\u00a0lenses are facing each other.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p> </p> <p>Place\u00a0the\u00a0Lenses\u00a0(both\u00a0C\u00a0and\u00a0D)\u00a0into\u00a0position, adjacent to the camera.</p> <p>The orientation of your PlanktoScope\u00a0and Lenses should match the\u00a0pictures.</p> <p></p> <ul> <li>Once\u00a0together,\u00a0place\u00a0the\u00a0lenses\u00a0(both\u00a0C and D) into position, adjacent to\u00a0the camera.</li> <li>Part\u00a0C\u00a0/\u00a025mm\u00a0lens\u00a0should\u00a0be\u00a0furthest\u00a0from the pump (orange piece).</li> </ul> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p></p> <p></p> <p>Info</p> <p>The Fluidic Path will have a\u00a0cardboard protector.</p> <p>Please take extra precaution while handling\u00a0this\u00a0part\u00a0and\u00a0avoid\u00a0touching\u00a0the glass element of the piece.</p> <p>Warning</p> <p>The Fluidic Path is very delicate.</p> <p></p> <p>Place the Tube Clamp over the long\u00a0piece\u00a0of\u00a0tube\u00a0at\u00a0the\u00a0end\u00a0of\u00a0the\u00a0Fluidic\u00a0Path.</p> <p></p> <p>Place the white clamp over the long\u00a0piece\u00a0of\u00a0tube\u00a0at\u00a0the\u00a0end\u00a0of\u00a0the\u00a0Fluidic Path.</p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>Press down on the Tube Clamp so\u00a0that it clicks into place with just one\u00a0click.</p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>Insert\u00a0a\u00a0small\u00a0plastic\u00a0Connector\u00a0into\u00a0the\u00a0end\u00a0of\u00a0the\u00a0tubing,\u00a0below\u00a0the\u00a0Tube\u00a0Clamp.</p> <p></p> <p>Make sure the tubing is over the\u00a0Connector.</p> <p>Info</p> <p>The result should look the same as\u00a0the picture.</p> <p></p> <p>Remove the cardboard protector\u00a0from the\u00a0Fluidic Path.</p> <p></p> <p>Warning</p> <p>A reminder, the glass part of the\u00a0Fluidic\u00a0Path\u00a0is\u00a0very\u00a0delicate.\u00a0Please\u00a0try\u00a0not to touch it.</p> <p></p> <p>Place another Connector at the end\u00a0of the tubing.</p> <p></p> <p>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</p> <p></p> <p>\u26a0 Gently place the Fluidic Path in\u00a0the designated indentation on\u00a0Part F.</p> <p>Warning</p> <p>Do not touch the glass.\u00a0</p> <ul> <li>You may have to slightly stretch the\u00a0tubing to get the Fluidic Path into\u00a0position.</li> <li>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</li> </ul> <p></p> <p>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.</p> <p>Avoid placing tape over the glass.</p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p> </p> <p>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.</p> <p></p> <p>Info</p> <p>The result should be similar to the\u00a0picture.</p> <p> </p> <ul> <li>Place the Fluidic Path into position\u00a0between the mount and the\u00a0Peristaltic Pump.</li> <li>Connect the magnets to face each\u00a0other.</li> </ul> <p></p> <p>The result should look the same as\u00a0the pictures.</p> <p> </p> <ul> <li>\ud83d\udfe2 Connect the Fluidic Path to the\u00a0Peristaltic Pump by twisting the two\u00a0connectors together.</li> <li>The\u00a0result\u00a0should\u00a0be\u00a0the\u00a0same\u00a0as\u00a0the\u00a0picture.</li> </ul>"},{"location":"setup/hardware/v2.5/assembly/#build-complete","title":"Build complete! \ud83d\udcaf \ud83d\udcab","text":""},{"location":"setup/hardware/v2.5/assembly/#next-steps","title":"Next steps","text":"<p>Next, you will need to set up the PlanktoScope software on the micro-SD card of your PlanktoScope's Raspberry Pi.</p>"},{"location":"setup/hardware/v2.5/kit/","title":"Kit Production","text":""},{"location":"setup/hardware/v2.5/kit/#mechanical-structure","title":"Mechanical Structure","text":"<p>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.</p> <p></p>"},{"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":"<p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>Strength: Valchromat has a high mechanical strength, making it suitable for use in structural applications such as flooring, furniture, and doors.</p> </li> <li> <p>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.</p> </li> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul> <p></p> <ul> <li> <p>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.</p> </li> <li> <p>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.</p> </li> </ul> <p>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.</p> <p>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.</p>"},{"location":"setup/hardware/v2.5/kit/#finishing","title":"Finishing","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>We use Rubio Monocoat Plus as a finishing product for Valchromat.</p>"},{"location":"setup/hardware/v2.5/kit/#cnc-workflow","title":"CNC workflow","text":"<p>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:</p> <ol> <li> <p>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:</p> </li> <li> <p>6mm end mill for straight flats</p> </li> <li>2mm end mill for inner contours</li> <li> <p>1mm end mill for small holes</p> </li> <li> <p>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:</p> </li> <li> <p>1500mm/min for 1-2mm end mills</p> </li> <li>2500mm/min for 3mm end mills</li> <li> <p>3500mm/min for 6mm end mills</p> </li> <li> <p>Load the end mill: Once the appropriate end mill has been selected, it can be loaded onto the spindle of the CNC milling machine.</p> </li> <li> <p>Set the workpiece: The workpiece should be securely clamped onto the table of the CNC milling machine.</p> </li> <li> <p>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.</p> </li> <li> <p>Begin machining: The machining process should be carried out in the following sequence:</p> </li> <li> <p>Mill the screw holes with a 2mm end mill and then with a 3mm end mill</p> </li> <li>Mill the corners with a 2mm end mill</li> <li>Mill everything else with a 3mm end mill</li> </ol> <p>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.</p> <p></p>"},{"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":"<ul> <li>Hammer</li> <li>Air Compressor</li> <li>Rubber gloves</li> <li>Paper carpet pad</li> <li>Clean piece of cotton fabric</li> <li>Support material for drying the parts</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#case-part-parts","title":"Case part parts","text":"<ul> <li>all case parts</li> <li>Rubio Monocoat Oil Plus 2C</li> <li>Rubio Monocoat Accelerator Component B</li> <li>Magnets</li> <li>Square nuts</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#clean","title":"Clean","text":""},{"location":"setup/hardware/v2.5/kit/#stir","title":"Stir","text":""},{"location":"setup/hardware/v2.5/kit/#apply","title":"Apply","text":""},{"location":"setup/hardware/v2.5/kit/#dry","title":"Dry","text":""},{"location":"setup/hardware/v2.5/kit/#inserting-the-screws","title":"Inserting the screws","text":""},{"location":"setup/hardware/v2.5/kit/#inserting-the-magnets","title":"Inserting the magnets","text":""},{"location":"setup/hardware/v2.5/kit/#package-housing-part","title":"Package Housing part","text":""},{"location":"setup/hardware/v2.5/kit/#planktoscope-hat","title":"PlanktoScope Hat","text":"<p>Welcome to the PCB production manual for the PlanktoScope Hat!</p> <p> </p> <p>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.</p> <p>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.</p> <p>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.</p> <p>Note</p> <p>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.</p>"},{"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":"<p>To order a PCB board including assembly, follow these steps:</p> <ul> <li>Select a manufacturing company based on your local availability, budget, delivery dates, and services such as assembly.</li> </ul> <p>Note</p> <p>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.</p> <ul> <li>Create a customer account if you do not already have one. Ensure to specify the correct tax, contact, and delivery information.</li> </ul> <p>Warning</p> <p>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.</p> <ul> <li>Create a project and select the quantity of PCB boards you need for production.</li> <li>Configure the order based on the values specified in this document.</li> <li>Upload the bill of material (BOM) and validate the component availability.</li> </ul> <p>Warning</p> <p>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.</p> <p>Info</p> <p>The component costs will now be calculated, and the price should be displayed.</p> <ul> <li>Upload the gerber files provided as a zip file in the repository under the following link.</li> <li>Upload the assembly instructions provided as a zip file in the repository under the following link.</li> <li>Check that there are no missing references in your order configuration.</li> <li>Place the order based on your delivery requirements.</li> <li>Select a payment method and complete the order process.</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#configuration","title":"Configuration","text":"<p>The following configuration parameters can be used for the production of the PCB.</p> <p>Info</p> <p>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.</p>"},{"location":"setup/hardware/v2.5/kit/#board-dimensions","title":"Board dimensions","text":"<p>65 mm x 100 mm</p>"},{"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 &gt; 0.15 mm Min. drill hole size &gt; 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":"<p>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.</p> <p>Warning</p> <p>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.</p>"},{"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":"<ul> <li>professional Soldering iron</li> <li>solder with flux</li> <li>Helping hand or Breadboard</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#thru-hole-parts","title":"Thru-Hole parts","text":"Files Description Planktoscope-Hat-bom-through-hole.csv The list of used SMD components <p>Warning</p> <p>When you solder this for the first time, take special care not to damage the board.</p> <p>Info</p> <p>To learn how to solder we recommend you the awesome Comic \"Soldering is easy\" by Mitch Altmal, Andie Nordgren and Jeff Keyzer</p>"},{"location":"setup/hardware/v2.5/kit/#soldering-of-the-stepper-motor-driver","title":"Soldering of the stepper motor driver","text":"<p>Unpack the motor driver and the connector strips and take the breadboard aside.</p> <p></p> <p>Plug the connectors with the appropriate distance to the breadboard.</p> <p>Info</p> <p>The breadboard supports you during soldering to ensure the spacing and angle of the connectors, alternatively you can also use a third hand.</p> <p></p> <p>Now position the motor driver on the connector strips of the beadboard.</p> <p>Warning</p> <p>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.</p> <p></p> <p>Now solder all pins of the connector strip.</p> <p>Info</p> <p>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.</p> <p>Tip</p> <p>You can also solder one pin on one side and then the opposite one to fix your workpiece, this ensures that nothing accidentally moves.</p>"},{"location":"setup/hardware/v2.5/kit/#soldering-of-the-motor-driver-sockets","title":"Soldering of the motor driver sockets","text":"<p>Now take the PlanktoScope Hat board and the female connector of the stepper motor driver and position them as shown in the picture.</p> <p></p> <p>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.</p> <p></p> <p>Now solder all pins of the connector strip.</p> <p>Info</p> <p>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.</p> <p>Tip</p> <p>You can also solder one pin on one side and then the opposite one to fix your workpiece, this ensures that nothing accidentally moves.</p> <p></p> <p>Repeat the procedure with the second motor driver. The end result should look like this.</p>"},{"location":"setup/hardware/v2.5/kit/#soldering-the-connection-sockets","title":"Soldering the connection sockets","text":"<p>Now solder the motor driver sockets, inserting the connector into the holes as shown.</p> <p></p> <p>Turn the board over and hold the loose connector while soldering it. Repeat the procedure with the second motor connector.</p> <p>Info</p> <p>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.</p> <p></p> <p>Repeat the procedure with the power connector. The end result should look like this.</p> <p></p> <p>Repeat the procedure with the led connector. The end result should look like this.</p>"},{"location":"setup/hardware/v2.5/kit/#soldering-the-raspberry-pi-connector","title":"Soldering the Raspberry Pi connector","text":"<p>Now solder the Raspberry Pi header connector with all 20 pins.</p> <p>Warning</p> <p>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.</p>"},{"location":"setup/hardware/v2.5/kit/#install-and-solder-the-cooling-fan","title":"Install and solder the cooling fan","text":"<p>Install the fan with the four screws and nuts.</p> <p>Warning</p> <p>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.</p> <p>Cut off the excess cable of the fan and leave about 6 cm.</p> <p></p> <p>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.</p> <p></p> <p>Solder the fan cables according to the marking and color codes \u26ab GND, \ud83d\udd34 VCC, \ud83d\udfe1 RPM, \ud83d\udd35 PWM.</p> <p>Note</p> <p>If your fan doesn't have a \ud83d\udd35 PWM connector, then that's not a problem, you can just leave it out.</p>"},{"location":"setup/hardware/v2.5/kit/#solder-the-display-connector","title":"Solder the display connector","text":"<p>Insert the pin headers into the holes provided, hold them in place, carefully turn the board over and solder the connector.</p> <p>Note</p> <p>If you do not use an OLED display, you do not need to solder the connector.</p>"},{"location":"setup/hardware/v2.5/kit/#solder-the-configuration-option-jumpers","title":"Solder the configuration option jumpers","text":"<p>Insert the pin headers into the holes provided, hold them in place, carefully turn the board over and solder the connector.</p> <p>Note</p> <p>If you do not use an OLED display, you do not need to solder the connector.</p>"},{"location":"setup/hardware/v2.5/kit/#you-have-finished-soldering-the-components","title":"You have finished soldering the components","text":"<p>The assembly of the thru-hole components for the planktoscope hat is now complete. The end result should look like this.</p>"},{"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":"<ul> <li>double sided adhesive tape</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#hard-case-parts","title":"Hard case parts","text":"<ul> <li>Hard case</li> </ul>"},{"location":"setup/hardware/v2.5/kit/#foam-preparation","title":"Foam preparation","text":"<p>Cut the foam block at the outer edge by gently tearing it apart with your fingers.</p> <p>Warning</p> <p>Be careful the foam tears easily and can not be repaired.</p> <p>Tip</p> <p>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.</p> <p></p> <p>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.</p> <p></p> <p>Now insert the foam edge in to the case and glue it to the outer wall.</p> <p>Note</p> <p>Before you fix the foam, position it completely and check that it is placed flush with the edge of the case.</p>"},{"location":"setup/hardware/v2.5/kit/#kit-composition","title":"Kit composition","text":"<p>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!</p>"},{"location":"setup/hardware/v2.6/","title":"Index","text":"<p>This is a marktext document avec</p> <p></p>"},{"location":"setup/software/","title":"PlanktoScope Software","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>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.</p>"},{"location":"setup/software/#choosing-an-sd-card-image","title":"Choosing an SD card image","text":"<p>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 <code>planktoscope-v2024.0.0+planktoscopehat.img.gz</code> 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. <code>planktoscopehat</code>).</p>"},{"location":"setup/software/#planktoscope-os-versions","title":"PlanktoScope OS versions","text":"<p>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.</p> <p>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:</p> <ul> <li> <p>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.</p> </li> <li> <p>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 <code>9</code> should not be interpreted as having any special meaning.</p> </li> <li> <p>v2024.0.0: this version is the first release of the PlanktoScope OS in 2024.</p> </li> <li> <p>v2024.1.0: this version will be the second release of the PlanktoScope OS in 2024.</p> </li> </ul>"},{"location":"setup/software/#hardware-configurations","title":"Hardware configurations","text":"<p>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:</p> <ul> <li> <p><code>adafruithat</code>: this configuration of the PlanktoScope OS is compatible with v2.1 of the PlanktoScope hardware, which uses the Adafruit Stepper Motor HAT.</p> </li> <li> <p><code>planktoscopehat</code>: 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.</p> </li> <li> <p><code>fairscope-latest</code>: this configuration of the PlanktoScope OS is identical to the <code>planktoscopehat</code> 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.</p> </li> </ul> <p>If you have a PlanktoScope from FairScope, you should probably use the <code>fairscope-latest</code> SD card image; otherwise, if you have a non-FairScope PlanktoScope with hardware version v2.3 or later, you should probably use the <code>planktoscopehat</code> SD card image; otherwise, if you have a v2.1 PlanktoScope, you should probably use an <code>adafruithat</code> SD card image.</p>"},{"location":"setup/software/#installation","title":"Installation","text":"<p>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.</p>"},{"location":"setup/software/#post-installation-configuration","title":"Post-installation configuration","text":"<p>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.</p>"},{"location":"setup/software/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"location":"setup/software/config/","title":"Post-Installation Configuration","text":"<p>After installing the PlanktoScope software onto your PlanktoScope, you will need to configure the software to match your PlanktoScope hardware and your operational requirements.</p> <p>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.</p>"},{"location":"setup/software/config/#hardware-version","title":"Hardware Version","text":"<p>Info</p> <p>This step is only required if you are using a <code>planktoscopehat</code> SD card image; it is not needed on the <code>adafruithat</code> and <code>fairscope-latest</code> SD card images.</p> <p>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.</p>"},{"location":"setup/software/config/#next-steps","title":"Next steps","text":"<p>Now that you have configured the PlanktoScope software, you can proceed to our guide on how to operate your PlanktoScope.</p>"},{"location":"setup/software/nonstandard-install/","title":"Non-Standard Installation","text":"<p>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.</p>"},{"location":"setup/software/nonstandard-install/#prerequisites","title":"Prerequisites","text":"<p>This guide assumes that:</p> <ol> <li>You have previous experience with using the command-line terminal on the Raspberry Pi OS or another Linux distribution.</li> <li>You have already confirmed that your PlanktoScope works without any problems with software installed by the standard PlanktoScope software setup process.</li> <li>You already know how to use the PlanktoScope software.</li> </ol> <p>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.</p> <p>In order to complete the non-standard setup process, you will need all of the following:</p> <ol> <li>A Raspberry Pi computer. We only test to ensure that the PlanktoScope software works on the Raspberry Pi 4; it may or may not work on the Raspberry Pi 3, and it does not yet work on the Raspberry Pi 5.</li> <li>A keyboard connected to your Raspberry Pi.</li> <li>A display connected to your Raspberry Pi.</li> <li>A micro-SD card for your Raspberry Pi.</li> <li>A way to provide internet access to your Raspberry Pi.</li> <li>A separate computer which can flash SD card images to your micro-SD card.</li> </ol>"},{"location":"setup/software/nonstandard-install/#install-and-set-up-raspberry-pi-os-on-your-raspberry-pi","title":"Install and set up Raspberry Pi OS on your Raspberry Pi","text":""},{"location":"setup/software/nonstandard-install/#download-a-raspberry-pi-os-sd-card-image","title":"Download a Raspberry Pi OS SD card image","text":"<p>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:</p> <ul> <li>\"Raspberry Pi OS with desktop\"</li> <li>\"Raspberry Pi OS with desktop and recommended software\"</li> <li>\"Raspberry Pi OS Lite\"</li> </ul> <p>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.</p> <p>Warning</p> <p>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.</p>"},{"location":"setup/software/nonstandard-install/#write-the-os-image-to-an-sd-card","title":"Write the OS image to an SD card","text":"<p>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.</p> <p>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 <code>.img</code>, <code>.img.gz</code>, or <code>.img.xz</code> 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.</p> <p>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 <code>ddrescue</code> on a Debian-based system, e.g. as follows:</p> <pre><code>gunzip planktoscope-v2.3-final.img.gz\nsudo ddrescue planktoscope-v2.3-final.img /dev/mmcblk0 --force\n</code></pre> <p>Warning: 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.</p>"},{"location":"setup/software/nonstandard-install/#configure-your-raspberry-pi","title":"Configure your Raspberry Pi","text":"<p>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.</p> <p>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.</p> <p>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 <code>en_US.UTF-8</code> 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 <code>pi</code> as the username, and you should choose a password you can remember. By default, the standard PlanktoScope SD card images use <code>copepode</code> 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.</p> <p>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.</p>"},{"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":"<p>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 <code>planktoscopehat</code> with the word <code>adafruithat</code> in any of the commands below.</p> <p>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):</p> StableBetaEdge <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- -v software/stable -H planktoscopehat\n</code></pre> <p>This 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.</p> <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- -v software/beta -H planktoscopehat\n</code></pre> <p>This 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.</p> <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- -v master -H planktoscopehat\n</code></pre> <p>This will install the current unstable development version of the PlanktoScope OS. This version is likely to be broken in various ways.</p> <p>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:</p> <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- -t tag -v v2024.0.0-alpha.1 -H planktoscopehat\n</code></pre> <p>You can also choose to install the PlanktoScope software from some other repository on GitHub instead of github.com/PlanktoScope/PlanktoScope, by using the <code>-r</code> 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:</p> <pre><code>wget -O - https://install.planktoscope.community/distro.sh \\\n  | sh -s -- --help\n</code></pre>"},{"location":"setup/software/nonstandard-install/#wait-for-installation-to-finish","title":"Wait for installation to finish","text":"<p>The 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.</p> <p>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.</p>"},{"location":"setup/software/nonstandard-install/#connect-to-the-planktoscope","title":"Connect to the PlanktoScope","text":"<p>Next, you will need to restart the Raspberry Pi, e.g. with the following command:</p> <pre><code>sudo reboot now\n</code></pre> <p>This step is necessary to finish the PlanktoScope software setup process.</p> <p>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 <code>pkscope</code> followed by the unique randomly-generated name of your PlanktoScope, and whose password is <code>copepode</code>.</p> <p>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):</p> <ul> <li>http://planktoscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)</li> <li>http://pkscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)</li> <li>http://home.pkscope (this should work unless your web browser is configured to use a Private DNS provider)</li> <li>http://192.168.4.1 (this should always work)</li> <li>http://192.168.5.1 (this should always work)</li> </ul> <p>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 <code>pkscope-chain-list-27764 login:</code>, then the PlanktoScope is named <code>pkscope-chain-list-27764</code>).</p> <p>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.</p>"},{"location":"setup/software/nonstandard-install/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"location":"setup/software/standard-install/","title":"Standard Installation","text":"<p>This page provides instructions for installing the most recent standard version of the PlanktoScope OS on a PlanktoScope.</p>"},{"location":"setup/software/standard-install/#set-up-the-sd-card","title":"Set up the SD card","text":"<p>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.</p>"},{"location":"setup/software/standard-install/#prerequisites","title":"Prerequisites","text":"<p>In order to complete this step, you will need all of the following:</p> <ol> <li>A microSD card for your Raspberry Pi.</li> <li>A separate computer which can flash SD card images to your microSD card.</li> </ol>"},{"location":"setup/software/standard-install/#download-the-planktoscope-software-sd-card-image","title":"Download the PlanktoScope software SD card image","text":"<p>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.</p>"},{"location":"setup/software/standard-install/#write-the-image-to-the-sd-card","title":"Write the image to the SD card","text":"<p>To write the image file to your microSD card:</p> <ol> <li>Download, install, and start the latest version of the Raspberry Pi Imager.</li> <li>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.</li> <li>Press the \"Choose Device\" button. Select \"No filtering\" from the menu. It actually doesn't matter what you select here.</li> <li>Press the \"Choose OS\" button. Select \"Use custom\" from the menu (this is why it doesn't matter what you selected in the \"Choose Device\" menu). In the file dialog, open the PlanktoScope SD card image file you downloaded in the previous section of this setup guide.</li> <li>Press the \"Choose Storage\" button. Select your SD card from the menu.</li> <li>Press the \"Next\" button. A pop-up dialog should appear asking if you would like to customize the OS. You should probably press the \"No\" button unless you are already experienced with the PlanktoScope software, because most of the settings inside don't matter to typical users of the PlanktoScope software, and because it's possible to break the software with incorrect settings.</li> <li>A pop-up dialog should appear asking you to confirm whether you selected the correct SD card and want to wipe all data on the SD card in order to write the PlanktoScope SD card image to your SD card. If you are ready, press the \"Yes\" button.</li> <li>The Raspberry Pi Imager will begin overwriting your SD card with the PlanktoScope SD card image. This will take a while to finish.</li> </ol> <p>Once flashing is complete, unmount the SD card and remove it from the computer.</p>"},{"location":"setup/software/standard-install/#insert-the-sd-card-into-the-planktoscope","title":"Insert the SD card into the PlanktoScope","text":"<p>Insert the microSD card into the Raspberry Pi computer installed in your PlanktoScope.</p>"},{"location":"setup/software/standard-install/#connect-to-the-planktoscope","title":"Connect to the PlanktoScope","text":"<p>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 <code>pkscope</code> followed by the unique randomly-generated name of your PlanktoScope. The password of this Wi-Fi network is <code>copepode</code>.</p> <p>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.</p> <p>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):</p> <ul> <li>http://planktoscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)</li> <li>http://pkscope.local (this should work unless you're on a device and web browser without mDNS support; notably, older versions of Android do not have mDNS support)</li> <li>http://home.pkscope (this should work unless your web browser is configured to use a Private DNS provider)</li> <li>http://192.168.4.1 (this should always work)</li> <li>http://192.168.5.1 (this should always work)</li> </ul> <p>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.</p>"},{"location":"setup/software/standard-install/#next-steps","title":"Next steps","text":"<p>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.</p>"},{"location":"troubleshooting/","title":"Troubleshooting","text":"<p>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 <code>#3-start-testing</code> channel on Slack.</p>"}]}
\ No newline at end of file
diff --git a/site/setup/hardware/v2.6/index.html b/site/setup/hardware/v2.6/index.html
index 685ded5..6efd538 100644
--- a/site/setup/hardware/v2.6/index.html
+++ b/site/setup/hardware/v2.6/index.html
@@ -7,7 +7,7 @@
     .gdesc-inner { font-size: 0.75rem; }
     body[data-md-color-scheme="slate"] .gdesc-inner { background: var(--md-default-bg-color);}
     body[data-md-color-scheme="slate"] .gslide-title { color: var(--md-default-fg-color);}
-    body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);}</style><script src=../../../assets/javascripts/glightbox.min.js></script></head> <body dir=ltr data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> </div> <div data-md-component=announce> </div> <header class="md-header md-header--shadow" data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="PlanktoScope Documentation (beta preview)" class="md-header__button md-logo" aria-label="PlanktoScope Documentation (beta preview)" data-md-component=logo> <img src=../../../images/logos/planktoscope_white.png alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> PlanktoScope Documentation (beta preview) </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Index </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3 3.19.09m3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95 2.06.05m-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31Z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5c-.84 0-1.65.15-2.39.42L12 2M3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29L3.34 7m.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14L3.36 17M20.65 7l-1.77 3.79a7.023 7.023 0 0 0-2.38-4.15l4.15.36m-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29L20.64 17M12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44L12 22Z"/></svg> </label> </form> <script>var media,input,key,value,palette=__md_get("__palette");if(palette&&palette.color){"(prefers-color-scheme)"===palette.color.media&&(media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']"),palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent"));for([key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg> </label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay for=__search></label> <div class=md-search__inner role=search> <form class=md-search__form name=search> <input type=text class=md-search__input name=query aria-label=Search placeholder=Search autocapitalize=off autocorrect=off autocomplete=off spellcheck=false data-md-component=search-query required> <label class="md-search__icon md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg> </label> <nav class=md-search__options aria-label=Search> <button type=reset class="md-search__icon md-icon" title=Clear aria-label=Clear tabindex=-1> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg> </button> </nav> </form> <div class=md-search__output> <div class=md-search__scrollwrap data-md-scrollfix> <div class=md-search-result data-md-component=search-result> <div class=md-search-result__meta> Initializing search </div> <ol class=md-search-result__list role=presentation></ol> </div> </div> </div> </div> </div> <div class=md-header__source> <a href="https://github.com/PlanktoScope/PlanktoScope" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 496 512"><!-- Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg> </div> <div class=md-source__repository> GitHub </div> </a> </div> </nav> </header> <div class=md-container data-md-component=container> <main class=md-main data-md-component=main> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component=sidebar data-md-type=navigation> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--primary" aria-label=Navigation data-md-level=0> <label class=md-nav__title for=__drawer> <a href=../../.. title="PlanktoScope Documentation (beta preview)" class="md-nav__button md-logo" aria-label="PlanktoScope Documentation (beta preview)" data-md-component=logo> <img src=../../../images/logos/planktoscope_white.png alt=logo> </a> PlanktoScope Documentation (beta preview) </label> <div class=md-nav__source> <a href="https://github.com/PlanktoScope/PlanktoScope" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 496 512"><!-- Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg> </div> <div class=md-source__repository> GitHub </div> </a> </div> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_1> <div class="md-nav__link md-nav__container"> <a href=../../.. class="md-nav__link "> <span class=md-ellipsis> Home </span> </a> <label class="md-nav__link " for=__nav_1 id=__nav_1_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_1_label aria-expanded=false> <label class=md-nav__title for=__nav_1> <span class="md-nav__icon md-icon"></span> Home </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../faq/ class=md-nav__link> <span class=md-ellipsis> Frequently Asked Questions </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2> <div class="md-nav__link md-nav__container"> <a href=../../ class="md-nav__link "> <span class=md-ellipsis> Setup </span> </a> <label class="md-nav__link " for=__nav_2 id=__nav_2_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_2_label aria-expanded=false> <label class=md-nav__title for=__nav_2> <span class="md-nav__icon md-icon"></span> Setup </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_2> <div class="md-nav__link md-nav__container"> <a href=../ class="md-nav__link "> <span class=md-ellipsis> Hardware </span> </a> <label class="md-nav__link " for=__nav_2_2 id=__nav_2_2_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_2_2_label aria-expanded=false> <label class=md-nav__title for=__nav_2_2> <span class="md-nav__icon md-icon"></span> Hardware </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_2_2> <div class="md-nav__link md-nav__container"> <a href=../v2.5/ class="md-nav__link "> <span class=md-ellipsis> v2.5 </span> </a> <label class="md-nav__link " for=__nav_2_2_2 id=__nav_2_2_2_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_2_2_2_label aria-expanded=false> <label class=md-nav__title for=__nav_2_2_2> <span class="md-nav__icon md-icon"></span> v2.5 </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../v2.5/kit/ class=md-nav__link> <span class=md-ellipsis> Kit Production </span> </a> </li> <li class=md-nav__item> <a href=../v2.5/assembly/ class=md-nav__link> <span class=md-ellipsis> Assembly </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_2_3> <div class="md-nav__link md-nav__container"> <a href=../v2.1/ class="md-nav__link "> <span class=md-ellipsis> v2.1 </span> </a> <label class="md-nav__link " for=__nav_2_2_3 id=__nav_2_2_3_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_2_2_3_label aria-expanded=false> <label class=md-nav__title for=__nav_2_2_3> <span class="md-nav__icon md-icon"></span> v2.1 </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../v2.1/kit/ class=md-nav__link> <span class=md-ellipsis> Kit Production </span> </a> </li> <li class=md-nav__item> <a href=../v2.1/assembly/ class=md-nav__link> <span class=md-ellipsis> Assembly </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_3> <div class="md-nav__link md-nav__container"> <a href=../../software/ class="md-nav__link "> <span class=md-ellipsis> Software </span> </a> <label class="md-nav__link " for=__nav_2_3 id=__nav_2_3_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_2_3_label aria-expanded=false> <label class=md-nav__title for=__nav_2_3> <span class="md-nav__icon md-icon"></span> Software </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../software/standard-install/ class=md-nav__link> <span class=md-ellipsis> Standard Installation </span> </a> </li> <li class=md-nav__item> <a href=../../software/nonstandard-install/ class=md-nav__link> <span class=md-ellipsis> Non-Standard Installation </span> </a> </li> <li class=md-nav__item> <a href=../../software/config/ class=md-nav__link> <span class=md-ellipsis> Post-Installation Configuration </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_3> <div class="md-nav__link md-nav__container"> <a href=../../../operation/ class="md-nav__link "> <span class=md-ellipsis> Operation </span> </a> <label class="md-nav__link " for=__nav_3 id=__nav_3_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_3_label aria-expanded=false> <label class=md-nav__title for=__nav_3> <span class="md-nav__icon md-icon"></span> Operation </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../operation/user-interface/ class=md-nav__link> <span class=md-ellipsis> User Interface </span> </a> </li> <li class=md-nav__item> <a href=../../../operation/maintenance/ class=md-nav__link> <span class=md-ellipsis> Maintenance </span> </a> </li> <li class=md-nav__item> <a href=../../../operation/clone-sd/ class=md-nav__link> <span class=md-ellipsis> Clone your SD card </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_4> <div class="md-nav__link md-nav__container"> <a href=../../../troubleshooting/ class="md-nav__link "> <span class=md-ellipsis> Troubleshooting </span> </a> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_4_label aria-expanded=false> <label class=md-nav__title for=__nav_4> <span class="md-nav__icon md-icon"></span> Troubleshooting </label> <ul class=md-nav__list data-md-scrollfix> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_5> <div class="md-nav__link md-nav__container"> <a href=../../../community/ class="md-nav__link "> <span class=md-ellipsis> Community </span> </a> <label class="md-nav__link " for=__nav_5 id=__nav_5_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_5_label aria-expanded=false> <label class=md-nav__title for=__nav_5> <span class="md-nav__icon md-icon"></span> Community </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_5_2> <label class=md-nav__link for=__nav_5_2 id=__nav_5_2_label tabindex=0> <span class=md-ellipsis> Contribute </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_5_2_label aria-expanded=false> <label class=md-nav__title for=__nav_5_2> <span class="md-nav__icon md-icon"></span> Contribute </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../community/contribute/github/ class=md-nav__link> <span class=md-ellipsis> Github </span> </a> </li> <li class=md-nav__item> <a href=../../../community/contribute/hardware/ class=md-nav__link> <span class=md-ellipsis> Hardware </span> </a> </li> <li class=md-nav__item> <a href=../../../community/contribute/software/ class=md-nav__link> <span class=md-ellipsis> Software </span> </a> </li> <li class=md-nav__item> <a href=../../../community/contribute/documentation/ class=md-nav__link> <span class=md-ellipsis> Documentation </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../../../community/code-of-conduct/ class=md-nav__link> <span class=md-ellipsis> Code of Conduct </span> </a> </li> <li class=md-nav__item> <a href=../../../community/license/ class=md-nav__link> <span class=md-ellipsis> License </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6> <div class="md-nav__link md-nav__container"> <a href=../../../reference/ class="md-nav__link "> <span class=md-ellipsis> Technical Reference </span> </a> <label class="md-nav__link " for=__nav_6 id=__nav_6_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_6_label aria-expanded=false> <label class=md-nav__title for=__nav_6> <span class="md-nav__icon md-icon"></span> Technical Reference </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_2> <label class=md-nav__link for=__nav_6_2 id=__nav_6_2_label tabindex=0> <span class=md-ellipsis> Hardware </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_6_2_label aria-expanded=false> <label class=md-nav__title for=__nav_6_2> <span class="md-nav__icon md-icon"></span> Hardware </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/hardware/product-specs/ class=md-nav__link> <span class=md-ellipsis> Product Specifications </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/hardware/hat/ class=md-nav__link> <span class=md-ellipsis> Planktoscope HAT </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/hardware/changelog/ class=md-nav__link> <span class=md-ellipsis> Changelog </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3> <label class=md-nav__link for=__nav_6_3 id=__nav_6_3_label tabindex=0> <span class=md-ellipsis> Software </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_6_3_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3> <span class="md-nav__icon md-icon"></span> Software </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/product-specs/ class=md-nav__link> <span class=md-ellipsis> Product Specifications </span> </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3_2> <label class=md-nav__link for=__nav_6_3_2 id=__nav_6_3_2_label tabindex=0> <span class=md-ellipsis> Architecture </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_6_3_2_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3_2> <span class="md-nav__icon md-icon"></span> Architecture </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/architecture/os/ class=md-nav__link> <span class=md-ellipsis> Operating System </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3_3> <label class=md-nav__link for=__nav_6_3_3 id=__nav_6_3_3_label tabindex=0> <span class=md-ellipsis> Functionalities </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_6_3_3_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3_3> <span class="md-nav__icon md-icon"></span> Functionalities </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/functionalities/camera-settings/ class=md-nav__link> <span class=md-ellipsis> Camera Settings </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/functionalities/sample-imaging/ class=md-nav__link> <span class=md-ellipsis> Sample Imaging </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/functionalities/segmentation/ class=md-nav__link> <span class=md-ellipsis> Image Segmentation </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3_4> <label class=md-nav__link for=__nav_6_3_4 id=__nav_6_3_4_label tabindex=0> <span class=md-ellipsis> Interfaces </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_6_3_4_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3_4> <span class="md-nav__icon md-icon"></span> Interfaces </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/interfaces/mqtt/ class=md-nav__link> <span class=md-ellipsis> MQTT API </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/interfaces/exported-metadata/ class=md-nav__link> <span class=md-ellipsis> Exported Metadata </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3_5> <label class=md-nav__link for=__nav_6_3_5 id=__nav_6_3_5_label tabindex=0> <span class=md-ellipsis> Subsystems </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_6_3_5_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3_5> <span class="md-nav__icon md-icon"></span> Subsystems </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/subsystems/installation/ class=md-nav__link> <span class=md-ellipsis> Installation </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/subsystems/startup/ class=md-nav__link> <span class=md-ellipsis> Startup </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../../../reference/software/release-process/ class=md-nav__link> <span class=md-ellipsis> Release Process </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/changelog/ class=md-nav__link> <span class=md-ellipsis> Changelog </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component=sidebar data-md-type=toc> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> </nav> </div> </div> </div> <div class=md-content data-md-component=content> <article class="md-content__inner md-typeset"> <a href="https://github.com/PlanktoScope/PlanktoScope/edit/master/documentation/docs/setup/hardware/v2.6/index.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4v-2m10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1 2.1 2.1Z"/></svg> </a> <h1>Index</h1> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1-2.1-2M12.5 7v5.2l4 2.4-1 1L11 13V7h1.5M11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2v1.8Z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">November 25, 2024</span> </span> </aside> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright PlanktoScope project contributors </div> Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> </div> <div class=md-social> <a href="https://github.com/PlanktoScope" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 480 512"><!-- Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M186.1 328.7c0 20.9-10.9 55.1-36.7 55.1s-36.7-34.2-36.7-55.1 10.9-55.1 36.7-55.1 36.7 34.2 36.7 55.1zM480 278.2c0 31.9-3.2 65.7-17.5 95-37.9 76.6-142.1 74.8-216.7 74.8-75.8 0-186.2 2.7-225.6-74.8-14.6-29-20.2-63.1-20.2-95 0-41.9 13.9-81.5 41.5-113.6-5.2-15.8-7.7-32.4-7.7-48.8 0-21.5 4.9-32.3 14.6-51.8 45.3 0 74.3 9 108.8 36 29-6.9 58.8-10 88.7-10 27 0 54.2 2.9 80.4 9.2 34-26.7 63-35.2 107.8-35.2 9.8 19.5 14.6 30.3 14.6 51.8 0 16.4-2.6 32.7-7.7 48.2 27.5 32.4 39 72.3 39 114.2zm-64.3 50.5c0-43.9-26.7-82.6-73.5-82.6-18.9 0-37 3.4-56 6-14.9 2.3-29.8 3.2-45.1 3.2-15.2 0-30.1-.9-45.1-3.2-18.7-2.6-37-6-56-6-46.8 0-73.5 38.7-73.5 82.6 0 87.8 80.4 101.3 150.4 101.3h48.2c70.3 0 150.6-13.4 150.6-101.3zm-82.6-55.1c-25.8 0-36.7 34.2-36.7 55.1s10.9 55.1 36.7 55.1 36.7-34.2 36.7-55.1-10.9-55.1-36.7-55.1z"/></svg> </a> <a href="https://planktoscope.slack.com" target="_blank" rel="noopener" title="planktoscope.slack.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M94.12 315.1c0 25.9-21.16 47.06-47.06 47.06S0 341 0 315.1c0-25.9 21.16-47.06 47.06-47.06h47.06v47.06zm23.72 0c0-25.9 21.16-47.06 47.06-47.06s47.06 21.16 47.06 47.06v117.84c0 25.9-21.16 47.06-47.06 47.06s-47.06-21.16-47.06-47.06V315.1zm47.06-188.98c-25.9 0-47.06-21.16-47.06-47.06S139 32 164.9 32s47.06 21.16 47.06 47.06v47.06H164.9zm0 23.72c25.9 0 47.06 21.16 47.06 47.06s-21.16 47.06-47.06 47.06H47.06C21.16 243.96 0 222.8 0 196.9s21.16-47.06 47.06-47.06H164.9zm188.98 47.06c0-25.9 21.16-47.06 47.06-47.06 25.9 0 47.06 21.16 47.06 47.06s-21.16 47.06-47.06 47.06h-47.06V196.9zm-23.72 0c0 25.9-21.16 47.06-47.06 47.06-25.9 0-47.06-21.16-47.06-47.06V79.06c0-25.9 21.16-47.06 47.06-47.06 25.9 0 47.06 21.16 47.06 47.06V196.9zM283.1 385.88c25.9 0 47.06 21.16 47.06 47.06 0 25.9-21.16 47.06-47.06 47.06-25.9 0-47.06-21.16-47.06-47.06v-47.06h47.06zm0-23.72c-25.9 0-47.06-21.16-47.06-47.06 0-25.9 21.16-47.06 47.06-47.06h117.84c25.9 0 47.06 21.16 47.06 47.06 0 25.9-21.16 47.06-47.06 47.06H283.1z"/></svg> </a> </div> </div> </div> </footer> </div> <div class=md-dialog data-md-component=dialog> <div class="md-dialog__inner md-typeset"></div> </div> <div class=md-progress data-md-component=progress role=progressbar></div> <script id=__config type=application/json>{"base": "../../..", "features": ["navigation.instant", "navigation.instant.progress", "navigation.indexes", "toc.follow", "content.action.edit", "content.code.annotate", "content.code.copy"], "search": "../../../assets/javascripts/workers/search.b8dbb3d2.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src=../../../assets/javascripts/bundle.3220b9d7.min.js></script> <script id=init-glightbox>document.querySelectorAll('.glightbox').forEach(function(element) {
+    body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);}</style><script src=../../../assets/javascripts/glightbox.min.js></script></head> <body dir=ltr data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> </div> <div data-md-component=announce> </div> <header class="md-header md-header--shadow" data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="PlanktoScope Documentation (beta preview)" class="md-header__button md-logo" aria-label="PlanktoScope Documentation (beta preview)" data-md-component=logo> <img src=../../../images/logos/planktoscope_white.png alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> PlanktoScope Documentation (beta preview) </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Index </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3 3.19.09m3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95 2.06.05m-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31Z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5c-.84 0-1.65.15-2.39.42L12 2M3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29L3.34 7m.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14L3.36 17M20.65 7l-1.77 3.79a7.023 7.023 0 0 0-2.38-4.15l4.15.36m-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29L20.64 17M12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44L12 22Z"/></svg> </label> </form> <script>var media,input,key,value,palette=__md_get("__palette");if(palette&&palette.color){"(prefers-color-scheme)"===palette.color.media&&(media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']"),palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent"));for([key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg> </label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay for=__search></label> <div class=md-search__inner role=search> <form class=md-search__form name=search> <input type=text class=md-search__input name=query aria-label=Search placeholder=Search autocapitalize=off autocorrect=off autocomplete=off spellcheck=false data-md-component=search-query required> <label class="md-search__icon md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg> </label> <nav class=md-search__options aria-label=Search> <button type=reset class="md-search__icon md-icon" title=Clear aria-label=Clear tabindex=-1> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg> </button> </nav> </form> <div class=md-search__output> <div class=md-search__scrollwrap data-md-scrollfix> <div class=md-search-result data-md-component=search-result> <div class=md-search-result__meta> Initializing search </div> <ol class=md-search-result__list role=presentation></ol> </div> </div> </div> </div> </div> <div class=md-header__source> <a href="https://github.com/PlanktoScope/PlanktoScope" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 496 512"><!-- Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg> </div> <div class=md-source__repository> GitHub </div> </a> </div> </nav> </header> <div class=md-container data-md-component=container> <main class=md-main data-md-component=main> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component=sidebar data-md-type=navigation> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--primary" aria-label=Navigation data-md-level=0> <label class=md-nav__title for=__drawer> <a href=../../.. title="PlanktoScope Documentation (beta preview)" class="md-nav__button md-logo" aria-label="PlanktoScope Documentation (beta preview)" data-md-component=logo> <img src=../../../images/logos/planktoscope_white.png alt=logo> </a> PlanktoScope Documentation (beta preview) </label> <div class=md-nav__source> <a href="https://github.com/PlanktoScope/PlanktoScope" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 496 512"><!-- Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg> </div> <div class=md-source__repository> GitHub </div> </a> </div> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_1> <div class="md-nav__link md-nav__container"> <a href=../../.. class="md-nav__link "> <span class=md-ellipsis> Home </span> </a> <label class="md-nav__link " for=__nav_1 id=__nav_1_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_1_label aria-expanded=false> <label class=md-nav__title for=__nav_1> <span class="md-nav__icon md-icon"></span> Home </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../faq/ class=md-nav__link> <span class=md-ellipsis> Frequently Asked Questions </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2> <div class="md-nav__link md-nav__container"> <a href=../../ class="md-nav__link "> <span class=md-ellipsis> Setup </span> </a> <label class="md-nav__link " for=__nav_2 id=__nav_2_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_2_label aria-expanded=false> <label class=md-nav__title for=__nav_2> <span class="md-nav__icon md-icon"></span> Setup </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_2> <div class="md-nav__link md-nav__container"> <a href=../ class="md-nav__link "> <span class=md-ellipsis> Hardware </span> </a> <label class="md-nav__link " for=__nav_2_2 id=__nav_2_2_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_2_2_label aria-expanded=false> <label class=md-nav__title for=__nav_2_2> <span class="md-nav__icon md-icon"></span> Hardware </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_2_2> <div class="md-nav__link md-nav__container"> <a href=../v2.5/ class="md-nav__link "> <span class=md-ellipsis> v2.5 </span> </a> <label class="md-nav__link " for=__nav_2_2_2 id=__nav_2_2_2_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_2_2_2_label aria-expanded=false> <label class=md-nav__title for=__nav_2_2_2> <span class="md-nav__icon md-icon"></span> v2.5 </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../v2.5/kit/ class=md-nav__link> <span class=md-ellipsis> Kit Production </span> </a> </li> <li class=md-nav__item> <a href=../v2.5/assembly/ class=md-nav__link> <span class=md-ellipsis> Assembly </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_2_3> <div class="md-nav__link md-nav__container"> <a href=../v2.1/ class="md-nav__link "> <span class=md-ellipsis> v2.1 </span> </a> <label class="md-nav__link " for=__nav_2_2_3 id=__nav_2_2_3_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_2_2_3_label aria-expanded=false> <label class=md-nav__title for=__nav_2_2_3> <span class="md-nav__icon md-icon"></span> v2.1 </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../v2.1/kit/ class=md-nav__link> <span class=md-ellipsis> Kit Production </span> </a> </li> <li class=md-nav__item> <a href=../v2.1/assembly/ class=md-nav__link> <span class=md-ellipsis> Assembly </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_3> <div class="md-nav__link md-nav__container"> <a href=../../software/ class="md-nav__link "> <span class=md-ellipsis> Software </span> </a> <label class="md-nav__link " for=__nav_2_3 id=__nav_2_3_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_2_3_label aria-expanded=false> <label class=md-nav__title for=__nav_2_3> <span class="md-nav__icon md-icon"></span> Software </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../software/standard-install/ class=md-nav__link> <span class=md-ellipsis> Standard Installation </span> </a> </li> <li class=md-nav__item> <a href=../../software/nonstandard-install/ class=md-nav__link> <span class=md-ellipsis> Non-Standard Installation </span> </a> </li> <li class=md-nav__item> <a href=../../software/config/ class=md-nav__link> <span class=md-ellipsis> Post-Installation Configuration </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_3> <div class="md-nav__link md-nav__container"> <a href=../../../operation/ class="md-nav__link "> <span class=md-ellipsis> Operation </span> </a> <label class="md-nav__link " for=__nav_3 id=__nav_3_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_3_label aria-expanded=false> <label class=md-nav__title for=__nav_3> <span class="md-nav__icon md-icon"></span> Operation </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../operation/user-interface/ class=md-nav__link> <span class=md-ellipsis> User Interface </span> </a> </li> <li class=md-nav__item> <a href=../../../operation/maintenance/ class=md-nav__link> <span class=md-ellipsis> Maintenance </span> </a> </li> <li class=md-nav__item> <a href=../../../operation/clone-sd/ class=md-nav__link> <span class=md-ellipsis> Clone your SD card </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_4> <div class="md-nav__link md-nav__container"> <a href=../../../troubleshooting/ class="md-nav__link "> <span class=md-ellipsis> Troubleshooting </span> </a> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_4_label aria-expanded=false> <label class=md-nav__title for=__nav_4> <span class="md-nav__icon md-icon"></span> Troubleshooting </label> <ul class=md-nav__list data-md-scrollfix> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_5> <div class="md-nav__link md-nav__container"> <a href=../../../community/ class="md-nav__link "> <span class=md-ellipsis> Community </span> </a> <label class="md-nav__link " for=__nav_5 id=__nav_5_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_5_label aria-expanded=false> <label class=md-nav__title for=__nav_5> <span class="md-nav__icon md-icon"></span> Community </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_5_2> <label class=md-nav__link for=__nav_5_2 id=__nav_5_2_label tabindex=0> <span class=md-ellipsis> Contribute </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_5_2_label aria-expanded=false> <label class=md-nav__title for=__nav_5_2> <span class="md-nav__icon md-icon"></span> Contribute </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../community/contribute/github/ class=md-nav__link> <span class=md-ellipsis> Github </span> </a> </li> <li class=md-nav__item> <a href=../../../community/contribute/hardware/ class=md-nav__link> <span class=md-ellipsis> Hardware </span> </a> </li> <li class=md-nav__item> <a href=../../../community/contribute/software/ class=md-nav__link> <span class=md-ellipsis> Software </span> </a> </li> <li class=md-nav__item> <a href=../../../community/contribute/documentation/ class=md-nav__link> <span class=md-ellipsis> Documentation </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../../../community/code-of-conduct/ class=md-nav__link> <span class=md-ellipsis> Code of Conduct </span> </a> </li> <li class=md-nav__item> <a href=../../../community/license/ class=md-nav__link> <span class=md-ellipsis> License </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6> <div class="md-nav__link md-nav__container"> <a href=../../../reference/ class="md-nav__link "> <span class=md-ellipsis> Technical Reference </span> </a> <label class="md-nav__link " for=__nav_6 id=__nav_6_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_6_label aria-expanded=false> <label class=md-nav__title for=__nav_6> <span class="md-nav__icon md-icon"></span> Technical Reference </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_2> <label class=md-nav__link for=__nav_6_2 id=__nav_6_2_label tabindex=0> <span class=md-ellipsis> Hardware </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_6_2_label aria-expanded=false> <label class=md-nav__title for=__nav_6_2> <span class="md-nav__icon md-icon"></span> Hardware </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/hardware/product-specs/ class=md-nav__link> <span class=md-ellipsis> Product Specifications </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/hardware/hat/ class=md-nav__link> <span class=md-ellipsis> Planktoscope HAT </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/hardware/changelog/ class=md-nav__link> <span class=md-ellipsis> Changelog </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3> <label class=md-nav__link for=__nav_6_3 id=__nav_6_3_label tabindex=0> <span class=md-ellipsis> Software </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_6_3_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3> <span class="md-nav__icon md-icon"></span> Software </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/product-specs/ class=md-nav__link> <span class=md-ellipsis> Product Specifications </span> </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3_2> <label class=md-nav__link for=__nav_6_3_2 id=__nav_6_3_2_label tabindex=0> <span class=md-ellipsis> Architecture </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_6_3_2_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3_2> <span class="md-nav__icon md-icon"></span> Architecture </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/architecture/os/ class=md-nav__link> <span class=md-ellipsis> Operating System </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3_3> <label class=md-nav__link for=__nav_6_3_3 id=__nav_6_3_3_label tabindex=0> <span class=md-ellipsis> Functionalities </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_6_3_3_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3_3> <span class="md-nav__icon md-icon"></span> Functionalities </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/functionalities/camera-settings/ class=md-nav__link> <span class=md-ellipsis> Camera Settings </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/functionalities/sample-imaging/ class=md-nav__link> <span class=md-ellipsis> Sample Imaging </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/functionalities/segmentation/ class=md-nav__link> <span class=md-ellipsis> Image Segmentation </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3_4> <label class=md-nav__link for=__nav_6_3_4 id=__nav_6_3_4_label tabindex=0> <span class=md-ellipsis> Interfaces </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_6_3_4_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3_4> <span class="md-nav__icon md-icon"></span> Interfaces </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/interfaces/mqtt/ class=md-nav__link> <span class=md-ellipsis> MQTT API </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/interfaces/exported-metadata/ class=md-nav__link> <span class=md-ellipsis> Exported Metadata </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_6_3_5> <label class=md-nav__link for=__nav_6_3_5 id=__nav_6_3_5_label tabindex=0> <span class=md-ellipsis> Subsystems </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=3 aria-labelledby=__nav_6_3_5_label aria-expanded=false> <label class=md-nav__title for=__nav_6_3_5> <span class="md-nav__icon md-icon"></span> Subsystems </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../../reference/software/subsystems/installation/ class=md-nav__link> <span class=md-ellipsis> Installation </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/subsystems/startup/ class=md-nav__link> <span class=md-ellipsis> Startup </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../../../reference/software/release-process/ class=md-nav__link> <span class=md-ellipsis> Release Process </span> </a> </li> <li class=md-nav__item> <a href=../../../reference/software/changelog/ class=md-nav__link> <span class=md-ellipsis> Changelog </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component=sidebar data-md-type=toc> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> </nav> </div> </div> </div> <div class=md-content data-md-component=content> <article class="md-content__inner md-typeset"> <a href="https://github.com/PlanktoScope/PlanktoScope/edit/master/documentation/docs/setup/hardware/v2.6/index.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4v-2m10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1 2.1 2.1Z"/></svg> </a> <h1>Index</h1> <p>This is a marktext document avec</p> <p><a class=glightbox data-type=image data-width=auto data-height=auto data-desc-position=bottom><img alt src></a></p> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1-2.1-2M12.5 7v5.2l4 2.4-1 1L11 13V7h1.5M11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2v1.8Z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">November 25, 2024</span> </span> </aside> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright PlanktoScope project contributors </div> Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> </div> <div class=md-social> <a href="https://github.com/PlanktoScope" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 480 512"><!-- Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M186.1 328.7c0 20.9-10.9 55.1-36.7 55.1s-36.7-34.2-36.7-55.1 10.9-55.1 36.7-55.1 36.7 34.2 36.7 55.1zM480 278.2c0 31.9-3.2 65.7-17.5 95-37.9 76.6-142.1 74.8-216.7 74.8-75.8 0-186.2 2.7-225.6-74.8-14.6-29-20.2-63.1-20.2-95 0-41.9 13.9-81.5 41.5-113.6-5.2-15.8-7.7-32.4-7.7-48.8 0-21.5 4.9-32.3 14.6-51.8 45.3 0 74.3 9 108.8 36 29-6.9 58.8-10 88.7-10 27 0 54.2 2.9 80.4 9.2 34-26.7 63-35.2 107.8-35.2 9.8 19.5 14.6 30.3 14.6 51.8 0 16.4-2.6 32.7-7.7 48.2 27.5 32.4 39 72.3 39 114.2zm-64.3 50.5c0-43.9-26.7-82.6-73.5-82.6-18.9 0-37 3.4-56 6-14.9 2.3-29.8 3.2-45.1 3.2-15.2 0-30.1-.9-45.1-3.2-18.7-2.6-37-6-56-6-46.8 0-73.5 38.7-73.5 82.6 0 87.8 80.4 101.3 150.4 101.3h48.2c70.3 0 150.6-13.4 150.6-101.3zm-82.6-55.1c-25.8 0-36.7 34.2-36.7 55.1s10.9 55.1 36.7 55.1 36.7-34.2 36.7-55.1-10.9-55.1-36.7-55.1z"/></svg> </a> <a href="https://planktoscope.slack.com" target="_blank" rel="noopener" title="planktoscope.slack.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M94.12 315.1c0 25.9-21.16 47.06-47.06 47.06S0 341 0 315.1c0-25.9 21.16-47.06 47.06-47.06h47.06v47.06zm23.72 0c0-25.9 21.16-47.06 47.06-47.06s47.06 21.16 47.06 47.06v117.84c0 25.9-21.16 47.06-47.06 47.06s-47.06-21.16-47.06-47.06V315.1zm47.06-188.98c-25.9 0-47.06-21.16-47.06-47.06S139 32 164.9 32s47.06 21.16 47.06 47.06v47.06H164.9zm0 23.72c25.9 0 47.06 21.16 47.06 47.06s-21.16 47.06-47.06 47.06H47.06C21.16 243.96 0 222.8 0 196.9s21.16-47.06 47.06-47.06H164.9zm188.98 47.06c0-25.9 21.16-47.06 47.06-47.06 25.9 0 47.06 21.16 47.06 47.06s-21.16 47.06-47.06 47.06h-47.06V196.9zm-23.72 0c0 25.9-21.16 47.06-47.06 47.06-25.9 0-47.06-21.16-47.06-47.06V79.06c0-25.9 21.16-47.06 47.06-47.06 25.9 0 47.06 21.16 47.06 47.06V196.9zM283.1 385.88c25.9 0 47.06 21.16 47.06 47.06 0 25.9-21.16 47.06-47.06 47.06-25.9 0-47.06-21.16-47.06-47.06v-47.06h47.06zm0-23.72c-25.9 0-47.06-21.16-47.06-47.06 0-25.9 21.16-47.06 47.06-47.06h117.84c25.9 0 47.06 21.16 47.06 47.06 0 25.9-21.16 47.06-47.06 47.06H283.1z"/></svg> </a> </div> </div> </div> </footer> </div> <div class=md-dialog data-md-component=dialog> <div class="md-dialog__inner md-typeset"></div> </div> <div class=md-progress data-md-component=progress role=progressbar></div> <script id=__config type=application/json>{"base": "../../..", "features": ["navigation.instant", "navigation.instant.progress", "navigation.indexes", "toc.follow", "content.action.edit", "content.code.annotate", "content.code.copy"], "search": "../../../assets/javascripts/workers/search.b8dbb3d2.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src=../../../assets/javascripts/bundle.3220b9d7.min.js></script> <script id=init-glightbox>document.querySelectorAll('.glightbox').forEach(function(element) {
     try {
         var img = element.querySelector('img');
         if (img && img.src) {
diff --git a/site/sitemap.xml.gz b/site/sitemap.xml.gz
index 5197a57735622f9c391580effd5107808430a96c..be6ab3e61c48be3b9af21c4f0868b2d48718616f 100644
GIT binary patch
delta 15
WcmX@aa)^aZzMF$Xar#C!8zulFiv#)q

delta 15
WcmX@aa)^aZzMF&N#<Y!WHcS8~&;+mm