docs: small various updates

docs/edit_this_doc.md

@@ -8,6 +8,8 @@ They are simple [Markdown files](https://www.markdownguide.org/), that you can e
 
 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/PlanktonScope/pulls).

docs/remote_access.md

@@ -2,21 +2,89 @@
 
 ## 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](https://www.raspberrypi.org/documentation/configuration/wireless/access-point.md#internet-sharing).
+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).
 
 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
+sudo apt install dnsmasq hostapd
 ```
 
 Since the configuration files are not ready yet, turn the new software off as follows::
 ```
-        sudo systemctl stop dnsmasq
+sudo systemctl unmask hostapd
-        sudo systemctl stop 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`
+
+```
+#2.4GHz setup wifi 80211 b,g,n
+interface=wlan0
+driver=nl80211
+ssid=RPiHotspotN
+hw_mode=g
+channel=8
+wmm_enabled=0
+macaddr_acl=0
+auth_algs=1
+ignore_broadcast_ssid=0
+wpa=2
+wpa_passphrase=1234567890
+wpa_key_mgmt=WPA-PSK
+wpa_pairwise=CCMP TKIP
+rsn_pairwise=CCMP
+
+#80211n - Change GB to your WiFi country code
+country_code=GB
+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 nano press `ctrl + X`.
+
+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:
+```
+#AutoHotspot config
+interface=wlan0
+bind-dynamic 
+server=8.8.8.8
+domain-needed
+bogus-priv
+dhcp-range=192.168.50.150,192.168.50.200,12h
+```
+
+and then save `ctrl + O` and exit `ctrl + X`.
+
+
 ### 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.

docs/update_device-tree.md

@@ -0,0 +1,118 @@
+# 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:
+```
+$ 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:
+```
+    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:
+
+```
+    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:
+```
+$ 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`:
+```
+$ 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:
+```
+$ 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:
+```
+    pin_define@CAMERA_0_LED {
+        type = "internal";
+        number = <5>;
+    };
+    pin_define@FLASH_0_ENABLE {
+        type = "absent";
+    };
+```
+
+into this:
+
+```
+    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.