Add an operations guide for upgrading/downgrading/resetting the OS

documentation/docs/operation/clone-sd.md

@@ -1,10 +1,10 @@
+# SD Card Cloning
 
 If you want to create an SD card image from your PlanktoScope to use on other PlanktoScopes, you can follow the following steps.
 
 ## Prepare the SD card for cloning
 
 Depending on whether you want to make an SD card image to reuse across multiple machines or whether you only want to make an exact backup of your SD card image, you will need to perform different steps to prepare your SD card for cloning.
-# Clone your SD card
 
 ### Prepare for cloning to reuse in other machines
 
@@ -18,12 +18,12 @@ Once this script finishes running, it will shut down your PlanktoScope's Raspber
 
 Next, you should remove the SD card from your PlanktoScope and plug it into another computer, so that you can clone the SD card into an SD card image; this guide assumes that your other computer runs Linux. With your SD card plugged into your other computer, you can mount the SD card's `rootfs` partition to delete any other sensitive files which were not removed by the `/usr/libexec/prepare-custom-image` script. For example, you may also want to delete or edit some or all of the following files from the `rootfs` partition in order to remove any sensitive or machine-specific information:
 
-- `etc/wpa_supplicant/wpa_supplicant.conf`: Wi-Fi configuration and network secrets.
-- `home/pi/.ssh/authorized_keys`: SSH public keys of devices authorized to remotely connect to the PlanktoScope.
-- `home/pi/data/`: all images acquired before by the PlanktoScope - this directory may be large, and you probably don't want to copy those datasets across all your other PlanktoScopes.
-- `home/pi/.bash_history`: Bash command history.
-- `home/pi/.python_history`: Python command history.
-- `home/pi/.gitconfig`: Git configuration, which may contain user-specific details.
+- `/var/lib/overlays/overrides/etc/wpa_supplicant/wpa_supplicant.conf`: Wi-Fi configuration and network secrets.
+- `/home/pi/.ssh/authorized_keys`: SSH public keys of devices authorized to remotely connect to the PlanktoScope.
+- `/home/pi/data/`: all images acquired before by the PlanktoScope - this directory may be large, and you probably don't want to copy those datasets across all your other PlanktoScopes.
+- `/home/pi/.bash_history`: Bash command history.
+- `/home/pi/.python_history`: Python command history.
+- `/home/pi/.gitconfig`: Git configuration, which may contain user-specific details.
 
 !!! info
     You can also delete the files listed above before running the `/usr/libexec/prepare-custom-image` script; the effect is the same. Either way, those files will be permanently deleted on your SD card. However, if you want to keep those files on your SD card, you should make backup copies of those files, and then you can copy those files back onto your SD card after you finish cloning the SD card to an image.
@@ -112,4 +112,4 @@ If you had set up the PlanktoScope software on a Raspberry Pi OS Lite image, you
 
 ## Use the SD card image
 
-You can now use this SD card image with the [non-standard installation guide](../setup/software/nonstandard-install.md) for installing the PlanktoScope OS on an SD card for one or more PlanktoScopes.
+You can now use this SD card image with the [standard installation guide](../setup/software/standard-install.md) for installing the PlanktoScope OS on an SD card for one or more PlanktoScopes.

documentation/docs/operation/index.md

