Skip to content

Commit 9d27564

Browse files
sonnypsonnyp
authored
doc: Add testing protocol (#637)
Adds an initial testing protocol. Objectives: * Establish a testing protocol for PlanktoScope OS 2025 * Establish a testing protocol for future versions of software/hardware * Have a base onto which starting automated testing for * Development * Production and Quality Control * User Diagnostics (troubleshooting)
1 parent a23976a commit 9d27564

File tree

3 files changed

+356
-0
lines changed

3 files changed

+356
-0
lines changed

‎.github/ISSUE_TEMPLATE/test-suite-run.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
name: Test suite run
3+
about: Run the test suite to help us
4+
title: ""
5+
labels: test-run
6+
assignees: ""
7+
---
8+
9+
# Info
10+
11+
**PlanktoScope**
12+
13+
- Hardware version: eg `v2.5`
14+
- Software version: eg `2025.0.0.alpha.1`
15+
- Machine name: eg `sponge-care-245`
16+
- Serial number: eg `U132` (leave empty if unknown)
17+
18+
**Computer**
19+
20+
- Operating system: eg `macOS 14.1`
21+
- Browser: eg `Firefox 128`
22+
23+
**Comment**
24+
25+
Anthing else worth knowing?
26+
27+
# Test suite
28+
29+
## Setup
30+
31+
1. [Set up the SD card and start the PlanktoScope](https://docs.planktoscope.community/setup/software/standard-install/)
32+
2. [ ] The PlanktoScope asks for Hardware version
33+
34+
## Sample
35+
36+
1. Go to "Sample"
37+
2. Select "Plankton net" for Sample gear
38+
3. Fill the form
39+
4. [ ] The calculations are correct
40+
41+
<!-- TODO: Add a tool to verify calculations -->
42+
43+
## Optic
44+
45+
**LED and preview**
46+
47+
1. [ ] "Light on" turns on the LED
48+
2. [ ] The preview shows images without significant lag
49+
3. [ ] Updating "ISO" modifies the image
50+
4. [ ] Updating "Shutter Speed" modifies the image
51+
<!-- 5. [ ] Verify white balance-->
52+
5. [ ] "Light off" turns off the LED
53+
54+
**Focus**
55+
56+
1. [ ] "UP 1MM" moves the focus in one direction
57+
2. [ ] "DOWN 1MM" moves the focus in the other direction
58+
3. [ ] Quick succession of "UP 100MM" moves the focus in one direction
59+
4. [ ] Quick succession of "DOWN 100MM" moves the focus in the other direction
60+
5. [ ] "Focus Distance" and "Focus Speed" impacts "⩓" in one direction
61+
6. [ ] "Focus Distance" and "Focus Speed" impacts "⩔" in the other direction
62+
7. [ ] "STOP FOCUS" stops movement
63+
64+
<!-- TODO: Add focus scenarios -->
65+
66+
**Pump**
67+
68+
1. [ ] The left arrow pumps in one direction
69+
2. [ ] The right arrow pumps in the other direction
70+
3. [ ] "Flowrate" and "Volume to pass" impacts speed in one direction
71+
4. [ ] "Flowrate" and "Volume to pass" impacts speed in the other direction
72+
5. [ ] "STOP PUMP" stops the pump
73+
74+
<!-- TODO: Add pump scenarios -->
75+
76+
**Prepare**
77+
78+
Prepare tubing, sample and flowcell.
79+
80+
Setup focus in "Optic Configuration"
81+
82+
## Fluidic acquisition
83+
84+
**UI**
85+
86+
1. [ ] "Number of images to acquire" and "Pumped volume" correctly updates "Total imaged volume" and "Total pumped volume"
87+
2. [ ] Delay to stabilize image cannot be lower than 0.1
88+
3. [ ] Delay to stabilize image cannot be higher than 5
89+
4. [ ] "Flowcell" offers 5 different options
90+
5. [ ] "Statistics" is coherent with information entered in "Sample"
91+
92+
**Small capture**
93+
94+
1. Start acquisition with 5 images
95+
2. [ ] "Capture progress" shows progress
96+
3. Wait for completion
97+
4. Go to "Gallery" in the menu
98+
5. [ ] Go to `img` -> `<today's date>` -> `name of the sample` -> `name of the acquisition`
99+
6. [ ] There are 5 jpeg images of acceptable quality
100+
7. [ ] There is a `metadata.json` file with coherent information
101+
8. [ ] There is an `integrity.check` file listing the 5 images and the `metadata.json` file
102+
9. Open one of the image and click the "HD" button
103+
10. The quality is acceptable and the focus is correct
104+
105+
**Big capture**
106+
107+
1. Start acquisition with 100 images
108+
109+
## Segmentation
110+
111+
1. Start segmentation
112+
2. [ ] "Status" updates and shows progress
113+
3. Wait for segmentation to complete
114+
4. Note the number of object counts
115+
5. Go to "Gallery" in the menu
116+
6. [ ] Go to `objects` -> `<today's date>` -> `name of the sample` -> `name of the acquisition`
117+
7. [ ] There are as many jpeg images as there were objects counted
118+
8. [ ] The jpeg images are of acceptable quality9.
119+
9. [ ] There is a `ecotaxa_<name of the acquisition>.tsv` file
120+
10. Open one of the image and click the "HD" button
121+
11. The quality is acceptable and the focus is correct
122+
123+
## Ecotaxa
124+
125+
1. Go to "Gallery" in the menu
126+
2. [ ] Go to `export` -> `ecotaxa`
127+
3. [ ] Download the `ecotaxa_<name of the acquisition>.zip` file
128+
4. Go to Ecotaxa
129+
5. Import the zip and wait for completion
130+
6. [ ] The result on Ecotaxa matches expectations
131+
132+
## System Monitoring
133+
134+
1. "Metrics" are coherent
135+
2. "Information" is correct
136+
137+
## Administration
138+
139+
1. [ ] Logs can be viewed and downloaded
140+
2. [ ] "Restart Hardware Controller" button is working
141+
3. [ ] "Restart Segmenter" button is working
142+
4. [ ] "Reboot" button is working
143+
5. [ ] "Shutdown" button is working
144+
145+
## Network
146+
147+
Replace `{machine-name}` with your PlanktoScope name.
148+
149+
### Direct Ethernet
150+
151+
1. Connect your computer to the PlanktoScope ethernet
152+
2. PlanktoScope is accessible at
153+
1. [ ] [http://planktoscope.local](http://planktoscope.local)
154+
2. [ ] [http://pkscope.local](http://pkscope.local)
155+
3. [ ] [http://home.pkscope](http://home.pkscope)
156+
4. [ ] [http://192.168.5.1/](http://192.168.5.1/)
157+
5. [ ] [http://pkscope-{machine-name}.local/](http://pkscope-{machine-name}.local/)
158+
159+
### Direct WiFi
160+
161+
1. Connect your computer to the PlanktoScope WiFi hotspot
162+
2. PlanktoScope is accessible at
163+
1. [ ] [http://planktoscope.local](http://planktoscope.local)
164+
2. [ ] [http://pkscope.local](http://pkscope.local)
165+
3. [ ] [http://home.pkscope](http://home.pkscope)
166+
4. [ ] [http://192.168.4.1/](http://192.168.4.1/)
167+
5. [ ] [http://pkscope-{machine-name}.local/](http://pkscope-{machine-name}.local/)
168+
169+
### LAN Ethernet
170+
171+
1. Connect the PlanktoScope to your router ethernet
172+
2. PlanktoScope is accessible at
173+
1. [ ] [http://pkscope-{machine-name}.local](http://pkscope-{machine-name}.local)
174+
175+
<!--
176+
177+
### LAN WiFi
178+
179+
1. Connect the PlanktoScope to your router wifi
180+
2. PlanktoScope is accessible at
181+
1. [ ] [http://pkscope-{machine-name}.local](http://pkscope-{machine-name}.local)
182+
183+
-->

‎documentation/docs/reference/testing/index.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Testing
2+
3+
This document provides a simple protocol for testing the PlanktoScope. This may be used when a new software or hardware release is made available.
4+
5+
Our long term goal is to automate as much of the testing as possible, until then, manual checks are required.
6+
7+
## Setup
8+
9+
1. [Set up the SD card and start the PlanktoScope](https://docs.planktoscope.community/setup/software/standard-install/)
10+
2. [ ] The PlanktoScope asks for Hardware version
11+
12+
## Sample
13+
14+
1. Go to "Sample"
15+
2. Select "Plankton net" for Sample gear
16+
3. Fill the form
17+
4. [ ] The calculations are correct
18+
19+
<!-- TODO: Add a tool to verify calculations -->
20+
21+
## Optic
22+
23+
**LED and preview**
24+
25+
1. [ ] "Light on" turns on the LED
26+
2. [ ] The preview shows images without significant lag
27+
3. [ ] Updating "ISO" modifies the image
28+
4. [ ] Updating "Shutter Speed" modifies the image
29+
<!-- 5. [ ] Verify white balance-->
30+
5. [ ] "Light off" turns off the LED
31+
32+
**Focus**
33+
34+
1. [ ] "UP 1MM" moves the focus in one direction
35+
2. [ ] "DOWN 1MM" moves the focus in the other direction
36+
3. [ ] Quick succession of "UP 100MM" moves the focus in one direction
37+
4. [ ] Quick succession of "DOWN 100MM" moves the focus in the other direction
38+
5. [ ] "Focus Distance" and "Focus Speed" impacts "⩓" in one direction
39+
6. [ ] "Focus Distance" and "Focus Speed" impacts "⩔" in the other direction
40+
7. [ ] "STOP FOCUS" stops movement
41+
42+
<!-- TODO: Add focus scenarios -->
43+
44+
**Pump**
45+
46+
1. [ ] The left arrow pumps in one direction
47+
2. [ ] The right arrow pumps in the other direction
48+
3. [ ] "Flowrate" and "Volume to pass" impacts speed in one direction
49+
4. [ ] "Flowrate" and "Volume to pass" impacts speed in the other direction
50+
5. [ ] "STOP PUMP" stops the pump
51+
52+
<!-- TODO: Add pump scenarios -->
53+
54+
**Prepare**
55+
56+
Prepare tubing, sample and flowcell.
57+
58+
Setup focus in "Optic Configuration"
59+
60+
## Fluidic acquisition
61+
62+
**UI**
63+
64+
1. [ ] "Number of images to acquire" and "Pumped volume" correctly updates "Total imaged volume" and "Total pumped volume"
65+
2. [ ] Delay to stabilize image cannot be lower than 0.1
66+
3. [ ] Delay to stabilize image cannot be higher than 5
67+
4. [ ] "Flowcell" offers 5 different options
68+
5. [ ] "Statistics" is coherent with information entered in "Sample"
69+
70+
**Small capture**
71+
72+
1. Start acquisition with 5 images
73+
2. [ ] "Capture progress" shows progress
74+
3. Wait for completion
75+
4. Go to "Gallery" in the menu
76+
5. [ ] Go to `img` -> `<today's date>` -> `name of the sample` -> `name of the acquisition`
77+
6. [ ] There are 5 jpeg images of acceptable quality
78+
7. [ ] There is a `metadata.json` file with coherent information
79+
8. [ ] There is an `integrity.check` file listing the 5 images and the `metadata.json` file
80+
9. Open one of the image and click the "HD" button
81+
10. The quality is acceptable and the focus is correct
82+
83+
**Big capture**
84+
85+
1. Start acquisition with 100 images
86+
87+
## Segmentation
88+
89+
1. Start segmentation
90+
2. [ ] "Status" updates and shows progress
91+
3. Wait for segmentation to complete
92+
4. Note the number of object counts
93+
5. Go to "Gallery" in the menu
94+
6. [ ] Go to `objects` -> `<today's date>` -> `name of the sample` -> `name of the acquisition`
95+
7. [ ] There are as many jpeg images as there were objects counted
96+
8. [ ] The jpeg images are of acceptable quality9.
97+
9. [ ] There is a `ecotaxa_<name of the acquisition>.tsv` file
98+
10. Open one of the image and click the "HD" button
99+
11. The quality is acceptable and the focus is correct
100+
101+
## Ecotaxa
102+
103+
1. Go to "Gallery" in the menu
104+
2. [ ] Go to `export` -> `ecotaxa`
105+
3. [ ] Download the `ecotaxa_<name of the acquisition>.zip` file
106+
4. Go to Ecotaxa
107+
5. Import the zip and wait for completion
108+
6. [ ] The result on Ecotaxa matches expectations
109+
110+
## System Monitoring
111+
112+
1. "Metrics" are coherent
113+
2. "Information" is correct
114+
115+
## Administration
116+
117+
1. [ ] Logs can be viewed and downloaded
118+
2. [ ] "Restart Hardware Controller" button is working
119+
3. [ ] "Restart Segmenter" button is working
120+
4. [ ] "Reboot" button is working
121+
5. [ ] "Shutdown" button is working
122+
123+
## Network
124+
125+
Replace `{machine-name}` with your PlanktoScope name.
126+
127+
### Direct Ethernet
128+
129+
1. Connect your computer to the PlanktoScope ethernet
130+
2. PlanktoScope is accessible at
131+
1. [ ] [http://planktoscope.local](http://planktoscope.local)
132+
2. [ ] [http://pkscope.local](http://pkscope.local)
133+
3. [ ] [http://home.pkscope](http://home.pkscope)
134+
4. [ ] [http://192.168.5.1/](http://192.168.5.1/)
135+
5. [ ] [http://pkscope-{machine-name}.local/](http://pkscope-{machine-name}.local/)
136+
137+
### Direct WiFi
138+
139+
1. Connect your computer to the PlanktoScope WiFi hotspot
140+
2. PlanktoScope is accessible at
141+
1. [ ] [http://planktoscope.local](http://planktoscope.local)
142+
2. [ ] [http://pkscope.local](http://pkscope.local)
143+
3. [ ] [http://home.pkscope](http://home.pkscope)
144+
4. [ ] [http://192.168.4.1/](http://192.168.4.1/)
145+
5. [ ] [http://pkscope-{machine-name}.local/](http://pkscope-{machine-name}.local/)
146+
147+
### LAN Ethernet
148+
149+
1. Connect the PlanktoScope to your router ethernet
150+
2. PlanktoScope is accessible at
151+
1. [ ] [http://pkscope-{machine-name}.local](http://pkscope-{machine-name}.local)
152+
153+
<!--
154+
155+
### LAN WiFi
156+
157+
1. Connect the PlanktoScope to your router wifi
158+
2. PlanktoScope is accessible at
159+
1. [ ] [http://pkscope-{machine-name}.local](http://pkscope-{machine-name}.local)
160+
161+
-->

‎documentation/docs/troubleshooting/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,18 @@ or
1616

1717
See also [#603](https://github.com/PlanktoScope/PlanktoScope/issues/603)
1818

19+
## No internet after connecting LAN to the PlanktoScope
20+
21+
If your laptop is connected to the PlanktoScope with a LAN cable and to the Internet with WiFi, it's possible your system will prefer LAN and try to use it for Internet.
22+
23+
Find the LAN setting to only use it for resources on its network.
24+
25+
For example on Fedora / Ubuntu, the setting is called
26+
27+
> Use this connection only for resources on its network
28+
29+
and is present on the IPv4 and IPv6 tabs of the LAN network options.
30+
1931
## Error with camera or Python backend
2032

2133
A common (and very broad) category of problems results in an error message like `If you see this, there probably is an error either with your camera or with the python service. Please try restarting your machine.` being displayed instead of a camera preview in the Node-RED dashboard. This error message can be caused by a variety of potential failure modes such as a disconnected camera or a crash in the Python hardware controller program (which controls the PlanktoScope's camera as well as the pump, focusing motors, etc.). If you see this problem, we recommend first checking whether the Python hardware controller is responsive to button-presses in the Node-RED dashboard for moving the pump and/or the focusing stepper motors; if so, then there is likely a problem specifically with the camera hardware or the camera preview. Otherwise, it is very possible that the Python hardware controller has crashed for other reasons. Troubleshooting this situation will require you to download the Python hardware controller's error logs so that you can attach the logs with a request for help on the PlanktoScope Slack community.

0 commit comments

Comments
 (0)