PlanktoScope OS (Sunray) v2024.0.0

[ethanjli]

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 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 exports un-importable by EcoTaxa for datasets with more than ~32,000 objects.
• 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.3

Deprecated

• Various non-functional or partially-broken pages and panels in the current Node-RED dashboard will be removed in the next major release of the PlanktoScope OS. See the deprecations in the v2024.0.0 changelog for details.

Fixed

• The segmenter no longer makes its EcoTaxa exports un-importable by EcoTaxa for datasets with more than ~32,000 objects.

Known Problems

• (Known as of v2024.0.0-beta.2) You may encounter issues with severe lag (latency) in the responsiveness of the camera preview stream. We have occasionally observed this behavior, but it has been difficult for us to reproduce consistently; based on results from the testing we were able to do, we've attempted to minimize occurrence of this behavior with changes in v2024.0.0-beta.3. But we're not sure if it will solve the problem for everyone. If you experience this behavior even after v2024.0.0-beta.2, please let us know!
• (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) 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 (@ethanjli), 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 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

• Update tech ref docs about camera & segmentation functionalities by @ethanjli in Update tech ref docs about camera & segmentation functionalities #503
• Use merge gatekeeper to avoid running slow CI workflows when not needed by @ethanjli in Use merge gatekeeper to avoid running slow CI workflows when not needed #504
• Bump mkdocs-redirects from 1.2.1 to 1.2.2 in /documentation by @dependabot in Bump mkdocs-redirects from 1.2.1 to 1.2.2 in /documentation #501
• Bump poethepoet from 0.29.0 to 0.30.0 in /documentation by @dependabot in Bump poethepoet from 0.29.0 to 0.30.0 in /documentation #500
• Add an operation guide for network-related administration by @ethanjli in Add an operation guide for network-related administration #506
• Replace PDFs of v2 & v3 of Fabien's protocol with a v4 draft by @ethanjli in Replace PDFs of v2 & v3 of Fabien's protocol with a v4 draft #509
• Fix incorrect use of img_rank field in EcoTaxa export metadata by @ethanjli in Fix incorrect use of img_rank field in EcoTaxa export metadata #505
• Clarify documentation of URLs for accessing the software by @ethanjli in Clarify documentation of URLs for accessing the software #510
• Add an operations guide for upgrading/downgrading/resetting the OS by @ethanjli in Add an operations guide for upgrading/downgrading/resetting the OS #511
• Bump jinja2 from 3.1.4 to 3.1.5 in /documentation by @dependabot in Bump jinja2 from 3.1.4 to 3.1.5 in /documentation #512
• Bump version numbers for v2024.0.0 by @ethanjli in Bump version numbers for v2024.0.0 #513

Full Changelog: software/v2024.0.0-beta.3...software/v2024.0.0

---

This discussion was created from the release PlanktoScope OS (Sunray) v2024.0.0.