Update dev docs (#605)

Fixes #603

Author: sonnyp

.editorconfig

@@ -8,6 +8,14 @@ root = true
 end_of_line = lf
 insert_final_newline = true
 
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.sh]
+indent_style = space
+indent_size = 2
+
 # Tab indentation (no size specified)
 [Makefile]
 indent_style = tab

device-backend/control/README.md

@@ -22,19 +22,27 @@ Please note that for camera we rely on the Raspberry OS packages `python3-picame
 
 ### Development
 
-To install all dependencies including development tooling, run:
+Install all dependencies including development tooling:
 
 ```sh
 poetry install --with dev
 ```
 
-Then you can run the code auto-formatter on the project by running:
+Start controller for development:
+
+```sh
+sudo systemctl stop planktoscope-org.device-backend.controller.service
+poetry run python -u planktoscopehat/main.py
+# make changes and restart
+```
+
+Run the code auto-formatter on the project:
 
 ```sh
 poetry run poe fmt
 ```
 
-And you can run all checks (including code formatting and linting) by running:
+Run all checks (including code formatting and linting):
 
 ```sh
 poetry run poe check

documentation/docs/community/contribute/tips-and-tricks.md

@@ -44,20 +44,6 @@ To setup the recommended development environment, run the following commands.
 
 Make sure to replace `$planktoscope` with your PlanktoScope hostname, eg. `pkscope-sponge-bob-123`
 
-<details>
-    <summary>On the PlanktoScope</summary>
-
-```sh
-cd ~/PlanktoScope
-# Enable Developer Mode
-./software/distro/setup/planktoscope-app-env/PlanktoScope/enable-developer-mode
-# Configure git
-git config --global user.email "you@example.com"
-git config --global user.name "Your Name"
-```
-
-</details>
-
 <details>
     <summary>On your computer</summary>
 
@@ -74,14 +60,37 @@ Host $planktoscope
   # https://docs.github.com/en/authentication/connecting-to-github-with-ssh/using-ssh-agent-forwarding
   ForwardAgent yes
   User pi
-  IdentityFile ~/.ssh/planktoscope
+  IdentityFile ~/.ssh/$planktoscope
 ```
 
 </details>
 
----
+You can now SSH into your PlanktoScope without username / password (using `ssh $planktoscope`).
+
+<details>
+    <summary>On the PlanktoScope</summary>
+
+```sh
+cd ~/PlanktoScope
+# Enable Developer Mode
+./software/distro/setup/planktoscope-app-env/PlanktoScope/enable-developer-mode
+
+# Configure git
+git config --global user.email "you@example.com"
+git config --global user.name "Your Name"
+
+# [Optional] change the remote
+
+# If you are a contributor to github.com/PlanktoScope/PlanktoScope
+git remote set-url origin git@github.com:PlanktoScope/PlanktoScope.git
+
+# If you have your own fork
+git remote set-url origin git@github.com:MYUSERNAME/PlanktoScope.git
+```
+
+</details>
 
-You can now SSH into your PlanktoScope without username / password (using `ssh $planktoscope`) and use `~/PlanktoScope` as a regular git repository.
+You can now use `~/PlanktoScope` as a regular git repository.
 
 ```sh
 ssh $planktoscope
@@ -91,30 +100,30 @@ git checkout master
 ```
 
 We recommend developping directly from the PlanktoScope using [Visual Studio Code and the Remote - SSH extension](https://code.visualstudio.com/docs/remote/ssh).
-Use `$planktoscope` as the host to connect to and open the "PlanktoScope" directory.
-
-If you make changes to the backend, you can restart the backend and test your changes with
-
-```sh
-sudo systemctl restart planktoscope-org.device-backend.controller.service
-```
+Use `$planktoscope` as the host to connect to and open the `/home/pi/PlanktoScope` directory.
 
 ## Connect to router
 
 The default behavior of the PlanktoScope is to act as a router to connect your computer to it directly via WiFi or Ethernet.
 
 If you have a LAN it may be more convenient to connect the PlanktoScope to it and act as a simple client.
 
+<details>
+    <summary>Ethernet</summary>
+
 ```sh
 nmcli connection up eth0-default
 ```
 
+</details>
+
 <details>
-    <summary>Revert changes</summary>
+    <summary>WiFi</summary>
 
 ```sh
