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!