doc: Add PlanktoScope OS v2025.0.0 product specs (#557)

ethanjli · web-flow · commit 35fae9d2e00e · 2025-04-03T02:33:39.000Z
* doc: Add more information to OS specs for v2024.0.0 and below

* doc: Add OS specs for v2025.0.0

* doc: Improve organization of software reset guide for general audience

* doc: Update release process reference to be clearer about goals vs. reality

* doc: Update release process ref doc to link to software upgrades guide
diff --git a/documentation/docs/operation/software-upgrades.md b/documentation/docs/operation/software-upgrades.md
@@ -2,7 +2,7 @@
 
 Your PlanktoScope's embedded Raspberry Pi computer has a PlanktoScope-specific operating system (the *[PlanktoScope OS](../reference/software/architecture/os.md)*) with software for operating your PlanktoScope. If you purchased a PlanktoScope, then the SD card you received with your PlanktoScope already includes a particular release of the PlanktoScope OS; if you assembled your own PlanktoScope, then you installed some release of the PlanktoScope OS following the [standard software installation guide](../setup/software/standard-install.md) (or maybe the [non-standard software installation guide](../setup/software/nonstandard-install.md)). This guide provides information to help you either reset the software installed on your PlanktoScope or change to a different (newer or older) release of the PlanktoScope OS.
 
-The PlanktoScope project aims to keep improving the PlanktoScope software by fixing problems and making the software simpler and easier to use, releasing a new version of the software at least once each year. At the same time, we aim to keep the software compatible with all previous officially-released versions of the PlanktoScope hardware. For this reason, we strongly recommend everyone to keep their PlanktoScopes updated to run the latest stable release of the PlanktoScope software; and the PlanktoScope documentation will only support the latest stable release. You can always find the latest stable release at <https://github.com/PlanktoScope/PlanktoScope/releases/latest>, which will redirect you to a web page for a specific release.
+The PlanktoScope project aims to keep improving the PlanktoScope software by fixing problems and making the software simpler and easier to use, [releasing](../reference/software/release-process.md) a new version of the software at least once (or hopefully twice) each year. At the same time, we aim to keep the software compatible with all previous officially-released versions of the PlanktoScope hardware. For this reason, we strongly recommend everyone to keep their PlanktoScopes updated to run the latest stable release of the PlanktoScope software; and the PlanktoScope documentation will only support the latest stable release. You can always find the latest stable release at <https://github.com/PlanktoScope/PlanktoScope/releases/latest>, which will redirect you to a web page for a specific release.
 
 All URLs in this guide are written assuming you access your PlanktoScope using [planktoscope.local](http://planktoscope.local) as the domain name; if you need to use a [different domain name](./index.md#access-your-planktoscopes-software) such as [home.pkscope](http://home.pkscope), you should substitute that domain name into the links on this page.
 
@@ -22,19 +22,27 @@ Advanced users may also want to take the following actions, depending on what ch
 
 ## Reset the PlanktoScope OS
 
-Multiple levels of reset are possible; from least-disruptive (and shallowest) to most-disruptive (and most thorough), they are:
+Multiple levels of reset are possible: a full reset, and various levels of partial resets.
 
-1. (Only recommended for advanced users) If you just need to reset some or all of your operating system configuration file changes (such as those described in the [networking operations guide](./networking.md)) back to the default settings for the PlanktoScope OS, then you can just delete the relevant files (or you can even delete all files) within `/var/lib/overlays/overrides/etc/` (for example in the file browser at <http://planktoscope.local/admin/fs/files/var/lib/overlays/overrides/etc/> ) and then reboot your PlanktoScope immediately afterwards.
+### Full reset
 
-2. (Only recommended for advanced users) If you want to reset the running software back to the original release of the PlanktoScope OS provided with your SD card image, while keeping any customizations you have made to override default PlanktoScope OS configurations (such as those described in the [networking operations guide](./networking.md)), then you can run the following command on your PlanktoScope (for example in the Cockpit Terminal at <http://planktoscope.local/admin/cockpit/system/terminal> ) and then reboot your PlanktoScope:
+For most users we recommend performing a full reset rather than a partial reset, because the "full reset" process is easier to understand. This involves completely wiping your SD card and resetting everything by re-flashing your PlanktoScope's SD card. You can do this by writing an SD card image to the SD card, following the instructions in our [standard software installation guide](../setup/software/standard-install.md). If you want to reset to the same release of the PlanktoScope as what you were originally using, you can check the release's version number in the "Software Version" field of the "Information" panel in [the Node-RED dashboard's System Monitoring page](./user-interface.md#system-monitoring); then you should download an SD card image for the corresponding release (as described in the software installation guide). When you re-flash the SD card, it will lose all data and non-default settings mentioned in [the section of this guide on backing up your data & settings](#back-up-your-data-settings).
+
+### Partial reset
+
+For now, partial reset approaches are only recommended for advanced users who can understand the implications of those partial reset approaches. Two kinds of partial reset are possible:
+
+1. If you just need to reset some or all of your operating system configuration file changes (such as those described in the [networking operations guide](./networking.md)) back to the default settings for the PlanktoScope OS, then you can just delete the relevant files (or you can even delete all files) within `/var/lib/overlays/overrides/etc/` (for example in the file browser at <http://planktoscope.local/admin/fs/files/var/lib/overlays/overrides/etc/> ) and then reboot your PlanktoScope immediately afterwards.
+
+2. If you want to reset the running software back to the original release of the PlanktoScope OS provided with your SD card image, while keeping any customizations you have made to override default PlanktoScope OS configurations (such as those described in the [networking operations guide](./networking.md)), then you can run the following command on your PlanktoScope (for example in the Cockpit Terminal at <http://planktoscope.local/admin/cockpit/system/terminal> ) and then reboot your PlanktoScope:
 
     ```sh
     forklift stage set-next --cache-img=false factory-reset
     ```
 
-    This reset will only have an effect if you had previously run a `forklift` command for configuring the OS; otherwise, it will not cause any visible change to your PlanktoScope. If your PlanktoScope is [connected to the internet](./networking.md#connect-your-planktoscope-to-the-internet), you can also omit the `--cache-img=false` flag, in order to ensure that the PlanktoScope will have all necessary programs at the originally-required versions before you reboot (if you never previously took manual action to delete any Docker container images from your PlanktoScope, you don't need to worry about this and you can keep the `--cache-img=false` flag in the command).
+    This reset will only have an effect if you had previously run a `forklift` command for configuring the OS; otherwise, it will not cause any visible change to your PlanktoScope. If your PlanktoScope is [connected to the internet](./networking.md#connect-your-planktoscope-to-the-internet), you can also omit the `--cache-img=false` flag, in order to ensure that the PlanktoScope will have all necessary programs at the originally-required versions before you reboot; but if you never previously took manual action to delete any Docker container images from your PlanktoScope, you don't need to worry about this and you can keep the `--cache-img=false` flag in the command.
 
-3. (Recommended for everyone) If you want to completely wipe your SD card and reset everything, then you should re-flash your PlanktoScope's SD card. You can do this by writing an SD card image to the SD card, following the instructions in our [standard software installation guide](../setup/software/standard-install.md). If you want to reset to the same release of the PlanktoScope as what you were originally using, you can check the release's version number in the "Software Version" field of the "Information" panel in [the Node-RED dashboard's System Monitoring page](./user-interface.md#system-monitoring); then you should download an SD card image for the corresponding release (as described in the software installation guide). When you re-flash the SD card, it will lose all data and non-default settings mentioned in [the section of this guide on backing up your data & settings](#back-up-your-data-settings).
+If you perform both kinds of partial reset consecutively, then you will reset the running software back to the original release of the PlanktoScope OS provided with your SD card image and you will also discard any customizations you have made to override default PlanktoScope OS configurations. Note that this does not reset certain kinds of application settings (such as for the Node-RED dashboard), and it does not delete any datasets you have collected with the PlanktoScope.
 
 ## Upgrade/downgrade the PlanktoScope OS
 
@@ -79,7 +87,7 @@ Eventually (i.e. if/when it becomes feasible and safe), we may make it possible
 
     If you don't know what `apt` or `apt-get` refer to, then please skip this section and just remember to avoid running `apt` or `apt-get` commands on your PlanktoScope!
 
-Most of the "interesting" software in the PlanktoScope OS (with Cockpit being a notable exception) is not managed using Raspberry Pi OS's APT package-management system, [for various reasons](../reference/software/architecture/os.md#system-upgrades). It's safe to run APT commands to install new packages in the PlanktoScope OS, at least for software which doesn't run during [early boot](../reference/software/architecture/os.md#boot-sequence), because of when the PlanktoScope OS's [filesystem overlay](../reference/software/architecture/os.md#filesystem) for `/usr` is initialized). It's *probably* safe to run APT commands to upgrade most packages installed in the PlanktoScope OS (at least for software which doesn't run during early boot), but we cannot make any guarantees or provide any support if you choose to do that. This is an issue of practicality: APT does not make it easy for us to exactly reproduce the changes to installed versions of packages caused by running `apt`/`apt-get`'s install/upgrade commands, when those commands are run at very different times; so it is not necessarily feasible for us to troubleshoot any resulting problems. If you want to undo the changes caused by running any APT commands, you should try to delete everything in `/var/lib/overlays/overrides/usr` (and maybe also `/var/lib/overlays/overrides/etc`) and reboot immediately afterwards.
+Most of the "interesting" software in the PlanktoScope OS (with Cockpit being a notable exception) is not managed using Raspberry Pi OS's APT package-management system, [for various reasons](../reference/software/architecture/os.md#system-upgrades). It's safe to run APT commands to install new packages in the PlanktoScope OS, at least for software which isn't needed during [early boot](../reference/software/architecture/os.md#boot-sequence), because of when the PlanktoScope OS's [filesystem overlay](../reference/software/architecture/os.md#filesystem) for `/usr` is initialized). It's *probably* safe to run APT commands to upgrade most packages installed in the PlanktoScope OS (at least for software which isn't needed during early boot), but we cannot make any guarantees or provide any support if you choose to do that. This is an issue of practicality: APT does not make it easy for us to exactly reproduce the changes to installed versions of packages caused by running `apt`/`apt-get`'s install/upgrade commands, when those commands are run at very different times; so it is not necessarily feasible for us to troubleshoot any resulting problems. If you want to undo the changes caused by running any APT commands, you should try to delete everything in `/var/lib/overlays/overrides/usr` (and maybe also `/var/lib/overlays/overrides/etc`) and reboot immediately afterwards.
 
 ## Restore your data & settings
 
diff --git a/documentation/docs/reference/software/product-specs.md b/documentation/docs/reference/software/product-specs.md
@@ -2,11 +2,84 @@
 
 The PlanktoScope OS includes all software which needs to run on the PlanktoScope's hardware to provide the [overall functionality of a PlanktoScope](../index.md). Product specifications for the PlanktoScope OS are listed below for ranges of software version numbers. To see software versions listed individually in chronological order, refer to the [project release notes](https://github.com/PlanktoScope/PlanktoScope/releases) or the [software changelog](./changelog.md). To understand how to interpret software version numbers, refer to our description of the PlanktoScope OS's [version numbering system](./release-process.md#version-numbering).
 
+## v2025.0.0
+
+Specs for v2025.0.0 are the same as in v2024.0.0, except for the following sections:
+
+- Base operating system: the distro has changed from Raspberry Pi OS 11 (bullseye) to Raspberry Pi OS 12 (bookworm).
+- Supported optional addons: additional support for up to one USB Wi-Fi adapter (with a compatible Wi-Fi chipset).
+
+### Functionalities
+
+Regular operation:
+
+- Image acquisition: stop-flow imaging (JPEG image output)
+- On-board image processing: detection and segmentation of objects (batch-processing only)
+- User interfacing: graphical interface accessible through web browser of a connected phone, tablet, or computer
+- Export of data for uploading to EcoTaxa
+
+Advanced operations:
+
+- User interfacing: web browser interfaces for system administration, system monitoring, and troubleshooting
+- Automation: MQTT-based API
+- Application deployment: ability to add software as OCI containers using Docker, optionally via [Forklift](https://docs-edge.planktoscope.community/reference/software/architecture/os/#package-management-with-forklift)
+- System configuration: ability to reversibly add, remove, replace, or override OS configuration files via Forklift
+
+### Base operating system
+
+- Distro: Raspberry Pi OS 12 (bookworm)
+- Binary target architecture: 64-bit (aarch64, also known as arm64)
+
+### Supported hardware
+
+Minimum for image acquisition (but not sufficient for on-board image processing):
+
+- PlanktoScope: hardware v2.1 with Raspberry Pi 4 Model B computer
+- Memory: 1 GB RAM
+- Storage: 8 GB capacity
+
+Minimum for full functionality, including on-board image processing:
+
+- Memory: 4 GB RAM
+
+Recommended:
+
+- PlanktoScope: hardware v2.5 or v2.6 with Raspberry Pi 4 Model B computer
+- Storage: 32 GB capacity
+
+Forwards-incompatibilities:
+
+- Unable to run on the Raspberry Pi 5 computer.
+- Incompatible with the upcoming PlanktoScope hardware v3.
+
+Backwards-incompatibilities:
+
+- Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.
+
+### Supported optional addons
+
+Networking peripherals:
+
+- Up to one phone (Android only) connected by USB cable in USB tethering mode: for internet access.
+- Up to one USB-to-Ethernet adapter: either for internet access or for direct access from a connected device.
+- Up to one USB Wi-Fi adapter (with [a compatible Wi-Fi chipset](https://github.com/morrownr/USB-WiFi/blob/main/home/USB_WiFi_Adapters_that_are_supported_with_Linux_in-kernel_drivers.md) such as RT5370): either for internet access or for creating an additional Wi-Fi hotspot to enable direct access.
+
+Miscellaneous data sources:
+
+- Up to one Adafruit Ultimate GPS HAT: for system clock synchronization, and for automatic detection of GPS location coordinates.
+
+### System performance
+
+With minimum supported hardware for full functionality:
+
+- On-board image processing: a dataset of 400 raw images is processed in approximately 1 hour
+
 ## v2024.0.0
 
 Specs for v2024.0.0 are the same as in v2023.9.0, except for the following sections:
 
 - Base operating system: the binary target architecture has changed from 32-bit to 64-bit.
+- Supported optional addons: support for up to one USB-to-Ethernet adapter as an optional addon.
 - System performance: on-board image processing speeds have improved (processing speeds have nearly doubled).
 
 ### Functionalities
@@ -50,11 +123,23 @@ Recommended:
 Forwards-incompatibilities:
 
 - Unable to run on the Raspberry Pi 5 computer.
+- Incompatible with the upcoming PlanktoScope hardware v3.
 
 Backwards-incompatibilities:
 
 - Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.
 
+### Supported optional addons
+
+Networking peripherals:
+
+- Up to one phone (Android only) connected by USB cable in USB tethering mode: for internet access.
+- Up to one USB-to-Ethernet adapter: either for internet access or for direct access from a connected device.
+
+Miscellaneous data sources:
+
+- Up to one Adafruit Ultimate GPS HAT: for system clock synchronization, and for automatic detection of GPS location coordinates.
+
 ### System performance
 
 With minimum supported hardware for full functionality:
@@ -103,11 +188,22 @@ Recommended:
 Forwards-incompatibilities:
 
 - Unable to run on the Raspberry Pi 5 computer.
+- Incompatible with the upcoming PlanktoScope hardware v3.
 
 Backwards-incompatibilities:
 
 - Might still work on a Raspberry Pi 3 Model B+ computer or a Raspberry Pi 4 Model B computer with 1 GB of RAM, but compatibility is not tested.
 
+### Supported optional addons
+
+Networking peripherals:
+
+- Up to one phone (Android only) connected by USB cable in USB tethering mode: for internet access.
+
+Miscellaneous data sources:
+
+- Up to one Adafruit Ultimate GPS HAT: for system clock synchronization, and for automatic detection of GPS location coordinates.
+
 ### System performance
 
 With minimum supported hardware for full functionality:
@@ -155,8 +251,19 @@ Recommended for full functionality:
 Forwards-incompatibilities:
 
 - Unable to run on the Raspberry Pi 5 computer.
+- Incompatible with the upcoming PlanktoScope hardware v3.
 - Incompatible with Adafruit Stepper Motor HATs (used in PlanktoScope hardware v2.1) manufactured after mid-2022.
 
+### Supported optional addons
+
+Networking peripherals:
+
+- Up to one phone (Android only) connected by USB cable in USB tethering mode: for internet access.
+
+Miscellaneous data sources:
+
+- Up to one Adafruit Ultimate GPS HAT: for system clock synchronization, and for automatic detection of GPS location coordinates.
+
 ### System performance
 
 With minimum supported hardware for full functionality:
diff --git a/documentation/docs/reference/software/release-process.md b/documentation/docs/reference/software/release-process.md
