latest changes
This commit is contained in:
Sebastian Wendel
parent
15fa729dc1
commit
bb7b4c579e
2
.gitignore
vendored
2
.gitignore
vendored
|
|
@ -30,3 +30,5 @@ result
|
|||
dist
|
||||
docs/_*
|
||||
site
|
||||
|
||||
TODOS.md
|
||||
|
|
|
|||
|
|
@ -8,14 +8,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0
|
|||
| --- | --- |
|
||||
| CI/CD | [](https://github.com/PlanktoScope/PlanktoScope/actions/workflows/test.yml) [](https://github.com/PlanktoScope/PlanktoScope/actions/workflows/build.yml) |
|
||||
| Package | [](https://pypi.org/project/planktoscope/) [](https://pypi.org/project/planktoscope/) |
|
||||
| Meta | [](https://github.com/pypa/hatch) [](https://github.com/psf/black) [](https://github.com/ambv/black) [](https://github.com/pycqa/isort) [!
|
||||
|
||||
[License - GPL](https://img.shields.io/badge/license-GPL-blue.svg)](<https://spdx.org/licenses/>) |
|
||||
|
||||
<https://shields.io/badge/reuse-compliant-green>
|
||||
| Meta | [](https://github.com/pypa/hatch) [](https://github.com/psf/black) [](https://github.com/ambv/black) [](https://github.com/pycqa/isort) [](<https://spdx.org/licenses/>) |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## What is this?
|
||||
|
|
|
|||
|
|
@ -1,57 +0,0 @@
|
|||
# Device Specifications
|
||||
|
||||
## Size
|
||||
|
||||
* height 150 mm
|
||||
* wide 350 mm
|
||||
* deep 150 mm
|
||||
|
||||
## Harware
|
||||
|
||||
* 4 Core ARM-Cortex-A72 Processor with 1,50 GHz
|
||||
* 4 GB Arbeitsspeicher (depending on the purchased version)
|
||||
* 64 GB Flash memory (depending on the purchased version)
|
||||
* [Sony IMX477R](https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/) Image sensor with 12.3MP
|
||||
* M12-Mount Optiken mit 16 und 25 mm Linsen
|
||||
* Automatic focus via linear guide
|
||||
* automatic sampling via peristaltic pump
|
||||
* the case is made of wood fiberboard
|
||||
|
||||
## Software
|
||||
|
||||
* [Debian](https://www.raspberrypi.com/software/operating-systems/) based Embedded Linux operating
|
||||
* [Node-Red](https://nodered.org/) based user interface
|
||||
* [Python](https://www.python.org/) Image processing service and cloud connection
|
||||
|
||||
## Characteristic
|
||||
|
||||
* Focus stage control
|
||||
* Pump control
|
||||
* Automatic image capture
|
||||
* Automatic segmentation, optimization and object detection
|
||||
* 4,200 images, 41,000 objects, ~ 1 minute
|
||||
* Control via smartphone or tablet
|
||||
|
||||
## License
|
||||
|
||||
* Hardware: CERN Open Hardware Licence
|
||||
* Software: GNU General Public License
|
||||
* Dokumentation: Creative Commons Attribution-ShareAlike
|
||||
|
||||
## Certification
|
||||
|
||||
* [DIN SPEC 3105-1: Open Source Hardware](https://www.researchgate.net/publication/342564027_DIN_SPEC_3105-1_Open_Source_Hardware)
|
||||
|
||||
## Areas of Application
|
||||
|
||||
* Plankton analysis
|
||||
* Image small animals and algae living in water
|
||||
* Mobile use via external power supply
|
||||
|
||||
## System Requirements
|
||||
|
||||
* Smartphone or tablet
|
||||
|
||||
## Accessories
|
||||
|
||||
* [Collector device]()
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Welcome to the PlanktoScope build and use documentation
|
||||
|
||||
|
||||
|
||||
You can find here more information about how to build your own PlanktoScope.
|
||||
|
||||
## Setup
|
||||
|
||||
- [How to setup your PlanktoScope the easy way](easy_install.md)
|
||||
- [How to setup your PlanktoScope the hard way (also known as the Expert's path)](expert_setup.md)
|
||||
- [Some information about how to setup a remote access](remote_access.md)
|
||||
|
||||
## Build your machine
|
||||
|
||||
- [Assembly Guide](images/assembly_guide.md)
|
||||
|
||||
## Usage
|
||||
|
||||
- [Information about collection devices](collection_devices.md)
|
||||
|
||||
## Under the hood
|
||||
|
||||
- [Software architecture](software_architecture.md)
|
||||
- [MQTT Messages](mqtt_messages.md)
|
||||
- [Create Master SD Card or backup your PlanktoScope](create_sd.md)
|
||||
- How does the segmentation works (soon)
|
||||
|
||||
## Changelog
|
||||
|
||||
- [Changelog](changelog.md)
|
||||
|
||||
## Contribute
|
||||
|
||||
- [Find out how to contribute to this documentation and help edit it](edit_this_doc.md)
|
||||
- [Contribute to the code, here is the getting started](edit_the_code.md)
|
||||
|
||||
## License of our work
|
||||
|
||||
- [More information about the licenses that we use](license.md)
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
# Research
|
||||
|
||||
## Plankton Planet: ‘seatizen’ oceanography to assess open ocean life at the planetary scale
|
||||
|
||||
* assets/2020.08.31.263442v1.full.pdf
|
||||
|
||||
## PlanktoScope: Affordable Modular Quantitative Imaging Platform for Citizen Oceanography
|
||||
|
||||
* assets/fmars-09-949428.pdf
|
||||
|
||||
## PlanktonScope: Affordable modular imaging platform for citizen oceanography
|
||||
|
||||
* assets/2020.04.23.056978v1.full.pdf
|
||||
|
|
@ -1,342 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Assembly guide of the PlanktoScope
|
||||
|
||||
|
||||
|
||||
## Step 0: Gather everything you need
|
||||
|
||||
- Laser cut structure
|
||||
- M12 lenses
|
||||
- Peristaltic pump and tubing
|
||||
- Raspberry Pi, motor driver board, GPIO connectors
|
||||
- Flashed SD card
|
||||
- Stepper motors
|
||||
- PiCam and flex cable
|
||||
- GPIO ribbon connector, headers, HATs, LED
|
||||
- DC Power terminal
|
||||
- Magnets
|
||||
- Super glue
|
||||
- Standoffs (M2.5), M3 screws and nuts
|
||||
|
||||
Make sure you have your screwdriver kit, soldering iron, and components ready. Also, remember to flash the PlanktoScope image disk on the SD card before installing the Raspberry Pi.
|
||||
|
||||
If you are not familiar with any process, such as soldering, tapping, or wiring, try and familiarize yourself with the topics first.
|
||||
|
||||
Soldering deals with high heat and potentially toxic materials, so make sure to use the proper precautions.
|
||||
|
||||
## Step 1: Laser cutting
|
||||
|
||||
|
||||
|
||||
Laser cut all components using the .ai file ensuring all cuts are complete. The current design should have a 5mm material thickness. Start by placing laser cut base A on a flat workspace. Make sure all holes are complete, and negative space is clear.
|
||||
|
||||
!!! warning
|
||||
If you are doing the laser cutting yourself, please take the time to check the calibration of the machine and its power output for the material you are using. A tight fit is needed between the different plates to avoid unwanted play between critical parts.
|
||||
|
||||
## Step 2: Standoff installation
|
||||
|
||||
|
||||
|
||||
|
||||
Place 8 standoffs (M2.5 6mm) into the designated holes on the laser-cut base A. A pair of pliers make the job more comfortable. Do not overtighten as it is possible to crack the base material.
|
||||
|
||||
|
||||
|
||||
## Step 3: Motor HAT preparation
|
||||
|
||||
|
||||
|
||||
Insert and solder the terminal blocks and headers onto the motor driver PCB.
|
||||
|
||||
|
||||
|
||||
Place the motor driver PCB on to the indicated standoffs.
|
||||
|
||||
## Step 4: Magnets setup
|
||||
|
||||
|
||||
|
||||
Now is a good time to think about how the magnets will function within the microscope. The magnets in the sample stage will need to attract to the magnets on the flow cell holder. The magnets in the objective holder will need to attract the magnets on the mount. Keep this in mind as you are adding your magnets and tapping your respective M12 holders so your orientation will be correct.
|
||||
|
||||
|
||||
|
||||
You can now fix your magnets into their appropriate holes on sample stage **B**.
|
||||
It is recommended to glue the magnets in place. If the magnets are too large to fit in, the holes can be widened with a handheld drill. However, they should be quite snug in place. Before you glue them in place make sure that the polarity is maintained, as they will be impossible to remove after gluing.
|
||||
|
||||
## Step 5: Sample stage assembly
|
||||
|
||||
|
||||
|
||||
Don’t be alarmed by the color swap, this is the sample stage **B**. You can now fit the pegs on the driver mounts into the corresponding holes on the sample stage. They should be glued in place with superglue or epoxy. You can spin the shaft to align the driver mounts on the 2 steppers if it helps making the process easier.
|
||||
|
||||
|
||||
|
||||
You should now have a sample stage and motor assembly that looks like this.
|
||||
|
||||
## Step 6: Lenses tapping and mounting
|
||||
|
||||
|
||||
|
||||
You now need to tap the holes for the M12 lenses in stage and mount **M** and **D**. It is helpful for alignment to do both the objeDtive and tube lens mount together. It is important to do this as straight as possible. A drop of mineral or olive oil can help the process. Be careful to use a right-hand tap (that goes down when turning clockwise).
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
You can now screw the objective lens (the 25mm one) in part **D**.
|
||||
|
||||
|
||||
## Step 7: Camera preparation
|
||||
|
||||
You can now unscrew the lens from the Pi camera, being careful not to disturb the sensor below.
|
||||
|
||||
|
||||
|
||||
## Step 8: Camera mount
|
||||
|
||||
|
||||
|
||||
You can mount the camera using the appropriate holes on the camera mount **G**. Be careful to avoid getting oil or dust on the sensor.
|
||||
|
||||
## Step 9: LED preparation
|
||||
|
||||
|
||||
|
||||
The LED can then be wired up and put into its mount **F**. If you wire the LED yourself, remember to give enough length to reach the motor driver on the other end of the microscope. You can also add a bit of glue to fix **F** to the motor mount **E** at this time to make assembly easier, though it is not required.
|
||||
|
||||
!!! warning
|
||||
|
||||
|
||||
This picture shows the correct wiring for the LED. Please make sure the red wire is on the long pin of the LED.
|
||||
|
||||
## Step 10: Vertical slices assembly
|
||||
|
||||
You can now start placing the motor mount/LED assembly- **B**,
|
||||
|
||||
|
||||
**C**,
|
||||
|
||||
|
||||
**D**,
|
||||
|
||||
|
||||
**E**,
|
||||
|
||||
|
||||
**F**,
|
||||
|
||||
|
||||
and **G** into the base **A**.
|
||||
|
||||
## Step 11: Pump setup
|
||||
|
||||
The pump can then be mounted in place on **H**. Thread the wires through the hole with the pump tubing pointed toward the holes on the mount.
|
||||
|
||||
|
||||
Fix the pump in place.
|
||||
|
||||
|
||||
## Step 12: Pump mounting
|
||||
|
||||
You can now mount the pump on base **A**.
|
||||
|
||||
|
||||
Your setup should look like this. Don't worry about the wiring, we'll have a look at it in the next step!
|
||||
|
||||
|
||||
|
||||
## Step 13: Motor HAT wiring
|
||||
|
||||
|
||||
|
||||
You will now want to wire the steppers and pump to the terminals on the motor driver board.
|
||||
|
||||
!!! info
|
||||
The PlanktoScope **uses only bipolar stepper motors** (with 4 wires coming out, and two coils inside), so you need to identify the two wires working together for each coil. The [RepRap Wiki has great information](https://reprap.org/wiki/Stepper_wiring#.22pair.22_wires_on_4_wire_motors) on how to do this, either with a multimeter or without.
|
||||
|
||||
You can find more information about stepper motors and how they work in this [document](http://resources.linengineering.com/acton/attachment/3791/f-00ca/1/-/-/-/-/Stepper%20Motor%20Basics.pdf).
|
||||
|
||||
!!! tip
|
||||
If your wires are too short, you can invert the pump and the focus wiring. However, you will have to remember to change the configuration later on.
|
||||
|
||||
!!! tip
|
||||
Make sure the wires are properly connected by pulling on them a little. They should not come loose.
|
||||
|
||||
## Step 14: Raspberry Pi setup and installation
|
||||
|
||||
|
||||
|
||||
At this point, you can insert your flashed SD card into your Raspberry Pi. [Consult the guide for flashing your SD card](https://www.planktoscope.org/replicate/assemble-your-kit) before you do this. The heat sink can also be added to the processor.
|
||||
|
||||
!!! note
|
||||
If you choose the Expert path, you still need to flash your sd card, either with the [lite version](https://downloads.raspberrypi.org/raspios_lite_armhf_latest) of Raspberry OS or with the [desktop version](https://downloads.raspberrypi.org/raspios_armhf_latest).
|
||||
|
||||
|
||||
|
||||
Mount the Raspberry Pi containing the flashed SD card on the standoffs attached to the laser cut base A.
|
||||
|
||||
## Step 15: Standoffs
|
||||
|
||||
|
||||
|
||||
Add 8 standoffs (M2.5 15mm) to fix the motor driver board and the Raspberry Pi to the base.
|
||||
|
||||
|
||||
|
||||
## Step 16: Camera flex cable
|
||||
|
||||
|
||||
|
||||
At this point you can use the Pi camera flex cable to connect the camera to the Pi. This is done by gently pulling up the tensioners, inserting the cable in the right orientation, then pushing the tensioners back in place to set the cable. Try not to kink or fold the flex cable too much as it is possible to damage it.
|
||||
|
||||
## Step 17: Power supply wiring
|
||||
|
||||
|
||||
|
||||
The power wires can be wired into place on the motor driver board.
|
||||
|
||||
!!! tip
|
||||
Make sure the wires are properly connected by pulling on them a little. They should not come loose.
|
||||
|
||||
## Step 18: Prepare the GPS HAT
|
||||
|
||||
|
||||
|
||||
Insert the battery to power the GPS HAT and solder the terminal mounts in place.
|
||||
|
||||
## Step 19: Install the GPS HAT
|
||||
|
||||
|
||||
|
||||
Mount the GPS HAT over the motor driver PCB using the standoffs attached to the laser cut base **A**.
|
||||
|
||||
## Step 20: Install the Fan HAT
|
||||
|
||||
|
||||
|
||||
Place the cooling fan HAT above the Raspberry Pi by mounting it to the standoffs on base **A**.
|
||||
|
||||
!!! warning
|
||||
Be careful to slide the camera flat cable in the slot in the HAT above the connector.
|
||||
|
||||
## Step 21: Secure the HATS
|
||||
|
||||
|
||||
|
||||
Secure the cooling fan HAT and GPS HAT by tightening the 8 screws to the standoffs on base A
|
||||
|
||||
## Step 22: Install back panel
|
||||
|
||||
|
||||
|
||||
Insert the laser cut border **I** into base **A**.
|
||||
|
||||
## Step 23: GPS output connector
|
||||
|
||||
|
||||
|
||||
Insert the power and GPS connectors into side plate **J**.
|
||||
|
||||
## Step 24: Install side panel
|
||||
|
||||
|
||||
|
||||
Place the side plate **J** into the designated slots on the base. You can connect the GPS cable to its connector on the board.
|
||||
|
||||
!!! warning
|
||||
The GPS connector is quite fragile, make sure to align it properly before inserting it.
|
||||
|
||||
## Step 25: Install the other side panel
|
||||
|
||||
|
||||
|
||||
Mount the side plate **K** on base **A** using the assigned slots.
|
||||
|
||||
## Step 26: Secure the sides together
|
||||
|
||||
|
||||
|
||||
Secure the laser cut sides with the screws and nuts.
|
||||
|
||||
## Step 27: Secure the sides to the base plate
|
||||
|
||||
|
||||
|
||||
Secure the laser cut sides to the base plate **A** with the screws and nuts.
|
||||
|
||||
!!! warning
|
||||
To make this easier, you can turn the assembly upside down or on its side. Be careful when doing so as the plates may fall.
|
||||
|
||||
## Step 28: Insert the camera ribbon cable in the camera
|
||||
|
||||
|
||||
|
||||
You can now connect the camera flex cable into the connector on the camera board. Once again, gently pull up the tensioners, insert the cable in the right orientation, and push the tensioners back in place to set the cable. Try not to kink or fold the flex cable too much as it is possible to damage it.
|
||||
|
||||
## Step 29: Assemble the GPIO ribbon cable
|
||||
|
||||
If you didn't get an already assembled ribbon cable, you need to build it yourself.
|
||||
|
||||
The orientation of the connector does not really matter. However, you need to make sure that both connectors are oriented in the same direction and are on the same side of the ribbon.
|
||||
|
||||
To assemble, slide the ribbon in its connector and close it off. You need to tighten it really hard. It's very warmly recommended to use a vice to do so.
|
||||
|
||||
!!! warning
|
||||
Once assembled, the ribbon should NOT look like this:
|
||||
|
||||
|
||||
It should rather look like this:
|
||||
|
||||
|
||||
## Step 30: Insert the ribbon cable
|
||||
|
||||
|
||||
|
||||
Attach the GPIO ribbon to connect the cooling fan HAT to the GPS HAT.
|
||||
|
||||
!!! tip
|
||||
You can try to route the flat ribbon from the camera under the ribbon cable you are connecting now.
|
||||
|
||||
|
||||
## Step 31: Fluidic assembly
|
||||
|
||||
|
||||
|
||||
Feed in the tubing from syringe 1 to form the fluidic path as shown.
|
||||
|
||||
|
||||
|
||||
Feed in the tubing from syringe 2 to form the fluidic path as shown
|
||||
|
||||
|
||||
|
||||
Feed in a length of tubing as shown through motor mount **H** and illumination mount **FE**
|
||||
|
||||
|
||||
|
||||
## Step 32: Close your PlanktoScope
|
||||
|
||||
!!! warning
|
||||
Take a moment to check your wiring one last time. Also check the routing, make sure the LED wires and the pump stepper wires are in their dedicated channel.
|
||||
|
||||
|
||||
|
||||
Place the top **L** into the slots on the PlanktoScope body. Secure it in place with screws and nuts.
|
||||
|
||||
|
||||
|
||||
## Step 33: Enjoy
|
||||
|
||||
Congratulations on a job well done. You can have some rest, get a tea and some biscuits!
|
||||
|
||||
|
||||
|
||||
You can now plug the machine in and test it. If you have choose the Expert's path, now is a good time to [finish setting up your machine](expert_setup.md).
|
||||
|
||||
## Step 34: Read the getting started guide
|
||||
|
||||
[A guide to get started with your machine use is available!](images/getting_started.md)
|
||||
|
|
@ -1,62 +0,0 @@
|
|||
# Chapter 1
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Be extremely careful because this is very sharp.
|
||||
|
||||
## Detach the **Parts** from **panels** by cutting the **tabs**
|
||||
|
||||
{ align=left }
|
||||
|
||||
### 👁 Locate the **panel S1** and discover the 5 differents **Parts F, P, K, J and I**
|
||||
|
||||
### 🎬 Flip your panel S1
|
||||
|
||||
### 🔴 Locate the outer **tabs** on the edges of the different **Parts**
|
||||
|
||||
### 🟠 B2. Razor blade
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Be extremely careful because this is very sharp.
|
||||
|
||||
### 🟣 Use the **razor blade** to cut the outer tabs located on the edges of the different Parts
|
||||
|
||||
❌ Do not cut the inner tabs present inside the different Parts for now and focus on the outer tabs attaching the Parts to the main panel.
|
||||
|
||||
Position your **razor blade** on the tab as close to the piece as possible to avoid residual tab after cutting.
|
||||
|
||||
Press firmly on the razor blade, being very careful with your finger, to cut your first tab.
|
||||
|
||||
Make sure you don't damage your table by placing a flat, rigid support under the **S1 panel**.
|
||||
|
||||
Keep going with the other tabs of this piece F.
|
||||
|
||||
Once you have removed your **Part** from the main panel by cutting off all the tabs holding it, inspect it for potential residual tabs.
|
||||
|
||||
🟣 Here is a **residual tab** that will need to be removed.
|
||||
🟠 Here there is no **residual tab** which is perfect.
|
||||
|
||||
🟣 Place your razor **blade flat** on the edge of your piece being very careful with your fingers and cut the residual tab.
|
||||
|
||||
Repeat the cutting of the **tabs** on all the **Parts F, P, K, J and I** present on the **panel S1**.
|
||||
⚠ Be extremely careful because this is very sharp.
|
||||
|
||||
🔴 Locate the **inner tabs** on the edges of the different **Parts**.
|
||||
|
||||
Cut out the **tabs** inside of all the **Parts F, P, K, J and I** detached from the **panel S1**.
|
||||
|
||||
✅ Good way of cutting inner tabs
|
||||
❌ Wrong way of cutting inner tabs
|
||||
|
||||
Repeat the process on the **panel S2**.
|
||||
|
||||
Discover the 11 differents **Parts**.
|
||||
|
|
@ -1,78 +0,0 @@
|
|||
# Chapter 10
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Mount the **Raspberry Pi Camera HQ** on **Part B**
|
||||
|
||||
🟣 Locate the 4 holes on the top of the **Part B**.
|
||||
|
||||
---
|
||||
|
||||
🔵 **A2**. Standoff M2.5 - 15mm - Brass
|
||||
|
||||
---
|
||||
|
||||
Insert the four **Standoff M2.5 - 15mm**.
|
||||
|
||||
---
|
||||
|
||||
The result should be similar to the picture.
|
||||
|
||||
---
|
||||
|
||||
🟢 **B4**. Wrenches for standoffs
|
||||
|
||||
---
|
||||
|
||||
Using the small side of the **Standoff Wrench**, secure the **4 M2.5 - 15mm Standoffs**
|
||||
|
||||
---
|
||||
|
||||
* ✅ Make sure to screw until the **Standoff** is properly tightened into the hole.
|
||||
* ❌ Do not stop screwing before.
|
||||
|
||||
---
|
||||
|
||||
Locate the **Raspberry Pi Camera HQ**
|
||||
|
||||
---
|
||||
|
||||
Remove the lens cap **Raspberry Pi Camera HQ**.
|
||||
|
||||
---
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Make sure your camera lens is clean. If it is not, gently wipe using cotton swab for this task.
|
||||
|
||||
---
|
||||
|
||||
Place the **Raspberry Pi Camera HQ** on top of the four **Standoffs** installed on **Part B**.
|
||||
|
||||
🟣Ensure correct orientation of the **Raspberry Pi Camera HQ**. The **black connector** where the **Ribbon Cable** was removed is on the same side as the 🟢slot circled in green
|
||||
|
||||
---
|
||||
|
||||
🟠 **A4**. Screw M2.5X5mm CHC - SS
|
||||
|
||||
---
|
||||
|
||||
🟡 **B3**. Allen key 2mm
|
||||
|
||||
---
|
||||
|
||||
Use the allen key and tighten the **Raspberry Pi Camera** to the **Standoffs**.
|
||||
|
||||
---
|
||||
|
||||
The result should be similar to the picture.
|
||||
|
||||
!!! info
|
||||
|
||||
🎬 Store this assembly for later.
|
||||
|
|
@ -1,62 +0,0 @@
|
|||
# Chapter 10
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Mount the **Linear Stepper Motor** on **Part E**
|
||||
|
||||
Locate the Stepper Motors ⚠ Avoid touching the metal rods on the Stepper Motors
|
||||
|
||||
🟣 You can touch the gold stands
|
||||
|
||||
---
|
||||
|
||||
🟡 **A5**. Screw **M2.5X10mm** CHC - SS
|
||||
|
||||
---
|
||||
|
||||
🟡 **B3**. Allen key 2mm
|
||||
|
||||
---
|
||||
|
||||
🔴 Lay the **Part E** down and make sure the pockets in these holes are
|
||||
facing upwards.
|
||||
|
||||
🟣 Locate the four holes on **Part E** and place four M2 Screws in the holes.
|
||||
|
||||
---
|
||||
|
||||
Attach the stepper motors to the screws we have just placed with the 🔴 pockets positioned on opposite to the cabling.
|
||||
|
||||
The result should be similar to the picture.
|
||||
|
||||
---
|
||||
|
||||
Use the 2mm allen key to fix the **Stepper Motors**.
|
||||
|
||||
The result should be similar to that picture.
|
||||
|
||||
---
|
||||
|
||||
The result should be similar to the picture.
|
||||
|
||||
---
|
||||
|
||||
Repeat the process on the other side with the other **Stepper Motor**.
|
||||
|
||||
---
|
||||
|
||||
Repeat the process on the other side with the other Stepper Motor.
|
||||
|
||||
---
|
||||
|
||||
The result should be similar to the picture.
|
||||
|
||||
!!! info
|
||||
|
||||
🎬 Store this assembly for later.
|
||||
|
|
@ -1,19 +0,0 @@
|
|||
# Chapter 2
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Place the 4 **Adhesive Pads** under the **Part I**
|
||||
|
||||
👁 Take the Part I.
|
||||
🟠 Take the four adhesive pads present in the bag A.
|
||||
🟣 Locate the four pockets that will receive the four adhesive pads.
|
||||
|
||||
Remove the paper and place the four adhesive pads in the pockets by pressing firmly on them, sticky-side down.
|
||||
|
||||
🎬 Store this assembly for later.
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# Chapter 3
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Screw the four **Standoffs** into **Part A**
|
||||
|
||||
👁 Grab the **Part A**.
|
||||
🟣 Locate the **four holes** on **Part A**.
|
||||
|
||||
🟢 **A1. Standoff M2.5 - 6mm**- Brass
|
||||
|
||||
🟢 **B4**. Wrenches for standoffs
|
||||
|
||||
🟣 Place the Standoff M2.5 - 6mm in the small side of the wrenches for
|
||||
standoffs B4.
|
||||
|
||||
🟠 Do not use the big side of the wrenches for standoffs since the standoff will be loose in it.
|
||||
|
||||
Place the standoff in the hole and start rotating **by hand** in a clockwise direction until secure.
|
||||
|
||||
Then tighten with the wrench.
|
||||
|
||||
✅ Make sure to screw until the standoff is properly inserted in the hole.
|
||||
❌ Do not stop screwing before.
|
||||
|
||||
Keep going for each of the **four holes**.
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
# Chapter 4
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Mount the **Heat Sinks** on the **Raspberry Pi**
|
||||
|
||||
Locate the **Raspberry Pi 4 Model B** packaging.
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Be careful removing it from its packaging.
|
||||
|
||||
Place the **four Heat Sinks** next to your **Raspberry Pi** and mark the locations of the **Heat Sinks** on the **Raspberry Pi**.
|
||||
|
||||
🟠 & 🔵 **Small Heat Sinks**
|
||||
🟢 **Medium Heat Sink**
|
||||
🟣 **Big Heat Sink**
|
||||
|
||||
Remove the protective labels under a **Heat Sink** and place the **Heat Sink** on the slot of the **Raspberry Pi**.
|
||||
|
||||
Remove the protective labels under all the **Heat Sinks** and place all the **Heat Sinks** on the slots of the **Raspberry Pi**.
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
# Chapter 5
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Insert the **micro SD card** in the **Raspberry Pi**
|
||||
|
||||
* Locate the **SD card adapter** in the **bag K**.
|
||||
* The **micro SD card** is inserted in the SD card adapter.
|
||||
* 🟣 Remove the **micro SD card** from the **SD card adapter**.
|
||||
|
||||
* Flip your **Raspberry Pi**.
|
||||
* 🟠 Locate the **micro SD port**.
|
||||
* 🟣 Insert the **micro SD card** in the **Raspberry Pi**.
|
||||
|
||||
* Push the **micro SD card** in the **Raspberry Pi** port to a point of resistance.
|
||||
* If you notice that the **micro SD card** protrudes about 2mm from its slot, this is normal.
|
||||
|
|
@ -1,25 +0,0 @@
|
|||
# Chapter 6
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Mount the **Raspberry Pi** on the **Part A**
|
||||
|
||||
* ✅ Make sure to position the Raspberry Pi properly on the four standoffs screwed on the Part A.
|
||||
* ❌ Do not invert the position of the Raspberry Pi on the four standoffs screwed on the Part A.
|
||||
|
||||
* 🟣 **A3. Standoff M2.5 - 16mm** - SS
|
||||
|
||||
* Screw by hand a Standoff M2.5 - 16mm on the **Raspberry Pi**.
|
||||
|
||||
* Screw by hand all Standoffs M2.5 - 16mm on the **Raspberry Pi**.
|
||||
* Make sure you insert all four standoffs by hand and tighten slightly.
|
||||
* 🟢 **B4**. Wrenches for standoffs
|
||||
|
||||
* 🟠 Secure the Standoff M2.5 - 16 mm - SS **A3** in the big side of the wrenches for standoffs **B4**.
|
||||
* 🟣 Do not use the small side of the wrenches for standoffs since the standoff won’t fit in it.
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
# Chapter 7
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Attach the **Ribbon Cable** to the **Raspberry Pi**
|
||||
|
||||
Locate the **Raspberry Pi Camera HQ** packaging.
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Be careful removing it from its packaging.
|
||||
|
||||
---
|
||||
|
||||
Lay your **Raspberry Pi Camera** face down on a suitable surface.
|
||||
|
||||
🔴 The **black connector** is simply a push/pull fit. To disengage the cable, pull the two corners of the black connector down, away from the camera board. It will unclip to about 3mm, make sure you don't pull it off! If you're struggling, try pulling off one corner of the connector at a time.
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Be careful with this, this part is delicate. Lift the black connector gently
|
||||
|
||||
---
|
||||
|
||||
Once the connector has been disengaged from the Raspberry Pi camera board, the cable will simply slide out!
|
||||
|
||||
* 🟣 Put aside Camera the Raspberry Pi
|
||||
* 🟢 Keep the Ribbon Cable for next step.
|
||||
|
||||
---
|
||||
|
||||
* 🔴 Locate the **black connector** present on the **Raspberry Pi**.
|
||||
|
||||
---
|
||||
|
||||
🔴 The **black connector** is simply a push/pull fit. To disengage the cable, pull the two corners of the black connector down, away from the camera board. It will unclip to about 3mm, make sure you don't pull it off! If you're struggling, try pulling off one
|
||||
corner of the connector at a time.
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Be careful, this part is delicate. Gently prise the black connector with nail or fingertip and thumb.
|
||||
|
||||
---
|
||||
|
||||
Insert the **Ribbon Cable** you just detached from the **Raspberry Pi Camera** in the **Raspberry Pi**.
|
||||
|
||||
✅ Make sure to insert in as much as you can.
|
||||
🟣 Blue rectangle on **Ribbon Cable** should face the same direction as the arrow below.
|
||||
|
||||
---
|
||||
|
||||
🔴 Secure the Ribbon Cable in the Raspberry Pi by pressing firmly on the black connector.
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
# Chapter 8
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Mount the PlanktoScope HAT on the Raspberry Pi
|
||||
|
||||
### Locate
|
||||
|
||||
Locate the **PlanktoScope HAT** present in **bag I**.
|
||||
|
||||
### Ribbon cable
|
||||
|
||||
🔴Thread the **Ribbon cable** through the **PlanktoScope HAT** slot from the
|
||||
underside.
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Make sure the two 🟣black connectors are aligned before threading through the ribbon.
|
||||
|
||||
### Plug
|
||||
|
||||
Plug the **PlanktoScope HAT** into the **Raspberry Pi**.
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Make sure the two black connectors are aligned before attaching them together.
|
||||
|
||||
### Connect
|
||||
|
||||
Press the **PlanktoScope HAT** against the **Raspberry Pi** until it is no longer possible to move them closer together.
|
||||
|
||||
!!! warning
|
||||
|
||||
⚠ Continue to feed through the Ribbon Cable and do not crush it while pressing the PlanktoScope HAT against the standoffs.
|
||||
|
||||
---
|
||||
|
||||
🟠 **A4**. Screw **M2.5X5mm** CHC - SS
|
||||
|
||||
---
|
||||
|
||||
🟣 Locate the 4 holes on the top of the **PlanktoScope HAT** and insert the four **M2.5X5mm**
|
||||
|
||||
---
|
||||
|
||||
🟡 **B3**. Allen key 2mm
|
||||
|
||||
---
|
||||
|
||||
Screw the four **A4** screws through the **PlanktoScope HAT** onto the **Standoff M2.5 - 16mm**.
|
||||
|
||||
🎬 Store this assembly for later.
|
||||
|
|
@ -1,30 +0,0 @@
|
|||
# Chapter 9
|
||||
|
||||
## Notes
|
||||
|
||||
| Topic | Description |
|
||||
| --------- | ----------- |
|
||||
| **Time** | |
|
||||
| **Tools** | |
|
||||
| **Parts** | |
|
||||
|
||||
## Place the **Power Socket** on **Part M**
|
||||
|
||||
Locate the **DC Power Jack** from the **Bag K**.
|
||||
|
||||
Remove the **Lock Ring** from the **DC Power Jack**
|
||||
|
||||
---
|
||||
|
||||
* 🔴 Lay the **Part M** down and make sure the pockets in these holes are facing upwards.
|
||||
* 🟣 Locate the **Power Socket** hole on **Part M**.
|
||||
|
||||
---
|
||||
|
||||
🔴 Insert the cable inside of the hole by being sure of the orientation of the **Part M**.
|
||||
|
||||
---
|
||||
|
||||
* 🟣 Flip the **Part M** and secure the **DC Power Jack** by hand on the **Part M** by screwing the **Lock Ring**.
|
||||
* ⚠ Make sure the **Lock Ring** doesn’t spin on itself.
|
||||
* 🎬 **Store this assembly for later**.
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Plankton Net
|
||||
|
||||
The simplest device you can use is a plankton net. It should be made of a fine mesh, down to 20 micron. It can be towed behind a boat at low speed (less than 2 knots) or towed by hand in a river or a lake.
|
||||
|
||||
Plankton nets can be made easily with a good sewind machine and some hardware.
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
# Content of the Kit
|
||||
|
||||
* note on the mapping of the component in the task to number in the BOM
|
||||
|
||||
## Bag A
|
||||
|
||||
## Bag B
|
||||
|
||||
## Bag C
|
||||
|
||||
## Bag D
|
||||
|
||||
## Bag E
|
||||
|
||||
## Bag F
|
||||
|
||||
## Bag G
|
||||
|
||||
## Bag H
|
||||
|
||||
## Bag I
|
||||
|
||||
## Bag J
|
||||
|
||||
## Bag K
|
||||
|
||||
## Bag L
|
||||
|
||||
## Bag M
|
||||
|
||||
## X1
|
||||
|
||||
## X2
|
||||
|
||||
## X3
|
||||
|
||||
## X4
|
||||
|
||||
## X5
|
||||
|
|
@ -1 +0,0 @@
|
|||
# Disposal and recycling
|
||||
|
|
@ -1,64 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# PlanktoScope Hat Hardware
|
||||
|
||||
## Buses and GPIO pinout
|
||||
|
||||
### I2C1 Bus
|
||||
|
||||
#### RTC RV-3028-C7
|
||||
|
||||
Address 0x52
|
||||
Configured through a kernel driver.
|
||||
|
||||
#### OLED Display
|
||||
|
||||
Address 0x3c
|
||||
|
||||
#### LED control: LM36011
|
||||
|
||||
Address 0x64
|
||||
Control through specific software, current range from 0 to 376mA in normal mode, up to 1.5A in flash mode.
|
||||
|
||||
### SPI0 Bus
|
||||
|
||||
#### Motor Controller 0: TMC5160
|
||||
|
||||
Chip Enable: SPI0_CE0
|
||||
Motor Enable: GPIO23
|
||||
|
||||
Diagnostic output:
|
||||
GPIO16 for Error output
|
||||
GPIO20 for Stall output
|
||||
|
||||
#### Motor Controller 1: TMC5160
|
||||
|
||||
Chip Enable: SPI0_CE1
|
||||
Motor Enable: GPIO5
|
||||
|
||||
Diagnostic output:
|
||||
GPIO16 for Error output
|
||||
GPIO20 for Stall output
|
||||
|
||||
### GPIO
|
||||
|
||||
#### Fan control
|
||||
|
||||
PWM1 control through GPIO13
|
||||
|
||||
#### LED Output selection
|
||||
|
||||
GPIO18: high for LED1, low for LED2
|
||||
|
||||
#### LED Strobe
|
||||
|
||||
GPIO22 for pulse
|
||||
|
||||
### I2C0 Bus
|
||||
|
||||
#### EEPROM M24C32
|
||||
|
||||
Address 0x50
|
||||
For HAT information only.
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# Manufacturing
|
||||
|
||||
## CAD Files
|
||||
|
|
@ -1,109 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# How to create a new SD master card, or backup efficiently your existing card
|
||||
|
||||
If you want to backup your machine, or prepare an image from the golden machine to share it to the world (or your students), you may want to follow those steps.
|
||||
|
||||
!!! tip
|
||||
The golden machine is the machine on which the setup is made. Everything is prepared according to your needs. Once it's ready, you just cleanly shut it down, pop the SD card out, and copy it to share the love!
|
||||
|
||||
Everything in this guide is written by using a Linux computer in which the sdcard is inserted.
|
||||
|
||||
## Find and unmount your sd card
|
||||
|
||||
Firsts things firsts, we need to know where is our sdcard in the linux filesystem.
|
||||
|
||||
To find the device, open a terminal and type in `sudo fdisk -l`.
|
||||
|
||||
In the output, there will be a section looking like this:
|
||||
|
||||
```txt
|
||||
Disk /dev/mmcblk0: 58.29 GiB, 62587404288 bytes, 122241024 sectors
|
||||
Units: sectors of 1 * 512 = 512 bytes
|
||||
Sector size (logical/physical): 512 bytes / 512 bytes
|
||||
I/O size (minimum/optimal): 512 bytes / 512 bytes
|
||||
Disklabel type: dos
|
||||
Disk identifier: 0xa2033091
|
||||
```
|
||||
|
||||
There is a very high probability that the device name we are looking for starts with `mmcblk`. To make sure this is the device we are looking for, use the size displayed (in this case, it is a 64GB sdcard).
|
||||
|
||||
We are now going to make sure the device is not mounted on your system (some OSes mount inserted sdcards automatically).
|
||||
|
||||
Simply type `sudo umount /dev/mmcblk0p1` and `sudo umount /dev/mmcblk0p2` to unmount the disk.
|
||||
|
||||
If the devices were not mounted, you may see an error message that you can ignore. The message looks like this:
|
||||
|
||||
```txt
|
||||
umount: /dev/mmcblk0p2: not mounted.
|
||||
```
|
||||
|
||||
## Copy the sdcard to your disk
|
||||
|
||||
Choose and navigate to an appropriate directory on your computer.
|
||||
|
||||
We are going to use `dd` to copy the sdcard. The command to type is the following:
|
||||
|
||||
```sh
|
||||
sudo dd if=/dev/mmcblk0 of=planktoscopeimage.img bs=4M status=progress
|
||||
```
|
||||
|
||||
- `if`: stands for `input file`, this is the input that we want to copy FROM
|
||||
- `of`: stands for `output file`, this is where the image is going to be written
|
||||
- `bs`: chooses a block size of 4M, this helps to speeds up the copy
|
||||
- `status`: just display a progression of the copy
|
||||
|
||||
The copy may take more than 15 minutes to complete, so you can go get a coffee or something.
|
||||
|
||||
Congratulations, you now have a complete copy of your sdcard!
|
||||
|
||||
However it's big. Huge even. We are going to resize it to make its storage and sharing easier.
|
||||
|
||||
## Shrink and share
|
||||
|
||||
Before shrinking the image, let's sanitize it first and remove eventual secrets stored in it (like wifi passwords for example).
|
||||
|
||||
```sh
|
||||
mkdir mnt
|
||||
sudo mount -o loop,rw,offset=$((532480 * 512)) planktoscopeimage.img ./mnt/
|
||||
```
|
||||
|
||||
You can now cleanup the image. The `mnt` directory is the same as the root of your sdcard. You should find your way from there.
|
||||
|
||||
Notably, do not forget to edit/remove the following files:
|
||||
|
||||
- `mnt/etc/wpa_supplicant/wpa_supplicant.conf`: wifi configuration and network secrets
|
||||
- `mnt/home/pi/.ssh/authorized_keys`: public ssh keys authorized to connect to this planktoscope
|
||||
- `mnt/home/pi/data/`: this folder has all the images taken before by your machine, you may want to clean it up too
|
||||
- `mnt/home/pi/.*history`: bash and python history
|
||||
- `mnt/home/pi/.gitconfig`: git config
|
||||
|
||||
!!! info
|
||||
If you want to distribute the image you created, you need to start the service that will recreate the host ssh keys on startup:
|
||||
`sudo ln -s /lib/systemd/system/regenerate_ssh_host_keys.service etc/systemd/system/multi-user.target.wants/regenerate_ssh_host_keys.service`
|
||||
|
||||
Once your cleanup is done, unmount the image with `sudo umount mnt`.
|
||||
|
||||
Now, let's shrink the image! To do so, we are going to use [PiShrink](https://github.com/Drewsif/PiShrink).
|
||||
|
||||
You can install the script using the following:
|
||||
|
||||
```sh
|
||||
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
|
||||
chmod +x pishrink.sh
|
||||
```
|
||||
|
||||
Now, starts PiShrink on your image, and watch it do its magic:
|
||||
|
||||
```sh
|
||||
sudo ./pishrink.sh -z -a planktoscopeimage.img
|
||||
```
|
||||
|
||||
The flags `-z -a` are used to compress the image to a gz file using the multithread version of gzip (pigz).
|
||||
|
||||
!!! info
|
||||
If you want to distribute the image you created, you should use the flag `-p` with PiShrink to remove logs, apt archives, ssh hosts keys and similar things.
|
||||
|
||||
You now have a compressed image that should be between 10 and 100 times smaller than the one you started with. You can distribute it (don't forget to do the steps above first), archive it, do whatever you please with it!
|
||||
|
|
@ -1,41 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# PlanktoScope Simple Setup Guide
|
||||
|
||||
## Download the image
|
||||
|
||||
For ease of setup, a preconfigured image is provided. You can download it from [here](https://drive.google.com/file/d/1y0k_NDXN0yT5caZrXhjLYXgQVxu-D5ql/view?usp=sharing).
|
||||
|
||||
## Writing the image to the SD card
|
||||
|
||||
Download the latest version of [balenaEtcher](https://www.balena.io/etcher/) and install it.
|
||||
|
||||
Connect an SD card reader with the micro SD card inside.
|
||||
|
||||
Open balenaEtcher and select from your hard drive the previously downloaded img file file you wish to write to the SD card.
|
||||
|
||||
Select the SD card you wish to write your image to.
|
||||
|
||||
Review your selections and click 'Flash!' to begin writing data to the SD card.
|
||||
|
||||
## Inserting the SD card
|
||||
|
||||
Once flashing is over, you can unmount the SD card from the computer (usually done by right clicking on the card icon in the taskbar).
|
||||
|
||||
Insert now the card in the Raspberry installed in your PlanktoScope.
|
||||
|
||||
## Install a mDNS client
|
||||
|
||||
To access the PlanktoScope services through your browser, you need to install a mDNS client.
|
||||
|
||||
If you are running a linux machine, you are in luck. Avahi-client is probably already installed on your machine. Check with your package manager.
|
||||
|
||||
If you are running a Windows machine, you will need to install the Bonjour service. It's a client developped by Apple. However, if you already use iTunes, Skype or even Photoshop, you may already have a client installed. Try skipping to the next step. If you can't access the linked page, come back here!
|
||||
|
||||
To install the client, download the installer [here](https://download.info.apple.com/Mac_OS_X/061-8098.20100603.gthyu/BonjourPSSetup.exe) and launch it.
|
||||
|
||||
## Start playing
|
||||
|
||||
Start up your PlanktoScope and connect to its WiFi network. You can now access the webpage at <http://planktoscope.local:1880/ui> to start using your machine!
|
||||
|
|
@ -1,787 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Expert Setup
|
||||
|
||||
## Install and setup Raspbian on your Raspberry Pi
|
||||
|
||||
### Computer setup
|
||||
|
||||
In order to make it easy to connect to the PlanktoScope, you may want to install [avahi](https://en.wikipedia.org/wiki/Avahi_%28software%29) or the [Bonjour](https://en.wikipedia.org/wiki/Bonjour_%28software%29) service on any computer you will use to access the PlanktoScope interface. This will allow you to connect to the PlantoScop using an address similar such as <http://planktoscope.local> instead of an IP address.
|
||||
|
||||
### Download the image
|
||||
|
||||
The latest Raspbian version can always be downloaded from [the Raspberry Pi Downloads page](https://www.raspberrypi.org/downloads/raspbian/).
|
||||
For a first build, it's recommende to download an image of Raspbian Buster with desktop.
|
||||
|
||||
#### Writing an image to the SD card
|
||||
|
||||
Download the latest version of [balenaEtcher](https://www.balena.io/etcher/) and install it.
|
||||
|
||||
Connect an SD card reader with the micro SD card inside.
|
||||
|
||||
Open balenaEtcher and select from your hard drive the image zip file you just downloaded.
|
||||
|
||||
Select the SD card you want to write your image to.
|
||||
|
||||
Review your selections and click `Flash!` to begin writing data to the SD card.
|
||||
|
||||
#### Prepare your Raspberry Pi
|
||||
|
||||
[Getting Started with your Raspberry Pi](https://projects.raspberrypi.org/en/projects/raspberry-pi-getting-started/)
|
||||
|
||||
Plug the SD Card in your Raspberry Pi and connect your Pi to a screen, mouse and a keyboard. Check the connection twice before plugging the power.
|
||||
|
||||
The first boot to the desktop may take up to 120 seconds. This is normal and is caused by the image expanding the filesystem to the whole SD card. DO NOT REBOOT before you reach the desktop.
|
||||
|
||||
#### Finish the setup
|
||||
|
||||
Make sure you have access to internet and update/upgrade your fresh Raspbian install.
|
||||
|
||||
Update your Pi first. Open up a terminal, and do the following:
|
||||
|
||||
```sh
|
||||
sudo apt update -y
|
||||
sudo apt full-upgrade -y
|
||||
sudo apt install git
|
||||
```
|
||||
|
||||
You can now reboot your Pi safely.
|
||||
|
||||
```sh
|
||||
sudo reboot now
|
||||
```
|
||||
|
||||
## Raspberry Pi configuration
|
||||
|
||||
### Clone this repository
|
||||
|
||||
First of all, and to ensure you have the latest documentation available locally, you should clone this repository using git.
|
||||
|
||||
Simply run the following in a terminal:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/PlanktonPlanet/PlanktoScope/
|
||||
```
|
||||
|
||||
### Enable Camera/SSH/I2C in raspi-config
|
||||
|
||||
You can now launch the configuration tool:
|
||||
|
||||
```sh
|
||||
sudo raspi-config
|
||||
```
|
||||
|
||||
While you're here, a wise thing to do would be to change the default password for the `pi` user. This is very warmly recommended if your PlanktoScope is connected to a shared network you do not control. Just select the first option `1 System Options`, the `S3 Password`.
|
||||
|
||||
You may also want to change the default hostname of your Raspberry. To do so, choose option `1 System Options` then `S4 Hostname`. Choose a new hostname. We recommend using `planktoscope` as this name will then appear.
|
||||
|
||||
We need to activate a few things for the PlanktoScope to work properly.
|
||||
|
||||
First, we need to activate the camera interface. Choose `3 Interface Options`, then `P1 Camera` and `Yes`.
|
||||
|
||||
Now, you can go to `3 Interface Options`, then `P2 SSH`. Choose `Yes` to activate the SSH access.
|
||||
|
||||
Again, select `3 Interface Options`, then `P4 SPI`. Choose `Yes` to enable the SPI interface.
|
||||
|
||||
One more, select `3 Interface Options`, then `P5 I2C`. Choose `Yes` to enable the ARM I2C interface of the Raspberry.
|
||||
|
||||
Finally, select `3 Interface Options`, then `P6 Serial`.
|
||||
|
||||
This time, choose `No` to deactivate the login shell on the serial connection, but then choose `Yes` to keep the Serial port hardware enabled.
|
||||
|
||||
Last steps we need to do is to increase the amount of memory available to the GPU. Select `4 Performance Options`, then `P2 GPU Memory`. Write `256` in the field and choose OK.
|
||||
|
||||
Also, to be able to use the ISO8601 datetime standard, we need to change the locale in use. Choose `5 Localisations Options`, then `L1 Locale` and press space after selecting the `en_DK.UTF8`. Press Enter and then select the en_DK locale as default for your system.
|
||||
|
||||
!!!info
|
||||
The en_DK is a hack where month and day names are in English, but date and time format uses the ISO8601 format. See <https://serverfault.com/questions/17118/how-do-i-set-the-date-format-to-iso-globally-in-linux>
|
||||
|
||||
These steps can also be done from the Raspberry Pi Configuration GUI tool that you can find in `Main Menu > Preferences`. Go to the `Interfaces` tab. Pay attention, here the Serial Port must be enabled, but the Serial Port Console must be disabled.
|
||||
|
||||
!!! tip
|
||||
Optional step: overclocking
|
||||
It's possible to overclock the machine and get a bit more performance out of it. Open `/boot/config.txt` with `sudo nano /boot/config.txt` and add at the end of the file on two new lines:
|
||||
|
||||
```txt
|
||||
over_voltage=6
|
||||
arm_freq=2000
|
||||
```
|
||||
|
||||
Those settings were verified to be stable, but if you notice any weird behavior under a high load, remove those lines.
|
||||
|
||||
Reboot your Pi safely.
|
||||
|
||||
```sh
|
||||
sudo reboot now
|
||||
```
|
||||
|
||||
## AutoHotSpot Setup
|
||||
|
||||
See the document [Remote Access](remote_access.md)
|
||||
|
||||
## Install the needed libraries for the PlanktoScope
|
||||
|
||||
Most of the following happens in a command line environment. If you are using the desktop, please start a terminal emulator.
|
||||
|
||||
You can also connect to your PlanktoScope by using ssh using `ssh pi@planktoscope.local`.
|
||||
|
||||
You can then run the following to make sure your Raspberry has the necessary components to install and build everything it needs and to create the necessary folders:
|
||||
|
||||
```sh
|
||||
sudo apt install build-essential python3 python3-pip
|
||||
sudo update-alternatives --install $(which python) python $(readlink -f $(which python2)) 1
|
||||
sudo update-alternatives --install $(which python) python $(readlink -f $(which python3)) 2
|
||||
sudo update-alternatives --config python
|
||||
# Choose line 0
|
||||
mkdir test libraries
|
||||
```
|
||||
|
||||
### Install all python libraries
|
||||
|
||||
To simplify setup, we provide requirements.txt:
|
||||
|
||||
```sh
|
||||
pip3 install -U -r /home/pi/PlanktoScope/requirements.txt
|
||||
```
|
||||
|
||||
### Add to python path
|
||||
|
||||
We need to do this to make sure we can call the modules from any path in the system, and not just from the `scripts` folder:
|
||||
|
||||
```
|
||||
ln -s /home/pi/PlanktoScope/scripts/planktoscope /home/pi/.local/lib/python3.7/site-packages/planktoscope
|
||||
ln -s /home/pi/PlanktoScope/scripts/shush /home/pi/.local/lib/python3.7/site-packages/shush
|
||||
sudo mkdir -p /root/.local/lib/python3.7/site-packages
|
||||
sudo ln -s /home/pi/PlanktoScope/scripts/planktoscope /root/.local/lib/python3.7/site-packages/planktoscope
|
||||
sudo ln -s /home/pi/PlanktoScope/scripts/shush /root/.local/lib/python3.7/site-packages/shush
|
||||
```
|
||||
|
||||
### [ADAFRUIT VERSION] Check CircuitPython's install
|
||||
|
||||
Start by following [Adafruit's guide](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi). You can start at the chapter `Install Python Libraries`.
|
||||
|
||||
#### Testing the installation and the wiring
|
||||
|
||||
It is recommended to test this setup by creating this small script under the name `test/blinkatest.py` and running it (you can use the editor nano if you are using the terminal). If you are using the image provided, you may find that the script is already there.
|
||||
|
||||
```python
|
||||
#!/usr/bin/python3
|
||||
import board
|
||||
import digitalio
|
||||
import busio
|
||||
|
||||
|
||||
print("Hello blinka!")
|
||||
|
||||
# Try to great a Digital input
|
||||
pin = digitalio.DigitalInOut(board.D4)
|
||||
print("Digital IO ok!")
|
||||
|
||||
# Try to create an I2C device
|
||||
i2c = busio.I2C(board.SCL, board.SDA)
|
||||
print("I2C ok!")
|
||||
|
||||
# Try to create an SPI device
|
||||
spi = busio.SPI(board.SCLK, board.MOSI, board.MISO)
|
||||
print("SPI ok!")
|
||||
|
||||
print("done!")
|
||||
```
|
||||
|
||||
To start the script, just run the following:
|
||||
|
||||
```sh
|
||||
chmod +x test/blinkatest.py
|
||||
./test/blinkatest.py
|
||||
```
|
||||
|
||||
The output should be similar to this:
|
||||
|
||||
```sh
|
||||
pi@planktoscope:~ $ ./test/blinkatest.py
|
||||
Hello blinka!
|
||||
Digital IO ok!
|
||||
I2C ok!
|
||||
SPI ok!
|
||||
done!
|
||||
```
|
||||
|
||||
Also, to make sure the wiring is good, we are going to use `sudo i2cdetect -y 1` to see if our devices are detected:
|
||||
|
||||
```sh
|
||||
pi@planktoscope:~ $ sudo i2cdetect -y 1
|
||||
0 1 2 3 4 5 6 7 8 9 a b c d e f
|
||||
00: -- -- -- -- -- -- -- -- -- -- 0d -- --
|
||||
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
|
||||
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
|
||||
30: -- -- -- -- -- -- -- -- -- -- -- -- 3c -- -- --
|
||||
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
|
||||
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
|
||||
60: 60 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
|
||||
70: 70 -- -- -- -- -- -- --
|
||||
```
|
||||
|
||||
The device appearing at addresses 60 and 70 is our motor controller. Address `0d` is the fan controller and `3c` is the oled screen (we'll set up both a bit further down). Your version of the RGB Cooling Hat may not have the screen, it's fine as the screen is not necessary for proper operation of the Planktoscope.
|
||||
|
||||
In case the motor controller does not appear, shutdown your Planktoscope and check the wiring. If your board is using a connector instead of a soldered pin connection (as happens with the Adafruit Bonnet Motor Controller), sometimes the pins on the male side need to be bent a little to make good contact. In any case, do not hesitate to ask for help in Slack.
|
||||
|
||||
### [PSCOPE_HAT VERSION] Test the stepper controllers
|
||||
|
||||
After wiring the steppers, please run the following script, you can create it in `~/test/stepper_controller.py`:
|
||||
|
||||
```python
|
||||
#!/usr/bin/python3
|
||||
import shush
|
||||
import time
|
||||
|
||||
m1 = shush.Motor(0)
|
||||
m1.enable_motor()
|
||||
m2 = shush.Motor(1)
|
||||
m2.enable_motor()
|
||||
|
||||
|
||||
# This function takes the target position as an input.
|
||||
# It prints the current position and the iteration.
|
||||
# The motor spins until it gets to the target position
|
||||
# before allowing the next command.
|
||||
def spin(motor, target):
|
||||
motor.go_to(target)
|
||||
|
||||
i = 0
|
||||
|
||||
while motor.get_position() != target:
|
||||
print(motor.get_position())
|
||||
print(i)
|
||||
i += 1
|
||||
|
||||
|
||||
while True:
|
||||
# Spin 5 rotations from start
|
||||
spin(m1, 256000)
|
||||
|
||||
time.sleep(0.5)
|
||||
# Spin back 5 rotations to starting point
|
||||
spin(m1, 0)
|
||||
|
||||
time.sleep(0.5)
|
||||
# Spin 5 rotations from start
|
||||
spin(m2, 256000)
|
||||
|
||||
time.sleep(0.5)
|
||||
# Spin back 5 rotations to starting point
|
||||
spin(m2, 0)
|
||||
|
||||
time.sleep(0.5)
|
||||
```
|
||||
|
||||
To start the script, just run the following:
|
||||
|
||||
```sh
|
||||
chmod +x ~/test/stepper_controller.py
|
||||
~/test/stepper_controller.py
|
||||
```
|
||||
|
||||
The pump should run in one direction then in the other, and the focus stage should move in one direction and then in another.
|
||||
|
||||
### Deactivate steppers
|
||||
|
||||
Create `sudo nano /etc/systemd/system/gpio-init.service`:
|
||||
|
||||
```
|
||||
[Unit]
|
||||
Description=GPIO Init
|
||||
DefaultDependencies=false
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/bin/stepper-disable
|
||||
Restart=no
|
||||
|
||||
[Install]
|
||||
WantedBy=sysinit.target
|
||||
```
|
||||
|
||||
And activate with `sudo systemctl enable autohotspot.service`.
|
||||
|
||||
Create the script with `sudo nano /usr/bin/stepper-disable`:
|
||||
|
||||
```sh
|
||||
#!/bin/sh -e
|
||||
|
||||
|
||||
# Initialise GPIO 4 and 12 to output to deactivate the steppers
|
||||
if [ ! -e /sys/class/gpio/gpio4 ]; then
|
||||
echo "4" > /sys/class/gpio/export
|
||||
fi
|
||||
|
||||
if [ ! -e /sys/class/gpio/gpio12 ]; then
|
||||
echo "12" > /sys/class/gpio/export
|
||||
fi
|
||||
echo "out" > /sys/class/gpio/gpio4/direction
|
||||
echo "out" > /sys/class/gpio/gpio12/direction
|
||||
echo "1" > /sys/class/gpio/gpio4/value
|
||||
echo "1" > /sys/class/gpio/gpio12/value
|
||||
```
|
||||
|
||||
### Install Ultimate GPS HAT
|
||||
|
||||
You can start by testing that the GPS module is working. Either install your PlanktoScope with a view of the sky, or connect the external antenna.
|
||||
|
||||
Now you need to run the following:
|
||||
|
||||
```sh
|
||||
sudo apt install gpsd gpsd-clients
|
||||
stty -F /dev/serial0 raw 9600 cs8 clocal -cstopb
|
||||
cat /dev/serial0
|
||||
```
|
||||
|
||||
If the GPS works, you should now see NMEA sentences scrolling:
|
||||
|
||||
```
|
||||
$GPGGA,000908.799,,,,,0,00,,,M,,M,,*7E
|
||||
$GPGSA,A,1,,,,,,,,,,,,,,,*1E
|
||||
$GPGSV,1,1,00*79
|
||||
$GPRMC,000908.799,V,,,,,0.00,0.00,060180,,,N*44
|
||||
$GPVTG,0.00,T,,M,0.00,N,0.00,K,N*32
|
||||
$GPGGA,000909.799,,,,,0,00,,,M,,M,,*7F
|
||||
$GPGSA,A,1,,,,,,,,,,,,,,,*1E
|
||||
$GPRMC,000909.799,V,,,,,0.00,0.00,060180,,,N*45
|
||||
$GPVTG,0.00,T,,M,0.00,N,0.00,K,N*32
|
||||
$GPGGA,000910.799,,,,,0,00,,,M,,M,,*77
|
||||
$GPGSA,A,1,,,,,,,,,,,,,,,*1E
|
||||
$GPRMC,000910.799,V,,,,,0.00,0.00,060180,,,N*4D
|
||||
$GPVTG,0.00,T,,M,0.00,N,0.00,K,N*32
|
||||
```
|
||||
|
||||
Until you get a GPS fix, most of the sentences are empty (see the lines starting with GPGSA and with lot of commas).
|
||||
|
||||
We are going to use gpsd to parse the GPS data. We need to set it up by editing `/etc/default/gpsd`. This file is source just before starting gpsd and allows to configure its working.
|
||||
|
||||
```sh
|
||||
sudo nano /etc/default/gpsd
|
||||
```
|
||||
|
||||
Change the `USB_AUTO` line to read `false`
|
||||
|
||||
```sh
|
||||
USBAUTO="false"
|
||||
```
|
||||
|
||||
Also change the `DEVICES` line to add the device we are going to use `/dev/serial0`:
|
||||
|
||||
```sh
|
||||
DEVICES="/dev/serial0"
|
||||
```
|
||||
|
||||
Finally, we want to add the parameter `-n -r` to `GPSD_OPTIONS`:
|
||||
|
||||
```sh
|
||||
GPSD_OPTIONS="-n -r"
|
||||
```
|
||||
|
||||
Save your work, and restart gpsd by running the following:
|
||||
|
||||
```sh
|
||||
sudo systemctl restart gpsd.service
|
||||
```
|
||||
|
||||
If you wait a bit, you can run `gpsmon` to check that your configuration is correct. You should get an output similar to this:
|
||||
|
||||
```
|
||||
pi@planktoscope:~ $ gpsmon
|
||||
/dev/serial0 NMEA0183>
|
||||
┌──────────────────────────────────────────────────────────────────────────────┐
|
||||
│Time: 2020-07-21T11:09:26.000Z Lat: 45 33' 28.08539" Non: 1 03' 44.02019" W│
|
||||
└───────────────────────────────── Cooked TPV ─────────────────────────────────┘
|
||||
┌──────────────────────────────────────────────────────────────────────────────┐
|
||||
│ GPGGA GPGSA GPRMC GPZDA GPGSV │
|
||||
└───────────────────────────────── Sentences ──────────────────────────────────┘
|
||||
┌──────────────────┐┌────────────────────────────┐┌────────────────────────────┐
|
||||
│Ch PRN Az El S/N ││Time: 110926.000 ││Time: 110927.000 │
|
||||
│ 0 27 351 78 49 ││Latitude: 4533.4809 N ││Latitude: 4533.4809 │
|
||||
│ 1 21 51 69 47 ││Longitude: 00103.7367 W ││Longitude: 00103.7367 │
|
||||
│ 2 16 184 61 43 ││Speed: 0.00 ││Altitude: -0.1 │
|
||||
│ 3 10 116 51 50 ││Course: 201.75 ││Quality: 2 Sats: 11 │
|
||||
│ 4 8 299 47 49 ││Status: A FAA: D ││HDOP: 0.87 │
|
||||
│ 5 20 66 42 46 ││MagVar: ││Geoid: 49.3 │
|
||||
│ 6 123 138 28 43 │└─────────── RMC ────────────┘└─────────── GGA ────────────┘
|
||||
│ 7 26 165 25 30 │┌────────────────────────────┐┌────────────────────────────┐
|
||||
│ 8 11 264 23 48 ││Mode: A3 ...s: 27 21 16 10 ││UTC: RMS: │
|
||||
│ 9 7 303 15 38 ││DOP: H=0.87 V=1.13 P=1.42 ││MAJ: MIN: │
|
||||
│10 18 56 14 44 ││TOFF: 0.530187817 ││ORI: LAT: │
|
||||
│11 30 330 5 35 ││PPS: ││LON: ALT: │
|
||||
└────── GSV ───────┘└──────── GSA + PPS ─────────┘└─────────── GST ────────────┘
|
||||
(42) $GPGSV,4,4,14,15,03,035,36,01,02,238,*72
|
||||
(72) $GPRMC,110922.000,A,4533.4809,N,00103.7366,W,0.01,322.19,210720,,,D*7E
|
||||
(35) $GPZDA,110922.000,21,07,2020,,*5B
|
||||
(81) $GPGGA,110923.000,4533.4809,N,00103.7367,W,2,11,0.87,-0.1,M,49.3,M,0000,0000*5B
|
||||
(64) $GPGSA,A,3,16,27,30,10,18,21,20,08,11,07,26,,1.43,0.87,1.13*0B
|
||||
(72) $GPRMC,110923.000,A,4533.4809,N,00103.7367,W,0.01,188.90,210720,,,D*7D
|
||||
(35) $GPZDA,110923.000,21,07,2020,,*5A
|
||||
(81) $GPGGA,110924.000,4533.4809,N,00103.7367,W,2,11,0.87,-0.1,M,49.3,M,0000,0000*5C
|
||||
(64) $GPGSA,A,3,16,27,30,10,18,21,20,08,11,07,26,,1.43,0.87,1.13*0B
|
||||
(72) $GPRMC,110924.000,A,4533.4809,N,00103.7367,W,0.01,156.23,210720,,,D*71
|
||||
```
|
||||
|
||||
You can leave with `CTRL+C`.
|
||||
|
||||
#### Bonus Configuration: Automatic time update from GPSD
|
||||
|
||||
The Adafruit GPS HAT allows your PlanktoScope to automatically sets its time to the GPS received one. Moreover, since the PPS (Pulse Per Second) output is activated, you can even set your PlanktoScope to act as a stratum 1 timeserver.
|
||||
|
||||
We are first going to make sure that your PlanktoScope receives proper PPS signal. We need to add the following line at the end of `/boot/config.txt`:
|
||||
|
||||
```
|
||||
sudo nano /boot/config.txt
|
||||
# Add the following line at the end of the line
|
||||
dtoverlay=pps-gpio,gpiopin=4
|
||||
```
|
||||
|
||||
We also need to activate the pps module of the kernel, by editing `/etc/modules`:
|
||||
|
||||
```
|
||||
sudo nano /etc/modules
|
||||
# Add the following line at the end of the line
|
||||
pps-gpio
|
||||
```
|
||||
|
||||
Now install `pps-tools` so we can check that this is properly running.
|
||||
|
||||
```sh
|
||||
sudo apt install pps-tools
|
||||
```
|
||||
|
||||
Finally, in the `/etc/default/gpsd` file, we need to add our pps device to the line `DEVICES`. Append `/dev/pps0`:
|
||||
|
||||
```sh
|
||||
DEVICES="/dev/serial0 /dev/pps0"
|
||||
```
|
||||
|
||||
Reboot your PlanktoScope now and check that the PPS signal is properly parsed by the PlanktoScope. You can do this by running `sudo ppstest /dev/pps0`:
|
||||
|
||||
```
|
||||
pi@planktoscope:~ $ sudo ppstest /dev/pps0
|
||||
trying PPS source "/dev/pps0"
|
||||
found PPS source "/dev/pps0"
|
||||
ok, found 1 source(s), now start fetching data...
|
||||
source 0 - assert 1595329939.946478786, sequence: 4125 - clear 0.000000000, sequence: 0
|
||||
source 0 - assert 1595329940.946459463, sequence: 4126 - clear 0.000000000, sequence: 0
|
||||
```
|
||||
|
||||
`gpsmon` should also show a PPS signal in the `GSA + PPS` box.
|
||||
|
||||
We now need to install the software that will act as timeserver, both locally and globally. Its name is Chrony. It's a more modern replacement for `ntp`, using the same underlying protocol. Let's go ahead and install it:
|
||||
|
||||
```sh
|
||||
sudo apt install chrony
|
||||
```
|
||||
|
||||
We need to edit the configuration of chrony, to activate both the GPS time synchronization and to allow clients to request time updates directly from our microscope.
|
||||
|
||||
Edit the file `/etc/chrony/chrony.conf` and replace its content with the following:
|
||||
|
||||
```
|
||||
pool pool.ntp.org iburst maxsources 4
|
||||
|
||||
driftfile /var/lib/chrony/drift
|
||||
|
||||
# allow to make big changes to clock if difference with ref clock is more than 1 seconds
|
||||
makestep 1 5
|
||||
|
||||
refclock SHM 0 refid NMEA offset 0.006
|
||||
refclock SHM 1 pps refid NME+
|
||||
refclock SOCK /var/run/chrony.sock delay 0.0 refid SOCK
|
||||
# noselect poll 8 filter 1000
|
||||
#refclock PPS /dev/pps0 precision 1e-7 noselect refid GPPS
|
||||
|
||||
allow all
|
||||
|
||||
rtcsync
|
||||
|
||||
logdir /var/log/chrony
|
||||
log rtc refclocks
|
||||
```
|
||||
|
||||
Before restarting `chrony`, we need to make sure the timesync service from systemd is deactivated:
|
||||
|
||||
```sh
|
||||
sudo systemctl stop systemd-timesyncd.service
|
||||
sudo systemctl disable systemd-timesyncd.service
|
||||
```
|
||||
|
||||
Final step, let's start `chrony` with its new configuration and restart `gpsd`:
|
||||
|
||||
```sh
|
||||
sudo systemctl restart chrony
|
||||
sudo systemctl restart gpsd
|
||||
```
|
||||
|
||||
To check that everything is working as intended, wait a few minutes, and then type `chronyc sources -v`. This command will show the time sources `chrony` is using, and right at the top there should be our NMEA source. Make sure its line starts with `#*`, which means this source is selected:
|
||||
|
||||
```
|
||||
pi@planktoscope:~ $ chronyc sources -v
|
||||
210 Number of sources = 5
|
||||
|
||||
.-- Source mode '^' = server, '=' = peer, '#' = local clock.
|
||||
/ .- Source state '*' = current synced, '+' = combined , '-' = not combined,
|
||||
| / '?' = unreachable, 'x' = time may be in error, '~' = time too variable.
|
||||
|| .- xxxx [ yyyy ] +/- zzzz
|
||||
|| Reachability register (octal) -. | xxxx = adjusted offset,
|
||||
|| Log2(Polling interval) --. | | yyyy = measured offset,
|
||||
|| \ | | zzzz = estimated error.
|
||||
|| | | \
|
||||
MS Name/IP address Stratum Poll Reach LastRx Last sample
|
||||
===============================================================================
|
||||
#* NMEA 0 4 377 13 -434ns[ -582ns] +/- 444ns
|
||||
^- mail.raveland.org 3 7 377 215 -18ms[ -18ms] +/- 53ms
|
||||
^- nio.nucli.net 2 6 377 19 -7340us[-7340us] +/- 63ms
|
||||
^- ntp4.kashra-server.com 2 8 377 146 -11ms[ -11ms] +/- 50ms
|
||||
^- pob01.aplu.fr 2 8 377 83 -15ms[ -15ms] +/- 66ms
|
||||
```
|
||||
|
||||
The other servers are here just as fallback measures, in case the GPS is not working for an unknown reason.
|
||||
|
||||
This part is now complete! Everytime you start your Planktoscope, it will set its own time after a few minutes (once a GPS signal is acquired).
|
||||
|
||||
The ultimate step will have to be done on the other equipment on the network where you want to use this time source. You will need to add the line `server planktoscope.local` to your ntp configuration file either at `/etc/ntp.conf` or at `/etc/chrony/chrony.conf` and then restart your ntp service.
|
||||
|
||||
You can find more information in this hardware module in Adafruit documentation at [Installing Adafruit GPS HAT](https://learn.adafruit.com/adafruit-ultimate-gps-hat-for-raspberry-pi/overview) or on this page to [use Python Thread with GPS HAT](http://www.danmandle.com/blog/getting-gpsd-to-work-with-python/)
|
||||
|
||||
### Install RGB Cooling HAT
|
||||
|
||||
To setup the RGB Cooling HAT, you just need to clone and build the WiringPi library:
|
||||
|
||||
```sh
|
||||
cd ~/libraries
|
||||
git clone https://github.com/WiringPi/WiringPi.git
|
||||
cd WiringPi
|
||||
sudo ./build
|
||||
gpio -v
|
||||
```
|
||||
|
||||
The last command should output something similar to the following:
|
||||
|
||||
```
|
||||
gpio version: 2.60
|
||||
Copyright (c) 2012-2018 Gordon Henderson
|
||||
This is free software with ABSOLUTELY NO WARRANTY.
|
||||
For details type: gpio -warranty
|
||||
|
||||
Raspberry Pi Details:
|
||||
Type: Pi 4B, Revision: 01, Memory: 4096MB, Maker: Sony
|
||||
* Device tree is enabled.
|
||||
*--> Raspberry Pi 4 Model B Rev 1.1
|
||||
* This Raspberry Pi supports user-level GPIO access.
|
||||
|
||||
```
|
||||
|
||||
You will also need to install some python modules:
|
||||
|
||||
```sh
|
||||
sudo apt install i2c-tools
|
||||
sudo pip3 install smbus2
|
||||
```
|
||||
|
||||
More information can be found on Yahboom website, on the page [Installing RGB Cooling HAT](https://www.yahboom.net/study/RGB_Cooling_HAT).
|
||||
|
||||
### Install Mosquitto MQTT
|
||||
|
||||
In order to send and receive data from Node-RED, you need to install this. Run the following:
|
||||
|
||||
```
|
||||
sudo apt install mosquitto mosquitto-clients
|
||||
|
||||
```
|
||||
|
||||
### Check OpenCV's installation
|
||||
|
||||
We need to install the latest OpenCV version. Unfortunately, it is not available in the repositories. We are going to install it directly by using pip.
|
||||
|
||||
First, we need to install the needed dependencies, then we will directly install opencv:
|
||||
|
||||
```sh
|
||||
sudo apt install libgtk-3-0 libavformat58 libavcodec58 libqt4-test libopenexr23 libilmbase23 libqtgui4 libavutil56 libjasper1 libqtcore4 libcairo-gobject2 libswscale5 libhdf5-dev libilmbase-dev libopenexr-dev libgstreamer1.0-dev libavcodec-dev libavformat-dev libswscale-dev libwebp-dev libatlas-base-dev
|
||||
```
|
||||
|
||||
Install now openCV diretly with pip:
|
||||
|
||||
```sh
|
||||
pip install opencv-contrib-python
|
||||
```
|
||||
|
||||
You can now check that opencv is properly installed by running a python interpreter and importing the cv2 module.
|
||||
|
||||
```sh
|
||||
pi@planktoscope:~ $ python3
|
||||
Python 3.7.3 (default, Jan 22 2021, 20:04:44)
|
||||
[GCC 8.3.0] on linux
|
||||
Type "help", "copyright", "credits" or "license" for more information.
|
||||
>>> import cv2
|
||||
>>> cv2.__version__
|
||||
'4.4.0'
|
||||
>>> quit()
|
||||
```
|
||||
|
||||
If all goes well, the displayed version number should be `4.4.0`.
|
||||
|
||||
More detailed information can be found on this [website](https://www.pyimagesearch.com/2019/09/16/install-opencv-4-on-raspberry-pi-4-and-raspbian-buster/).
|
||||
|
||||
### Check MorphoCut's installation
|
||||
|
||||
To test the installation, open up once again a python interpreter and import the morphocut module:
|
||||
|
||||
```sh
|
||||
pi@planktoscope:~ $ python3
|
||||
Python 3.7.3 (default, Dec 20 2019, 18:57:59)
|
||||
[GCC 8.3.0] on linux
|
||||
Type "help", "copyright", "credits" or "license" for more information.
|
||||
>>> import morphocut
|
||||
>>> morphocut.__version__
|
||||
'0.1.1+42.g01a051e'
|
||||
>>> quit()
|
||||
```
|
||||
|
||||
The MorphoCut documentation can be found [on this page](https://morphocut.readthedocs.io/en/stable/index.html).
|
||||
|
||||
### Nginx Setup
|
||||
|
||||
To display the gallery, we need to setup an nginx webserver.
|
||||
|
||||
Type in the following commands:
|
||||
|
||||
```
|
||||
sudo apt install nginx
|
||||
sudo rm /etc/nginx/sites-enabled/default
|
||||
sudo ln -s /home/pi/PlanktoScope/scripts/gallery/gallery.conf /etc/nginx/sites-enabled/gallery.conf
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
If you navigate to <http://planktoscope.local:80>, you should see the library opened.
|
||||
|
||||
### Install Node-RED
|
||||
|
||||
#### Download and installation
|
||||
|
||||
To install Node.js, npm and Node-RED onto a Raspberry Pi, you just need to run the following command. You can review the content of this script [here](https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered).
|
||||
|
||||
```sh
|
||||
bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)
|
||||
```
|
||||
|
||||
Type `y` at both prompts to accept the installation and its settings.
|
||||
|
||||
### Override Node-RED default settings to make it start after Mosquitto
|
||||
|
||||
We need to make sure nodered only starts after Mosquitto. And Mosquitto waits for a network connection to appear before starting.
|
||||
|
||||
To change this behavior, we need to override Node-red default setting. We modify the default service unit file with the following:
|
||||
|
||||
```sh
|
||||
sudo mkdir -p /etc/systemd/system/nodered.service.d/
|
||||
sudo cp /home/pi/PlanktoScope/scripts/raspbian_configuration/etc/systemd/system/nodered.service.d/override.conf /etc/systemd/system/nodered.service.d/override.conf
|
||||
sudo systemctl daemon-reload
|
||||
```
|
||||
|
||||
#### Enable start on boot and launch Node-RED
|
||||
|
||||
To run Node-RED when the Pi is turned on or restarted, you need to enable the systemd service by running this command:
|
||||
|
||||
```sh
|
||||
sudo systemctl enable nodered.service
|
||||
```
|
||||
|
||||
You can now start Node-RED by running the following:
|
||||
|
||||
```sh
|
||||
sudo systemctl start nodered.service
|
||||
```
|
||||
|
||||
#### Check the installation
|
||||
|
||||
Make sure Node-RED is correctly installed by reaching the following page from the browser of your pi <http://localhost:1880> or <http://planktoscope.local:1880> from another computer on the same network.
|
||||
|
||||
#### Install the necessary nodes and activate necessary features
|
||||
|
||||
We are going to activate the Projects feature of Node-Red as this will help us manage and track changes to the flows. Open the file `settings.js` with an editor (for example with `nano ~/.node-red/settings.js`) so we can change the following lines (you can use `CTRL+_` to quickly navigate to the line indicated):
|
||||
|
||||
- Line 75: uncomment the line (remove the //) that ends with flowFilePretty: true,
|
||||
- Line 337: set enabled to true
|
||||
|
||||
Restart Node-RED to take into account those changes:
|
||||
|
||||
```sh
|
||||
sudo systemctl restart nodered.service
|
||||
```
|
||||
|
||||
We need to move the PlanktoScope folder in the right place, in the `projects` subfolder of Node-Red and link this new folder to our `/home/`. To do so, in the terminal type the following::
|
||||
|
||||
```sh
|
||||
mv /home/pi/PlanktoScope /home/pi/.node-red/projects/
|
||||
ln -s ./.node-red/projects/PlanktoScope /home/pi/PlanktoScope
|
||||
```
|
||||
|
||||
We will now install the missing nodes. These nodes will be used by the PlanktoScope software:
|
||||
|
||||
```sh
|
||||
cd /home/pi/.node-red/
|
||||
npm install copy-dependencies
|
||||
node_modules/copy-dependencies/index.js projects/PlanktoScope ./
|
||||
npm update
|
||||
```
|
||||
|
||||
Save you changes.
|
||||
|
||||
The final step before restarting node-red is to link the projects directory from within node-red folder to our main home directory. To do so, just open a terminal and type the following:
|
||||
|
||||
You can now restart the nodered service:
|
||||
|
||||
```
|
||||
sudo systemctl restart nodered.service
|
||||
```
|
||||
|
||||
#### Import the last GUI
|
||||
|
||||
If you now open the Node-Red GUI in your browser, it will ask you to setup the project, an email and a username (so if you make changes to the flow and want to share them we can know who made them).
|
||||
|
||||
Open your browser and navigate to <http://planktoscope.local:1880>. In the prompt, select `Open existing project` button at the bottom, choose the PlanktoScope project and click on `Open Project`. Eventually, merge the proposed changes.
|
||||
|
||||
The latest flow version will be available immediately.
|
||||
|
||||
#### More information
|
||||
|
||||
[Installing Node-RED on Raspberry Pi](https://nodered.org/docs/getting-started/raspberrypi)
|
||||
|
||||
## Finishing the install
|
||||
|
||||
Make sure to update your Pi
|
||||
|
||||
```
|
||||
sudo apt update -y
|
||||
sudo apt full-upgrade -y
|
||||
```
|
||||
|
||||
Reboot your Pi safely
|
||||
|
||||
```
|
||||
sudo reboot now
|
||||
|
||||
```
|
||||
|
||||
## Useful later maybe
|
||||
|
||||
### Update the cloned repository
|
||||
|
||||
Updates are published on Github regurlarly. Make sure to update once in a while by running this command:
|
||||
|
||||
```sh
|
||||
cd PlanktoScope
|
||||
git pull
|
||||
```
|
||||
|
||||
This will pull and merge all the changes made since your last update.
|
||||
|
||||
### Share WiFi via Ethernet
|
||||
|
||||
At this link : <https://www.instructables.com/id/Share-WiFi-With-Ethernet-Port-on-a-Raspberry-Pi/>
|
||||
|
|
@ -1,130 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Using a flash with the camera
|
||||
|
||||
The Pi's camera module includes an LED flash driver which can be used to illuminate a scene upon capture. The flash driver has two configurable GPIO pins:
|
||||
|
||||
- one for connection to an LED based flash (xenon flashes won't work with the camera module due to it having a `rolling shutter`). This will fire before (`flash metering`) and during capture
|
||||
- one for an optional privacy indicator (a requirement for cameras in some jurisdictions). This will fire after taking a picture to indicate that the
|
||||
camera has been used
|
||||
|
||||
These pins are configured by updating the `VideoCore device tree blob`. Firstly, install the device tree compiler, then grab a copy of the default
|
||||
device tree source:
|
||||
|
||||
```sh
|
||||
sudo apt-get install device-tree-compiler
|
||||
wget https://github.com/raspberrypi/firmware/raw/master/extra/dt-blob.dts
|
||||
```
|
||||
|
||||
The device tree source contains a number of sections enclosed in curly braces, which form a hierarchy of definitions. The section to edit will depend on which revision of Raspberry Pi you have (check the silk-screen writing on the board for the revision number if you are unsure):
|
||||
|
||||
| Model | Section |
|
||||
| -------------------------------------- | :----------------------- |
|
||||
| Raspberry Pi Model B rev 1 | `/videocore/pins_rev1` |
|
||||
| Raspberry Pi Model A and Model B rev 2 | `/videocore/pins_rev2` |
|
||||
| Raspberry Pi Model A+ | `/videocore/pins_aplus` |
|
||||
| Raspberry Pi Model B+ rev 1.1 | `/videocore/pins_bplus1` |
|
||||
| Raspberry Pi Model B+ rev 1.2 | `/videocore/pins_bplus2` |
|
||||
| Raspberry Pi 2 Model B rev 1.0 | `/videocore/pins_2b1` |
|
||||
| Raspberry Pi 2 Model B rev 1.1-1.2 | `/videocore/pins_2b2` |
|
||||
| Raspberry Pi 3 Model B rev 1.0 | `/videocore/pins_3b1` |
|
||||
| Raspberry Pi 3 Model B rev 1.2 | `/videocore/pins_3b2` |
|
||||
| Raspberry Pi Zero rev 1.2-1.3 | `/videocore/pins_pi0` |
|
||||
|
||||
Under the section for your particular model of Pi you will find `pin_config` and `pin_defines` sections. Under the `pin_config` section you need to configure the GPIO pins you want to use for the flash and privacy indicator as using pull down termination. Then, under the `pin_defines` section you need to associate those pins with the `FLASH_0_ENABLE` and `FLASH_0_INDICATOR` pins.
|
||||
|
||||
For example, to configure GPIO 17 as the flash pin, leaving the privacy indicator pin absent, on a Raspberry Pi 2 Model B rev 1.1 you would add the following line under the `/videocore/pins_2b2/pin_config` section:
|
||||
|
||||
```txt
|
||||
pin@p17 { function = "output"; termination = "pull_down"; };
|
||||
```
|
||||
|
||||
Please note that GPIO pins will be numbered according to the `Broadcom pin numbers`(BCM mode in the RPi.GPIO library, _not_ BOARD mode). Then change the following section under `/videocore/pins_2b2/pin_defines`. Specifically, change the type from "absent" to "internal", and add a number property defining the flash pin as GPIO 17:
|
||||
|
||||
```c
|
||||
pin_define@FLASH_0_ENABLE {
|
||||
type = "internal";
|
||||
number = <17>;
|
||||
};
|
||||
```
|
||||
|
||||
With the device tree source updated, you now need to compile it into a binary blob for the firmware to read. This is done with the following command line:
|
||||
|
||||
```sh
|
||||
dtc -q -I dts -O dtb dt-blob.dts -o dt-blob.bin
|
||||
```
|
||||
|
||||
Dissecting this command line, the following components are present:
|
||||
|
||||
- `dtc` - Execute the device tree compiler
|
||||
- `-I dts` - The input file is in device tree source format
|
||||
- `-O dtb` - The output file should be produced in device tree binary format
|
||||
- `dt-blob.dts` - The first anonymous parameter is the input filename
|
||||
- `-o dt-blob.bin` - The output filename
|
||||
|
||||
This should output nothing. If you get lots of warnings, you've forgotten the `-q` switch; you can ignore the warnings. If anything else is output, it will most likely be an error message indicating you have made a mistake in the device tree source. In this case, review your edits carefully (note that sections and properties _must_ be semi-colon terminated for example), and try again.
|
||||
|
||||
Now the device tree binary blob has been produced, it needs to be placed on the first partition of the SD card. In the case of non-NOOBS Raspbian installs, this is generally the partition mounted as `/boot`:
|
||||
|
||||
```sh
|
||||
sudo cp dt-blob.bin /boot/
|
||||
```
|
||||
|
||||
However, in the case of NOOBS Raspbian installs, this is the recovery partition, which is not mounted by default:
|
||||
|
||||
```sh
|
||||
sudo mkdir /mnt/recovery
|
||||
sudo mount /dev/mmcblk0p1 /mnt/recovery
|
||||
sudo cp dt-blob.bin /mnt/recovery
|
||||
sudo umount /mnt/recovery
|
||||
sudo rmdir /mnt/recovery
|
||||
```
|
||||
|
||||
Please note that the filename and location are important. The binary blob must be named `dt-blob.bin` (all lowercase), and it must be placed in the root
|
||||
directory of the first partition on the SD card. Once you have rebooted the Pi (to activate the new device tree configuration) you can test the flash with the following simple script:
|
||||
|
||||
```python
|
||||
import picamera
|
||||
|
||||
with picamera.PiCamera() as camera:
|
||||
camera.flash_mode = 'on'
|
||||
camera.capture('foo.jpg')
|
||||
```
|
||||
|
||||
You should see your flash LED blink twice during the execution of the script.
|
||||
|
||||
!!! warning
|
||||
The GPIOs only have a limited current drive which is insufficient for powering the sort of LEDs typically used as flashes in mobile phones. You will require a suitable drive circuit to power such devices, or risk damaging your Pi.
|
||||
|
||||
For reference, the flash driver chips we have used on mobile phones will often drive up to 500mA into the LED. If you're aiming for that, then please think about your power supply too.
|
||||
|
||||
If you wish to experiment with the flash driver without attaching anything to the GPIO pins, you can also reconfigure the camera's own LED to act as the flash LED. Obviously this is no good for actual flash photography but it can demonstrate whether your configuration is good. In this case you need not add anything to the `pin_config` section (the camera's LED pin is already defined to use pull down termination), but you do need to set `CAMERA_0_LED` to absent, and `FLASH_0_ENABLE` to the old `CAMERA_0_LED` definition (this will be pin 5 in the case of `pins_rev1` and `pins_rev2``, and pin 32 in the case of everything else).
|
||||
|
||||
For example, change:
|
||||
|
||||
```c
|
||||
pin_define@CAMERA_0_LED {
|
||||
type = "internal";
|
||||
number = <5>;
|
||||
};
|
||||
pin_define@FLASH_0_ENABLE {
|
||||
type = "absent";
|
||||
};
|
||||
```
|
||||
|
||||
into this:
|
||||
|
||||
```c
|
||||
pin_define@CAMERA_0_LED {
|
||||
type = "absent";
|
||||
};
|
||||
pin_define@FLASH_0_ENABLE {
|
||||
type = "internal";
|
||||
number = <5>;
|
||||
};
|
||||
```
|
||||
|
||||
After compiling and installing the device tree blob according to the instructions above, and rebooting the Pi, you should find the camera LED now
|
||||
acts as a flash LED with the Python script above.
|
||||
|
|
@ -1,34 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Getting started with using the machine
|
||||
|
||||
Congratulations! You have finished assembling your machine, now is the time to test it and learn how to use it!
|
||||
|
||||
## How to connect to and control the machine
|
||||
|
||||
On powering up, your PlanktoScope will create its own isolated WiFi network. It should appear on the list of available wifi networks about two minutes after the first startup.
|
||||
|
||||
|
||||
As you can see, its name will be similar to `PlanktoScope-Baba*****_*****`. This name is unique to your machine and is linked to the serial number of the Raspberry CPU. You can connect to this network now.
|
||||
|
||||
Once connected, you will not have acces to the Internet, only to the PlanktoScope interface. You can access the page at [http://planktoscope.local:1880/ui](http://planktoscope.local:1880/ui) from your favorite web browser.
|
||||
|
||||
!!! tip
|
||||
You are able to configure your machine to connect to another network if you want in the [Wifi settings page](images/ui_guide.md#wifi). If you do this, your machine will be accessible to anybody connected to this network. Please keep in mind your organisation security policies before doing this.
|
||||
|
||||
From there, you can have a look at the [UI guide](images/ui_guide.md) to get a handle on how it works.
|
||||
|
||||
## How to image plankton
|
||||
|
||||
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).
|
||||
|
||||
However, if you have access to a body of water (even a tiny lake or river is enough), you can build yourself a plankton net to collect a sample. Once the sample is collected, either pump it with a syringe that you connect to the machine, or dip one of the silicone tube inside the sample tube you have.
|
||||
|
||||
You can then do an acquisition run. **This is the best way to learn about the machine and this process!**
|
||||
|
||||
!!! warning
|
||||
After doing an acquisition, the machine should be cleaned, especially in the fluidic part. One good way to do this is to first flush the machine with clear water (distilled if possible). You can then push through a 5-10% bleach solution, or some alcohol.
|
||||
|
||||
If needed you can also clean the outside of the objective lens with a soft cloth. You can do the same on the flow cell if there are traces of finger on it too.
|
||||
|
|
@ -1,231 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Details about used MQTT messages
|
||||
|
||||
## Topic lists
|
||||
|
||||
- [`actuator`](#actuator)
|
||||
- [`actuator/pump`](#actuatorpump)
|
||||
- [`actuator/focus`](#actuatorfocus)
|
||||
- [`imager/image`](#imagerimage)
|
||||
- [`segmenter/segment`](#segmentersegment)
|
||||
- [`status`](#status)
|
||||
- [`status/pump`](#statuspump)
|
||||
- [`status/focus`](#statusfocus)
|
||||
- [`status/imager`](#statusimager)
|
||||
- [`status/segmenter`](#statussegmenter)
|
||||
- [`status/segmenter/name`](#statussegmentername)
|
||||
- [`status/segmenter/object_id`](#statussegmenterobject_id)
|
||||
- [`status/segmenter/metric`](#statussegmentermetric)
|
||||
|
||||
## Topic details
|
||||
|
||||
### `actuator`
|
||||
|
||||
#### `actuator/pump`
|
||||
|
||||
Control the movement of the pump. The message is a JSON object:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "move",
|
||||
"direction": "FORWARD",
|
||||
"volume": 10,
|
||||
"flowrate": 1
|
||||
}
|
||||
```
|
||||
|
||||
This messages make the pump move 10mL forward at 1mL/min.
|
||||
|
||||
Another supported message is:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "stop"
|
||||
}
|
||||
```
|
||||
|
||||
- Receive only
|
||||
|
||||
#### `actuator/focus`
|
||||
|
||||
Control of the focus stage. The message is a JSON object, speed is optional:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "move",
|
||||
"direction": "UP",
|
||||
"distance": 0.26,
|
||||
"speed": 1
|
||||
}
|
||||
```
|
||||
|
||||
This message makes the stage move up by 10mm.
|
||||
|
||||
Another supported message is:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "stop"
|
||||
}
|
||||
```
|
||||
|
||||
- Receive only
|
||||
|
||||
### `imager/image`
|
||||
|
||||
This topic controls the camera and capture. The message allowed is a JSON message:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "image",
|
||||
"pump_direction": "FORWARD",
|
||||
"volume": 1,
|
||||
"nb_frame": 200
|
||||
}
|
||||
```
|
||||
|
||||
Volume is in mL.
|
||||
|
||||
This topic can also receive a config update message:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "config",
|
||||
"config": {...}
|
||||
}
|
||||
```
|
||||
|
||||
A camera settings message can also be received here. The fields `iso`, `shutter_speed`, `white_balance_gain`, `white_balance` and `image_gain` are optionals:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "settings",
|
||||
"settings":{
|
||||
"iso": 100,
|
||||
"shutter_speed": 40,
|
||||
"white_balance_gain": {"red": 100, "blue": 100},
|
||||
"white_balance": "auto",
|
||||
"image_gain": {"analog": 100, "digital": 100}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Receive only
|
||||
|
||||
### `segmenter/segment`
|
||||
|
||||
This topic controls the segmentation process. The message is a JSON object:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "segment",
|
||||
"path": "/path/to/segment",
|
||||
"settings": {
|
||||
"force": False,
|
||||
"recursive": True,
|
||||
"ecotaxa": True,
|
||||
"keep": True
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`action` can also be `stop`.
|
||||
The `action` element is the only element required. If no `path` is supplied, the whole images repository is segmented recursively (this is very long!).
|
||||
|
||||
`force` is going to overcome the presence of the file `done` that is here to prevent for resegmenting a folder already segmented.
|
||||
|
||||
`recursive` will force parsing all folders below `path`.
|
||||
|
||||
`ecotaxa` activates the export of an ecotaxa compatible archive.
|
||||
|
||||
`keep` allows to remove or keep the roi (when you do an ecotaxa export, no effects otherwise, the roi are kept).
|
||||
|
||||
- Receive only
|
||||
|
||||
### `status`
|
||||
|
||||
This high-level topic is used to send information to the Node-Red process. There is no publication or receive at this level.
|
||||
|
||||
#### `status/pump`
|
||||
|
||||
State of the pump. It's a JSON object with:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "Started",
|
||||
"duration": 25
|
||||
}
|
||||
```
|
||||
|
||||
Duration is a best guess estimate. It should not be used to control the other events. If you want to wait for a movement to finish, the best thing to do is to wait for the message `Done`.
|
||||
|
||||
Status can be `Started`, `Ready`, `Done`, `Interrupted`, `Error`, `Dead`.
|
||||
|
||||
- Publish only
|
||||
|
||||
#### `status/focus`
|
||||
|
||||
State of the focus stage. It's a JSON object with:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "Started",
|
||||
"duration": 25
|
||||
}
|
||||
```
|
||||
|
||||
Duration is a best guess estimate. It should not be used to control the other events. If you want to wait for a movement to finish, the best thing to do is to wait for the message `Done`.
|
||||
|
||||
Status is one of `Started`, `Ready`, `Done`, `Interrupted`, `Error`, `Dead`.
|
||||
|
||||
- Publish only
|
||||
|
||||
#### `status/imager`
|
||||
|
||||
State of the imager. It's a JSON object with:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "Started",
|
||||
"time_left": 25
|
||||
}
|
||||
```
|
||||
|
||||
Status is one of `Started`, `Ready`, `Completed` or `12_11_15_0.1.jpg has been imaged`.
|
||||
|
||||
- Publish only
|
||||
|
||||
#### `status/segmenter`
|
||||
|
||||
Status of the segmentation. It's a JSON object with:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "Started",
|
||||
}
|
||||
```
|
||||
|
||||
`status` is one of `Started`, `Done`, `Interrupted`, `Busy`, `Ready` or `Dead`.
|
||||
|
||||
- Publish only
|
||||
|
||||
#### `status/segmenter/object_id`
|
||||
|
||||
```json
|
||||
{
|
||||
"object_id": "13449"
|
||||
}
|
||||
```
|
||||
|
||||
#### `status/segmenter/metric`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "01_13_28_232066_0",
|
||||
"metadata": {
|
||||
"label": 0, "width": 29, "height": 80, ....
|
||||
}
|
||||
```
|
||||
|
|
@ -1,408 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Remote access via a standalone network
|
||||
|
||||
This tutorial is adapted from a tutorial that you can find [here](https://www.raspberryconnect.com/projects/65-raspberrypi-hotspot-accesspoints/157-raspberry-pi-auto-wifi-hotspot-switch-internet).
|
||||
|
||||
All the files modified in this document are also available in the repository, in the folder `scripts/raspbian_configuration`. The architecture of this folder shows where each file belong.
|
||||
|
||||
In order to work as an access point, the Raspberry Pi will need to have access point software installed, along with DHCP server software to provide connecting devices with a network address.
|
||||
|
||||
To create an access point, we'll need DNSMasq and HostAPD. Install all the required software in one go with this command::
|
||||
|
||||
```sh
|
||||
sudo apt install dnsmasq hostapd
|
||||
```
|
||||
|
||||
Since the configuration files are not ready yet, turn the new software off as follows::
|
||||
|
||||
```sh
|
||||
sudo systemctl unmask hostapd
|
||||
sudo systemctl disable dnsmasq
|
||||
sudo systemctl disable hostapd
|
||||
```
|
||||
|
||||
## Configuring HostAPD
|
||||
|
||||
Using a text editor edit the hostapd configuration file. This file won't exist at this stage so will be blank: `sudo nano /etc/hostapd/hostapd.conf`
|
||||
|
||||
```txt
|
||||
#2.4GHz setup wifi 80211 b,g,n
|
||||
interface=wlan0
|
||||
driver=nl80211
|
||||
ssid=PlanktoScope-Bababui_Tuogaore
|
||||
hw_mode=g
|
||||
channel=8
|
||||
wmm_enabled=0
|
||||
macaddr_acl=0
|
||||
auth_algs=1
|
||||
ignore_broadcast_ssid=0
|
||||
wpa=2
|
||||
wpa_passphrase=copepode
|
||||
wpa_key_mgmt=WPA-PSK
|
||||
wpa_pairwise=CCMP TKIP
|
||||
rsn_pairwise=CCMP
|
||||
|
||||
#80211n - Change GB to your WiFi country code
|
||||
country_code=FR
|
||||
ieee80211n=1
|
||||
ieee80211d=1
|
||||
```
|
||||
|
||||
The interface will be wlan0. The driver nl80211 works with the Raspberry RPi 4, RPi 3B+, RPi 3 & Pi Zero W onboard WiFi but you will need to check that your wifi dongle is compatable and can use Access Point mode.
|
||||
|
||||
For more information on wifi dongles see elinux.org/RPi_USB_Wi-Fi_Adapters
|
||||
|
||||
The SSID is the name of the WiFi signal broadcast from the RPi, which you will connect to with your Tablet or phones WiFi settings.
|
||||
Channel can be set between 1 and 13. If you are having trouble connection because of to many wifi signals in your area are using channel 8 then try another channel.
|
||||
Wpa_passphrase is the password you will need to enter when you first connect a device to your Raspberry Pi's hotspot. This should be at least 8 characters and a bit more difficult to guess than my example.
|
||||
The country_code should be set to your country to comply with local RF laws. You may experience connection issues if this is not correct. Your country_code can be found in /etc/wpa_supplicant/wpa_supplicant.conf or in Raspberry Pi Configuration - Localisation settings
|
||||
|
||||
To save the config file press `CTRL+O` and to exit press `CTRL+X`.
|
||||
|
||||
We also use a special function to change the network name to the machine name. Add this to `/etc/rc.local` with `sudo nano /etc/rc.local`:
|
||||
|
||||
```sh
|
||||
# Replace wifi hostname
|
||||
sed -i "s/^ssid.*/ssid=PlanktoScope-$(python3 -c "import planktoscope.uuidName as uuidName; print(uuidName.machineName(machine=uuidName.getSerial()).replace(' ','_'))")/" /etc/hostapd/hostapd.conf
|
||||
```
|
||||
|
||||
Now the defaults file needs to be updated to point to where the config file is stored.
|
||||
In terminal enter the command `sudo nano /etc/default/hostapd`
|
||||
|
||||
Change `#DAEMON_CONF=""` to `DAEMON_CONF="/etc/hostapd/hostapd.conf"`
|
||||
|
||||
Check the `DAEMON_OPTS=""` is preceded by a #, so is `#DAEMON_OPTS=""`.
|
||||
|
||||
And save.
|
||||
|
||||
## DNSmasq configuration
|
||||
|
||||
Next dnsmasq needs to be configured to allow the Rpi to act as a router and issue ip addresses. Open the dnsmasq.conf file with `sudo nano /etc/dnsmasq.conf`
|
||||
|
||||
Go to the bottom of the file and add the following lines:
|
||||
|
||||
```txt
|
||||
#AutoHotspot config
|
||||
interface=wlan0
|
||||
bind-dynamic
|
||||
server=1.1.1.1
|
||||
domain-needed
|
||||
bogus-priv
|
||||
dhcp-range=192.168.4.100,192.168.4.200,12h
|
||||
|
||||
#AutoEthernet config
|
||||
interface=eth0
|
||||
bind-dynamic
|
||||
server=1.1.1.1
|
||||
domain-needed
|
||||
bogus-priv
|
||||
dhcp-range=192.168.5.100,192.168.5.200,12h
|
||||
```
|
||||
|
||||
and then save `CTRL+O` and exit `CTRL+X`.
|
||||
|
||||
Reload dnsmasq to use the updated configuration:
|
||||
|
||||
```sh
|
||||
sudo systemctl reload dnsmasq
|
||||
```
|
||||
|
||||
## DHCPCD
|
||||
|
||||
DHCPCD is the software that manages the network setup. The next step is to stop dhcpcd from starting the wifi network so the autohotspot script in the next step takes control of that. Ethernet will still be managed by dhcpcd.
|
||||
|
||||
This will also create a fallback configuration to a static IP if no DHCP server is present on the Ethernet network.
|
||||
|
||||
Just add this line to the end of /etc/dhcpcd.conf with `sudo nano /etc/dhcpcd.conf`:
|
||||
|
||||
```txt
|
||||
nohook wpa_supplicant
|
||||
|
||||
# define static profile
|
||||
profile static_eth0
|
||||
static ip_address=192.168.5.1/24
|
||||
static routers=192.168.5.1
|
||||
static domain_name_servers=192.168.5.1
|
||||
|
||||
# fallback to static profile on eth0
|
||||
interface eth0
|
||||
fallback static_eth0
|
||||
```
|
||||
|
||||
Save and exit.
|
||||
|
||||
For the fallback Ethernet network to work, we also need to add a hook to DHCPCD so it starts up the local DHCP server (dnsmasq). Edit the file `/etc/dhcpcd.enter-hook` with `sudo nano /etc/dhcpcd.enter-hook`:
|
||||
|
||||
```sh
|
||||
if [ "$interface" = "eth0" ] && [ "$if_up" ]; then
|
||||
systemctl start dnsmasq
|
||||
if [ "$reason" = "STATIC" ] || [ "$reason" = "TIMEOUT" ] || [ "$reason" = "EXPIRE" ] || [ "$reason" = "NAK" ]; then
|
||||
systemctl start dnsmasq
|
||||
elif [ "$reason" = "NOCARRIER" ] || [ "$reason" = "INFORM" ] || [ "$reason" = "DEPARTED" ]; then
|
||||
systemctl stop dnsmasq
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
## Autohotspot service file
|
||||
|
||||
Next we have to create a service which will run the autohotspot script when the Raspberry Pi starts up.
|
||||
Create a new file with the command `sudo nano /etc/systemd/system/autohotspot.service`
|
||||
|
||||
Then enter the following text:
|
||||
|
||||
```txt
|
||||
[Unit]
|
||||
Description=Automatically generates a Hotspot when a valid SSID is not in range
|
||||
After=multi-user.target
|
||||
[Service]
|
||||
Type=oneshot
|
||||
RemainAfterExit=yes
|
||||
ExecStart=/usr/bin/autohotspotN
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Save and exit.
|
||||
|
||||
For the service to work it has to be enabled. To do this enter the command `sudo systemctl enable autohotspot.service`.
|
||||
|
||||
## Service Timer
|
||||
|
||||
Create the timer with `sudo nano /etc/systemd/system/autohotspot.timer`:
|
||||
|
||||
```txt
|
||||
# /etc/systemd/system/autohotspot.timer
|
||||
[Unit]
|
||||
Description=Run autohotspot every 5 minutes, starting 10 seconds after system boot
|
||||
|
||||
[Timer]
|
||||
OnBootSec=5sec
|
||||
OnUnitActivateSec=5min
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
```
|
||||
|
||||
Save and exit.
|
||||
|
||||
Activate with `sudo systemctl enable autohotspot.timer`.
|
||||
|
||||
### AutoHotspot Script
|
||||
|
||||
This is the main script that will manage your wifi connections between a wifi router and an Access Point.
|
||||
|
||||
It will search for any wifi connection that is setup on you Raspberry Pi by using the details found in /etc/wpa_supplicant/wpa_supplicant.conf
|
||||
|
||||
If no wifi signal is found for a known SSID then the script will shutdown the wifi network setup and create a Hotspot. If an ethernet cable that allows internet access is connect then the Hotspot will become a full internet access point. Allowing all connected devices to use the Internet. Without an ethernet connect the Raspberry Pi can be accessed from a wifi device using SSH or VNC.
|
||||
|
||||
The script works with SSID's that contain spaces and by entering your routers MAC address it can be used with hidden SSID's.
|
||||
|
||||
!!! info
|
||||
Hidden SSIDs
|
||||
|
||||
If your routers SSID is not broadcast/hidden then find this section in the script
|
||||
|
||||
```txt
|
||||
#Enter the Routers Mac Addresses for hidden SSIDs, seperated by spaces ie
|
||||
#( '11:22:33:44:55:66' 'aa:bb:cc:dd:ee:ff' )
|
||||
mac=()
|
||||
```
|
||||
|
||||
and enter you routers MAC address in the brackets of mac=() as shown in the example. Make sure mutiple MAC addresses are seperated by a space.
|
||||
|
||||
Create a new file with the command `sudo nano /usr/bin/autohotspotN` and add the following:
|
||||
|
||||
```sh
|
||||
#!/bin/bash
|
||||
#version 0.961-N/HS-I-PlanktonPlanet
|
||||
|
||||
#changes by PlanktonPlanet includes the following:
|
||||
#- formatting and shellcheck validation
|
||||
#- removal of ip forwarding setup
|
||||
|
||||
#You may share this script on the condition a reference to RaspberryConnect.com
|
||||
#must be included in copies or derivatives of this script.
|
||||
|
||||
#Network Wifi & Hotspot with Internet
|
||||
#A script to switch between a wifi network and an Internet routed Hotspot
|
||||
#A Raspberry Pi with a network port required for Internet in hotspot mode.
|
||||
#Works at startup or with a seperate timer or manually without a reboot
|
||||
#Other setup required find out more at
|
||||
#http://www.raspberryconnect.com
|
||||
|
||||
wifidev="wlan0" #device name to use. Default is wlan0.
|
||||
ethdev="eth0" #Ethernet port to use with IP tables
|
||||
#use the command: iw dev ,to see wifi interface name
|
||||
|
||||
#These two lines capture the wifi networks the RPi is setup to use
|
||||
wpassid=$(awk '/ssid="/{ print $0 }' /etc/wpa_supplicant/wpa_supplicant.conf | awk -F'ssid=' '{ print $2 }' | sed 's/\r//g' | awk 'BEGIN{ORS=","} {print}' | sed 's/\"/''/g' | sed 's/,$//')
|
||||
IFS="," read -r -a ssids <<<"$wpassid"
|
||||
|
||||
#Note:If you only want to check for certain SSIDs
|
||||
#Remove the # in in front of ssids=('mySSID1'.... below and put a # infront of all four lines above
|
||||
# separated by a space, eg ('mySSID1' 'mySSID2')
|
||||
#ssids=('mySSID1' 'mySSID2' 'mySSID3')
|
||||
|
||||
#Enter the Routers Mac Addresses for hidden SSIDs, seperated by spaces ie
|
||||
#( '11:22:33:44:55:66' 'aa:bb:cc:dd:ee:ff' )
|
||||
mac=()
|
||||
|
||||
ssidsmac=("${ssids[@]}" "${mac[@]}") #combines ssid and MAC for checking
|
||||
|
||||
createAdHocNetwork() {
|
||||
echo "Creating Hotspot"
|
||||
ip link set dev "$wifidev" down
|
||||
ip a add 192.168.4.1/24 brd + dev "$wifidev"
|
||||
ip link set dev "$wifidev" up
|
||||
dhcpcd -k "$wifidev" >/dev/null 2>&1
|
||||
systemctl start dnsmasq
|
||||
systemctl start hostapd
|
||||
}
|
||||
|
||||
KillHotspot() {
|
||||
echo "Shutting Down Hotspot"
|
||||
ip link set dev "$wifidev" down
|
||||
systemctl stop hostapd
|
||||
systemctl stop dnsmasq
|
||||
ip addr flush dev "$wifidev"
|
||||
ip link set dev "$wifidev" up
|
||||
dhcpcd -n "$wifidev" >/dev/null 2>&1
|
||||
}
|
||||
|
||||
ChkWifiUp() {
|
||||
echo "Checking WiFi connection ok"
|
||||
sleep 20 #give time for connection to be completed to router
|
||||
if ! wpa_cli -i "$wifidev" status | grep 'ip_address' >/dev/null 2>&1; then #Failed to connect to wifi (check your wifi settings, password etc)
|
||||
echo 'Wifi failed to connect, falling back to Hotspot.'
|
||||
wpa_cli terminate "$wifidev" >/dev/null 2>&1
|
||||
createAdHocNetwork
|
||||
fi
|
||||
}
|
||||
|
||||
chksys() {
|
||||
#After some system updates hostapd gets masked using Raspbian Buster, and above. This checks and fixes
|
||||
#the issue and also checks dnsmasq is ok so the hotspot can be generated.
|
||||
#Check Hostapd is unmasked and disabled
|
||||
if systemctl -all list-unit-files hostapd.service | grep "hostapd.service masked" >/dev/null 2>&1; then
|
||||
systemctl unmask hostapd.service >/dev/null 2>&1
|
||||
fi
|
||||
if systemctl -all list-unit-files hostapd.service | grep "hostapd.service enabled" >/dev/null 2>&1; then
|
||||
systemctl disable hostapd.service >/dev/null 2>&1
|
||||
systemctl stop hostapd >/dev/null 2>&1
|
||||
fi
|
||||
#Check dnsmasq is disabled
|
||||
if systemctl -all list-unit-files dnsmasq.service | grep "dnsmasq.service masked" >/dev/null 2>&1; then
|
||||
systemctl unmask dnsmasq >/dev/null 2>&1
|
||||
fi
|
||||
if systemctl -all list-unit-files dnsmasq.service | grep "dnsmasq.service enabled" >/dev/null 2>&1; then
|
||||
systemctl disable dnsmasq >/dev/null 2>&1
|
||||
systemctl stop dnsmasq >/dev/null 2>&1
|
||||
fi
|
||||
}
|
||||
|
||||
FindSSID() {
|
||||
#Check to see what SSID's and MAC addresses are in range
|
||||
ssidChk='NoSSid'
|
||||
i=0
|
||||
j=0
|
||||
until [ $i -eq 1 ]; do #wait for wifi if busy, usb wifi is slower.
|
||||
ssidreply=$( (iw dev "$wifidev" scan ap-force | grep -E "^BSS|SSID:") 2>&1) >/dev/null 2>&1
|
||||
#echo "SSid's in range: " $ssidreply
|
||||
printf '%s\n' "${ssidreply[@]}"
|
||||
echo "Device Available Check try " $j
|
||||
if ((j >= 5)); then #if busy 5 times goto hotspot
|
||||
echo "Device busy or unavailable 5 times, going to Hotspot"
|
||||
ssidreply=""
|
||||
i=1
|
||||
elif echo "$ssidreply" | grep "No such device (-19)" >/dev/null 2>&1; then
|
||||
echo "No Device Reported, try " $j
|
||||
NoDevice
|
||||
elif echo "$ssidreply" | grep "Network is down (-100)" >/dev/null 2>&1; then
|
||||
echo "Network Not available, trying again" $j
|
||||
j=$((j + 1))
|
||||
sleep 2
|
||||
elif echo "$ssidreply" | grep "Read-only file system (-30)" >/dev/null 2>&1; then
|
||||
echo "Temporary Read only file system, trying again"
|
||||
j=$((j + 1))
|
||||
sleep 2
|
||||
elif echo "$ssidreply" | grep "Invalid exchange (-52)" >/dev/null 2>&1; then
|
||||
echo "Temporary unavailable, trying again"
|
||||
j=$((j + 1))
|
||||
sleep 2
|
||||
elif echo "$ssidreply" | grep -v "resource busy (-16)" >/dev/null 2>&1; then
|
||||
echo "Device Available, checking SSid Results"
|
||||
i=1
|
||||
else #see if device not busy in 2 seconds
|
||||
echo "Device unavailable checking again, try " $j
|
||||
j=$((j + 1))
|
||||
sleep 2
|
||||
fi
|
||||
done
|
||||
|
||||
for ssid in "${ssidsmac[@]}"; do
|
||||
if (echo "$ssidreply" | grep -F -- "$ssid") >/dev/null 2>&1; then
|
||||
#Valid SSid found, passing to script
|
||||
echo "Valid SSID Detected, assesing Wifi status"
|
||||
ssidChk=$ssid
|
||||
return 0
|
||||
else
|
||||
#No Network found, NoSSid issued"
|
||||
echo "No SSid found, assessing WiFi status"
|
||||
ssidChk='NoSSid'
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
NoDevice() {
|
||||
#if no wifi device,ie usb wifi removed, activate wifi so when it is
|
||||
#reconnected wifi to a router will be available
|
||||
echo "No wifi device connected"
|
||||
wpa_supplicant -B -i "$wifidev" -c /etc/wpa_supplicant/wpa_supplicant.conf >/dev/null 2>&1
|
||||
exit 1
|
||||
}
|
||||
|
||||
chksys
|
||||
FindSSID
|
||||
|
||||
#Create Hotspot or connect to valid wifi networks
|
||||
if [ "$ssidChk" != "NoSSid" ]; then
|
||||
if systemctl status hostapd | grep "(running)" >/dev/null 2>&1; then #hotspot running and ssid in range
|
||||
KillHotspot
|
||||
echo "Hotspot Deactivated, Bringing Wifi Up"
|
||||
wpa_supplicant -B -i "$wifidev" -c /etc/wpa_supplicant/wpa_supplicant.conf >/dev/null 2>&1
|
||||
ChkWifiUp
|
||||
elif { wpa_cli -i "$wifidev" status | grep 'ip_address'; } >/dev/null 2>&1; then #Already connected
|
||||
echo "Wifi already connected to a network"
|
||||
else #ssid exists and no hotspot running connect to wifi network
|
||||
echo "Connecting to the WiFi Network"
|
||||
wpa_supplicant -B -i "$wifidev" -c /etc/wpa_supplicant/wpa_supplicant.conf >/dev/null 2>&1
|
||||
ChkWifiUp
|
||||
fi
|
||||
else #ssid or MAC address not in range
|
||||
if systemctl status hostapd | grep "(running)" >/dev/null 2>&1; then
|
||||
echo "Hostspot already active"
|
||||
elif { wpa_cli status | grep "$wifidev"; } >/dev/null 2>&1; then
|
||||
echo "Cleaning wifi files and Activating Hotspot"
|
||||
wpa_cli terminate >/dev/null 2>&1
|
||||
ip addr flush "$wifidev"
|
||||
ip link set dev "$wifidev" down
|
||||
# ip addr flush "$ethdev"
|
||||
# ip link set dev "$ethdev" down
|
||||
rm -r /var/run/wpa_supplicant >/dev/null 2>&1
|
||||
createAdHocNetwork
|
||||
else #"No SSID, activating Hotspot"
|
||||
createAdHocNetwork
|
||||
fi
|
||||
fi
|
||||
|
||||
```
|
||||
|
||||
Save and exit.
|
||||
|
||||
Make this script executable with `sudo chmod +x /usr/bin/autohotspotN`.
|
||||
|
||||
You can now reboot your machine. If it doesn't find the a setup wifi network, it will generate its own.
|
||||
|
|
@ -1,167 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# User interface guide
|
||||
|
||||
Starting with the release of v2.2, a new user interface brings a whole new user interface. This guide will help you get familiar with it.
|
||||
|
||||
|
||||
|
||||
## Home
|
||||
|
||||
As you can see above, when you first connect with your planktoscope at [http://planktoscope.local:1880/ui](http://planktoscope.local:1880/ui), you will reach this page.
|
||||
|
||||
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):
|
||||
|
||||
* Wifi
|
||||
* Administration
|
||||
* Hardware Config
|
||||
|
||||
|
||||
|
||||
!!! tip
|
||||
This list is also available from any other tab and allows you to quickly navigate between tabs.
|
||||
|
||||
## Machine shutdown
|
||||
|
||||
From this page, you can also shutdown the machine when you are done.
|
||||
|
||||
!!! warning
|
||||
It's **very very very important** to **always** shutdown the machine and wait a minute for it to completely shutdown before unplugging the power supply!
|
||||
**You risk data corruption is you savagely shutdown your machine!**
|
||||
|
||||
To shutdown the machine, first unlock the shutdown button by clicking on "Unlock Button".
|
||||
|
||||
|
||||
|
||||
You can then click on "Shutdown". The machine will ask for a final confirmation and will then shut itself down.
|
||||
|
||||
|
||||
|
||||
## Sample Tab
|
||||
|
||||
|
||||
|
||||
In this page, you can enter all the information regarding the current sample you want to image. This includes the project name, the operator, but also the type of collection device you used.
|
||||
|
||||
|
||||
|
||||
Depending on the device you choose, the page will change to reflect the needed information.
|
||||
|
||||
There is a mechanism of validation of the submitted data. Please be careful to use the format given in example for each input field.
|
||||
|
||||
|
||||
|
||||
The GPS status block will give you the current information on the GPS fix and location, your direction and speed. This can be used to grab the location when in the field.
|
||||
|
||||
|
||||
|
||||
Once all the fields are completed, you can go to the next tab by clicking the -> arrow. This will make sure all the inserted data is valid.
|
||||
|
||||
## Optic Configuration
|
||||
|
||||
This page allows you to control the optical setup of the acquisition.
|
||||
|
||||
|
||||
|
||||
In the Optic Characterization block, you can control to turn the light on or not. You also have to choose the optics in use in the machine.
|
||||
|
||||
!!! warning
|
||||
For now, the characteristics shown here are not true values (except if you use the 25mm/16mm lens couple).
|
||||
|
||||
The Camera Settings block allows you to change the shutter speed, the ISO number and the camera white balance settings. You can set it to automatic, but it's better if you control it by hand to make sure the setting doesn't change when the acquisition is started.
|
||||
|
||||
The Fluidic Manual Manipulation allows you to control the pump. You can change both the flowrate and the volume pumped. If you click on the rotating arrow, it will start the pump for the given volume at the chosen flowrate.
|
||||
|
||||
The Focus Adjustment block allows you to control the focus stage. With the leftmost buttons, you can choose to move the stage quickly by one mm, either up or down. The rightmost buttons move the stage by the specified distance in the slider under.
|
||||
|
||||
As with all the tabs, once you are satisfied with your focus and your image settings, you can click on "Continue".
|
||||
|
||||
## Fluidic Acquisition
|
||||
|
||||
Finally, this is where the magic happens! You will be able to chose the final parameters of your capture.
|
||||
|
||||
|
||||
|
||||
First of all, change the Fraction Size of your sample. You can then choose a unique ID for your acquisition, the number of pictures you want to take, the pumped volume (in between images), the delay to stabilize the image and the Flowcell thickness. All those settings will influence the Total imaged volume (the total volume captured during the acquisition) and the Total pumped volume.
|
||||
|
||||
!!! warning
|
||||
Make sure the Total pumped volume is lower than the volume of your sample.
|
||||
|
||||
## Gallery
|
||||
|
||||
|
||||
|
||||
This simple page will allow you to navigate the local directory of the machine and visualize the captured data.
|
||||
|
||||
## System Monitoring
|
||||
|
||||
This tab allows you to monitor the physical characteristics of the machine and follow the processor load, CPU temperature, memory use and disk usage.
|
||||
|
||||
|
||||
|
||||
You also can find information about the software version you are using, the machine name and its camera.
|
||||
|
||||
### USB Backup of the data
|
||||
|
||||
Using the USB Backup block, you can backup the data from the machine to a connected USB device.
|
||||
|
||||
!!! info
|
||||
Use one of the center USB ports on the machine, since those are USB3.0. They can be recognized by the blue insert in the middle of the connector. Those ports are faster.
|
||||
|
||||
After you connected your drive, click on "Detect Drive" to make it appear in the list. You can then choose "Backup to USB" to launch the copy. Wait until a completion message is displayed.
|
||||
|
||||
Before purging the local data, make sure your data has been backed up at least twice!
|
||||
|
||||
!!! warning
|
||||
It's very warmly recommended to use the 3-2-1 backup strategy. 3 copies on 2 devices with at least 1 offsite.
|
||||
For this machine, this means creating two copies on two different USB drives of the data before purging it from the device.
|
||||
Also, you should backup your device after each acquisition.
|
||||
|
||||
## Wifi
|
||||
|
||||
|
||||
|
||||
This page will give you information about the network the PlanktoScope is connected to. It will also allows you to connect your machine to a new WiFi network.
|
||||
|
||||
Start by doing a network scan by clicking on the `Scan` button. The list will be populated with detected networks after a few seconds. You can then choose one of them, enter its password and click on `Add the network` to connect to it. The wifi network of the PlanktoScope will disappear after a few seconds, so **you will need to connect back to the same network you just put the machine on**.
|
||||
|
||||
Finally, if you are not located in France, please update the Country code in the field below. This will ensure the PlanktoScope complies with local Wifi regulations (such as maximum emitted power, duty cycle and such).
|
||||
|
||||
Clicking on the button `Reset wifi networks` will erase ALL networks saved previously by the machine. If you do this, it will disconnect immediately from any network it's connected to, and will put up its own network.
|
||||
|
||||
!!! info
|
||||
For now, only WPA/WPA2 Personnal security system is supported. If you need another security system supported, get in touch with us.
|
||||
|
||||
!!! warning
|
||||
Please be mindful about the security policies of your organisation before connecting your device to a network (either through Wifi or with an Ethernet cable). A lot of research institutions don't allow devices not controlled by them to be connected to their network without first going on an approved list with a least a basic security checkup.
|
||||
|
||||
## Administration
|
||||
|
||||
|
||||
|
||||
On this page you can find the logs generated by the python script and also the [Danger Zone](https://www.youtube.com/watch?v=siwpn14IE7E).
|
||||
|
||||
You should only touch here if you know what you are doing. The update process can be started from here. Also you can restart the python script if something becomes unresponsive (like the pump or the focus stage). You can also restart the machine or shut it down from this page.
|
||||
|
||||
### Update process
|
||||
|
||||
After clicking on the button to launch the update, the script will first check that there is an available update.
|
||||
|
||||
|
||||
|
||||
The script will then kill node-red, update its code and restart it.
|
||||
|
||||
|
||||
The python script will also restart the python script.
|
||||
|
||||
|
||||
Once the message displayed top right show "The segmenter is ready", you're good to go on the latest version!
|
||||
|
||||
|
||||
## Hardware Configuration
|
||||
|
||||
|
||||
|
||||
You can change the hardware settings of your machine here. If you use a Waveshare hat for the steppers, instead of the adafruit one, if you want to invert the stepper output (switch the stepper 1 with the stepper 2 for example) and the Steps per ml settings of the pump.
|
||||
|
|
@ -1,118 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Contributing
|
||||
|
||||
First of all, thank you for contributing to the PlanktoScope! The goal of this document is to provide everything you need to know in order to contribute to PlanktoScope.
|
||||
|
||||
There are several ways to join the development effort, share your progress with your build or just ask for help.
|
||||
|
||||
We are using slack as a communication platform between interested parties. You can [request to join by filling this form](https://docs.google.com/forms/d/e/1FAIpQLSfcod-avpzWVmWj42_hW1v2mMSHm0DAGXHxVECFig2dnKHxGQ/viewform).
|
||||
|
||||
This repository is also a good way to get involved. Please fill in an issue if you witnessed a bug in the software or hardware. If you are able, you can also join the development effort. Look through the [issues opened](https://github.com/PlanktonPlanet/PlanktoScope/labels/good%20first%20issue) and choose one that piques your interest. Let us know you want to work on it in the comments, we may even be able to guide your beginnings around the code.
|
||||
|
||||
- [Contributing](#contributing)
|
||||
- [Assumptions](#assumptions)
|
||||
- [How to Contribute](#how-to-contribute)
|
||||
- [Development Workflow](#development-workflow)
|
||||
- [Git Guidelines](#git-guidelines)
|
||||
- [Release Process (for internal team only)](#release-process-for-internal-team-only)
|
||||
|
||||
## Assumptions
|
||||
|
||||
1. **You're familiar with [git](https://git-scm.com/) and the [Merge Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)(PR) workflow.**
|
||||
2. **You've read the PlanktoScope [documentation](https://planktonscope.readthedocs.io/) and the [images/readme](/images/readme.md).**
|
||||
3. **You know about the PlanktoScope [community on Slack](https://planktoscope.slack.com/). Please use this for help.**
|
||||
|
||||
## How to Contribute
|
||||
|
||||
1. Make sure that the contribution you want to make is explained or detailed in a GitHub issue! Find an [existing issue](https://github.com/PlanktoScope/PlanktoScope/issues) or [open a new one](https://github.com/PlanktoScope/PlanktoScope/issues/new/choose).
|
||||
2. Once done, [fork the PlanktoScope repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) in your Github account. Ask a mastertainer if you want your issue to be checked before making a PR.
|
||||
3. [Create a new Git branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository).
|
||||
4. Review the [Development Workflow](#development-workflow) section that describes the steps to mastertain the repository.
|
||||
5. Make the changes on your branch.
|
||||
6. [Submit the branch as a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) pointing to the `master` branch of the master fabcity-os-core-chart repository. A mastertainer should comment and/or review your Pull Request within a few days. Although depending on the circumstances, it may take longer. We do not enforce a naming convention for the PRs, but **please use something descriptive of your changes**, having in mind that the title of your PR will be automatically added to the next [release changelog](https://github.com/PlanktoScope/PlanktoScope/releases).
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Setup <!-- omit in toc -->
|
||||
|
||||
In order to use the different tools on this repository, you will first need to:
|
||||
|
||||
```sh
|
||||
```
|
||||
|
||||
### Tests and Linter <!-- omit in toc -->
|
||||
|
||||
Each PR should pass the linter to be accepted.
|
||||
|
||||
```sh
|
||||
make lint
|
||||
```
|
||||
|
||||
Each PR should also check if the generated file `manifests/fcoscore.yaml` is updated with the new modifications.
|
||||
You can generated the manifest with the command line:
|
||||
|
||||
```bash
|
||||
helm template fcoscore . | grep -v 'helm.sh/chart:\|app.kubernetes.io/managed-by:' > manifests/PlanktoScope.yaml
|
||||
```
|
||||
|
||||
Or just by comment the PR:
|
||||
|
||||
```txt
|
||||
@PlanktoScope sync-manifest
|
||||
```
|
||||
|
||||
Additionally, the CI will run a test to check if there are changes introduced to the charts. If changes were introduced, it will require you to update the Chart version.
|
||||
|
||||
## Git Guidelines
|
||||
|
||||
### Git Branches <!-- omit in toc -->
|
||||
|
||||
All changes must be made in a branch and submitted as PR.
|
||||
We do not enforce any branch naming style, but please use something descriptive of your changes.
|
||||
|
||||
### Git Commits <!-- omit in toc -->
|
||||
|
||||
As minimal requirements, your commit message should:
|
||||
|
||||
- be capitalized
|
||||
- not finish by a dot or any other punctuation character (!,?)
|
||||
- start with a verb so that we can read your commit message this way: "This commit will ...", where "..." is the commit message.
|
||||
e.g.: "Fix the home page button" or "Add more tests for create_index method"
|
||||
|
||||
We don't follow any other convention, but if you want to use one, we recommend [this one](https://chris.beams.io/posts/git-commit/).
|
||||
|
||||
### Pull Requests <!-- omit in toc -->
|
||||
|
||||
Some notes on PRs:
|
||||
|
||||
- [Convert your PR as a draft]() if your changes are a work in progress: no one will review it until you pass your PR as ready for review.<br>
|
||||
The draft PR can be very useful if you want to show that you are working on something and make your work visible.
|
||||
- The branch related to the PR must be **up-to-date with `master`** before merging. Fortunately, this project [integrates a bot]() to automatically enforce this requirement without the PR author having to do it manually.
|
||||
- All PRs must be reviewed and approved by at least one mastertainer.
|
||||
- The PR title should be accurate and descriptive of the changes. The title of the PR will be indeed automatically added to the next [release changelogs]().
|
||||
|
||||
## Release Process (for internal team only)
|
||||
|
||||
PlanktoScope tools follow the [Semantic Versioning Convention](https://semver.org/).
|
||||
|
||||
### Automation to Rebase and Merge the PRs <!-- omit in toc -->
|
||||
|
||||
This project integrates a bot that helps us manage pull requests merging.<br>
|
||||
_[Read more about this]()._
|
||||
|
||||
### How to Publish the Release <!-- omit in toc -->
|
||||
|
||||
⚠️ Before doing anything, make sure you got through the guide about [Releasing an Integration]().
|
||||
|
||||
⚠️ Every PR that is merged to `master` introducing changes to the PlanktoScope needs to modify the file [``](), by increasing the version of the chart accordingly.
|
||||
|
||||
Every PR that is merged to `master` triggers the automated release process, as specified at [``](). A GitHub Action will be triggered and publish a new release on the GitHub repository [releases](). This will enable users to start using the new version of the chart immediately after publishing.
|
||||
|
||||
Thank you again for reading this through, we can not wait to begin to work with you if you made your way through this contributing guide ❤️
|
||||
|
||||
- pdfimages -all protocols/PlanktoScope\ -\ Setup\ and\ Sampling\ Guide\ VER3.pdf protocols/dumps/PlanktoScope_Setup_and_Sampling_Guide_VER3
|
||||
sudo apt-get install pandoc texlive-latex-base texlive-fonts-recommended texlive-extra-utils texlive-latex-extra
|
||||
sudo apt install poppler-utils
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Our software architecture
|
||||
|
||||
## Node-Red
|
||||
|
||||
Node-Red is our main process. We use the flow to manage our user interface through a dashboard instance.
|
||||
|
||||
## Python
|
||||
|
||||
The python code is separated in four main processes, each with a specific set of responsibilities:
|
||||
|
||||
- The main process controls all the others, starts everything up and cleans up on shutdown
|
||||
- The stepper process manages the stepper movements.
|
||||
- The imager process controls the camera and the streaming server via a state machine.
|
||||
- The segmenter process manages the segmentation and its outputs.
|
||||
|
||||
Those processes all communicates together using MQTT and json messages. Each message is adressed to one topic. The high level topic controls which process receives the message. The details of each topic is at the end of this commit message. You can learn more about the [MQTT Messages here](mqtt_messages).
|
||||
|
||||
The code is architectured around 6 modules and about 10 classes. I encourage you to have a look at the files, they're pretty straightforward to understand.
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# How to help development for the PlanktoScope code
|
||||
|
||||
We are using the [Github Flow approach](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests) for our development efforts.
|
||||
|
||||
If you want to join us, have a look at the [currently opened issues](https://github.com/PlanktonPlanet/PlanktoScope/issues) and pick one where you feel like you can have an impact. Let us know you want to work it in the comments and get started.
|
||||
|
||||
For working on Node-Red, we recommend to install it directly on your development machine to allow for faster cycles of testing (and ease of use). But feel free to setup a Pi Zero as a portable and compact development environment! (One of us is using one configured as usb gadget to do so!)
|
||||
|
||||
If you don't know how to code, [the documentation could use your help](edit_this_doc)!
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Edit this documentation
|
||||
|
||||
This documentation is hosted by [ReadTheDocs.org](https://readthedocs.org/) at <https://planktonscope.readthedocs.io/>.
|
||||
|
||||
The source files are in the main [github repository](https://www.github.com/PlanktonPlanet/PlanktoScope), in the `docs` folder.
|
||||
|
||||
They are simple [Markdown files](https://www.markdownguide.org/), that you can edit in any text editor of your choice.
|
||||
|
||||
The local development and test is made using [mkdocs](https://www.mkdocs.org/). This allows you to test your documentation changes for styling issues and see what it will look like once rendered.
|
||||
|
||||
After installing mkdocs, you can use `mkdocs serve` in the main folder of this repository to start the development server.
|
||||
|
||||
If you want to include pictures and diagrams in the documentation, please set the pictures in a dedicated folder to the name of the page you are creating (for example, if your page is named `expert_setup.md`, please put all the related pictures in the `docs/expert_setup/` folder). Each picture should be named with a simple yet descriptive name, using jpg or png format if possible. Try to limit the size of the file by limiting the resolution to what is necessary for the picture to be clear on screen.
|
||||
|
||||
Contributions should be made by creating pull requests on [Github directly](https://github.com/PlanktonPlanet/PlanktoScope/pulls).
|
||||
|
||||
## Extensions available
|
||||
|
||||
In addition to the common markdown syntax, several extensions are activated. If you want more information on any of them, please follow the linked guides.
|
||||
|
||||
- [SmartyPants](https://python-markdown.github.io/extensions/smarty/): Converts ASCII dashes, quotes and ellipses to their HTML entity equivalents.
|
||||
- [Sane Lists](https://python-markdown.github.io/extensions/sane_lists/): Alters the behavior of the Markdown List syntax to be less surprising.
|
||||
- [Admonition](https://python-markdown.github.io/extensions/admonition/): Adds rST-style admonitions to Markdown documents.
|
||||
- [Table of contents](https://python-markdown.github.io/extensions/toc/): Generates a Table of Contents from a Markdown document and adds it into the resulting HTML document.
|
||||
- [Metadata](https://python-markdown.github.io/extensions/meta_data/): Adds a syntax for defining meta-data about a document.
|
||||
- [Tables](https://python-markdown.github.io/extensions/tables/): Adds the ability to create tables in Markdown documents.
|
||||
- [Fenced Code Blocks](https://python-markdown.github.io/extensions/fenced_code_blocks/): Adds a secondary way to define code blocks.
|
||||
|
|
@ -1 +0,0 @@
|
|||
# Getting in touch with the community
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# Trainer notes
|
||||
|
||||
## Organizing a Build Workshop
|
||||
18
flake.lock
18
flake.lock
|
|
@ -18,11 +18,11 @@
|
|||
},
|
||||
"flake-utils": {
|
||||
"locked": {
|
||||
"lastModified": 1659877975,
|
||||
"narHash": "sha256-zllb8aq3YO3h8B/U0/J1WBgAL8EX5yWf5pMj3G0NAmc=",
|
||||
"lastModified": 1667395993,
|
||||
"narHash": "sha256-nuEHfE/LcWyuSWnS8t12N1wc105Qtau+/OdUAjtQ0rA=",
|
||||
"owner": "numtide",
|
||||
"repo": "flake-utils",
|
||||
"rev": "c0e246b9b83f637f4681389ecabcb2681b4f3af0",
|
||||
"rev": "5aed5285a952e0b949eb3ba02c12fa4fcfef535f",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
|
|
@ -33,11 +33,11 @@
|
|||
},
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1664281702,
|
||||
"narHash": "sha256-haixZ4TJLu1Dciow54wrHrHvlGDVr5sW6MTeAV/ZLuI=",
|
||||
"lastModified": 1667991831,
|
||||
"narHash": "sha256-DHgEsLZI044B9T4AjA3K6+yB9/DqLr4dyA7OIx0FG7o=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "7e52b35fe98481a279d89f9c145f8076d049d2b9",
|
||||
"rev": "872fceeed60ae6b7766cc0a4cd5bf5901b9098ec",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
|
|
@ -57,11 +57,11 @@
|
|||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1663082609,
|
||||
"narHash": "sha256-lmCCIu4dj59qbzkGKHQtolhpIEQMeAd2XUbXVPqgPYo=",
|
||||
"lastModified": 1667992213,
|
||||
"narHash": "sha256-8Ens8ozllvlaFMCZBxg6S7oUyynYx2v7yleC5M0jJsE=",
|
||||
"owner": "cachix",
|
||||
"repo": "pre-commit-hooks.nix",
|
||||
"rev": "60cad1a326df17a8c6cf2bb23436609fdd83024e",
|
||||
"rev": "ebcbfe09d2bd6d15f68de3a0ebb1e4dcb5cd324b",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
|
|
|
|||
|
|
@ -1,7 +1,4 @@
|
|||
# SPDX-License-Identifier: GPL-3.0-or-later
|
||||
|
||||
# coding: utf-8
|
||||
# file generated by setuptools_scm
|
||||
# don't change, don't track in version control
|
||||
__version__ = version = '0.1.dev654+g9630e46.d19800101'
|
||||
__version_tuple__ = version_tuple = (0, 1, 'dev654', 'g9630e46.d19800101')
|
||||
__version__ = version = '0.1.dev656+g56869d2.d19800101'
|
||||
__version_tuple__ = version_tuple = (0, 1, 'dev656', 'g56869d2.d19800101')
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"name": "planktoscope",
|
||||
"description": "PlanktoScope main software project",
|
||||
"description": "The PlanktoScope Frontend based on Node-Red",
|
||||
"version": "2.3",
|
||||
"dependencies": {
|
||||
"node-red-contrib-dir2files": "^0.3.0",
|
||||
|
|
|
|||
Loading…
Reference in a new issue