software/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 software.

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 responsibility for address...

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

Software: Sunray v2023.9.0-alpha.0

v2023.9.0 will be our first software update in 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. The goal of this release is to fix some bugs in the existing software, and to take a few early steps towards enabling smaller and more frequent software updates in the future, so that we can deliver bugfixes and improvements to you on a more timely schedule, and so that you can apply those changes in a safer, easier, and simpler way.

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. The v2023.12.0 release, which is planned for December 2023, will introduce big changes for users (including requiring users to re-flash their SD cards with a new SD card image) and thus will have a different release name.

v2023.9.0-alpha.0 is an unstable testing version for the PlanktoScope development team and any advanced users who are feeling particularly adventurous. It definitely has undiscovered software bugs, breakage, and other problems, and we will be using this prerelease in order to discover those bugs. We will eventually make a v2023.9.0-beta.0 prerelease where more of those bugs should be discovered and fixed, for more people to test out. If you decide to try out v2023.9.0-alpha.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!

Planning, management, and maintenance of the v2023.9.0 software release is led by Ethan Li (@ethanjli), with approval and oversight from Thibaut Pollina. 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 Ethan in a new discussion on Github or in the #6-dev-software channel on the PlanktoScope Slack workspace!

The changes listed below are just the ones we think users are likely to notice or to need to know about since the previous stable release (v2.3.0); for a full list of changes between each stable release and unstable prerelease, please refer to the software/CHANGELOG.md file in this repository.

Changelog

Added:

• The PlanktoScope can now be accessed from your web browser using 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 (planktoscope.local, 192.168.4.1, and 192.168.5.1). Each PlanktoScope can now also be accessed at unique domain names of format <machine-name>.planktoscope and 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 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.
  • Note that home.planktoscope and <machine-name>.planktoscope will probably work even if planktoscope.local and planktoscope-<machine-name>.local don’t work (e.g. if you’re on an Android device) - so you might not need to type 192.168.4.1 on your phone anymore!
  • If your web browser tries to do a Google search for the URL instead of actually opening it as a URL, type http:// at the start or add a / at the end (e.g. http://home.planktoscope or home.planktoscope/ or http://home.planktoscope/ instead of home.planktoscope)
  • If you’re a new user, you no longer have to remember to type http://planktoscope.local:1880/ui in order to access the dashboard - instead, you should just open http://home.planktoscope/ (or http://planktoscope.local/ or http://192.168.4.1/ or etc.) in your web browser and follow the “Node-RED dashboard” link to open the dashboard!
  • If you have multiple PlanktoScopes (lucky you!) and you need to access them by SSH or FileZilla without having to deal with security warnings about different SSH host fingerprints on home.planktoscope or planktoscope.local or 192.168.4.1 or 192.168.5.1, then you should use either the <machine-name>.planktoscope domain name or the planktoscope-<machine-name>.local domain name - for example, ssh pi@metal-slope-23501.planktoscope, or ssh pi@planktoscope-plant-range-10581.local - so that each PlanktoScope is accessed at a domain name with a different host fingerprint.
• A web-browser computer administration panel called Cockpit is now available. It's accessible by a link from the PlanktoScope's landing page.
  • This is provided to enable users to manage system settings easily (e.g. changing the password from copepode to something more secure), and to help users with troubleshooting problems.
  • Cockpit provides a web browser-based SSH terminal for remotely running commands, at http://ethan-dev-1.planktoscope.d.prakashlab.fluitans.org/admin/cockpit/system/terminal.
  • Cockpit also allows you to inspect the logs of any system service, such as the autohotspot service.
• A web-browser system file manager for the PlanktoScope’s entire SD card is now available. It's accessible by a link from the PlanktoScope's landing page.
  • Among many other things, it allows you to create, edit, rename, and delete text files.
  • This way, you may be able to fix a broken system without having to re-flash your SD card - at least for certain kinds of breakage.
• An offline version of the PlanktoScope documentation is now available. It's accessible by a link from the PlanktoScope's landing page.
  • This way, you can check the PlanktoScope’s documentation even if you don’t have internet access!
