software/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 (Sunray) 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 (Sunray) 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 (...

PlanktoScope OS (Sunray) v2024.0.0-alpha.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 Operating System (PlanktoScope OS).

About this pre-release

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

PlanktoScope OS v2024.0.0-alpha.2 is a pre-release version for developers 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.
• 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.
• 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 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 its 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.

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

Changed

• 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 image quality of frames in the camera preview stream is increased, and frames also have greater width and height (960x720); previously, it was 640x480.

• The default settings configuration file for the planktoscopehat SD card image is now for the v2.6 PlanktoScope hardware; previously, it was still for the v2.5 hardware.

Deprecated

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

Fixed

• The incorrect scaling factor for converting between ISO settings (in the Node-RED dashboard) and camera image gains in the new picamera2-based imager is fixed. This should cause images (and the camera preview) to appear brighter than v2024.0.0-alpha.1 when the same ISO settings are used.

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

Software: Sunray v2024.0.0-alpha.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

Software v2024.0.0-alpha.1 is a pre-release version for developers to test out. It probably has 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 software distro is a community effort, and this release would not have been possible without the PlanktoScope community:

• Thanks to @W7CH for code contributions in the new picamera2-based image-acquisition module!
• Thanks to (in alphabetical order) Ana Fernandez Carrera, @babo989, @fabienlombard, @kevin-duclos, @kitazy52, @pkostyrka, and @tpollina, for contributing feature requests, bug reports, and software testing efforts for this release!

Changelog since v2024.0.0-alpha.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.

Changed:

• The hardware controller now uses picamera2 instead of raspimjpeg for camera control; this fixes various issues we had with raspimjpeg. This change may require different ISO and white balance gains to be used. The camera preview stream may also be displayed more smoothly.

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.

Known Problems

(known problems are not catalogued in alpha pre-releases)

Planning, management, and maintenance of the v2024.0.0 software release is led by Ethan Li (@ethanjli), with approval and oversight from attendees of the weekly PlanktoScope software development meetings. If this software release causes new problems for how you are using PlanktoScope, Ethan will take responsibility for addressing any 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

• Try to fix GitHub Actions permissions for docker/build-and-push action by @ethanjli in #338
• build(deps): bump caddy from 2.7.5 to 2.7.6 in /documentation by @dependabot in #337
• build(deps): bump actions/configure-pages from 3 to 4 by @dependabot in #331
• build(deps): bump mkdocs-material from 9.5.1 to 9.5.3 in /documentation by @dependabot in #336
• build(deps): bump actions/deploy-pages from 2 to 4 by @dependabot in #329
• build(deps): bump actions/upload-pages-artifact from 2 to 3 by @dependabot in #330
• build(deps): bump actions/setup-python from 4 to 5 by @dependabot in #328
• build(deps): bump actions/upload-artifact from 3 to 4 by @dependabot in #327
• build(deps): bump mkdocs-git-revision-date-localized-plugin from 1.2.1 to 1.2.2 in /documentation by @dependabot in #332
• build(deps): bump mkdocs-glightbox from 0.3.5 to 0.3.6 in /documentation by @dependabot in #335
• build(deps): bump pymdown-extensions from 10.5 to 10.7 in /documentation by @dependabot in #334
• Fix issue with required status checks not running by @ethanjli in #339
• build(deps): bump mkdocs-minify-plugin from 0.7.1 to 0.7.2 in /documentation by @dependabot in #333
• Fix some issues with running the distro setup scripts on RPi OS 12 (bookworm) by @ethanjli in #324
• Allow running Docker commands without sudo by @ethanjli in #341
• Bump pallet-standard to add Dozzle by @ethanjli in #342
• Update hostname separately from the /etc/hosts file by @ethanjli in #344
• build(deps): bump gitpython from 3.1.40 to 3.1.41 in /documentation by @dependabot in #345
• build(deps): bump jinja2 from 3.1.2 to 3.1.3 in /documentation by @dependabot in #347
• Add Prometheus+Grafana-based monitoring of host machine, enable resetting system time to browser time by @ethanjli in #346
• Run forklift plt apply with parallelization by @ethanjli in #348
• os/pallet: Move some scripts and local files over into management by forklift by @ethanjli in #350
• Add support for usb0, eth1, and wlan1 interfaces by @ethanjli in #351
• Deploy the backend segmenter with forklift rather than the distro setup scripts by @ethanjli in #352
• Replace <object> tags with <iframe> tags by @ethanjli in #361
• Don't suppress wget errors in the docs's non-standard install commands by @ethanjli in #362
• Replace slider with text input to set pump volume by @ethanjli in #363
• Export the filtered volume metadata field on all sample types by @ethanjli in #364
• Repopulate input fields of input forms on Sample page by @ethanjli in #365
• Bump mkdocs-material to bump pillow to resolve dependabot alert by @ethanjli in #366
• build(deps): bump mkdocs-glightbox from 0.3.6 to 0.3.7 in /documentation by @dependabot in #367
• build(deps): bump mkdocs-minify-plugin from 0.7.2 to 0.8.0 in /documentation by @dependabot in #368
• Bump changelog version number for v2024.0.0-alpha.0 by @ethanjli in #369
• Bump Python segmenter by @ethanjli in #372
• build(deps): bump mkdocs-git-revision-date-localized-plugin from 1.2.2 to 1.2.4 in /documentation by @dependabot in #373
• build(deps): bump mkdocs-material from 9.5.6 to 9.5.12 in /documentation by @dependabot in #375
• build(deps): bump poethepoet from 0.24.4 to 0.25.0 in /documentation by @dependabot in #374
• Move tech specs in the docs to their own pages by @ethanjli in #379
• Switch from raspimjpeg to picamera2 for image acquisition by @ethanjli in #380
• Bump forklift from v0.5.3 to v0.6.0 by @ethanjli in #381
• Fix the Node-RED dashboard's "Restart segmenter" button by @ethanjli in #382
• Bump version numbers for v2024.0.0-alpha.1 by @ethanjli in #383

Full Changelog: software/v2023.9.0...software/v2024.0.0-alpha.1

Software: Sunray v2024.0.0-alpha.0

The v2024.0.0 software release, which is part of the "Sunray" series of software releases started with v2023.9.0, includes fixes for various problems and improvements to existing functionality with the PlanktoScope software. Significant behind-the-scenes changes are also included in this release.

About this pre-release

Software v2024.0.0-alpha.0 is a pre-release version for developers to test out. It definitely has 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!

Changelog

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:

• Added network configuration support for a few additional network interfaces (USB tethering, USB Wi-Fi dongle, and USB-to-Ethernet adapter). Thus, the PlanktoScope now shares internet access over its Wi-Fi hotspot and Ethernet port(s) from a phone connected to it in USB tethering mode.
• On the Node-RED dashboard, the System Monitoring page now shows a prompt for the user to reset the PlanktoScope’s system clock to match the time from their web browser, if the two clocks differ by more than one minute.

Changed:

• In the Node-RED dashboard, various input elements have been improved for better usability.
• 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. The Grafana dashboard can be customized by advanced users.

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.

Known Problems

(known problems are not catalogued in alpha pre-releases)

Pull Requests

• Try to fix GitHub Actions permissions for docker/build-and-push action by @ethanjli in #338
• build(deps): bump caddy from 2.7.5 to 2.7.6 in /documentation by @dependabot in #337
• build(deps): bump actions/configure-pages from 3 to 4 by @dependabot in #331
• build(deps): bump mkdocs-material from 9.5.1 to 9.5.3 in /documentation by @dependabot in #336
• build(deps): bump actions/deploy-pages from 2 to 4 by @dependabot in #329
• build(deps): bump actions/upload-pages-artifact from 2 to 3 by @dependabot in #330
• build(deps): bump actions/setup-python from 4 to 5 by @dependabot in #328
• build(deps): bump actions/upload-artifact from 3 to 4 by @dependabot in #327
• build(deps): bump mkdocs-git-revision-date-localized-plugin from 1.2.1 to 1.2.2 in /documentation by @dependabot in #332
• build(deps): bump mkdocs-glightbox from 0.3.5 to 0.3.6 in /documentation by @dependabot in #335
• build(deps): bump pymdown-extensions from 10.5 to 10.7 in /documentation by @dependabot in #334
• Fix issue with required status checks not running by @ethanjli in #339
• build(deps): bump mkdocs-minify-plugin from 0.7.1 to 0.7.2 in /documentation by @dependabot in #333
• Fix some issues with running the distro setup scripts on RPi OS 12 (bookworm) by @ethanjli in #324
• Allow running Docker commands without sudo by @ethanjli in #341
• Bump pallet-standard to add Dozzle by @ethanjli in #342
• Update hostname separately from the /etc/hosts file by @ethanjli in #344
• build(deps): bump gitpython from 3.1.40 to 3.1.41 in /documentation by @dependabot in #345
• build(deps): bump jinja2 from 3.1.2 to 3.1.3 in /documentation by @dependabot in #347
• Add Prometheus+Grafana-based monitoring of host machine, enable resetting system time to browser time by @ethanjli in #346
• Run forklift plt apply with parallelization by @ethanjli in #348
• os/pallet: Move some scripts and local files over into management by forklift by @ethanjli in #350
• Add support for usb0, eth1, and wlan1 interfaces by @ethanjli in #351
• Deploy the backend segmenter with forklift rather than the distro setup scripts by @ethanjli in #352
• Replace <object> tags with <iframe> tags by @ethanjli in #361
• Don't suppress wget errors in the docs's non-standard install commands by @ethanjli in #362
• Replace slider with text input to set pump volume by @ethanjli in #363
• Export the filtered volume metadata field on all sample types by @ethanjli in #364
• Repopulate input fields of input forms on Sample page by @ethanjli in #365
• Bump mkdocs-material to bump pillow to resolve dependabot alert by @ethanjli in #366
• build(deps): bump mkdocs-glightbox from 0.3.6 to 0.3.7 in /documentation by @dependabot in #367
• build(deps): bump mkdocs-minify-plugin from 0.7.2 to 0.8.0 in /documentation by @dependabot in #368
• Bump changelog version number for v2024.0.0-alpha.0 by @ethanjli in #369

Full Changelog: software/v2023.9.0...software/v2024.0.0-alpha.0

Software: Sunray v2023.9.0

v2023.9.0 is our first software update in two years, and we’re excited to make it simpler and easier for you to use your PlanktoScope in this update and in future updates!

This release’s name is “Sunray” (named after the Sunray Venus clam). We will keep this name for future versions until the next release which introduces big changes for users. This release includes big changes to how you access the PlanktoScope's software.

With this release, we are decoupling the evolution and versioning of the PlanktoScope software from the PlanktoScope hardware. Our goal is to make the latest version of the PlanktoScope software be compatible with every previous supported version of the PlanktoScope hardware. Thus, you may see references to “v2.1 hardware”, “v2.3 hardware”, and “v2.5 hardware” at the same time as “v2023.9.0 software” or “v2.3 software”.

A few notes:

• Anyone trying to build or set up a new Adafruit Stepper HAT-based PlanktoScope should use the v2023.9.0 software instead of the v2.3 software, as v2023.9.0 solves some critical firmware/driver version incompatibilities which Adafruit has caused over the past year on their Adafruit Stepper HATs; those incompatibilities make it difficult to get the v2.3 SD card image to work with Adafruit Stepper HATs purchased since around mid-2022.
• Because of the nature of a known problem related to the camera control system (see the "Known Problems" section for details), we recommend that anyone who's currently relying on the v2.3 software as part of mission-critical operations should probably continue using the v2.3 software for now.

Download links:

• SD card image for PlanktoScopes using the custom PlanktoScope HAT (e.g. v2.3 hardware and above)
• SD card image for PlanktoScopes using the Adafruit Stepper HAT (e.g. v2.1 hardware)

Contributors

The PlanktoScope software distro is a community effort, and this release would not have been possible without the PlanktoScope community:

• Thanks to (in alphabetical order) Ana Fernandez Carrera, Arief Rachman, @fabienlombard, @glx314, @hankertrix, @kitazy52, @pkostyrka, Rodrigo Gonçalves, Savannah Mapes, and @tpollina, for testing out pre-release versions of this software release and reporting bugs!
• Thanks also to @sourceindex for revamping the project documentation which is now included in this software release; and to @LaurentPV for contributing software improvements as part of this software release.

Notable changes since v2.3

Highlights:

• To use the PlanktoScope from your web browser, now you should just open http://pkscope.local/ or (if that doesn’t work) http://home.pkscope/ or (if that doesn’t work either) http://192.168.4.1/, which will show you a landing page with a link to the Node-RED dashboard as well as other useful links. The previous URLs used for accessing the PlanktoScope's Node-RED dashboard (e.g. http://192.168.4.1:1880/ui) no longer work.
• The name of your PlanktoScope (and its Wi-Fi hotspot) has changed to a new naming scheme.
• PlanktoScopes will no longer stay connected to any Wi-Fi network which doesn’t provide internet access.
• The PlanktoScope now acts like a router, so if it has internet access then it will share that internet access with your computer/phone.
• The PlanktoScope project has a new and improved documentation website, at https://docs.planktoscope.community/ .

Added:

• The PlanktoScope can now be accessed from your web browser at http://pkscope.local/ (assuming your web browser supports mDNS), and http://home.pkscope/ (assuming your web browser isn’t configured to use a custom DNS server).
• The PlanktoScope now shares any internet access it has from Wi-Fi with all devices connected to its Ethernet port; and it also shares any internet access it has from Ethernet with all devices connected to its Wi-Fi hotspot.
• An offline version of the PlanktoScope documentation is now available. It's accessible by a link from the PlanktoScope's landing page. The online version of the documentation is now at https://docs.planktoscope.community/ .

Changed:

• The Node-RED dashboard (previously available at http://planktoscope.local:1880/ui) has been moved to a different URL, accessible by a link on the new landing page (see the note in the “Added” section about new URLs and the landing page).
• The file gallery (previously available at http://planktoscope.local/) has now been renamed to the dataset file manager and moved to a different URL, accessible by a link on the new landing page. It now allows you to delete folders, preview images, and download folders as ZIP files.
• Previously, PlanktoScope machine names were generated as gibberish words like "Babaxio-Detuiau". 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.
• Previously, the PlanktoScope would stay connected to a Wi-Fi network even if it didn’t have internet access on that network. Now, if it connects to a Wi-Fi network but can’t get internet access on that network (specifically, if it’s unable to find google.com), then it will revert to creating its own Wi-Fi hotspot for your computer or phone to connect to.

Deprecated:

• The planktoscope.local mDNS name is no longer recommended for use; instead, you should use pkscope.local or the machine-specific mDNS name of format pkscope-{machine-name}.local.
• We might need to eventually transition the adafruithat version of the Node-RED dashboard to maintenance mode (i.e. no new features), if we can't merge it into the pscopehat version of the Node-RED dashboard. Nothing has been decided yet.

Fixed:

• 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 will now be reset, instead of causing the PlanktoScope software to crash after every subsequent restart.
• In certain network configurations, the Node-RED dashboard was used incorrect URLs to embed the MJPEG streams of the camera preview, resulting in a potentially misleading error message being shown about Python scripts. Now, the Node-RED dashboard uses the correct URLs for the MJPEG streams.
• The brightness of the illumination LED for the pscopehat version of software has been reduced; this is a temporary workaround to a bug with our camera control system where saved images are overexposed on the pscopehat version of the hardware even on the default brightness settings with minimum shutter speed and ISO, despite the brightness of the camera preview looking reasonable.
• The adafruit-blinka, adafruit-platformdetect, and adafruit-circuitpython-busdevice driver libraries are now updated, so that the PlanktoScope software should no longer crash just because it is being used with recent versions of the Adafruit Stepper HAT.

Notable changes since v2023.9.0-beta.2

(this release involves no changes from the v2023.9.0-beta.2 software prerelease; it's just a promotion of v2023.9.0-beta.2 to a stable release)

Known Problems

If you experience any of the following problems, please report it and describe your testing circumstances to help us understand and fix these problems:

• Sometimes, image acquisition will fail to start, with a “camera timeout” error; or sometimes the camera will not respond to camera settings changes. This problem may go away after one or more attempts to restart the Python hardware controller (from the Node-RED dashboard’s “Administration” page), but it might come back sometimes. This is a complicated issue and we still don’t know exactly why it happens.
• You may encounter weird behavior with the system time if you try to use Cockpit to manually adjust the system clock. If you file a bug report about this problem, please describe your GPS situation and the time you tried to change the system clock to.
• In certain cases, some computers connected both to a Wi-Fi network providing internet access and to a PlanktoScope may still be unable to access anything on the internet. If you file a bug report about this problem, please describe your operating system and your network configuration for internet access.
• If you restart the Node-RED dashboard without rebooting, you will also need to manually restart the Python hardware controller afterwards, or else the Node-RED dashboard won’t know the type of camera installed in the PlanktoScope.

Planning, management, and maintenance of the v2023.9.0 software release was led by Ethan Li (@ethanjli), with approval and oversight from Thibaut Pollina (@tpollina). If this software release causes new problems for how you are using your PlanktoScope, Ethan will take responsibility for addressing any 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!

Software: Sunray v2023.9.0-beta.2

v2023.9.0 will be our first software update in around two years, and we’re excited to make it easier for you to use your PlanktoScope in this update and in future updates! The v2023.9.0 software release focuses on improving the software infrastructure of the PlanktoScope software distro in preparation for future software improvements and maintenance, and making various usability improvements.

This release’s name is “Sunray” (named after the Sunray Venus clam). We will keep this name for future versions until the next release which introduces big changes for users.

Planning, management, and maintenance of the v2023.9.0 software release is led by Ethan Li (@ethanjli), with approval and oversight from Thibaut Pollina (@tpollina). If this software release causes new problems for how you are using PlanktoScope, Ethan will take responsibility for addressing any 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!

About this pre-release

Software v2023.9.0-beta.2 is a pre-release testing version for you to test out. It definitely has software bugs and other problems (the problems we know about are listed under the “Known Issues” section near the end of these release notes), so you should not use it for collecting scientific data! We would greatly appreciate it if you could flash the v2023.9.0-beta.2 image to an SD card and let us know about any bugs or problems you encounter while trying to use your PlanktoScope. This will help us to deliver a higher-quality software release with our v2023.9.0 release.

If you decide to try out the v2023.9.0-beta.2 software, 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!

Because this pre-release includes many changes, the changelogs below only list 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.

Changelog since v2.3

Highlights:

• To use the PlanktoScope from your web browser, now you should just open http://home.pkscope/ or http://pkscope.local/ or http://192.168.4.1/.
• You no longer need to use FileZilla to download and delete the datasets on your PlanktoScope - now you can do it from your web browser.
• The PlanktoScope now acts like a router, so if it has internet access then it will share that internet access with your computer/phone.
  PlanktoScopes will no longer stay connected to any Wi-Fi network which doesn’t provide internet access.
• PlanktoScopes now use a new naming scheme for machine names.
• We will eventually transition the Node-RED dashboard for the v2.1 hardware (Adafruit HAT) into maintenance mode.
• The Node-RED dashboard will no longer try to use incorrect URLs to show the camera preview stream.
• Entering invalid white balance values in the Node-RED dashboard should no longer break the PlanktoScope software upon restart.

Added:

• The PlanktoScope can now be accessed from your web browser at http://home.pkscope/ (assuming your web browser isn’t configured to use a custom DNS server such as 1.1.1.1 or 8.8.8.8) and http://pkscope.local/ (assuming your web browser supports mDNS), in addition to the other URLs which previously worked (http://planktoscope.local/, http://192.168.4.1/, and http://192.168.5.1/).
  • Each PlanktoScope can now also be accessed at machine-specific URLs of format http://<machine-name>.pkscope and http://pkscope-<machine-name>.local, where <machine-name> is replaced with your PlanktoScope’s machine name (see the note in the “Changed” section below about machine names).
  • If your web browser tries to do a Google search for the URL instead of actually opening it as a webpage, make sure you type http:// at the start or / at the end (e.g. home.pkscope/ or http://home.pkscope/ instead of home.pkscope)
  • If you connect directly from your computer/phone to the PlanktoScope and then use your web browser to open http://home.pkscope/, http://<machine-name>.pkscope, http://pkscope-<machine-name>.local, http://pkscope.local/, http://192.168.4.1/, or http://192.168.5.1/, you will now see a landing page with a list of useful links to software running on the PlanktoScope.
• The PlanktoScope now shares any internet access it has from Wi-Fi with all devices connected to its Ethernet port; and it also shares any internet access it has from Ethernet with all devices connected to its Wi-Fi hotspot, if it’s operating in wireless AP mode.
• An offline version of the PlanktoScope documentation is now available. It's accessible by a link from the PlanktoScope's landing page. The online version of the documentation is now at https://docs.planktoscope.community .
  • The PlanktoScope documentation now includes the reference protocol for quantitative imaging with PlanktoScope, which is normally available at https://www.protocols.io/view/planktoscope-protocol-for-plankton-imaging-bp2l6bq3zgqe/v2 . You can access the protocol from the bottom of the “Usage” → “Getting Started” page of the PlanktoScope documentation.
  • The PlanktoScope documentation pages have been redone in a new system, and improved in various ways. The hardware documentation now describes the v2.5 PlanktoScope hardware. Thanks to Sebastian Wendel (@sourceindex) for starting this work, and for contributing lots of documentation!

Changed:

• The Node-RED dashboard (previously available at http://planktoscope.local:1880/ui) has been moved to a different URL, accessible by a link on the new landing page (see the note in the “Added” section about new URLs and the landing page).
• The file gallery (previously available at http://planktoscope.local/) has now been renamed to the dataset file manager and moved to a different URL, accessible by a link on the new landing page. It now allows you to delete folders, preview images, edit text files, download folders as ZIP files, rename folders, and perform other common tasks.
  • This way, you no longer have to install FileZilla in order to copy or delete any of your datasets!
• Previously, PlanktoScope machine names were generated as gibberish words like "Babaxio-Detuiau", and the machine names were used as the names of the Wi-Fi hotspot networks made by the PlanktoScope. 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.
  • This change makes it easier for you to tell someone else which PlanktoScope to connect to if multiple PlanktoScope Wi-Fi hotspot networks are available nearby.
  • If you know a language besides US English and you’d like to help us add support for generating machine names in that language, please start a discussion on Github or in the #6-dev-software channel on the PlanktoScope Slack workspace!
• Previously, the PlanktoScope would stay connected to a wifi network even if it didn’t have internet access on that network. Now, if it connects to a Wi-Fi network but can’t get internet access on that network (specifically, if it’s unable to find google.com), then it will revert to creating its own Wi-Fi hotspot for your computer or phone to connect to.

Deprecated:

• The planktoscope.local mDNS name is no longer recommended for use; instead, you should use pkscope.local or the machine-specific mDNS name of format pkscope-{machine-name}.local.
  • However, we will continue to support planktoscope.local for a while, to maintain compatibility with earlier software versions.
• In a future release (timeline not yet decided), the version of the Node-RED dashboard for the Adafruit HAT (hardware v2.1) will stop receiving new features even as the version of the Node-RED dashboard for the custom PlanktoScope HAT (hardware v2.3+) continues receiving new features.
  • Depending on the amount of work required, we might be able to make the Node-RED dashboard for the custom PlanktoScope HAT be compatible with the Adafruit HAT. However, we do not have any specific plans yet.
  • Regardless, we do plan to continue to fix bugs in the Node-RED dashboard for the Adafruit HAT for some time, and we will continue to build SD card images for the Adafruit HAT which will also include new features in other software components.

Fixed:

• 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 hardware.json configuration file). Previously, invalid white balance values were written to the hardware.json configuration file, which would cause the PlanktoScope software to crash after every subsequent restart until the hardware.json file was manually ...

Software: Sunray v2023.9.0-beta.1

v2023.9.0 will be our first software update in over a year and a half, and we’re excited to make it easier for you to use your PlanktoScope in this update and in future updates! The v2023.9.0 software release focuses on improving the software infrastructure of the PlanktoScope software distro in preparation for future software improvements and maintenance, and making various usability improvements.

This release’s name is “Sunray” (named after the Sunray Venus clam). We will keep this name for future versions until the next release which introduces big changes for users.

Planning, management, and maintenance of the v2023.9.0 software release is led by Ethan Li (@ethanjli), with approval and oversight from Thibaut Pollina (@tpollina). If this software release causes new problems for how you are using PlanktoScope, Ethan will take responsibility for addressing any 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!

About this pre-release

v2023.9.0-beta.1 is a pre-release testing version for you to test out. It definitely has software bugs and other problems (the problems we know about are listed under the “Known Issues” section near the end of these release notes), so you should not use it for collecting scientific data! We would greatly appreciate it if you could flash the v2023.9.0-beta.1 image to an SD card and let us know about any bugs or problems you encounter while trying to use your PlanktoScope. This will help us to deliver a higher-quality software release with our v2023.9.0 release.

If you decide to try out v2023.9.0-beta.1, 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!

Because this pre-release includes many changes, the changelogs below only list 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.

Changelog since v2.3

Highlights:

• To use the PlanktoScope from your web browser, now you should just open http://home.pkscope/ or http://pkscope.local/ or http://192.168.4.1/.
• You no longer need to use FileZilla to download and delete the datasets on your PlanktoScope - now you can do it from your web browser.
• The PlanktoScope now acts like a router, so if it has internet access then it will share that internet access with your computer/phone.
• PlanktoScopes will no longer stay connected to any Wi-Fi network which doesn’t provide internet access.
• PlanktoScopes now use a new naming scheme for machine names.
• We will eventually transition the Node-RED dashboard for the v2.1 hardware (Adafruit HAT) into maintenance mode.
• The Node-RED dashboard will no longer try to use incorrect URLs to show the camera preview stream.
• Entering invalid white balance values in the Node-RED dashboard should no longer break the PlanktoScope software upon restart.

Added:

• The PlanktoScope can now be accessed from your web browser at http://home.pkscope/ (assuming your web browser isn’t configured to use a custom DNS server such as 1.1.1.1 or 8.8.8.8) and http://pkscope.local/ (assuming your web browser supports mDNS), in addition to the other URLs which previously worked (http://planktoscope.local/, http://192.168.4.1/, and http://192.168.5.1/).
  • Each PlanktoScope can now also be accessed at machine-specific URLs of format http://<machine-name>.pkscope and http://pkscope-<machine-name>.local, where <machine-name> is replaced with your PlanktoScope’s machine name (see the note in the “Changed” section below about machine names).
  • If your web browser tries to do a Google search for the URL instead of actually opening it as a webpage, make sure you type http:// at the start or / at the end (e.g. home.pkscope/ or http://home.pkscope/ instead of home.pkscope)
  • If you connect directly from your computer/phone to the PlanktoScope and then use your web browser to open http://home.pkscope/, http://<machine-name>.pkscope, http://pkscope-<machine-name>.local, http://pkscope.local/, http://192.168.4.1/, or http://192.168.5.1/, you will now see a landing page with a list of useful links to software running on the PlanktoScope.
• The PlanktoScope now shares any internet access it has from Wi-Fi with all devices connected to its Ethernet port; and it also shares any internet access it has from Ethernet with all devices connected to its Wi-Fi hotspot, if it’s operating in wireless AP mode.
• An offline version of the PlanktoScope documentation is now available. It's accessible by a link from the PlanktoScope's landing page. The online version of the documentation is now at https://planktoscope.github.io/PlanktoScope/
  • The PlanktoScope documentation now includes the reference protocol for quantitative imaging with PlanktoScope, which is normally available at https://www.protocols.io/view/planktoscope-protocol-for-plankton-imaging-bp2l6bq3zgqe/v2 . You can access the protocol from the bottom of the “Usage” → “Getting Started” page of the PlanktoScope documentation.
  • The PlanktoScope documentation pages have been redone in a new system, and improved in various ways. The hardware documentation now describes the v2.5 PlanktoScope hardware. Thanks to Sebastian Wendel (@sourceindex) for starting this work, and for contributing lots of documentation!

Changed:

• The Node-RED dashboard (previously available at http://planktoscope.local:1880/ui) has been moved to a different URL, accessible by a link on the new landing page (see the note in the “Added” section about new URLs and the landing page).
• The file gallery (previously available at http://planktoscope.local/) has now been renamed to the dataset file manager and moved to a different URL, accessible by a link on the new landing page. It now allows you to delete folders, preview images, edit text files, download folders as ZIP files, rename folders, and perform other common tasks.
  • This way, you no longer have to install FileZilla in order to copy or delete any of your datasets!
• Previously, PlanktoScope machine names were generated as gibberish words like "Babaxio-Detuiau", and the machine names were used as the names of the Wi-Fi hotspot networks made by the PlanktoScope. 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.
  • This change makes it easier for you to tell someone else which PlanktoScope to connect to if multiple PlanktoScope Wi-Fi hotspot networks are available nearby.
  • If you know a language besides US English and you’d like to help us add support for generating machine names in that language, please start a discussion on Github or in the #6-dev-software channel on the PlanktoScope Slack workspace!
• Previously, the PlanktoScope would stay connected to a wifi network even if it didn’t have internet access on that network. Now, if it connects to a Wi-Fi network but can’t get internet access on that network (specifically, if it’s unable to find google.com), then it will revert to creating its own Wi-Fi hotspot for your computer or phone to connect to.

Deprecated:

• The planktoscope.local mDNS name is no longer recommended for use; instead, you should use pkscope.local or the machine-specific mDNS name of format pkscope-{machine-name}.local.
  • However, we will continue to support planktoscope.local for a while, to maintain compatibility with earlier software versions.
• In a future release (timeline not yet decided), the version of the Node-RED dashboard for the Adafruit HAT (hardware v2.1) will stop receiving new features even as the version of the Node-RED dashboard for the custom PlanktoScope HAT (hardware v2.3+) continues receiving new features.
  • Depending on the amount of work required, we might be able to make the Node-RED dashboard for the custom PlanktoScope HAT be compatible with the Adafruit HAT. However, we do not have any specific plans yet.
  • Regardless, we do plan to continue to fix bugs in the Node-RED dashboard for the Adafruit HAT for some time, and we will continue to build SD card images for the Adafruit HAT which will also include new features in other software components.

Fixed:

• 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 hardware.json configuration file). Previously, invalid white balance values were written to the hardware.json configuration file, which would cause the PlanktoScope software to crash after every subsequent restart until the hardware.json file was manually removed...

Software: Sunray v2023.9.0-beta.0

v2023.9.0 will be our first software update in over a year and a half, and we’re excited to make it easier for you to use your PlanktoScope in this update and in future updates! The v2023.9.0 software release focuses on improving the software infrastructure of the PlanktoScope software distro in preparation for future software improvements and maintenance, and making various usability improvements.

This release’s name is “Sunray” (named after the Sunray Venus clam). We will keep this name for future versions until the next release which introduces big changes for users.

Planning, management, and maintenance of the v2023.9.0 software release is led by Ethan Li (@ethanjli), with approval and oversight from Thibaut Pollina (@tpollina). If this software release causes new problems for how you are using PlanktoScope, Ethan will take responsibility for addressing any 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!

About this pre-release

v2023.9.0-beta.0 is a pre-release testing version for you to test out; it probably has software bugs and other problems, so you should not use it for collecting scientific data - expect bugs and software breakage! We would greatly appreciate it if you could flash the v2023.9.0-beta.0 image to an SD card and let us know about any bugs or problems you encounter while trying to use your PlanktoScope. This will help us to deliver a higher-quality software release with our v2023.9.0 release.

If you decide to try out v2023.9.0-beta.0, 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!

Because this pre-release includes many changes, the changelogs below only list 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.

Changelog since v2.3

Highlights:

• To use the PlanktoScope from your web browser, now you should just open http://home.planktoscope/ or http://planktoscope.local/ or http://192.168.4.1/.
• You no longer need to use FileZilla to download and delete the datasets on your PlanktoScope - now you can do it from your web browser.
• The PlanktoScope now acts like a router, so if it has internet access then it will share that internet access with your computer/phone.
• PlanktoScopes will no longer stay connected to any Wi-Fi network which doesn’t provide internet access.
• PlanktoScopes now use a new naming scheme for machine names.
• We will eventually transition the Node-RED dashboard for the v2.1 hardware (Adafruit HAT) into maintenance mode.
• The Node-RED dashboard will no longer try to use incorrect URLs to show the camera preview stream.
• Entering invalid white balance values in the Node-RED dashboard should no longer break the PlanktoScope software upon restart.

Added:

• The PlanktoScope can now be accessed from your web browser at http://home.planktoscope/ (assuming your web browser isn’t configured to use a custom DNS server such as 1.1.1.1 or 8.8.8.8), in addition to the other URLs which previously worked (http://planktoscope.local/, http://192.168.4.1/, and http://192.168.5.1/).
  • Each PlanktoScope can now also be accessed at machine-specific URLs of format http://<machine-name>.planktoscope and http://planktoscope-<machine-name>.local, where <machine-name> is replaced with your PlanktoScope’s machine name (see the note in the “Changed” section below about machine names).
  • If your web browser tries to do a Google search for the URL instead of actually opening it as a webpage, make sure you type http:// at the start or / at the end (e.g. home.planktoscope/ or http://home.planktoscope/ instead of home.planktoscope)
  • If you connect directly from your computer/phone to the PlanktoScope and then use your web browser to open http://home.planktoscope/, http://<machine-name>.planktoscope, http://planktoscope-<machine-name>.local, http://planktoscope.local/, http://192.168.4.1/, or http://192.168.5.1/, you will now see a landing page with a list of useful links to software running on the PlanktoScope.
• The PlanktoScope now shares any internet access it has from Wi-Fi with all devices connected to its Ethernet port; and it also shares any internet access it has from Ethernet with all devices connected to its Wi-Fi hotspot, if it’s operating in wireless AP mode.
• An offline version of the PlanktoScope documentation is now available. It's accessible by a link from the PlanktoScope's landing page. The online version of the documentation is now at https://planktoscope.github.io/PlanktoScope/
  • The PlanktoScope documentation now includes the reference protocol for quantitative imaging with PlanktoScope, which is normally available at https://www.protocols.io/view/planktoscope-protocol-for-plankton-imaging-bp2l6bq3zgqe/v2 . You can access the protocol from the bottom of the “Usage” → “Getting Started” page of the PlanktoScope documentation.
  • The PlanktoScope documentation pages have been redone in a new system, and improved in various ways. The hardware documentation now describes the v2.5 PlanktoScope hardware. Thanks to Sebastian Wendel (@sourceindex) for starting this work, and for contributing lots of documentation!

Changed:

• The Node-RED dashboard (previously available at http://planktoscope.local:1880/ui) has been moved to a different URL, accessible by a link on the new landing page (see the note in the “Added” section about new URLs and the landing page).
• The file gallery (previously available at http://planktoscope.local/) has now been renamed to the dataset file manager and moved to a different URL, accessible by a link on the new landing page. It now allows you to delete folders, preview images, edit text files, download folders as ZIP files, rename folders, and perform other common tasks.
  • This way, you no longer have to install FileZilla in order to copy or delete any of your datasets!
• Previously, PlanktoScope machine names were generated as gibberish words like "Babaxio-Detuiau", and the machine names were used as the names of the Wi-Fi hotspot networks made by the PlanktoScope. 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.
  • This change makes it easier for you to tell someone else which PlanktoScope to connect to if multiple PlanktoScope Wi-Fi hotspot networks are available nearby.
  • If you know a language besides US English and you’d like to help us add support for generating machine names in that language, please start a discussion on Github or in the #6-dev-software channel on the PlanktoScope Slack workspace!
• Previously, the PlanktoScope would stay connected to a wifi network even if it didn’t have internet access on that network. Now, if it connects to a Wi-Fi network but can’t get internet access on that network (specifically, if it’s unable to find google.com), then it will revert to creating its own Wi-Fi hotspot for your computer or phone to connect to.

Deprecated:

• In a future release (timeline not yet decided), the version of the Node-RED dashboard for the Adafruit HAT (hardware v2.1) will stop receiving new features even as the version of the Node-RED dashboard for the custom PlanktoScope HAT (hardware v2.3+) 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.

Fixed:

• 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 hardware.json configuration file). Previously, invalid white balance values were written to the hardware.json configuration file, which would cause the PlanktoScope software to crash after every subsequent restart until the hardware.json file was manually removed or fixed.
  • Thanks to Gilles Orazi (@glx314) for filing an issue about this problem!
• In various use cases (e.g. when accessing the PlanktoScope over a mesh VPN, or in some bug reports by users accessing the PlanktoScope over Ethernet), the Node-RED dashboard would be unable to show the MJPEG streams of the camera preview and the object segmentation preview, resulting in a potentially misleading error message being shown about the Python scripts. Now, the Node-RED dashboard uses URLs for the MJPEG streams which we expect to be accessible wherever the Node-RED dashboard...