Software: Sunray v2023.9.0-beta.1

[ethanjli]

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 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 itself is accessible.
  • Thanks to Rodrigo Gonçalves on the PlanktoScope Slack for reporting a bug related to this issue and helping us to troubleshoot it!
• The adafruit-blinka and adafruit-platformdetect software dependencies are now updated to their latest version. As a result, the PlanktoScope software should not crash just because it is being used with recent versions of the Adafruit Stepper HAT.
  • This fix removes the need for you to give your PlanktoScope internet access and then connect to the PlanktoScope over SSH to manually run the pip3 install --upgrade adafruit-blinka adafruit-platformdetect command before your PlanktoScope can work properly.

Changelog since v2023.9.0-beta.0

Highlights:

• In the domain names and SSIDs for accessing PlanktoScopes, we’ve shortened the word “planktoscope” to “pkscope” (so e.g. use http://home.pkscope/ instead of http://home.planktoscope/, and use http://pkscope-{machine-name}.local instead of http://planktoscope-{machine-name}.local).
• We fixed most of the regressions reported about v2023.9.0-beta.0 which we’ve been able to reproduce so far. We’ll need more people to help with testing in order for us to figure out the other problems which have been reported and which we haven’t yet been able to reproduce.

Added:

• The PlanktoScope can now be accessed with the mDNS name pkscope.local (so e.g. you can access the landing page at http://pkscope.local/ if you previously were able to use http://planktoscope.local/ )
• The Node-RED dashboard now provides some additional guidance about how to navigate the software logs, since it’s more complicated now.
  • Thanks to Ana Fernandez Carrera on the PlanktoScope Slack for providing feedback which led to this change!
• The Node-RED dashboard now provides some additional warnings about what will happen if you touch the “Hardware Version” dropdown menu on the “Hardware Settings” page, since now the white balance settings get overwritten.
  • Thanks to Fabien Lombard (@fabienlombard) for providing feedback which led to this change!

Changed:

• The top-level domain for domain names of format home.planktoscope and {machine-name}.planktoscope (e.g. http://metal-slope-23501.planktoscope) has been changed to replace planktoscope with pkscope, so that the domain names are now of format home.pkscope and {machine-name}.pkscope. Similarly, the machine-specific mDNS name has been changed from format planktoscope-{machine-name}.local to pkscope-{machine-name}.local.
• The SSIDs of wifi hotspots generated by the PlanktoScope has been changed from the format PlanktoScope {machine-name} to the format pkscope-{machine-name}. This makes it easier to determine the machine-specific mDNS URL: just add .local, to get pkscope-{machine-name}.local (e.g. pkscope-metal-slope-23501.local).

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.

Fixed:

• The segmenter should now be able to start running, instead of crashing and becoming unresponsive.
  • Thanks to Fabien Lombard (@fabienlombard) and Ana Fernandez Carrera on the PlanktoScope Slack for reporting this bug and helping us to troubleshoot it!
• The Node-RED dashboard should once again be able to receive information about the camera type from the Python backend when the Python backend starts.
  • Thanks to Fabien Lombard (@fabienlombard) and Ana Fernandez Carrera on the PlanktoScope Slack for reporting this bug and helping us to troubleshoot it!
• The Node-RED dashboard should once again have a default pixel size calibration, so that it doesn’t produce raw image datasets which crash the segmenter.
  • Thanks to Fabien Lombard (@fabienlombard) and Ana Fernandez Carrera on the PlanktoScope Slack for reporting this bug and helping us to troubleshoot it!
• Sometimes the PlanktoScope would generate a machine name which was so long that it prevented the Wi-Fi hotspot from being started; now, there’s a limit on how long the generated machine names can be.
  • Thanks to Fabien Lombard (@fabienlombard) for reporting this bug and helping us to troubleshoot it!
• Machine-specific links on the landing page were broken; now they should be fixed.
• The offline documentation site was actually pinned at v2023.9.0-alpha.0; now it’s at v2023.9.0-beta.1, which (notably) includes fixes to some broken links to hardware design files.

Known Problems:

• (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 v2.3, but potentially worse in v2023.9.0-beta.0) In certain cases, image acquisition will fail to start, with a “camera timeout” error. If you experience this problem, please report it and your testing circumstances (e.g. when would the error occur, how repeatable was it, 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) The Node-RED dashboard is too eager and aggressive in undoing any changes you make to the white balance which could cause an invalid white balance value. If you experience this problem, please report what you were doing (including the exact sequence of keys you pressed on the keyboard) and how the software behaved as a result, so that we can design a solution which works reasonably well for everyone!
• (Known as of v2023.9.0-beta.0) The landing page links to the old PlanktoScope documentation site at https://planktoscope.readthedocs.io/en/latest/ as the online documentation site, instead of linking to the new PlanktoScope documentation site. This is because we don’t yet have a URL for a stable version of the new documentation. For now, you should just use the landing page’s offline documentation link instead.
• (Known as of v2023.9.0-beta.0) The changelog in the offline documentation on the PlanktoScope is out-of-date. This will be fixed before the stable release of v2023.9.0.
• (Known as of v2023.9.0-beta.0) The PlanktoScope takes a while to start up and to reboot. This is a complicated problem, and we won’t be able to solve it before the v2023.9.0 stable release.
• (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. The solution will take some work and will not be delivered in the v2023.9.0 stable release.
• (Known as of v2.3) After restarting the hardware controller from the Node-RED dashboard’s “Administration” page, the Node-RED dashboard will report that the sample illumination LED is still on even though the hardware controller will have turned the LED off upon starting. The solution will take lots of work and will not be delivered in the v2023.9.0 stable release.
• (Known as of v2.3) The filenames of raw images produced by image acquisition can’t be sorted chronologically, because the filename includes acquisition time but not date. We plan to fix this in a future release after v2023.9.0.

Pull Requests

• Make v2.5 hardware files available by @ethanjli in Make v2.5 hardware files available #215
• Limit SSID length for wifi hotspot networks by @ethanjli in Limit SSID length for wifi hotspot networks #214
• build(deps-dev): bump mkdocs-charts-plugin from 0.0.9 to 0.0.10 in /documentation by @dependabot in build(deps-dev): bump mkdocs-charts-plugin from 0.0.9 to 0.0.10 in /documentation #194
• build(deps-dev): bump pillow from 9.5.0 to 10.0.0 in /documentation by @dependabot in build(deps-dev): bump pillow from 9.5.0 to 10.0.0 in /documentation #192
• Bump device-backend to use new machine naming scheme by @ethanjli in Bump device-backend to use new machine naming scheme #216
• Fix some Node-RED usability papercuts with a limited scope of changes by @ethanjli in Fix some Node-RED usability papercuts with a limited scope of changes #223
• Bump the docs version number to v2023.9.0-beta.1 by @ethanjli in Bump the docs version number to v2023.9.0-beta.1 #226
• Update setup scripts and bump version numbers for v2023.9.0-beta.1 by @ethanjli in Update setup scripts and bump version numbers for v2023.9.0-beta.1 #227

Full Changelog: software/v2023.9.0-beta.0...software/v2023.9.0-beta.1

---

This discussion was created from the release Software: Sunray v2023.9.0-beta.1.