• We are now using a system for running containerized apps called Docker for deploying various programs (e.g. the system file manager, the PlanktoScope documentation, and the landing page) as part of the PlanktoScope software distribution.
  • Docker provides a way to download and run containerized apps, and to upgrade and downgrade their versions. Containerized apps run in isolation, which makes them easier to troubleshoot, to update, and to uninstall cleanly. The isolation mechanism also helps us to limit the potential impact of any software bugs or security vulnerabilities. Most of the new apps we’re adding in this release (with the notable exception of Cockpit) are running as containerized apps.
  • We are using Docker as a tool to make it more safe, simple, and easy for you to upgrade your PlanktoScope’s software, and for you to download and run other apps on your PlanktoScope.
  • Note for advanced users: in this release we are running Docker in Swarm Mode, with the only member of the cluster being the Raspberry Pi itself; use of Swarm Mode should be considered an experimental feature, and we may stop using Swarm Mode in a future release (e.g. if we determine that the Python backend needs to be run as a privileged container in order to work in a container; see moby/swarmkit#1030 & moby/moby#43419 for details).
• A web-browser Docker management panel called Portainer is now available. It's accessible by a link from the PlanktoScope's landing page.
  • Portainer is only provided for advanced users to inspect, manage, and troubleshoot containerized programs easily.
  • Our use of the Portainer dashboard should be considered an experimental feature, and in a future release we will probably switch to a different default dashboard for monitoring and troubleshooting Docker containerized applications.
  • If we switch to a different default dashboard, we may still provide an easy way for users to install Portainer on their PlanktoScopes - it just won’t be provided as part of the default software distribution provided by our SD card images. If you want to use Portainer and you want to a way to easily install Portainer in the future even if we remove it from our standard software distribution, please start a discussion on Github or in the #6-dev-software channel on the PlanktoScope Slack workspace!
• An experimental command-line tool called Forklift can now be run by advanced users on the PlanktoScope (e.g. via SSH or via Cockpit’s Terminal), for (re)configuring the set of Docker containerized applications running on the PlanktoScope. We will continue to improve Forklift in future releases of the PlanktoScope software distribution.
  • As we add more functionality to Forklift, and as we make the tool more stable, we plan for it to eventually become an open “app store” system, with a simple web browser interface allowing users to add third-party (Docker containerized) programs and/or to easily replicate their custom software configuration across multiple PlanktoScopes.
  • If you’re interested in trying out Forklift, or if you think Forklift might be useful for something you’re trying to do with PlanktoScope if certain features will be added to it, please [start a discussion on Github](https://github.com/PlanktoScope/PlanktoScope/...

v2.3

Direct link to image download:
Adafruit version (if in doubt, this is the one you want)
Custom hat version

Summary of changes:

• Segmenter: working version with basic and solid settings. It's not possible to change those settings for every run, but this will come.
• Network: you can connect directly to Ethernet now, it should work on any machine and OS you use.
• All dependencies were updated to their latest version
• OS is fully updated as of 2021-12-03, base version is RaspberryOS buster (the move to bullseye is planned for the next release)
• Various UI changes happened that should make your life easier (please help us and give us feedback on what isn't clear or missing).
• Culture mode: Location is forced set to the South pole. If you need another way of this to work, please make your voice heard! Time and date are set to current machine date and time, but can be modified before progressing to the next stage.
• Test mode: To be able to capture test runs, without having to worry about datetime, location. Location is forced set to the South pole (again), datetime is forced set to local machine time.
• Stream and machine access: For those of you that were having problems with the streams, or straight up with the access to the machine through http://planktoscope.local:1880/ui we should have solved most of the issues with Bonjour's installation and stuff like that. It's now not needed anymore. The machine can be accessed either through the above URI, through http://192.168.1.4:1880/ui if you are connecting directly to the machine WiFi network, or through http://192.168.1.5:1880/ui if you are connecting directly to the Ethernet port.
• A flurry of tiny bugs with Node-red not behaving exactly as expected were also fixed (#80 #82 #91 #87 #96 #98 #97 #74)

Limitations and known issues:

• Segmenter: can't be stopped (yet). Be careful if you start runs on more than 500 images, those can take a long long time.
• Imager: captured images are brighter than what we see on the stream in the optic configuration and capture tabs. There is an issue internally with the camera that we haven't been able to solve yet. Please be aware of that and set your exposition to a (slightly) darker image than you would otherwise.
• On the new hat: RTC is not working properly yet. Date is stuck in 2019 when there is no network connection or no GPS signal.

Full Changelog:
v2.2.1...v2.3

v2.2.1

Small update to bring some small improvements and tiny changes.

Mainly, this was caused by #80, we had to update some python packages to make sure newest Raspberry's would be properly detected.

We took this opportunity to fix tiny bugs in the flows and introduce a new feature. It's now possible to switch development branch. Yeah, useful only for us dev.

Download link: https://drive.google.com/file/d/1y0k_NDXN0yT5caZrXhjLYXgQVxu-D5ql/view?usp=sharing

For most people, just clicking on the "Update" button in the "System Administration" tab of the interface will do the trick.