software/v2025.0.0

We're very happy to share the new release of the PlanktoScope software. We encourage users to update. You can follow official instructions.

Highlights 🌟

Acquisitions parameters now permit using 500µm Capillary flowcell. You can contact FairScope to procure them.

When you press the "Start Acquisition" button, it now automatically adjusts the system time to match the time in your web browser, to ensure datasets are created with correct timestamps. The PlanktoScope remains in UTC+0.

The focus distance was incorrect. The focus will now exactly move by the distance specified in optics configuration.

The default white balance values have been adjusted to provide a better default experience. If you get your PlanktoScope from FairScope, the white balance is always re-calibrated to the most accurate value.

The sample page's "Dilution Factor" input field was misleading and has been renamed to "Concentration Factor" and now defaults to 1.0.

The ISO value stored in dataset metadata now correctly matches the user-set ISO setting, instead of being a constant scaling of the image gain.

We fixed a bug where the pump would stop when using focus.

Several features which were unused or unmaintained have been removed:

• USB backup
• Connect to WiFi
• GPS support
• Desktop images
• PWM LED
• Second LED
• Waveshare stepper HAT support
• Display module

We understand that removing functionalities may be disappointing, but it allows our small development team to focus on core features and reliability. Please get in touch if you'd like to contribute or bring back one of them.

Contributors ❤️

In no particular order

@ethanjli @sonnyp @jeremyszym @tcebron @LaurentPV @W7CH @chevreuill3000

Full changelog 👨‍💻

software/v2024.0.0...software/v2025.0.0

software/v2025.0.0-alpha.3

What's Changed

• Fix controller service dependency by @sonnyp in #695

Full Changelog: software/v2025.0.0-alpha.2...software/v2025.0.0-alpha.3

Know issues

After turning on the PlanktoScope, the hardware controller may take time to start. Please give it some time if preview/focus/pump/light doesn't respond immediately.

software/v2025.0.0-alpha.2

• Fix controller taking too long to restart @sonnyp
• Add 500µm Capillary flowcell #667 @tcebron
• Fix configuration of planktoscopehat-latest 26977bb @sonnyp
• Update default white balance values #678 @tcebron
• Correct the focus distance #693 @jeremyszym

Full Changelog: software/v2025.0.0-alpha.1...software/v2025.0.0-alpha.2

software/v2025.0.0-alpha.1

Changes since v2025.0.0-alpha.0

• Fix segmenter not starting #633
• Remove "PlanktoScope v3.0" configuration / option

software/v2025.0.0-alpha.0

The v2025.0.0 software release, which is part of the "Calico" series of software releases started with v2025.0.0, includes various incremental fixes/improvements for PlanktoScope to improve usability, along with big lower-level technical changes.

About this pre-release

PlanktoScope OS v2025.0.0 is a pre-release version for developers and advanced users to test out. It may have undiscovered software bugs, breakage, and other problems. If you decide to try out this pre-release, please file bug reports on GitHub Issues or informally let us know about any bugs you encounter in the #6-dev-software channel on the PlanktoScope Slack workspace! Here are quick links to the SD card images - you should download the image specific to your PlanktoScope hardware version:

• fairscope-latest: use this if your PlanktoScope hardware is v2.6.

• planktoscopehat: use this if your PlanktoScope hardware is v2.5, v2.3, or some other nonstandard design using the PlanktoScope HAT. Note: you can also use this SD card image on the v2.6 PlanktoScope hardware, it'll just have a setup step on the Node-RED dashboard's homepage which you wouldn't need to do if you used the fairscope-latest image.

• adafruithat: use this if your PlanktoScope hardware is v2.1 or some other nonstandard design using the Adafruit Stepper HAT.

Contributors

The PlanktoScope OS is a community effort, and the v2025.0.0 release would not have been possible without the PlanktoScope community:

• Thanks to (in alphabetical order) Fabien Lombard (@fabienlombard), Morgan Coulm (@redhox), Satoshi Kitajima (@kitazy52), Steven Herbert Gerd Fleischer (@Guelakais), and Thibaut Pollina (@chevreuill3000) for contributing feature requests, improvement suggestions, bug reports, and software+documentation testing efforts for this release!

Notable changes since v2024.0.0

Here we only list items we think most people are likely to notice or to need to know about as end-users; for a full changelog, please refer to software/CHANGELOG.md.

Added

• If your PlanktoScope is connected to a Wi-Fi network with a captive portal, you now should be able to access and proceed through the captive portal from a computer/phone connected to the PlanktoScope.
• The PlanktoScope now supports creating its own Wi-Fi hotspot while simultaneously being connected to the internet via a Wi-Fi network, if you plug in a supported USB Wi-Fi dongle. For more information, refer to our Networking operations guide’s section on how to connect your PlanktoScope to the internet.
• The landing page now has a “MAC address viewer” link to show you your PlanktoScope’s MAC addresses, in case you need that information to register your PlanktoScope on a Wi-Fi network for internet access.

Changed

• When you press the "Start Acquisition" button in the Node-RED dashboard, it now automatically adjusts the PlanktoScope's system time to match the time in your web browser (but still in UTC time zone on the PlanktoScope) if the times are different by more than one minute. This way, datasets will be created with correct dates in the dataset directory structure even if the PlanktoScope doesn’t have internet access.