@@ -30,12 +30,12 @@ Unless you have [changed the password](./networking.md#change-the-wi-fi-hotspots
 
 Once you connect your computer (or phone/tablet/etc.) to your PlanktoScope, you will need to access your PlanktoScope's software from a web browser on your computer.
 
-If you know the machine name of your PlanktoScope (which you can determine from the name of your PlanktoScope's Wi-Fi hotspot, as described above), you can try using your web browser to open a URL of format `http://pkscope-{machine-name}.local`, where `{machine-name}` should be substituted with your PlanktoScope's machine name. This URL should work unless you're on a device and web browser without mDNS support; notably, older versions of Android did not support mDNS, and web browsers installed on Linux computers via Flatpak [do not yet support mDNS](https://github.com/flatpak/xdg-desktop-portal/discussions/1365).
+If you know the machine name of your PlanktoScope (which you can determine from the name of your PlanktoScope's Wi-Fi hotspot, as described above), you can try using your web browser to open a URL of format `http://pkscope-{machine-name}.local`, where `{machine-name}` should be substituted with your PlanktoScope's machine name. This URL should work unless you're on a device or web browser without mDNS support; notably, older versions of Android did not support mDNS, and web browsers installed on Linux computers via Flatpak [do not yet support mDNS](https://github.com/flatpak/xdg-desktop-portal/discussions/1365).
 
 If you are connecting your computer directly to your PlanktoScope (i.e. via your PlanktoScope's Wi-Fi hotspot, or via an Ethernet cable from your computer to your PlanktoScope's Ethernet port) but you don't know (or you don't want to type out) your PlanktoScope's machine name, then you can try opening the following URLs in your web browser instead (try opening them in the following order, and just use the first one which works):
 
-- [http://planktoscope.local](http://planktoscope.local) (this should work unless you're on a device and web browser without mDNS support)
-- [http://pkscope.local](http://pkscope.local) (this should work unless you're on a device and web browser without mDNS support)
+- [http://planktoscope.local](http://planktoscope.local) (this should work unless you're on a device or web browser without mDNS support)
+- [http://pkscope.local](http://pkscope.local) (this should work unless you're on a device or web browser without mDNS support)
 - [http://home.pkscope](http://home.pkscope) (this should work unless your web browser is configured to use a Private DNS provider)
 - [http://192.168.4.1](http://192.168.4.1) (this should always work on devices connected directly to the PlanktoScope, especially for devices connected directly to the PlanktoScope's Wi-Fi hotspot)
 - [http://192.168.5.1](http://192.168.5.1) (this should always work on devices connected directly to the PlanktoScope, especially for devices connected directly to the PlanktoScope's Ethernet port)
@@ -58,11 +58,11 @@ One of the above URLs should work, and your web browser should show a landing pa
 
 !!! tip
 
-    If you access the landing page using any URL not of the format `http://pkscope-{machine-name}.local`, then the landing page will suggest its own machine-specific URL for you to try opening; you can see that in the above screenshot, which shows a yellow information box with the URL for the PlanktoScope used to make that screenshot. You should try opening it to see if it works in your web browser, and you may want to bookmark it for future reference for the reasons discussed in the warnings listed earlier in this section of the documentation.
+    If you access the landing page using any URL not of the format `http://pkscope-{machine-name}.local`, then the landing page will suggest its own machine-specific URL for you to try opening; you can see that in the above screenshot, which shows a yellow information box with the URL for the PlanktoScope used to make that screenshot. You should try opening your PlanktoScope's machine-specific URL to see if it works in your web browser, and you may want to bookmark it for future reference for the reasons discussed in the warnings listed earlier in this section of the documentation.
 
 You should click on the "Node-RED dashboard" link; this will open a new tab with the primary interface for operating your PlanktoScope. Once you have opened the Node-RED dashboard, you should proceed to our [User interface guide](user-interface.md) to understand how to use it.
 
-## How to image plankton
+## Acquire data on plankton samples
 
 Before doing an acquisition, you will need to collect targets. There are several ways to do this, and you probably already have a source nearby (in a culture if you are working in a lab).
 
@@ -79,3 +79,11 @@ If needed you can also clean the outside of the objective lens with a soft cloth
 For quantitative imaging of water samples, refer to the following protocols published by members of the PlanktoScope community:
 
 - "[Planktoscope protocol for plankton imaging](https://www.protocols.io/view/planktoscope-protocol-for-plankton-imaging-bp2l6bq3zgqe)". A [PDF copy](protocol-v4.pdf) of a draft of version 4 of this protocol is also available for offline use.
+
+## Manage your PlanktoScope's embedded computer
+
+Your PlanktoScope has a Raspberry Pi computer embedded inside it which runs the PlanktoScope's software. You may need to perform various system administration/operations tasks on it, such as:
+
+- [Resetting or upgrading/downgrading the software on it](./software-upgrades.md), such as for resetting your PlanktoScope's settings back to its factory defaults, testing out new software updates, or switching back to an older software version after testing out a newer version.
+- [Changing its network configuration](./networking.md), such as for connecting your PlanktoScope to the internet, maintaining internet access on a computer connected simultaneously to both your PlanktoScope (e.g. by Ethernet) and an external network (e.g. by Wi-Fi), making your PlanktoScope more secure, or customizing your PlanktoScope's machine name.
+- [Cloning its SD card](./clone-sd.md) to back up its settings and data, or to replicate its exact settings and data across multiple PlanktoScopes

documentation/docs/operation/maintenance.md

@@ -9,8 +9,6 @@ Instructions for maintaining and repairing the PlanktoScope.
 * To clean the lenses and other optics, use a lens cleaning solution and a lens cleaning tissue or cloth. Gently wipe the optics in a circular motion, starting from the center and working outward. Avoid applying too much pressure or using a rough cloth, as this can scratch or damage the optics.
 * Once you have finished cleaning the optics, use a dry cloth to remove any excess moisture or cleaning solution.
 
-## Software updates
+## Software
 
-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 a few times 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 the latest stable release.
-
-Currently, you will need to re-flash the SD card of your PlanktoScope's embedded Raspberry Pi in order to update the PlanktoScope software to the latest version, and then you will need to reapply any custom software configurations you had set (e.g. hardware settings). We are also developing an easier and less disruptive way to update the PlanktoScope software, but it is not yet ready for use.
+For information about maintaining the software on your PlanktoScope (such as installing software updates), see our [software reset & upgrades guide](./software-upgrades.md).