diff --git a/documentation/docs/operation/clone-sd.md b/documentation/docs/operation/clone-sd.md index e9f79160c..40637b52c 100644 --- a/documentation/docs/operation/clone-sd.md +++ b/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. diff --git a/documentation/docs/operation/index.md b/documentation/docs/operation/index.md index c14328944..a0d5b7d55 100644 --- a/documentation/docs/operation/index.md +++ b/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 diff --git a/documentation/docs/operation/maintenance.md b/documentation/docs/operation/maintenance.md index c1c63c1ca..d7d07cff5 100644 --- a/documentation/docs/operation/maintenance.md +++ b/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 , 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). diff --git a/documentation/docs/operation/software-upgrades.md b/documentation/docs/operation/software-upgrades.md new file mode 100644 index 000000000..d4d65498c --- /dev/null +++ b/documentation/docs/operation/software-upgrades.md @@ -0,0 +1,95 @@ +# Software Reset & Upgrades + +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 , 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. + +## Back up your data & settings + +Before you reset/upgrade/downgrade the software installed on your PlanktoScope, you may want to back up any important data and settings on your PlanktoScope. We recommend everyone to take the following actions: + +- You should use the dataset file browser (accessible via a link on our PlanktoScope's landing page, or via [the Node-RED dashboard's Gallery page](./user-interface.md#gallery)) to download any data you don't want to lose. +- You should write down the white balance gains you have calibrated on [the Node-RED dashboard's Optic Configuration page](./user-interface.md#optic-configuration), as those values may be lost depending on how you reset or upgrade/downgrade the PlanktoScope OS. +- You should write down the hardware settings and calibrations you see on [the Node-RED dashboard's Hardware Settings page](./user-interface.md#hardware-settings), as those values may be lost depending on how you reset or upgrade/downgrade the PlanktoScope OS. + +Advanced users may also want to take the following actions, depending on what changes they have made: + +- If you don't want to write down your white balance gains and hardware settings/calibrations, you can instead back up your PlanktoScope's hardware settings file, which is saved at `/home/pi/PlanktoScope/hardware.json`, for example in the file browser at . This file includes some hidden settings not exposed in the PlanktoScope's Node-RED dashboard - so if you have changed any such settings by editing this file, then you may want to back up this file. +- If you have [changed your PlanktoScope's networking configurations](./networking.md) by editing files in `/etc` (which overrides the default configuration files exported by Forklift into the operating system, as well as configuration files originally provided by the Raspberry Pi OS as part of the PlanktoScope OS), you may want to back up your changes. You can download your changes from within `/var/lib/overlays/overrides/etc`, for example in the file browser at . +- If you have made extensive changes to your operating system by running `forklift` commands which modified your local Forklift pallet, you may want to back them up by using Git to commit those changes and then push your local Forklift pallet (which is a local Git repository at `/home/pi/.local/share/forklift/pallet`) to a repository (e.g. on GitHub). + +## Reset the PlanktoScope OS + +Multiple levels of reset are possible; from least-disruptive (and shallowest) to most-disruptive (and most thorough), they are: + +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 ) and then reboot your PlanktoScope immediately afterwards. + +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 ) and then reboot your PlanktoScope: + + ```sh + forklift stage set-next --no-cache-img 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 `--no-cache-img` 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 `--no-cache-img` 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). + +## Upgrade/downgrade the PlanktoScope OS + +Currently, to upgrade or downgrade your PlanktoScope to some other release of the PlanktoScope OS, we recommend flashing a new SD card with an SD card image for that release of the PlanktoScope OS, following the instructions in our [standard software installation guide](../setup/software/standard-install.md) (or, if you are an advanced user doing something weird/interesting, using the [non-standard software installation guide](../setup/software/nonstandard-install.md)). That way, you can always swap back to your previous SD card if needed. If you only have one SD card, you can re-flash that SD card with the SD card image you want to run - but you will lose all your data and settings, unless you previously [backed them up](#back-up-your-data-settings). + +### Perform an in-place upgrade/downgrade + +Starting with the [v2024.0.0 release](https://github.com/PlanktoScope/PlanktoScope/releases/tag/software%2Fv2024.0.0) of the PlanktoScope OS, certain software upgrades/downgrades can be performed without re-flashing your SD card, by running a `forklift` command on a PlanktoScope [connected to the internet](./networking.md#connect-your-planktoscope-to-the-internet). However, for now we only recommend using this mechanism for testing certain kinds of changes to the PlanktoScope OS (e.g. as described in specific instructions posted on the PlanktoScope Slack for software-testing volunteers), because certain kinds of frequent software changes (namely, changes to [the Node-RED dashboard](../reference/software/architecture/os.md#user-interface) and [the PlanktoScope hardware controller](../reference/software/architecture/os.md#planktoscope-specific-hardware-abstraction), and changes to the installed version of the `forklift` command) are not yet ready to be managed using `forklift`. + +!!! warning + + The PlanktoScope OS's support for in-place upgrade/downgrade functionality is still a work in progress. If you are unsure, then you should perform upgrades/downgrades by (re-)flashing your SD card, not by running a `forklift` command. + +When an in-place upgrade to a new release is possible, specific instructions and backwards-compatibility information will be mentioned in the GitHub release notes for that release. However, the general pattern will look something like running the following command (from v2024.0.0 of the PlanktoScope OS), where `{version-query}` would be replaced by a Git branch name (e.g. `beta`), tagged version (e.g. `v2024.0.0`), or (potentially-abbreviated) Git commit SHA: + +```sh +forklift pallet switch github.com/PlanktoScope/pallet-standard@{version-query} +``` + +or one of the following commands (from v2025.0.0-alpha.0 of the PlanktoScope OS): + +```sh +# for a specific version: +forklift pallet upgrade @{version-query} +# for the latest version available in the most-recently-used version query: +forklift pallet upgrade +``` + +and then rebooting after that command finishes successfully. + +Eventually (i.e. if/when it becomes feasible and safe), we may make it possible for you to turn on automatic upgrade checks, automatic background downloads of available upgrades, or even automatic installation of upgrades; those features will only have any effects on PlanktoScopes connected to the internet. However, even in that scenario some releases (once every few years) will still require you to re-flash your PlanktoScope's SD card with a new SD card image; this is because of the major release cadence of the Raspberry Pi OS, which is used for building PlanktoScope OS SD card images, and which itself is not safe to upgrade in-place. + +!!! info + + If you try to use `forklift` to switch to a version (prerelease/branch/commit) of `github.com/PlanktoScope/pallet-standard` or some other Forklift pallet which attempts to deploy a program which cannot start for some reason, then `forklift` will record that failure and automatically revert back to the previously-running pallet/version combination on every subsequent boot, until the next time you attempt to switch/upgrade/downgrade to some version of some pallet. + + Thus, if you find that you attempted to upgrade the PlanktoScope OS using `forklift` but your PlanktoScope automatically returned to the previous installed version of the OS after a reboot, then that means that your PlanktoScope couldn't run the newer version for some reason. Information about this will be reported if you run the command `forklift stage show`. + +### Avoid touching `apt`/`apt-get`! + +!!! info + + 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 *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](../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), 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 reboot immediately afterwards. + +## Restore your data & settings + +If you reset/upgraded/downgraded the PlanktoScope OS by re-flashing your SD card, then: + +- You can restore your [backed-up data & settings](#back-up-your-data-settings) by re-uploading your backup files to their respective locations and then rebooting your PlanktoScope. +- (Only relevant for advanced users) If you were running a non-standard Forklift pallet (i.e. anything other than [github.com/PlanktoScope/pallet-standard](https://github.com/PlanktoScope/pallet-standard)) which you had pushed to a GitHub repository host (such as GitHub), then you can run a Forklift command to switch back to that pallet (assuming that your PlanktoScope [has an internet connection](./networking.md#connect-your-planktoscope-to-the-internet) so that it can download the pallet), for example in the Cockpit Terminal at : + + ```sh + forklift pallet switch github.com/name-of/your-pallet@version-query + ``` + + Afterwards, you should reboot your PlanktoScope; it will try to boot using the pallet you had specified. diff --git a/documentation/docs/operation/user-interface.md b/documentation/docs/operation/user-interface.md index 2197d53c6..510ad1780 100644 --- a/documentation/docs/operation/user-interface.md +++ b/documentation/docs/operation/user-interface.md @@ -8,7 +8,7 @@ This guide will help you understand how to use the Node-RED dashboard, which is When you open the "Node-RED dashboard link" from the [PlanktoScope's landing page](index.md#access-your-planktoscopes-software), you will reach a page like what is shown in the screenshot above. -From here, you can quickly access any of the available tabs. The buttons are only the most used functionnalities of the machine. Three others tabs are accessible only through the hamburger menu on the top left of the screen (the three horizontal lines): +From here, you can quickly access any of the available tabs. The buttons are only the most used functionalities of the machine. Three others tabs are accessible only through the hamburger menu on the top left of the screen (the three horizontal lines): - Wifi - Administration @@ -97,17 +97,17 @@ This simple page will allow you to preview and download the captured data. ## System Monitoring -This tab allows you to view more detailed information about your PlanktoScope. The Metrics panel has graphs for monitoring your the CPU temperature, memory usage, and SD card usage of your PlanktoScope's embedded Raspberry Pi computer, as well as an expandable (collapsed-by-default) panel with more detailed information about CPU usage, system load, network bandwidth usage, and disk reads/writes. +This tab allows you to view more detailed information about your PlanktoScope. The Metrics panel has graphs for monitoring the CPU temperature, memory usage, and SD card usage of your PlanktoScope's embedded Raspberry Pi computer, as well as an expandable (collapsed-by-default) panel with more detailed information about CPU usage, system load, network traffic volumes, and disk read/write volumes. ![System Monitoring](../images/ui_guide/system-monitoring-dashboard.png) -The Information panel shows your PlanktoScope's machine name, its hardware version, its PlanktoScope's software version, its camera model, the system time on the PlanktoScope, and . +The Information panel shows your PlanktoScope's machine name, its hardware version, its PlanktoScope's software version, its camera model, the system time on the PlanktoScope, and the system time on the device running your web browser. Note: if your PlanktoScope's system time is different from your web browser's time by more than 1 minute, the Metrics graphs will be replaced with a prompt for you to change your PlanktoScope's system time to match your web browser's time: ![System Monitoring time-adjustment prompt](../images/ui_guide/system-monitoring-time-prompt.png) -You will need to do change the PlanktoScope's system time in order for the Metrics panel to work. The system time will be accurate until your PlanktoScope shuts down; the next time you turn on your PlanktoScope, you will need to change the PlanktoScope's system time again. This is a known problem, and we will improve the usability of this situation in future versions of the PlanktoScope software. +You will need to change the PlanktoScope's system time (for example by pressing the button displayed in the prompt) in order for the Metrics panel to work, and in order for your PlanktoScope to record accurate timestamps with its image acquisition datasets. The system time will be accurate until your PlanktoScope shuts down; the next time you turn on your PlanktoScope, you will need to change the PlanktoScope's system time again. This is a known problem, and we will improve the usability of this situation in future versions of the PlanktoScope software. !!! warning diff --git a/documentation/docs/reference/software/architecture/os.md b/documentation/docs/reference/software/architecture/os.md index d5f77f61e..ccc1c00a2 100644 --- a/documentation/docs/reference/software/architecture/os.md +++ b/documentation/docs/reference/software/architecture/os.md @@ -38,7 +38,7 @@ In order to abstract the Raspberry Pi computer hardware to enable execution of o - Lower-level system services - including services which we've added on top of the default Raspberry Pi OS - are launched and supervised by [systemd](https://systemd.io/), which provides a system and service manager. We use systemd because the Raspberry Pi OS provides it and relies on it. -- Most of the PlanktoScope's software is (or eventually will be) executed as [Docker](https://www.docker.com/) containers by the [`dockerd`](https://docs.docker.com/get-started/overview/#the-docker-daemon) daemon (which in turn is run by the `docker.service` systemd service). In the PlanktoScope OS, all Docker containers are declaratively specified, configured, and integrated together as [Docker Compose](https://docs.docker.com/compose/) applications. We use Docker because it enables us to isolate programs from each other so that they interact only in specifically-defined ways; this makes it easier for us to configure, integrate, distribute, and deploy the various programs running on the PlanktoScope. +- Most of the PlanktoScope's software is (or eventually will be) executed as [Docker](https://www.docker.com/) containers by the [`dockerd`](https://docs.docker.com/get-started/overview/#the-docker-daemon) daemon (which in turn is run by the `docker.service` systemd service). In the PlanktoScope OS, all Docker containers are declaratively specified, configured, and integrated together as [Docker Compose](https://docs.docker.com/compose/) applications. We use Docker because it enables us to isolate programs from each other so that they interact only in specifically-defined ways; this makes it easier for us to configure, integrate, distribute, and deploy the various programs running on the PlanktoScope. Docker does cause some usability quirks (specifically related to user permissions on files) because it runs in rootful mode, so we might consider switching to Podman at some (far?) point in the future - but that would be a serious decision requiring thorough consideration. The PlanktoScope OS is a 64-bit operating system. @@ -54,6 +54,12 @@ Because the PlanktoScope OS is a systemd-based Linux system running on the Raspb The systemd system manager starts a variety of services added by the PlanktoScope OS which do not exist in the default installation of the Raspberry Pi OS, such as `docker.service`. The startup ordering relationships between those services are listed in our reference document about [services in the startup process](../subsystems/startup.md#services). +Notably as part of basic boot-up (systemd's `basic.target`), systemd will run [a set of PlanktoScope OS-specific services](../subsystems/startup.md#software-deployment-execution) for remounting `/etc` and `/usr` as overlay filesystems to merge the following sets of OS files, which are stored/mounted in different locations of the OS's [filesystem](#filesystem): + +- OS files provided by the standard Raspberry Pi OS (and a few PlanktoScope OS-specific files added added by the process of building PlanktoScope OS SD card images). Before boot these files are stored at `/etc` and `/usr`, but during boot they are instead found at `/sysroot/etc` and `/sysroot/usr` . +- OS files (including some overrides of files provided by the standard Raspberry Pi OS) managed by Forklift (introduced in the next section) in `/var/lib/forklift/stages`. Storing these files separately makes it easy for them to be atomically added/removed/replaced as a group for reliable [in-place upgrades/downgrades](../../../operation/software-upgrades.md#perform-an-in-place-upgradedowngrade) of the operating system. +- User-applied customizations and overrides to any of those OS files in `/var/lib/overlays/overrides/etc` and `/var/lib/overlays/overrides/usr`. Storing these overrides separately makes it easy for user-made changes to be identified and reverted individually, e.g. as described in our [networking operations guide](../../../operation/networking.md). + ### System upgrades Traditional Linux distros such as the Raspberry Pi OS are designed to run software directly on the host OS using a shared collection of programs and system libraries provided by the Linux distro, and with programs and libraries installed and upgraded in-place directly on the host OS via the package managers provided by the distro, such as [APT](https://en.wikipedia.org/wiki/APT_(software)) and [`pip`](https://pip.pypa.io/en/stable/). This causes the following challenges for system administration on the PlanktoScope: @@ -70,41 +76,45 @@ All of the factors listed above increase the perceived risk (and/or the required - Running all PlanktoScope-specific programs which require system libraries (e.g. the PlanktoScope's Python-based programs) in Docker containers - with the required versions of the required system libraries bundled inside those containers - to isolate them from the host OS's libraries installed via APT. This way, APT packages will always be safe to add, upgrade, and remove on the host OS with negligible risk of interfering with PlanktoScope-specific software. -- Enabling (almost) all software not provided by the default installation of the Raspberry Pi OS to be upgraded and downgraded in-place - either as container images or as replacements of files on the filesystem - with just a reboot. This way, software upgrades can be reverted in-place in case new bugs are introduced, and SD cards will only need to be re-flashed with new images once every few years (i.e. after a new major version of the Raspberry Pi OS is released). +- Enabling (almost) all software and OS configuration files not provided by the default installation of the Raspberry Pi OS to be upgraded and downgraded in-place - either as container images or as replacements of files on the filesystem - with just a reboot. This way, software upgrades can be (perhaps even automatically, for certain kinds of bugs) reverted in-place in case new bugs are introduced, and SD cards will only need to be re-flashed with new images once every few years (i.e. after a new major version of the Raspberry Pi OS is released). - Enabling most types of user-initiated OS customizations to be version-controlled (in a Git repository) and applied (as a system upgrade/downgrade) together with most of the default configurations added by the PlanktoScope OS over what is already present from the default installation of the Raspberry Pi OS. This way, user-initiated OS customizations can be easy to re-apply automatically even after an SD card is re-flashed with a fresh SD card image of the PlanktoScope OS. -Currently, we have partially implemented the systems necessary for these goals. Much of the PlanktoScope's software is not installed or upgraded directly on the host OS via APT or `pip`; instead, we use a (partially-implemented) tool called [`forklift`](https://github.com/PlanktoScope/forklift) which we're developing specifically to support the goals listed above, and which provides a robust way for us to fully manage deployment, configuration, and upgrading of: +We have implemented most of the systems necessary for these goals. Much of the PlanktoScope's software is not installed or upgraded directly on the host OS via APT or `pip`; instead, we use a (mostly-complete) tool called [`forklift`](https://github.com/PlanktoScope/forklift) which we're developing specifically to support the goals listed above, and which provides a robust way for us to fully manage deployment, configuration, and upgrading of: - All software which we run using Docker. - PlanktoScope-specific systemd services. - PlanktoScope-specific OS configuration files. -Everything managed by `forklift` is version-controlled in a [Git](https://git-scm.com/) repository, enabling easy backup and restoration of `forklift`-managed configurations even if the PlanktoScope's SD card is wiped and re-flashed. +Everything managed by `forklift` is version-controlled in a [Git](https://git-scm.com/) repository with a special file structure (so that the repository is called a *pallet*), enabling easy backup and restoration of `forklift`-managed configurations even if the PlanktoScope's SD card is wiped and re-flashed. Forklift is designed so that a pallet is effectively a version-controlled, configurable, declarative [bill of materials](https://en.wikipedia.org/wiki/Bill_of_materials) for software/configuration modules which are composed together by Forklift into a significant layer of the PlanktoScope OS. Performing an OS upgrade/downgrade with Forklift is just a matter of running a `forklift` command to switch to a different version of a pallet, as described [in our OS upgrade operations guide](../../../operation/software-upgrades.md#perform-an-in-place-upgradedowngrade). + +!!! info + + Forklift was created mostly because the PlanktoScope OS really needs to be built around the Raspberry Pi OS, and because the Raspberry Pi OS is not yet compatible with [bootc](https://containers.github.io/bootc/) (and not even [OSTree](https://ostreedev.github.io/ostree/introduction/)), and because the Raspberry Pi OS also does not yet have mature support for [systemd-sysext](https://www.freedesktop.org/software/systemd/man/latest/systemd-sysext.html), and those systems also don't meet the PlanktoScope OS's full set of requirements - so we don't yet have a sufficiently simple (and free-and-easy-for-project-maintainers-to-operate) alternative to facilitate system upgrades+downgrades and system customization for the PlanktoScope OS. + + In an ideal world, we would not need to use/maintain Forklift in the PlanktoScope OS for achieving the goals which originally motivated the creation of Forklift...or at least Forklift could outsource so much functionality to externally-maintained systems that Forklift could be reduced to a UI wrapper. Or maybe the PlanktoScope OS's goals will later be reduced to the point that Forklift will no longer be very useful for the PlanktoScope OS. ### Package management with `forklift` -When you're just experimenting and you can tolerate the challenges mentioned above, it's fine to customize the PlanktoScope OS by installing software packages using `pip` directly on the OS and/or by making extensive changes to OS configuration files. However, once you actually care about keeping your customizations around - and especially if/when you want to share your customizations with other people - we recommend migrating those customizations into Forklift packages, which are just files and configuration files stored in a specially-structured Git repository which is also published online (e.g. on GitHub, GitLab, Gitea, etc.). `forklift` provides an easy way to [package, publish](https://github.com/PlanktoScope/forklift/blob/main/docs/design.md#app-packaging-and-distribution), [combine, and apply](https://github.com/PlanktoScope/forklift/blob/main/docs/design.md#app-deployment-configuration) customizations via YAML configuration files in Git repositories; this enables easy sharing, configuration, (re-)composition, and downloading of Docker Compose applications, systemd services, and OS configuration files. Configurations of all deployments of Forklift packages on a computer running the PlanktoScope OS are specified and integrated in a single Git repository, a *Forklift pallet*. At any given time, each PlanktoScope has exactly one Forklift pallet deployed; switching between Forklift pallets (whether to try out a different set of customizations or to upgrade/downgrade all programs and OS configurations managed by Forklift) is easy and can be done by running just one command (`forklift pallet switch`, described below in the [Applying published customizations](#applying-published-customizations) subsection). +When you're just experimenting and you can tolerate the challenges mentioned above, it's fine to customize the PlanktoScope OS by installing software packages using `pip` directly on the OS and/or by making extensive changes to OS configuration files. However, once you actually care about keeping your customizations around - and especially if/when you want to share your customizations with other people - we recommend migrating those customizations into Forklift packages, which are just files and configuration files stored in a specially-structured Git repository which is also published online (e.g. on GitHub, GitLab, Gitea, etc.). `forklift` provides an easy way to [package, publish](https://github.com/PlanktoScope/forklift/blob/main/docs/design.md#app-packaging-and-distribution), [combine, and apply](https://github.com/PlanktoScope/forklift/blob/main/docs/design.md#app-deployment-configuration) customizations via YAML configuration files in Git repositories; this enables easy sharing, configuration, (re-)composition, and downloading of Docker Compose applications, systemd services, and OS configuration files. Configurations of all deployments of Forklift packages on a computer running the PlanktoScope OS are specified and integrated in a single Git repository, a *Forklift pallet*. At any given time, each PlanktoScope has exactly one Forklift pallet applied; switching between Forklift pallets (whether to try out a different set of customizations or to upgrade/downgrade all programs and OS configurations managed by Forklift) is easy and can be done by running just one command (`forklift pallet switch`, described below in the [Applying published customizations](#applying-published-customizations) subsection). -`forklift` is used very differently compared to traditional Linux system package managers like APT, for which you must run step-by-step commands in order to modify the state of your system (e.g. to install some package or install some other package). When using `forklift`, you instead edit configuration files which declare the desired state of your system (though some step-by-step commands are also provided by `forklift` to make editing of files easier), and then you ask `forklift` to try to reconcile the actual state of your system with the desired state. If you've worked with [Hashicorp Terraform](https://www.terraform.io/)/[OpenTofu](https://opentofu.org/) before, this may sound very familiar to you - in fact, several aspects of `forklift`'s design were inspired by Terraform. +`forklift` is used very differently compared to traditional Linux system package managers like APT, for which you must run step-by-step commands in order to modify the state of your system (e.g. to install some package or install some other package). When using `forklift`, you instead edit configuration files which declare the desired state of your system (or you can instead run some commands provided by `forklift` for common operations, such as in [this example](../../../operation/networking.md#dont-allow-the-planktoscope-to-be-used-as-a-default-gateway-to-the-internet)), and then you ask `forklift` to prepare to make your system match the desired state on its next boot. -#### Dependency management +#### (No traditional) dependency management -`forklift` is simpler than traditional package managers in some notable ways, including in the concept of dependencies between packages. For example, Forklift packages cannot specify dependencies on other Forklift packages; instead, they may declare that they depend on certain resources - and you must declare a deployment of some other package which provides those resources. And although `forklift` checks whether resource dependencies between package deployments are satisfied, it does not attempt to solve unmet dependencies. If you've worked with the [Go programming language](https://go.dev/) before, resource dependency relationships among Forklift packages are analogous to the relationships between functions which require arguments with particular [interfaces](https://www.alexedwards.net/blog/interfaces-explained) and the types which implement those interfaces, with Forklift resources being analogous to Go interfaces. +`forklift` is simpler than traditional package managers in some notable ways (because `forklift` is designed to be much less than a traditional package manager), including in the concept of dependencies between packages. For example, Forklift packages cannot specify dependencies on other Forklift packages; instead, they may declare that they depend on certain resources - and you must declare a deployment of some other package which provides those resources. And although `forklift` checks whether resource dependencies between package deployments are satisfied, it does not attempt to solve unmet dependencies (as that is an NP-complete problem which also happens to be a major source of complexity in traditional package managers). If you've worked with the [Go programming language](https://go.dev/) before, resource dependency relationships among Forklift packages are analogous to the relationships between functions which require arguments with particular [interfaces](https://www.alexedwards.net/blog/interfaces-explained) and the types which implement those interfaces, with Forklift resources being analogous to Go interfaces. -This design is intended to facilitate replacement of particular programs with modified or customized versions of those programs. For example, a Forklift package could be declared as providing the same API on the same network port as some other package, so that one package can be substituted for the other while still maintaining compatibility with some other program which relies on the existence of that API. `forklift` also checks these resource declarations to ensure that any two packages which would conflict with each other (e.g. by trying to listen on the same network port) will be prevented from being deployed together. +This design is intended to facilitate replacement of particular programs with modified or customized versions of those programs. For example, a Forklift package could be declared as providing the same API on the same network port as some other package, so that one package can be substituted for the other while still being treated by Forklift as being compatible with some other program which relies on the existence of that API. `forklift` also checks these resource declarations to ensure that any two packages which would conflict with each other (e.g. by trying to listen on the same network port) will be prevented from being deployed together. #### Making & publishing customizations The workflow with `forklift` for developing/testing OS customizations, such as new package deployments or non-standard configurations of existing package deployments or substitutions of existing package deployments, is as follows: -- Initialize a custom pallet based on (i.e. layered over) an existing pallet, using the `forklift pallet init` command (e.g. `forklift pallet init --from github.com/PlanktoScope/pallet-standard@stable --as github.com/ethanjli/custom-pallet` to make a starter which will be a customization of the latest stable version of the [github.com/PlanktoScope/pallet-standard](https://github.com/PlanktoScope/pallet-standard) pallet, and which can be published to `github.com/ethanjli/custom-pallet`). (Note: the `forklift pallet init` command is not yet implemented, and pallet layering is not yet implemented; currently, pallets can only be created manually via the filesystem by cloning from an existing Git repository.) +- Initialize a custom pallet based on (i.e. layered over) an existing pallet, using the `forklift pallet init` command (e.g. `forklift pallet init --from github.com/PlanktoScope/pallet-standard@stable --as github.com/ethanjli/custom-pallet` to make a starter which will be a customization of the latest stable version of the [github.com/PlanktoScope/pallet-standard](https://github.com/PlanktoScope/pallet-standard) pallet, and which can be published to `github.com/ethanjli/custom-pallet`). (Note: the `forklift pallet init` command is not yet implemented, so currently a new pallet can only be created by manually initializing a new Git repository and creating a few YAML files inside it) - Optionally, create new Forklift packages with definitions of Docker Compose applications and/or systemd services and/or OS configuration files, and configure the deployment of those packages by creating particular files in the pallet. -- Optionally, add published Forklift repositories to the pallet with the `forklift pallet add-repo` command (e.g. `forklift pallet add-repo github.com/ethanjli/pallet-example-minimal@main`), so that one or more packages provided by those repositories can be deployed with the pallet by creating one or more package deployment configuration files for each package. The `forklift pallet add-repo` command is also used to upgrade or downgrade the version of the Forklift repository used by the pallet. - -- Optionally, add one or more files which override files from the existing pallet, in order to override the configurations specified by those files. (Note: file overrides are not yet implemented, because they are part of pallet layering functionality which is not yet implemented.) +- Optionally, add one or more files which override files from the existing pallet, in order to override the configurations specified by those files. - Stage the pallet to be applied on the next boot of the PlanktoScope OS, with the `forklift pallet stage` command; when Forklift applies a pallet, it makes the PlanktoScope OS match the configuration of Forklift package deployments specified by the pallet. @@ -114,15 +124,13 @@ The workflow with `forklift` for developing/testing OS customizations, such as n #### Applying published customizations -The envisioned workflow for applying published customizations (which you or someone else already developed and pushed to a Git repository served by an online host such as GitHub) is only partially implemented so far, but it already works well for basic use-cases - and it is already used as part of the PlanktoScope OS's [installation process](../subsystems/installation.md) for setting up the PlanktoScope OS over a Raspberry Pi OS image: - -- Stage the customized pallet to be applied on the next boot of the PlanktoScope OS, using the `forklift pallet switch` command (e.g. `forklift pallet switch github.com/PlanktoScope/pallet-segmenter@edge` to use the latest development/unstable version of the [github.com/PlanktoScope/pallet-segmenter](https://github.com/PlanktoScope/pallet-segmenter) pallet). +To apply published customizations (which you or someone else already developed and pushed to a Git repository served by an online host such as GitHub): -- Reboot the Raspberry Pi computer to apply the staged pallet. If the staged pallet cannot be successfully applied during boot, on subsequent boots `forklift` will instead apply the last staged pallet which was successfully applied. (Note: only a failure to update the Docker containers running on the OS is detected as a failed attempt to apply the staged pallet; if you cause problems with the systemd services or other OS configurations provided by your pallet but the Docker containers are all correctly updated, the pallet will still be considered to have been successfully applied.) +1. Stage the customized pallet to be applied on the next boot of the PlanktoScope OS, using the `forklift pallet switch` command (e.g. `forklift pallet switch github.com/PlanktoScope/pallet-segmenter@edge` to use the latest development/unstable version of the [github.com/PlanktoScope/pallet-segmenter](https://github.com/PlanktoScope/pallet-segmenter) pallet). -(TODO: create a "tutorial"-style page elsewhere in this docs site, and link to it from here; it could just be a pallet which reconfigures the docs-site deployment to serve the full site with hardware instructions, and which includes https://hub.docker.com/r/linuxserver/firefox or https://github.com/linuxserver/docker-chromium and/or https://github.com/linuxserver/docker-webtop and/or ZeroTier and/or an ML classifier GUI and/or Jupyter Tensorflow) +2. Reboot the Raspberry Pi computer to apply the staged pallet. If the staged pallet cannot be successfully applied during boot, on subsequent boots `forklift` will instead apply the last staged pallet which was successfully applied. (Note: only a failure to update the Docker containers running on the OS is detected as a failed attempt to apply the staged pallet; if you cause problems with the systemd services or other OS configurations provided by your pallet but the Docker containers are all correctly updated, the pallet will still be considered to have been successfully applied.) -Note: currently all of `forklift`'s functionality is only exposed through a command-line interface, but after the `forklift` tool stabilizes we plan to add a web browser-based graphical interface for use by a general audience. +Note: currently all of `forklift`'s functionality is only exposed through a command-line interface, but after the `forklift` tool stabilizes we will consider the possibility of adding a web browser-based graphical interface for use by a general audience. ## PlanktoScope-specific hardware abstraction @@ -184,7 +192,7 @@ The PlanktoScope is often deployed in settings with limited or unstable internet We solve this problem by allowing the PlanktoScope to connect to the internet over a known Wi-Fi network, and/or over Ethernet, so that the PlanktoScope's web browser-based interfaces can be accessed over the internet; and by making the PlanktoScope bring up a Wi-Fi hotspot (more formally, a [wireless access point](https://en.wikipedia.org/wiki/Wireless_access_point)) using the Raspberry Pi's integrated Wi-Fi module in the absence of any known Wi-Fi network, so that the web browser-based interfaces can be accessed over the Wi-Fi hotspot. -When a device connects directly to the PlanktoScope (e.g. via the PlanktoScope's Wi-Fi hotspot, or via an Ethernet cable), the PlanktoScope acts as a [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol) server to assign itself certain static IP addresses (e.g. 192.168.4.1) and as a DNS server to assign itself certain domain names (e.g. `home.pkscope`), so that user can locate and open the PlanktoScope's web browser-based interfaces via those domain names. The PlanktoScope also announces itself under certain [mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) names (e.g. `pkscope.local`) which may work on networks where the PlanktoScope does not have a static IP address (e.g. because the PlanktoScope is connected to an existing Wi-Fi network). +When a device connects directly to the PlanktoScope (e.g. via the PlanktoScope's Wi-Fi hotspot, or via an Ethernet cable), the PlanktoScope acts as a [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol) server to assign itself certain static IP addresses (e.g. 192.168.4.1) and as a DNS server to assign itself certain domain names (e.g. `home.pkscope`), so that user can locate and open the PlanktoScope's web browser-based interfaces via those domain names. The PlanktoScope also announces itself under certain [mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) names (e.g. `planktoscope.local`) which may work on networks where the PlanktoScope does not have a static IP address (e.g. because the PlanktoScope is connected to an existing Wi-Fi network). When the PlanktoScope both has internet access and has devices connected to it (e.g. over a Wi-Fi hotspot or over Ethernet), the PlanktoScope shares its internet access with all connected devices, to enable the user to access web pages even when connected to the PlanktoScope. This is implemented in the PlanktoScope OS with network configurations for the PlanktoScope to act as a network router using [Network Address Translation](https://en.wikipedia.org/wiki/Network_address_translation) when it has internet access. @@ -218,15 +226,15 @@ The standard PlanktoScope OS also adds the following systemd services for dynami The PlanktoScope OS also adds the following common services for integrating network APIs provided by various programs, and to facilitate communication among programs running on the PlanktoScope OS: -- [Mosquitto](https://mosquitto.org/): a server which acts as an MQTT broker. This is used by the PlanktoScope hardware controller and segmenter (described below) to receive commands and broadcast notifications. This is also used by the PlanktoScope's Node-RED dashboard (described below) to send commands and receive notifications. +- [Mosquito](https://mosquitto.org/): a server which acts as an MQTT broker. This is used by the PlanktoScope hardware controller and segmenter (described below) to receive commands and broadcast notifications. This is also used by the PlanktoScope's Node-RED dashboard (described below) to send commands and receive notifications. - [Caddy](https://caddyserver.com/) with the [caddy-docker-proxy plugin](https://github.com/lucaslorentz/caddy-docker-proxy): an HTTP server which acts as a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) to route all HTTP requests on port 80 from HTTP clients (e.g. web browsers) to the appropriate HTTP servers (e.g. the Node-RED server, Prometheus, and the PlanktoScope hardware controller's HTTP-MJPEG camera preview stream) running on the PlanktoScope. ## Filesystem -The PlanktoScope OS's filesystem makes some changes from the default Debian/Raspberry Pi OS filesystem structure so that `/etc` and `/usr` can be managed by Forklift while still being directly customizable by the system administrator. Specifically, a number of systemd services in the PlanktoScope OS run during early boot to: +The PlanktoScope OS's filesystem makes some changes from the default Debian/Raspberry Pi OS filesystem structure so that various sets of files in `/etc` and `/usr` can be atomically upgraded/downgraded/replaced together (using Forklift) while still being directly customizable by the system administrator. Specifically, a number of systemd services in the PlanktoScope OS run during early boot to: -- Make a read-only mount (via the `overlay-sysroot` systemd service) of the initial root filesystem, at `/sysroot`. +- Make a read-only mount (via the `overlay-sysroot` systemd service) of the initial root filesystem, at `/sysroot` (this layout is loosely inspired by [OSTree's filesystem layout](https://ostreedev.github.io/ostree/adapting-existing/)). - Make a read-only mount of the next Forklift pallet to be applied (via the `bindro-run-forklift-stages-current.service`) from a subdirectory within `/var/lib/forklift/stages` to `/run/forklift/stages/current`. diff --git a/documentation/docs/setup/software/nonstandard-install.md b/documentation/docs/setup/software/nonstandard-install.md index 55c2834d4..ee525f774 100644 --- a/documentation/docs/setup/software/nonstandard-install.md +++ b/documentation/docs/setup/software/nonstandard-install.md @@ -141,7 +141,7 @@ You will only be able to access the PlanktoScope's graphical user interface by p - If you plan to connect another device directly to your PlanktoScope via its Wi-Fi hotspot or via an Ethernet cable, follow the same instructions for connecting to your PlanktoScope as in the [standard installation guide](./standard-install.md#connect-to-the-planktoscope). -- If you had previously configured your PlanktoScope's Raspberry Pi to connect to a Wi-Fi network, it will not make its own Wi-Fi hotspot. On the Wi-Fi network it's connected to, it will only be accessible by its machine-specific mDNS URL, which has the format `pkscope-{machine-name}.local`, where `{machine-name}` should be replaced by your PlanktoScope's specific machine name (which you should have recorded in the previous step). +- If you had previously configured your PlanktoScope's Raspberry Pi to connect to a Wi-Fi network, it will not make its own Wi-Fi hotspot. On the Wi-Fi network it's connected to, it will only be accessible by its machine-specific mDNS URL, which has the format `http://pkscope-{machine-name}.local`, where `{machine-name}` should be replaced by your PlanktoScope's specific machine name (which you should have recorded in the previous step). ## Next steps diff --git a/documentation/docs/setup/software/standard-install.md b/documentation/docs/setup/software/standard-install.md index b12dd90cc..2b9627a67 100644 --- a/documentation/docs/setup/software/standard-install.md +++ b/documentation/docs/setup/software/standard-install.md @@ -17,7 +17,7 @@ In order to complete this step, you will need all of the following: ### Download the PlanktoScope software SD card image -For ease of setup, we distribute the PlanktoScope OS as SD card image files. You can download the latest release from the [releases page](https://github.com/PlanktoScope/PlanktoScope/releases?q=prerelease%3Afalse+draft%3Afalse&expanded=true) for the PlanktoScope project on GitHub. Each released version of the PlanktoScope OS has downloadable SD card images under the "Assets" dropdown, which has multiple SD card image files corresponding to different types of PlanktoScope hardware; for information about how to select the appropriate SD card image for your PlanktoScope hardware, refer to the ["Hardware configurations"](index.md#hardware-configurations) section of the software setup overview. +For ease of setup, we distribute the PlanktoScope OS as SD card image files. You can download the latest release from the [stable releases page](https://github.com/PlanktoScope/PlanktoScope/releases?q=prerelease%3Afalse+draft%3Afalse&expanded=true) for the PlanktoScope project on GitHub (if you are experienced with the PlanktoScope software, you can also try the latest alpha or beta testing releases on the [full releases page](https://github.com/PlanktoScope/PlanktoScope/releases?q=draft%3Afalse&expanded=true)). Each released version of the PlanktoScope OS has downloadable SD card images under the "Assets" dropdown, which has multiple SD card image files corresponding to different types of PlanktoScope hardware; for information about how to select the appropriate SD card image for your PlanktoScope hardware, refer to the ["Hardware configurations"](index.md#hardware-configurations) section of the software setup overview. ### Write the image to the SD card @@ -40,23 +40,23 @@ Insert the microSD card into the Raspberry Pi computer installed in your Plankto ## Connect to the PlanktoScope -Power on your PlanktoScope, and wait for it to start up. Note that it may take a few minutes to start up, depending on the speed of your SD card. Once it has finished starting up, its internal Raspberry Pi computer should create a new isolated Wi-Fi network (which we call the PlanktoScope's *Wi-Fi hotspot*) whose name starts with the word `pkscope` followed by the unique randomly-generated name of your PlanktoScope; for example, if your PlanktoScope is named `clear-request-6329`, then the Wi-Fi network will be named `pkscope-clear-request-6329`. The password of this Wi-Fi network is `copepode`. +Power on your PlanktoScope, and wait for it to start up. Note that it may take a few minutes to start up, depending on the speed of your SD card. Once it has finished starting up, its internal Raspberry Pi computer should create a new isolated Wi-Fi network (which we call the PlanktoScope's *Wi-Fi hotspot*) whose name starts with the word `pkscope` followed by your PlanktoScope's *machine name*, a unique randomly-generated name; for example, if your PlanktoScope's machine name is `clear-request-6329`, then the Wi-Fi network will be named `pkscope-clear-request-6329`. The password of this Wi-Fi network is `copepode`. !!! info You will not be able to access the PlanktoScope's graphical user interface by plugging in a display to the Raspberry Pi. This is because the SD card image we provide does not include a graphical desktop or web browser, in order to keep the SD card image file smaller and to keep the PlanktoScope's Raspberry Pi running more efficiently. -Once your PlanktoScope has created its Wi-Fi hotspot, you can connect another device (e.g. a phone or a computer) directly to the PlanktoScope - either over its Wi-Fi hotspot or over an Ethernet cable directly to the PlanktoScope's Ethernet port. Afterwards, you can open a web browser on the device to access the PlanktoScope's graphical user interface at one of the following URLs (try them in the following order, and just use the first one which works): +Once your PlanktoScope has created its Wi-Fi hotspot, you can connect another device (e.g. a phone or a computer) directly to the PlanktoScope - either through its Wi-Fi hotspot or through an Ethernet cable directly to the PlanktoScope's Ethernet port. Afterwards, you can open a web browser on the device to access the PlanktoScope's graphical user interface at one of the following URLs (try them in the following order, and just use the first one which works): -- (this 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)) -- (this should work unless you're on a device and web browser without mDNS support) +- (this 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)) +- (this should work unless you're on a device or web browser without mDNS support) - (this should work unless your web browser is configured to use a Private DNS provider) - (this should always work on devices connected directly to the PlanktoScope, especially for devices connected directly to the PlanktoScope's Wi-Fi hotspot) - (this should always work on devices connected directly to the PlanktoScope, especially for devices connected directly to the PlanktoScope's Ethernet port) !!! warning - The URLs listed above will **only** work when you are connecting directly to the PlanktoScope through its Wi-Fi hotspot or through an Ethernet cable. If you use one of those URLs, the landing page (shown in the screenshot below) will also display a link with a different URL (a machine-specific URL) to try using; you may want to try that link to see if it works, and you may want to write it down or bookmark it for future reference. That machine-specific URL, which has format `pkscope-{machine-name}.local` (e.g. `pkscope-clear-request-6329.local`) should work even if your device is connected indirectly to the PlanktoScope (e.g. via a Wi-Fi router which is providing internet access to the PlanktoScope). + The URLs listed above will **only** work when you are connecting directly to the PlanktoScope through its Wi-Fi hotspot or through an Ethernet cable. If you use one of those URLs, the landing page (shown in the screenshot below) will also display a link with a different URL (a machine-specific URL) to try using; you may want to try that link to see if it works, and you may want to write it down or bookmark it for future reference. That machine-specific URL, which has format `http://pkscope-{machine-name}.local` (e.g. `http://pkscope-clear-request-6329.local`) should work even if your device is connected indirectly to the PlanktoScope (e.g. via a Wi-Fi router which is providing internet access to the PlanktoScope). For more information, refer to the [operation guide](../../operation/index.md#access-your-planktoscopes-software). diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 55dfa9fb4..cfc0693d4 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -6,9 +6,7 @@ repo_url: https://github.com/PlanktoScope/PlanktoScope edit_uri: edit/master/documentation/docs/ nav: - - Home: - - index.md - - Frequently Asked Questions: faq.md + - Home: index.md - Setup: - setup/index.md - Hardware: @@ -30,10 +28,11 @@ nav: - operation/index.md # (@ethanjli) I'm hiding this page because I don't consider it ready for public use: # - Sample Collection: operation/sample-collection.md - - User Interface: operation/user-interface.md + - Graphical User Interface: operation/user-interface.md - Maintenance: operation/maintenance.md - - Clone your SD card: operation/clone-sd.md + - Software Reset & Upgrades: operation/software-upgrades.md - Networking: operation/networking.md + - SD Card Cloning: operation/clone-sd.md - Troubleshooting: - troubleshooting/index.md - Community: @@ -69,6 +68,7 @@ nav: - Startup: reference/software/subsystems/startup.md - Release Process: reference/software/release-process.md - Changelog: reference/software/changelog.md + - Frequently Asked Questions: faq.md theme: logo: images/logos/planktoscope_white.png