Removed

• Various elements of the Node-RED dashboard which were deprecated in v2024.0.0 have now been removed, including the old USB backup functionality.
• Refer to the full changelog for other removals which shouldn’t affect you unless you’re doing something unconventional.

Deprecated

• We plan to remove GPS hardware support after v2025.0.0, in order to enable a potential future unification of the Node-RED dashboard variants for the PlanktoScope HAT vs. the Adafruit HAT (i.e. by just having the Adafruit HAT-based PlanktoScopes use the Node-RED dashboard which is currently being used for the PlanktoScope HAT); note that the OS maintainers make no promises about doing any extra work needed for unification. If you rely on the PlanktoScope v2.1 hardware’s GPS module, please let us know - or else we’ll assume that nobody is using the GPS module!
• Refer to the full changelog for other deprecations which shouldn’t affect you unless you’re doing something unconventional.

Fixed

• We fixed a regression from v2024.0.0 which caused the software to store incorrectly-scaled values for the camera ISO setting in dataset metadata.
• The PlanktoScope’s system time no longer resets back to an earlier time in the past across reboots. Instead, the system time now strictly increases across reboots, even if it’s still in the past (e.g. because you haven’t started an image acquisition since the last reboot).
• planktoscope.local and pkscope.local should now work correctly on local area networks (i.e. when the PlanktoScope is connected to a network router with sufficiently-permissive firewall settings) and not just on direct connections.
• The Node-RED dashboard's sample page's "Dilution Factor" input field has been renamed to "Concentration Factor", which is a less misleading name for what that input field actually represents.
• We fixed a regression from v2023.0.0 which made it impossible to manage dataset files via an SFTP/SCP connection (e.g. with FileZilla).
• We fixed a likely regression from v2024.0.0 in handling certain errors when trying to start image acquisition with a previously-used acquisition ID.

Known Problems

• (Known as of v2023.9.0-beta.0) If you restart the Node-RED dashboard (e.g. via Cockpit), you will also need to manually restart the hardware controller, or else the Node-RED dashboard won’t know the type of camera installed in the PlanktoScope. We are working on a solution to this problem, for a future release after v2025.0.0.
• (Known as of v2025.0.0-alpha.0) The LCD display on the Fan HAT in the adafruithat-based PlanktoScopes doesn’t work. We will try to fix this before the stable release of v2025.0.0.

Planning, management, and maintenance of the v2025.0.0 release of PlanktoScope OS is led by Ethan Li (@ethanjli) and Sonny Piers (@sonnyp), with input and oversight from attendees of the weekly PlanktoScope software development meetings. If this release causes new problems for how you are using PlanktoScope, Ethan & Sonny will take responsibility for addressing new issues caused by this release - just tag them in a new Github Discussions post or in the #6-dev-software channel on the PlanktoScope Slack workspace!

Pull Requests

• Remove raspimjpeg by @ethanjli in #515
• Bump cookie and socket.io in /software/node-red-dashboard by @dependabot in #486
• Bump send and serve-static in /software/node-red-dashboard by @dependabot in #478
• Delete deprecated GUI elements, set default dilution factor by @ethanjli in #516
• Bump Raspberry Pi OS base images & Forklift by @ethanjli in #517
• Bump pymdown-extensions from 10.12 to 10.13 in /documentation by @dependabot in #518
• Simplify & speed up OS build process using Github's arm64 runners by @ethanjli in #520
• Split up the enable-interface-forwarding service by @ethanjli in #521
• Report MAC addresses by @ethanjli in #522
• Rename "Dilution Factor" input field to "Concentration Factor" by @ethanjli in #523
• Bump pymdown-extensions from 10.13 to 10.14.3 in /documentation by @dependabot in #528
• Bump pygments from 2.18.0 to 2.19.1 in /documentation by @dependabot in #529
• Bump caddy from 2.8.4 to 2.9.1 in /documentation by @dependabot in #527
• Migrate from dhcpcd to NetworkManager by @ethanjli in #526
• Try symlinking from docs to externals (changelog, hardware assets) by @ethanjli in #531
• Add an operations guide for customizing the PlanktoScope OS software by @ethanjli in #534
• Try to remove piwiz from desktop images by @ethanjli in #535
• Fix permissions UX issues with data directories by @ethanjli in #538
• Bump ethanjli/pishrink-action from 0.1.3 to 0.1.4 by @dependabot in #539
• Build adafruithat & planktoscopeha...

PlanktoScope OS v2024.0.0

The v2024.0.0 software release, which is part of the "Sunray" series of software releases started with v2023.9.0, includes major fixes for various problems and improvements to existing functionality with the PlanktoScope software.

About this release

Starting with v2024.0.0, we are calling the software we provide in our SD card images the "PlanktoScope OS" (because it is an operating system for the PlanktoScope).

PlanktoScope OS v2024.0.0 includes major improvements over v2023.9.0, including the complete replacement of the old camera controller which turned out to be buggy in v2023.9.0. Please review the major changes (listed below), try out this release, and formally file bug reports on GitHub Issues or informally let us know about any bugs you encounter in the #6-dev-software channel on the PlanktoScope Slack workspace! Here are quick links to the SD card images - you should download the image specific to your PlanktoScope hardware version:

• fairscope-latest: use this if your PlanktoScope hardware is v2.6.

• planktoscopehat: use this if your PlanktoScope hardware is v2.5, v2.3, or some other nonstandard design using the PlanktoScope HAT. Note: you can also use this SD card image on the v2.6 PlanktoScope hardware, it'll just have a setup step on the Node-RED dashboard's homepage which you wouldn't need to do if you used the fairscope-latest image.

• adafruithat: use this if your PlanktoScope hardware is v2.1 or some other nonstandard design using the Adafruit Stepper HAT.

Contributors

The PlanktoScope OS is a community effort, and the v2024.0.0 release would not have been possible without the PlanktoScope community:

• Thanks to Wassim Chakroun (@W7CH) for code contributions in the new picamera2-based image-acquisition module; and to Romain Fauvel (@RomainFauvel) for a code contribution in the segmenter!
• Thanks to Thibaut Pollina (@tpollina) and Melissa Djadoun (@melissadjadoun) for documentation contributions!
• Thanks to (in alphabetical order) Ana Fernandez Carrera, Adam Larson (@babo989), Fabien Lombard (@fabienlombard), Guillaume Leguen (@gheleguen), Johan Viljoen, Kevin Du Close (@kevin-duclos), Loïc Vassaux-Artur (@bayous), Melissa Djadoun (@melissadjadoun), Morgan Coulm (@redhox), Oumayma Elbez (@Oumayma-hy), Satoshi Kitajima (@kitazy52), Patrick White, Pierre Kostyrka (@pkostyrka), Tanguy Cebron, Thibaut Pollina (@tpollina), and Wassim Chakroun (@W7CH), for contributing feature requests, bug reports, and software+documentation testing efforts for this release!
• Special thanks to Fabien and Satoshi for a heroic troubleshooting effort with a tricky, hard-to-reproduce bug involving the new camera driver introduced for v2024.0.0!

Changelog since v2023.9.0

This changelog only lists items we think you are likely to notice or to need to know about; for a full list of changes, please refer to software/CHANGELOG.md.

Added

• A fairscope-latest SD card image is now built for FairScope customers; its only difference from the planktoscopehat SD card image is that the default hardware settings are set for the v2.6 hardware, instead of the v2.5 hardware.
• On the Node-RED dashboard, the System Monitoring page will now prompt you to reset the PlanktoScope's system clock to match the time from your web browser, if the two times are very different. This enables you to temporarily fix an inaccurate system clock on your PlanktoScope, at least until the next time you unplug the PlanktoScope from power.
• The PlanktoScope now shares internet access over its Wi-Fi hotspot and Ethernet port (and a USB-to-Ethernet adapter, if one is attached) from a phone connected to it in USB tethering mode.

Changed

• The pscopehat version of the SD card image has been renamed to planktoscopehat for more consistent naming.
• The first time you boot up the planktoscopehat SD card image, the Node-RED dashboard's homepage will ask you to select the hardware version of your PlanktoScope - instead of assuming that you are using the v2.5 hardware (and providing default hardware settings for the v2.5 hardware).
• The hardware controller's camera driver has been fully rewritten to fix various problems we had with raspimjpeg (which has now been replaced with a different camera control mechanism). This change may require you to use different ISO and white balance gains than before; accordingly, the Node-RED dashboard's ISO selector has been changed to a slider to enable finer adjustment of the ISO setting, and the default ISO value has been changed from 100 to 150.
• 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. WARNING: This changes the data-processing behavior of the segmenter, resulting in slightly different outputs compared to the previous version of the segmenter even for the same input datasets!
• The PlanktoScope OS is now built as a 64-bit OS, instead of a 32-bit OS. This change speeds up the segmenter, potentially by a factor of 2.
• On the Node-RED dashboard, the System Monitoring page’s monitoring panel has been replaced with an embedded Grafana dashboard, with additional graphs available in an expandable subpanel.
• SD card images are now provided as .img.xz files instead of .img.gz files; they will still work with the Raspberry Pi Imager software.

Deprecated