-# Ethernet
-nmcli connection down eth0-default
+nmcli connection down wlan0-hotspot
+nmcli device wifi list
+nmcli device wifi connect "<SSID>" --ask
 ```
 
 </details>
@@ -127,7 +136,17 @@ And access the UI with http://pkscope-example-name-0000/
 
 If that doesn't work, type `nmap -sn 192.168.1.0/24` from your computer to find the PlanktoScope hostname and/or ip address.
 
-See also the operating guide [Networking](https://docs-edge.planktoscope.community/operation/networking/)
+See also the operating guide [Networking](https://docs-edge.planktoscope.community/operation/networking/).
+
+## Offline access
+
+When network is not available you have several options for debugging
+
+- Plug-in a keyboard and display (needs micro HDMI adapter)
+- [Connect a serial cable](https://www.jeffgeerling.com/blog/2021/attaching-raspberry-pis-serial-console-uart-debugging)
+- Use the [NanoKVM USB](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_USB/introduction.html)
+
+The NanoKVM USB solution works for all setups.
 
 ## Backup and Restore SD Card
 
@@ -147,6 +166,14 @@ xzcat sdcard.img.xz | sudo dd bs=1M of=/dev/device status=progress conv=fdatasyn
 
 See also the operating guide [SD Card Cloning](../../operation/clone-sd.md).
 
+## Opening a port on the firewall
+
+https://firewalld.org/documentation/howto/open-a-port-or-service.html
+
+## Working with GPIOs on the CLI
+
+https://lloydrochester.com/post/hardware/libgpiod-intro-rpi/
+
 ## Documentation quick setup
 
 This is a quick setup guide. See also

documentation/docs/troubleshooting/index.md

@@ -2,6 +2,20 @@
 
 We don't yet have complete documentation to help you troubleshoot problems with your PlanktoScope! For now, you should [sign up](https://www.planktoscope.org/join) to join the PlanktoScope community on Slack, and ask for help in the `#3-start-testing` channel on Slack; or, if you have a GitHub account, you can start a new discussion in the PlanktoScope GitHub repository's ["Help/Support" forum](https://github.com/PlanktoScope/PlanktoScope/discussions/categories/help-support). Below, we provide some guides for troubleshooting particular situations:
 
+## Hostname/DHCP issue with Orange Livebox router
+
+If you connected your PlanktoScope to a Orange Livebox, its hostname may be incorrect and change often. For example if your PlanktoScope name is `pretty-flower-123` the router may assign the hostname `pkscope-pretty-flower` instead of `pkscope-pretty-flower-123`.
+
+You can workaround this issue by:
+
+Assign the static hostname `pkscope-pretty-flower-123` to the PlanktoScope in the Livebox
+
+or
+
+[Change the PlanktoScope machine name](../operation/networking.md/#change-your-planktoscopes-name) to `pretty-flower`
+
+See also [#603](https://github.com/PlanktoScope/PlanktoScope/issues/603)
+
 ## Error with camera or Python backend
 
 A common (and very broad) category of problems results in an error message like `If you see this, there probably is an error either with your camera or with the python service. Please try restarting your machine.` being displayed instead of a camera preview in the Node-RED dashboard. This error message can be caused by a variety of potential failure modes such as a disconnected camera or a crash in the Python hardware controller program (which controls the PlanktoScope's camera as well as the pump, focusing motors, etc.). If you see this problem, we recommend first checking whether the Python hardware controller is responsive to button-presses in the Node-RED dashboard for moving the pump and/or the focusing stepper motors; if so, then there is likely a problem specifically with the camera hardware or the camera preview. Otherwise, it is very possible that the Python hardware controller has crashed for other reasons. Troubleshooting this situation will require you to download the Python hardware controller's error logs so that you can attach the logs with a request for help on the PlanktoScope Slack community.
@@ -18,4 +32,4 @@ Then click on the download button in the upper-right toolbar:
 This will open a dialogue to select the archive format for downloading the logs. You can click the ".zip" button:
 
 ![landing page](./images/download-hardware-controller-logs-4.png)
-This will open a file saving dialogue to download a ZIP archive of the Python hardware controller's logs. Then you can upload this as an attachment to a message on Slack or GitHub asking for help with troubleshooting your problem.
+This will open a file saving dialogue to download a ZIP archive of the Python hardware controller's logs. Then you can upload this as an attachment to a message on Slack or GitHub asking for help with troubleshooting your problem.

software/distro/setup/planktoscope-app-env/PlanktoScope/enable-developer-mode

@@ -6,11 +6,13 @@ commit=$(yq -r '.commit' /usr/share/planktoscope/installer-versioning.yml)
 
 cd $HOME/PlanktoScope
 git init --initial-branch=master
-git remote add origin git@github.com:PlanktoScope/PlanktoScope.git
+git remote add origin https://github.com/PlanktoScope/PlanktoScope.git
 git fetch origin --filter=blob:none
 # "Resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated."
 # https://git-scm.com/docs/git-reset#Documentation/git-reset.txt---mixed
 git reset --mixed $commit
 
 cd $HOME/PlanktoScope/device-backend/control
 poetry install --with dev
+
+cd $HOME/PlanktoScope