curious.bio/planktoscope
curious.bio/planktoscope
9
0
Fork 0
Code Issues 10 Pull requests Packages Projects 7 Releases Wiki Activity

basic doc structure in place

Browse source
This commit is contained in:
Romain Bazile 2020-09-28 13:33:52 +02:00
parent 67f7a24207
commit 73edb84226
12 changed files with 105 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
docs/README.md
View file

@ -1 +1,21 @@
Welcome to the PlanktoScope build and use documentation
# Welcome to the PlanktoScope build and use documentation
![PlanktoScope](readme/planktoscope_cad.png)
You can find here more information about how to build your own PlanktoScope.
## Setup
- [How to setup your PlanktoScope the easy way](easy_install)
- [How to setup your PlanktoScope the hard way (also known as the Expert's path)](expert_setup)
## Usage
- [Information about collection devices](collection_devices)
## Contribute
- [Find out how to contribute to this documentation and help edit it](edit_this_doc)
- [Contribute to the code, here is the getting started](edit_the_code)
## Under the hood:
- [Software architecte](software_architecture)
- [MQTT Messages](mqtt_messages)

5
docs/collection_devices.md Normal file
View file

@ -0,0 +1,5 @@
# 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
docs/collections_devices.md
View file

@ -1 +0,0 @@
We need to add information here about collection devices.

0
docs/install.md → docs/easy_install.md
View file

1
docs/edit_the_code.md Normal file
View file

@ -0,0 +1 @@
# How to help development for the PlanktoScope code

2
docs/edit_this_doc.md
View file

@ -1,3 +1,5 @@
# 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/PlanktonScope), in the `docs` folder.

2
docs/license.md
View file

@ -1 +1 @@
This work is released under a [LET'S CHOOSE A LICENSE].
# This work is released under a [LET'S CHOOSE A LICENSE].

1
docs/mqtt_messages.md Normal file
View file

@ -0,0 +1 @@
# Details about used MQTT messages

BIN
docs/readme/planktoscope_cad.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 535 KiB

130
docs/remote_access.md
View file

@ -1,93 +1,90 @@
======================================
Remote access via a standalone network
======================================
# Remote access via a standalone network
Setting up a Raspberry Pi as an access point in a standalone network (NAT)
==========================================================================
## Setting up a Raspberry Pi as an access point in a standalone network (NAT)
This tutorial is adapted from an official Raspberry Pi tutorial that you can find `here`_.
.. _here: https://www.raspberrypi.org/documentation/configuration/wireless/access-point.md#internet-sharing
This tutorial is adapted from an official Raspberry Pi tutorial that you can find [here](https://www.raspberrypi.org/documentation/configuration/wireless/access-point.md#internet-sharing).
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::
```
sudo apt install dnsmasq hostapd
Since the configuration files are not ready yet, turn the new software off as follows::
```
Since the configuration files are not ready yet, turn the new software off as follows::
```
sudo systemctl stop dnsmasq
sudo systemctl stop hostapd
```
Configuring a static IP
=======================
### Configuring a static IP
We are configuring a standalone network to act as a server, so the Raspberry Pi needs to have a static IP address assigned to the wireless port. This documentation assumes that we are using the standard 192.168.x.x IP addresses for our wireless network, so we will assign the server the IP address 192.168.4.1. It is also assumed that the wireless device being used is wlan0.
To configure the static IP address, edit the dhcpcd configuration file with::
```
sudo touch /etc/dhcpcd.conf
chmod 777 /etc/dhcpcd.conf
```
Send the desired IP address to the end of the previous generated .conf::
```
echo "interface wlan0" >> /etc/dhcpcd.conf
echo " static ip_address=192.168.4.1/24" >> /etc/dhcpcd.conf
echo " nohook wpa_supplicant" >> /etc/dhcpcd.conf
```
Now restart the dhcpcd daemon and set up the new wlan0 configuration::
```
sudo service dhcpcd restart
```
Configuring the DHCP server (dnsmasq)
=====================================
### Configuring the DHCP server (dnsmasq)
The DHCP service is provided by dnsmasq. By default, the configuration file contains a lot of information that is not needed, and it is easier to start from scratch. Rename this configuration file, and edit a new one::
```
sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.orig
sudo touch /etc/dnsmasq.conf
sudo chmod 777 /etc/dnsmasq.conf
```
Type or copy the following information into the dnsmasq configuration file and save it::
```
sudo echo "interface=wlan0" >> /etc/dnsmasq.conf
sudo echo " dhcp-range=192.168.4.2,192.168.4.20,255.255.255.0,24h" >> /etc/dnsmasq.conf
```
So for wlan0, we are going to provide IP addresses between 192.168.4.2 and 192.168.4.20, with a lease time of 24 hours. If you are providing DHCP services for other network devices (e.g. eth0), you could add more sections with the appropriate interface header, with the range of addresses you intend to provide to that interface.
There are many more options for dnsmasq; see the dnsmasq `documentation`_ for more details.
.. _documentation: http://www.thekelleys.org.uk/dnsmasq/doc.html
There are many more options for dnsmasq; see the dnsmasq [documentation](http://www.thekelleys.org.uk/dnsmasq/doc.html) for more details.
Reload dnsmasq to use the updated configuration::
```
sudo systemctl reload dnsmasq
```
Configuring the access point host software (hostapd)
====================================================
### Configuring the access point host software (hostapd)
You need to edit the hostapd configuration file, located at /etc/hostapd/hostapd.conf, to add the various parameters for your wireless network. After initial install, this will be a new/empty file. ::
```
sudo touch /etc/hostapd/hostapd.conf
sudo chmod 777 /etc/hostapd/hostapd.conf
```
Add the information below to the configuration file. This configuration assumes we are using channel 7, with a network name of NameOfNetwork, and a password AardvarkBadgerHedgehog. Note that the name and password should not have quotes around them. The passphrase should be between 8 and 64 characters in length.
To use the 5 GHz band, you can change the operations mode from hw_mode=g to hw_mode=a. Possible values for hw_mode are:
* a = IEEE 802.11a (5 GHz)
* b = IEEE 802.11b (2.4 GHz)
* g = IEEE 802.11g (2.4 GHz)
* ad = IEEE 802.11ad (60 GHz) (Not available on the Raspberry Pi)
- `a` = IEEE 802.11a (5 GHz)
- `b` = IEEE 802.11b (2.4 GHz)
- `g` = IEEE 802.11g (2.4 GHz)
- `ad` = IEEE 802.11ad (60 GHz) (Not available on the Raspberry Pi)
.. warning::
Make sure you **define the wished name (ssid)** of the futur generated Wifi and its **password (wpa_passphrase)**.
WARNING: Make sure you **define the wished name (ssid)** of the futur generated Wifi and its **password (wpa_passphrase)**.
Set up your hoastapd.conf as follow ::
```
sudo echo "interface=wlan0" >> /etc/hostapd/hostapd.conf
sudo echo "driver=nl80211" >> /etc/hostapd/hostapd.conf
sudo echo "ssid=NameOfNetwork" >> /etc/hostapd/hostapd.conf
@ -102,62 +99,67 @@ Set up your hoastapd.conf as follow ::
sudo echo "wpa_key_mgmt=WPA-PSK" >> /etc/hostapd/hostapd.conf
sudo echo "wpa_pairwise=TKIP" >> /etc/hostapd/hostapd.conf
sudo echo "rsn_pairwise=CCMP" >> /etc/hostapd/hostapd.conf
```
We now need to tell the system where to find this configuration file. ::
We now need to tell the system where to find this configuration file.
```
sudo chmod 777 /etc/default/hostapd
Find the line with #DAEMON_CONF, and replace it with this ::
```
Find the line with #DAEMON_CONF, and replace it with this
```
sudo echo 'DAEMON_CONF="/etc/hostapd/hostapd.conf"' >> /etc/default/hostapd
```
Start it up
===========
Now enable and start hostapd ::
### Start it up
Now enable and start hostapd
```
sudo systemctl unmask hostapd
sudo systemctl enable hostapd
sudo systemctl start hostapd
```
Do a quick check of their status to ensure they are active and running ::
Do a quick check of their status to ensure they are active and running
```
sudo systemctl status hostapd
sudo systemctl status dnsmasq
```
Add routing and masquerade
==========================
Edit /etc/sysctl.conf and uncomment a line ::
Edit /etc/sysctl.conf and uncomment a line
```
VAR=$(sudo grep -n -m 1 net.ipv4.ip_forward=1 /etc/sysctl.conf | sudo sed 's/\([0-9]*\).*/\1/')
sudo sed -i "${VAR}s/# *//" /etc/sysctl.conf
Add a masquerade for outbound traffic on eth0 ::
```
Add a masquerade for outbound traffic on eth0
```
sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
```
Save the iptables rule ::
Save the iptables rule
```
sudo sh -c "iptables-save > /etc/iptables.ipv4.nat"
Edit /etc/rc.local and add this just above "exit 0" to install these rules on boot ::
```
Edit /etc/rc.local and add this just above "exit 0" to install these rules on boot
```
sudo chmod 777 /etc/rc.local
sudo sed -i '/exit 0/d' /etc/rc.local
sudo echo "iptables-restore < /etc/iptables.ipv4.nat" >> /etc/rc.local
sudo echo "exit 0" >> /etc/rc.local
```
Reboot and ensure it still functions.
Using a wireless device, search for networks. The network SSID you specified in the hostapd configuration should now be present, and it should be accessible with the specified password.
If SSH is enabled on the Raspberry Pi access point, it should be possible to connect to it from another Linux box (or a system with SSH connectivity present) as follows, assuming the pi account is present ::
If SSH is enabled on the Raspberry Pi access point, it should be possible to connect to it from another Linux box (or a system with SSH connectivity present) as follows, assuming the pi account is present
```
ssh pi@192.168.4.1
.. note::
Most likely your password will be **raspberry**
```
Most likely your password will be **raspberry**.
By this point, the Raspberry Pi is acting as an access point, and other devices can associate with it. Associated devices can access the Raspberry Pi access point via its IP address for operations such as rsync, scp, or ssh.

2
docs/software_architecture.md
View file

@ -1 +1 @@
# The software architecture is described here
# The software architecture will be described here eventually

10
mkdocs.yml
View file

@ -1,15 +1,19 @@
site_name: PlanktoScope
nav:
- Setup:
- Basic Install: install.md
- Basic Install: easy_install.md
- Expert Setup: expert_setup.md
- Remote Access: remote_access.md
- Usage:
- Collection devices: collection_devices.md
- Software architecture: software_architecture.md
- Under the hood:
- Software architecture: software_architecture.md
- MQTT Messages: mqtt_messages.md
- Contribute:
- Edit this doc: edit_this_doc.md
- Edit the code: edit_the_code.md
- About:
- License: license.md
- Edit this doc: edit_this_doc.md
theme:
name: readthedocs
collapse_navigation: false