• 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 or on the PlanktoScope Slack.
• The "USB backup" functionality of the Node-RED dashboard will be removed after v2024.0.0. Instead, you should use the datasets file browser (which you can access by a link on the PlanktoScope's landing page) for backing up and deleting dataset files on your PlanktoScope.
• Various other non-functional or partially-broken pages and panels in the current Node-RED dashboard will also be removed in the next major release of the PlanktoScope OS. See the deprecations in the v2024.0.0 changelog for details.
• 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 the next major release.
• Portainer will no longer be installed/provided by default after v2024.0.0, because it takes up lots of disk space and it is difficult to set up and its functionality overlaps with the much simpler Dozzle. After we remove Portainer from the default SD card image, you can use Forklift to install Portainer.
• Now that the PlanktoScope project is building 64-bit versions of the PlanktoScope OS, 32-bit versions of the PlanktoScope OS are no longer built or officially supported by the project. However, for v2024.0.0 you can still use the installer scripts (with the PlanktoScope OS's non-standard installation process) to set up the PlanktoScope OS on 32-bit base images of the Raspberry Pi OS. After v2024.0.0 we will no longer test whether the installer scripts work on 32-bit Raspberry Pi OS images.

Fixed

• The segmenter's previously incorrect method for filtering segmented objects by size has now been corrected to filter object sizes by filled area rather than bounding box area, and directly using the mesh size as the threshold for equivalent spherical diameter (ESD) instead of calculating a fictional ESD. WARNING: This changes the data-processing behavior of the segmenter, resulting in slightly different outputs compared to the previous version of the segmenter even for the same input datasets!
• The segmenter no longer makes its EcoTaxa e...

PlanktoScope OS v2024.0.0-beta.3

The v2024.0.0 software release, which is part of the "Sunray" series of software releases started with v2023.9.0, includes major fixes for various problems and improvements to existing functionality with the PlanktoScope software.

About this pre-release

Starting with v2024.0.0, we are calling the software we provide in our SD card images the "PlanktoScope OS" (because it is an operating system for the PlanktoScope).

PlanktoScope OS v2024.0.0-beta.3 is a pre-release version for everyone to test out. It is a release candidate: v2024.0.0-beta.3 will most likely be promoted to the v2024.0.0 stable release. Please try out this pre-release and file bug reports on GitHub Issues and/or let us know about any bugs you discover in the #6-dev-software channel on the PlanktoScope Slack workspace! Here are quick links to the SD card images - you should download the image specific to your PlanktoScope hardware version:

• fairscope-latest: use this if your PlanktoScope hardware is v2.6.

• planktoscopehat: use this if your PlanktoScope hardware is v2.5, v2.3, or some other nonstandard design using the PlanktoScope HAT. Note: you can also use this SD card image on the v2.6 PlanktoScope hardware, it'll just have a setup step on the Node-RED dashboard's homepage which you wouldn't need to do if you used the fairscope-latest image.

• adafruithat: use this if your PlanktoScope hardware is v2.1 or some other nonstandard design using the Adafruit Stepper HAT.

Contributors

The PlanktoScope OS is a community effort, and the v2024.0.0 release would not have been possible without the PlanktoScope community:

• Thanks to Wassim Chakroun (@W7CH) for code contributions in the new picamera2-based image-acquisition module; and to Romain Fauvel (@RomainFauvel) for a code contribution in the segmenter!
• Thanks to Thibaut Pollina (@tpollina) and Melissa Djadoun (@melissadjadoun) for documentation contributions!
• Thanks to (in alphabetical order) Ana Fernandez Carrera, Adam Larson (@babo989), Fabien Lombard (@fabienlombard), Guillaume Leguen (@gheleguen), Johan Viljoen, Kevin Du Clos (@kevin-duclos), Loïc Vassaux-Artur (@BiyouS), Melissa Djadoun (@melissadjadoun), Morgan Coulm (@redhox), Oumayma Elbez (@Oumayma-hy), Satoshi Kitajima (@kitazy52), Patrick White, Pierre Kostyrka (@pkostyrka), Tanguy Cebron, Thibaut Pollina (@tpollina), and Wassim Chakroun (@W7CH), for contributing feature requests, bug reports, and software+documentation testing efforts for this release!
• Special thanks to Fabien and Satoshi for a heroic troubleshooting effort with a tricky, hard-to-reproduce bug involving the new camera driver introduced for v2024.0.0!

Changelog since v2023.9.0

This changelog only lists items we think you are likely to notice or to need to know about; for a full list of changes, please refer to software/CHANGELOG.md.

Added:

• A fairscope-latest SD card image is now built for FairScope customers; its only difference from the planktoscopehat SD card image is that the default hardware settings are set for the v2.6 hardware, instead of the v2.5 hardware.
• The PlanktoScope now shares internet access over its Wi-Fi hotspot and Ethernet port (and a USB-to-Ethernet adapter, if one is attached) from a phone connected to it in USB tethering mode.
• On the Node-RED dashboard, the System Monitoring page will now prompt you to reset the PlanktoScope's system clock to match the time from your web browser, if the two times are very different. This enables you to temporarily fix an inaccurate system clock on your PlanktoScope, at least until the next time you unplug the PlanktoScope from power.

Changed:

• The pscopehat version of the SD card image has been renamed to planktoscopehat for more consistent naming.
• The first time you boot up the planktoscopehat SD card image, the Node-RED dashboard's homepage will ask you to select the hardware version of your PlanktoScope - instead of assuming that you are using the v2.5 hardware (and providing default hardware settings for the v2.5 hardware).
• The hardware controller's camera driver has been fully rewritten to fix various problems we had with raspimjpeg (which has now been replaced with a different camera control mechanism). This change may require you to use different ISO and white balance gains than before; accordingly, the Node-RED dashboard's ISO selector has been changed to a slider to enable finer adjustment of the ISO setting.
• 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. WARNING: This changes the data-processing behavior of the segmenter, resulting in slightly different outputs compared to the previous version of the segmenter even for the same input datasets!
• The PlanktoScope OS is now built as a 64-bit OS, instead of a 32-bit OS. This change speeds up the segmenter, potentially by a factor of 2.
• On the Node-RED dashboard, the System Monitoring page’s monitoring panel has been replaced with an embedded Grafana dashboard, with additional graphs available in an expandable subpanel.
• SD card images are now provided as .img.xz files instead of .img.gz files; they will still work with the Raspberry Pi Imager software.
• The default ISO value is now 150 instead of 100.

Deprecated:

• 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 or on the PlanktoScope Slack.
• The "USB backup" functionality of the Node-RED dashboard will be removed after v2024.0.0. Instead, you should use the datasets file browser (which you can access by a link on the PlanktoScope's landing page) for backing up and deleting dataset files on your PlanktoScope.
• 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 after we get sufficient information about the picamera2-based imaging module's reliability for PlanktoScope users.
• Portainer will no longer be installed/provided by default after v2024.0.0, because it takes up lots of disk space and it is difficult to set up and its functionality overlaps with the much simpler Dozzle. After we remove Portainer from the default SD card image, you can use Forklift to install Portainer.
• Now that the PlanktoScope project is building 64-bit versions of the PlanktoScope OS, 32-bit versions of the PlanktoScope OS are no longer built or officially supported by the project. However, for v2024.0.0 you can still use the installer scripts (with the PlanktoScope OS's non-standard installation process) to set up the PlanktoScope OS on 32-bit base images of the Raspberry Pi OS. After v2024.0.0 we may stop testing whether the installer scripts work on 32-bit Raspberry Pi OS images.

Fixed:

• The segmenter's previously incorrect method for filtering segmented objects by size has now been corrected to filter object sizes by filled area rather than bounding box area, and directly using the mesh size as the threshold for equivalent spherical diameter (ESD) instead of calculating a fictional ESD. WARNING: This changes the data-processing behavior of the segmenter, resulting in slightly different outputs compared to the previous version of the segmenter even for the same input datasets!
• The segmenter now includes 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 t...

PlanktoScope OS v2024.0.0-beta.2

The v2024.0.0 software release, which is part of the "Sunray" series of software releases started with v2023.9.0, includes major fixes for various problems and improvements to existing functionality with the PlanktoScope software.

About this pre-release

Starting with v2024.0.0, we are calling the software we provide in our SD card images the "PlanktoScope OS" (because it is an operating system for the PlanktoScope).

PlanktoScope OS v2024.0.0-beta.2 is a pre-release version for everyone to test out. It is a release candidate: if no major software regressions are discovered and reported, v2024.0.0-beta.2 will be promoted to the v2024.0.0 stable release. Please try out this pre-release and file bug reports on GitHub Issues and/or let us know about any bugs you discover in the #6-dev-software channel on the PlanktoScope Slack workspace! Here are quick links to the SD card images - you should download the image specific to your PlanktoScope hardware version:

• fairscope-latest: use this if your PlanktoScope hardware is v2.6.

• planktoscopehat: use this if your PlanktoScope hardware is v2.5, v2.3, or some other nonstandard design using the PlanktoScope HAT. Note: you can also use this SD card image on the v2.6 PlanktoScope hardware, it'll just have a setup step on the Node-RED dashboard's homepage which you wouldn't need to do if you used the fairscope-latest image.

• adafruithat: use this if your PlanktoScope hardware is v2.1 or some other nonstandard design using the Adafruit Stepper HAT.

Contributors

The PlanktoScope OS is a community effort, and the v2024.0.0 release would not have been possible without the PlanktoScope community:

• Thanks to Wassim Chakroun (@W7CH) for code contributions in the new picamera2-based image-acquisition module; and to Romain Fauvel (@RomainFauvel) for a code contribution in the segmenter!
• Thanks to Thibaut Pollina (@tpollina) and Melissa Djadoun (@melissadjadoun) for documentation contributions!
• Thanks to (in alphabetical order) Ana Fernandez Carrera, Adam Larson (@babo989), Fabien Lombard (@fabienlombard), Guillaume Leguen (@gheleguen), Johan Viljoen, Kevin Du Clos (@kevin-duclos), Loïc Vassaux--Artur (@BiyouS), Melissa Djadoun (@melissadjadoun), Morgan Coulm (@redhox), Oumayma Elbez (@Oumayma-hy), Satoshi Kitajima (@kitazy52), Patrick White, Pierre Kostyrka (@pkostyrka), Tanguy Cebron, Thibaut Pollina (@tpollina), and Wassim Chakroun (@W7CH), for contributing feature requests, bug reports, and software+documentation testing efforts for this release!

Changelog since v2023.9.0

This changelog only lists items we think you are likely to notice or to need to know about; for a full list of changes, please refer to software/CHANGELOG.md.

Added:

• A fairscope-latest SD card image is now built for FairScope customers; its only difference from the planktoscopehat SD card image is that the default hardware settings are set for the v2.6 hardware, instead of the v2.5 hardware.
• The PlanktoScope now shares internet access over its Wi-Fi hotspot and Ethernet port (and a USB-to-Ethernet adapter, if one is attached) from a phone connected to it in USB tethering mode.
• On the Node-RED dashboard, the System Monitoring page will now prompt you to reset the PlanktoScope's system clock to match the time from your web browser, if the two times are very different. This enables you to temporarily fix an inaccurate system clock on your PlanktoScope, at least until the next time you unplug the PlanktoScope from power.

Changed:

• The pscopehat version of the SD card image has been renamed to planktoscopehat for more consistent naming.
• The first time you boot up the planktoscopehat SD card image, the Node-RED dashboard's homepage will ask you to select the hardware version of your PlanktoScope - instead of assuming that you are using the v2.5 hardware (and providing default hardware settings for the v2.5 hardware).
• The hardware controller's camera driver has been fully rewritten to fix various problems we had with raspimjpeg (which has now been replaced with a different camera control mechanism). This change may require you to use different ISO and white balance gains than before; accordingly, the Node-RED dashboard's ISO selector has been changed to a slider to enable finer adjustment of the ISO setting.
• 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.
• The PlanktoScope OS is now built as a 64-bit OS, instead of a 32-bit OS. This change speeds up the segmenter, potentially by a factor of 2.
• On the Node-RED dashboard, the System Monitoring page’s monitoring panel has been replaced with an embedded Grafana dashboard, with additional graphs available in an expandable subpanel.
• SD card images are now provided as .img.xz files instead of .img.gz files; they will still work with the Raspberry Pi Imager software.
• The default ISO value is now 150 instead of 100.

Deprecated:

• 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 or on the PlanktoScope Slack.
• 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 (which you can access by a link on the PlanktoScope's landing page) for backing up and deleting dataset files on your PlanktoScope.
• 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 after we get sufficient information about the picamera2-based imaging module's reliability for PlanktoScope users.
• Portainer will no longer be installed/provided by default after v2024.0.0, because it takes up lots of disk space and it is difficult to set up and its functionality overlaps with the much simpler Dozzle. After we remove Portainer from the default SD card image, you can use Forklift to install Portainer.
• Now that the PlanktoScope project is building 64-bit versions of the PlanktoScope OS, 32-bit versions of the PlanktoScope OS are no longer built or officially supported by the project. However, for v2024.0.0 you can still use the installer scripts (with the PlanktoScope OS's non-standard installation process) to set up the PlanktoScope OS on 32-bit base images of the Raspberry Pi OS. After v2024.0.0 we may stop testing whether the installer scripts work on 32-bit Raspberry Pi OS images.

Fixed:

• The segmenter now includes 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 ecotaxa_export.tsv filename for all metadata TSV files.
• The Node-RED dashboard’s “Sample” page’s Filtered Volume field is now exported as the sample_total_volume metadata field for all sample types; previously it was only exported for horizontal plankton tow samples.
• The Node-RED dashboard should now correctly load the flowcell setting from the config.json settings file.
• Startup is now faster.

Changelog since v2024.0.0-beta.1

Changed

• The default ISO value is now 150 instead of 100.

Fixed

• The segmenter now includes the acquisition ID in the filename of the metadata TSV file included with the EcoTaxa export ZIP archive; this is necessary to allow efficient bul...

PlanktoScope OS v2024.0.0-beta.1

The v2024.0.0 software release, which is part of the "Sunray" series of software releases started with v2023.9.0, includes major fixes for various problems and improvements to existing functionality with the PlanktoScope software.

About this pre-release

Starting with v2024.0.0, we are calling the software we provide in our SD card images the "PlanktoScope OS" (because it is an operating system for the PlanktoScope).

PlanktoScope OS v2024.0.0-beta.1 is a pre-release version for everyone to test out. It may have undiscovered software bugs, breakage, and other problems. If you decide to try out this pre-release, please file bug reports on GitHub Issues and/or let us know about any bugs you discover in the #6-dev-software channel on the PlanktoScope Slack workspace! Here are quick links to the SD card images - you should download the image specific to your PlanktoScope hardware version:

• fairscope-latest: use this if your PlanktoScope hardware is v2.6.

• planktoscopehat: use this if your PlanktoScope hardware is v2.5, v2.3, or some other nonstandard design using the PlanktoScope HAT. Note: you can also use this SD card image on the v2.6 PlanktoScope hardware, it'll just have a setup step on the Node-RED dashboard's homepage which you wouldn't need to do if you used the fairscope-latest image.

• adafruithat: use this if your PlanktoScope hardware is v2.1 or some other nonstandard design using the Adafruit Stepper HAT.

Contributors

The PlanktoScope OS is a community effort, and the v2024.0.0 release would not have been possible without the PlanktoScope community:

• Thanks to Wassim Chakroun (@W7CH) for code contributions in the new picamera2-based image-acquisition module!
• Thanks to (in alphabetical order) Ana Fernandez Carrera, Adam Larson (@babo989), Fabien Lombard (@fabienlombard), Kevin Du Clos (@kevin-duclos), Satoshi Kitajima (@kitazy52), Pierre Kostyrka (@pkostyrka), Tanguy Cebron, and Thibaut Pollina (@tpollina), for contributing feature requests, bug reports, and software testing efforts for this release!

Changelog since v2023.9.0

This changelog only lists items we think you are likely to notice or to need to know about; for a full list of changes, please refer to software/CHANGELOG.md.

Added:

• A fairscope-latest SD card image is now built for FairScope customers; its only difference from the planktoscopehat SD card image is that the default hardware settings are set for the v2.6 hardware, instead of the v2.5 hardware.
• The PlanktoScope now shares internet access over its Wi-Fi hotspot and Ethernet port (and a USB-to-Ethernet adapter, if one is attached) from a phone connected to it in USB tethering mode.
• On the Node-RED dashboard, the System Monitoring page will now prompt you to reset the PlanktoScope's system clock to match the time from your web browser, if the two times are very different. This enables you to temporarily fix an inaccurate system clock on your PlanktoScope, at least until the next time you unplug the PlanktoScope from power.

Changed:

• The pscopehat version of the SD card image has been renamed to planktoscopehat for more consistent naming.
• The first time you boot up the planktoscopehat SD card image, the Node-RED dashboard's homepage will ask you to select the hardware version of your PlanktoScope - instead of assuming that you are using the v2.5 hardware (and providing default hardware settings for the v2.5 hardware).
• The hardware controller's camera driver has been fully rewritten to fix various problems we had with raspimjpeg (which has now been replaced with a different camera control mechanism). This change may require you to use different ISO and white balance gains than before; accordingly, the Node-RED dashboard's ISO selector has been changed to a slider to enable finer adjustment of the ISO setting.
• 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.
• The PlanktoScope OS is now built as a 64-bit OS, instead of a 32-bit OS. This change speeds up the segmenter, potentially by a factor of 2.
• On the Node-RED dashboard, the System Monitoring page’s monitoring panel has been replaced with an embedded Grafana dashboard, with additional graphs available in an expandable subpanel.
• SD card images are now provided as .img.xz files instead of .img.gz files; they will still work with the Raspberry Pi Imager software.

Deprecated:

• 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 or on the PlanktoScope Slack.
• 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 (which you can access by a link on the PlanktoScope's landing page) for backing up and deleting dataset files on your PlanktoScope.
• 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 after we get sufficient information about the picamera2-based imaging module's reliability for PlanktoScope users.
• Portainer will no longer be installed/provided by default after v2024.0.0, because it takes up lots of disk space and it is difficult to set up and its functionality overlaps with the much simpler Dozzle. After we remove Portainer from the default SD card image, you can use Forklift to install Portainer.
• Now that the PlanktoScope project is building 64-bit versions of the PlanktoScope OS, 32-bit versions of the PlanktoScope OS are no longer built or officially supported by the project. However, for v2024.0.0 you can still use the installer scripts (with the PlanktoScope OS's non-standard installation process) to set up the PlanktoScope OS on 32-bit base images of the Raspberry Pi OS. After v2024.0.0 we may stop testing whether the installer scripts work on 32-bit Raspberry Pi OS images.

Fixed:

• The Node-RED dashboard’s “Sample” page’s Filtered Volume field is now exported as the sample_total_volume metadata field for all sample types; previously it was only exported for horizontal plankton tow samples.
• The Node-RED dashboard should now correctly load the flowcell setting from the config.json settings file.
• Startup is now faster.

Changelog since v2024.0.0-beta.0

Added

• A fairscope-latest SD card image is now built for FairScope customers; its only difference from the planktoscopehat SD card image is that the default hardware settings are set for the v2.6 hardware, instead of the v2.5 hardware.

Changed

• The first time you boot up the planktoscopehat SD card image, the Node-RED dashboard's homepage will ask you to select the hardware version of your PlanktoScope - instead of assuming that you are using the v2.5 hardware (and providing default hardware settings for the v2.5 hardware).

• SD card images are now provided as .img.xz files instead of .img.gz files; they will still work with the Raspberry Pi Imager software.

Fixed

• The Node-RED dashboard should now correctly load the flowcell setting from the config.json settings file.

Known Problems

• (Known as of v2023.9.0-beta.1) You may encounter weird behavior with the system time if you try to use Cockpit to manually adjust the system clock. If you experience this problem, please report it and your testing circumstances (e.g. your GPS situation, and the time you tried to change the system clock to), to help us determin...

PlanktoScope OS v2024.0.0-beta.0

The v2024.0.0 software release, which is part of the "Sunray" series of software releases started with v2023.9.0, includes major fixes for various problems and improvements to existing functionality with the PlanktoScope Operating System (PlanktoScope OS).

About this pre-release

Starting with this beta pre-release, we are calling the software we provide in our SD card images the "PlanktoScope OS" (because it is an operating system for the PlanktoScope).

PlanktoScope OS v2024.0.0-beta.0 is a pre-release version for everyone to test out. It may have undiscovered software bugs, breakage, and other problems. If you decide to try out this pre-release, please file bug reports on GitHub Issues and/or let us know about any bugs you discover in the #6-dev-software channel on the PlanktoScope Slack workspace!

Contributors

The PlanktoScope OS is a community effort, and the v2024.0.0 release would not have been possible without the PlanktoScope community:

• Thanks to Wassim Chakroun (@W7CH) for code contributions in the new picamera2-based image-acquisition module!
• Thanks to (in alphabetical order) Ana Fernandez Carrera, Adam Larson (@babo989), Fabien Lombard (@fabienlombard), Kevin Du Clos (@kevin-duclos), Satoshi Kitajima (@kitazy52), Pierre Kostyrka (@pkostyrka), Tanguy Cebron, and Thibaut Pollina (@tpollina), for contributing feature requests, bug reports, and software testing efforts for this release!

Changelog since v2023.9.0

This changelog only lists items we think users are likely to notice or to need to know about; for a full list of changes, please refer to software/CHANGELOG.md.

Added:

• The PlanktoScope now shares internet access over its Wi-Fi hotspot and Ethernet port (and a USB-to-Ethernet adapter, if one is attached) from a phone connected to it in USB tethering mode.
• On the Node-RED dashboard, the System Monitoring page will now prompt you to reset the PlanktoScope's system clock to match the time from your web browser, if the two times are very different. This enables you to temporarily fix an inaccurate system clock on your PlanktoScope, at least until the next time you unplug the PlanktoScope from power.

Changed:

• The pscopehat version of the SD card image has been renamed to planktoscopehat for more consistent naming.
• On the planktoscopehat version of the SD card image, the default hardware configuration has been changed from the v2.5 PlanktoScope hardware to the v2.6 hardware. If you're upgrading the software on a PlanktoScope with v2.5 hardware, you will need to change the hardware configuration back to v2.5 on the "Hardware Settings" page of the Node-RED dashboard.
• The hardware controller's camera driver has been fully rewritten to fix various problems we had with raspimjpeg (which has now been replaced with a different camera control mechanism). This change may require you to use different ISO and white balance gains than before; accordingly, the Node-RED dashboard's ISO selector has been changed to a slider to enable finer adjustment of the ISO setting.
• 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.
• The PlanktoScope OS is now built as a 64-bit OS, instead of a 32-bit OS. This change speeds up the segmenter, potentially by a factor of 2.
• On the Node-RED dashboard, the System Monitoring page’s monitoring panel has been replaced with an embedded Grafana dashboard, with additional graphs available in an expandable subpanel.

Deprecated:

• 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 or on the PlanktoScope Slack.
• 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 (which you can access by a link on the PlanktoScope's landing page) for backing up and deleting dataset files on your PlanktoScope.
• 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 after we get sufficient information about the picamera2-based imaging module's reliability for PlanktoScope users.
• Portainer will no longer be installed/provided by default after v2024.0.0, because it takes up lots of disk space and it is difficult to set up and its functionality overlaps with the much simpler Dozzle. After we remove Portainer from the default SD card image, you can use Forklift to install Portainer.
• Now that the PlanktoScope project is building 64-bit versions of the PlanktoScope OS, 32-bit versions of the PlanktoScope OS are no longer built or officially supported by the project. However, for v2024.0.0 you can still use the installer scripts (with the PlanktoScope OS's non-standard installation process) to set up the PlanktoScope OS on 32-bit base images of the Raspberry Pi OS. After v2024.0.0 we may stop testing whether the installer scripts work on 32-bit Raspberry Pi OS images.

Fixed:

• The Node-RED dashboard’s “Sample” page’s Filtered Volume field is now exported as the sample_total_volume metadata field for all sample types; previously it was only exported for horizontal plankton tow samples.
• Startup is now faster.

Changelog since v2024.0.0-alpha.2

Changed

• The PlanktoScope OS is now built as a 64-bit OS. This change speeds up the segmenter, potentially by a factor of 2.

• The Node-RED dashboard's ISO selector has been changed to a slider to enable finer adjustment of the ISO setting.

Deprecated

• Now that the PlanktoScope project is building 64-bit versions of the PlanktoScope OS, 32-bit versions of the PlanktoScope OS are no longer built or officially supported by the project. However, for v2024.0.0 you can still use the installer scripts (with the PlanktoScope OS's non-standard installation process) to set up the PlanktoScope OS on 32-bit base images of the Raspberry Pi OS.

Fixed

• Because v2024.0.0-alpha.2 had fixed an incorrect formula for converting the ISO setting to an image gain for the camera hardware, in that pre-release it was possible (in the planktoscopehat build of the PlanktoScope OS) to use the Node-RED dashboard to attempt to set an ISO value (anything above 650) which would be rejected and ignored by the Python hardware controller because it resulted in an image gain value above the maximum allowed value. Now the planktoscopehat version of the Node-RED dashboard limits the ISO setting to 650.

Known Problems

• (Known as of v2024.0.0-beta.0) In some cases, changing the ISO setting may cause the camera preview to disappear. You can reload the camera preview by refreshing your web browser tab. We will fix this problem before the v2024.0.0 stable release.
• (Known as of v2023.9.0-beta.1) You may encounter weird behavior with the system time if you try to use Cockpit to manually adjust the system clock. If you experience this problem, please report it and your testing circumstances (e.g. your GPS situation, and the time you tried to change the system clock to), to help us determine why this problem is happening for you, so that we can fix it!
• (Known as of v2023.9.0-beta.0) In certain cases, some computers connected to both a Wi-Fi network providing internet access and to a PlanktoScope may be unable to access anything on the internet. If you experience this problem, please report it and your testing circumstances (e.g. your OS, your network configuration for internet access, etc.), to help us determine why this problem is happening for you, so that we can fix it!
• (Known as of v2023.9.0-beta.0) If you restart the Node-RED dashboard (e.g. via Cockpit), you will also need to manually restart the hardware controller, or else the Node-RED dashboard won’t know the type of camera installed in the PlanktoScope. We are working on a solution to this problem, for a future release after v2024.0.0.

Planning, management, and maintenance of the v2024.0.0 release of PlanktoScope OS is led by Ethan Li (...