Documentation: Improve firmware overview page. Naming things. Fix links.

.github/workflows/platformio-ci.yaml

@@ -89,7 +89,7 @@ jobs:
               - 'trudering/bienenwaage-2.0/**/*.ino'
             trudering-bienenwaage-50:
               - 'trudering/bienenwaage-5.0/**/*.ini'
-              - 'trudering/bienenwaage-5.0/**/*.ino'
+              - 'trudering/bienenwaage-5.0/**/*.cpp'
 
   build:
     needs: changes

CHANGES.rst

@@ -137,9 +137,9 @@ in-progress
 
 2017-01-10 0.11.0
 =================
-- Add firmware for :ref:`node-wifi-mqtt-homie` (`node-wifi-mqtt-homie.ino`_).
+- Add firmware for :ref:`node-wifi-mqtt-homie` (`node-homie-basic.ino`_).
   Contributed as `PR #1`_ by Alexander Wilms of `Imkerverein Nettetal e.V.`_. Thanks a bunch!
-- Update firmware for :ref:`open-hive-firmware-gprs`: (`node-gprs-http.ino`_). Thanks, Clemens!
+- Update firmware for :ref:`open-hive-firmware-gprs`: (`openhive-gsm-wifi.ino`_). Thanks, Clemens!
 
     - Add support for HX711
     - Add support for ESP8266
@@ -155,7 +155,7 @@ in-progress
 2016-11-01 0.10.0
 =================
 - Add sketch and update documentation about CSV payload transmission and forwarding to UART using a JeeLink device
-  to complete the Open Hive RFM69 trio: :ref:`open-hive-firmware-rfm69-gateway-uart` (`gateway-rfm69-csv-uart.ino`_).
+  to complete the Open Hive RFM69 trio: :ref:`openhive-rfm69-gateway-uart` (`rfm69-gateway-uart.ino`_).
   Thanks Richard!
 - Update sketch (beta release) and add documentation about :ref:`node-wifi-mqtt` (`node-wifi-mqtt.ino`_).
   Thanks Clemens and Karsten!
@@ -164,25 +164,25 @@ in-progress
 2016-09-17 0.9.0
 ================
 - Add documentation about :ref:`scale-adjust-firmware`.
-- Update firmware for :ref:`open-hive-firmware-gprs` "`node-gprs-http.ino`_": Modularize sensors and debugging. Thanks, Clemens!
+- Update firmware for :ref:`open-hive-firmware-gprs` "`openhive-gsm-wifi.ino`_": Modularize sensors and debugging. Thanks, Clemens!
 - Add firmwares for Open Hive RFM69 tandem with build infrastructure and documentation
 
-    - :ref:`open-hive-firmware-rfm69-node`: `node-rfm69-csv.ino`_
-    - :ref:`open-hive-firmware-rfm69-gateway-sdcard`: `gateway-rfm69-csv-sdcard.ino`_
+    - :ref:`open-hive-firmware-rfm69-node`: `rfm69-node.ino`_
+    - :ref:`open-hive-firmware-rfm69-gateway-sdcard`: `rfm69-gateway-sdcard.ino`_
 
 - Improve documentation
 
 
 2016-07-08 0.8.1
 ================
-- Add documentation about the new :ref:`generic-firmware`, "`generic.ino`_".
+- Add documentation about the new :ref:`generic-firmware`, "`multihop.ino`_".
 - Switch “node-gprs-http” sketch from Rob Tillaarts DHTlib to DHTstable, as suggested by Clemens. Thanks again!
 
 
 2016-07-08 0.8.0
 ================
 - Make building “generic” sketch for x86_64 a bit easier, just do ``cd generic; ./sim/build``.
-- Add :ref:`open-hive-firmware-gprs` from Clemens Gruber as "`node-gprs-http.ino`_". Thanks, Clemens!
+- Add :ref:`open-hive-firmware-gprs` from Clemens Gruber as "`openhive-gsm-wifi.ino`_". Thanks, Clemens!
 - Satisfy dependencies of “node-gprs-http” per git submodules (mostly), accompanied by Arduino Makefile yak shaving.
 - Add :ref:`scale-adjust-firmware`. Thanks again, Clemens!
 - Finish restructuring work on "generic" sketch. Proof-of-Concept ``node69-relay69x95-gateway95`` is working!
@@ -198,7 +198,7 @@ in-progress
 
 General
 -------
-- Add sketch `generic.ino`_ as a module composition breadboard.
+- Add sketch `multihop.ino`_ as a module composition breadboard.
 - Add Terrine_, an application boilerplate for convenient MCU development.
 - Run generic sketch on x86_64 incl. pseudo radio link
   communication using RadioHead RH_TCP driver.
@@ -234,7 +234,7 @@ Libraries
 
 2016-06-17 0.6.1
 ================
-- Add Firmware-Builder helper to Linux Makefile for `node-gprs-http.ino`_.
+- Add Firmware-Builder helper to Linux Makefile for `openhive-gsm-wifi.ino`_.
 - Update docs.
 
 
@@ -266,7 +266,7 @@ Terkin_, `Hiveeyes-Lib`_ and `OpenHive-Lib`_.
 
 - Add ArduinoJson_ and `GPRSbee library`_ as git submodules under ``libraries/``.
 
-- Add example sketch `node-gprs-http.ino`_ demonstrating
+- Add example sketch `openhive-gsm-wifi.ino`_ demonstrating
   simple HTTP+JSON communication over GPRSbee.
 
 - Update ``HE_API_URL`` to use different url for non-TLS

Makefile

@@ -9,8 +9,10 @@ include util.mk
 #
 # Miscellaneous tools:
 # Software tests, Documentation builder, Virtual environment builder
-#
+
 docs-html: virtualenv
+	@# TODO: Invoke from `conf.py`.
+	$(MAKE) rst2md
 	export SPHINXBUILD="$(PWD)/$(sphinx)"; cd doc; make html
 
 docs-autobuild: virtualenv
@@ -21,6 +23,9 @@ virtualenv: setup-virtualenv
 	@echo Installing packages from requirements-docs.txt.
 	$(pip) install --quiet --upgrade --requirement requirements-docs.txt
 
+rst2md:
+	cat doc/source/resources.rst | $(python) doc/rst2md.py > doc/source/resources-md.md
+
 
 # ==========================================
 #            ptrace.hiveeyes.org

README.rst

@@ -21,9 +21,10 @@ Hiveeyes Arduino README
 About
 *****
 
-This is the firmware source code documentation of the `Hiveeyes project`_, which is
-developing a flexible beehive monitoring infrastructure toolkit and platform based
-on affordable hardware, wireless telemetry and modern software.
+This is the firmware source code and documentation repository of the `Hiveeyes project`_,
+which is developing a flexible beehive monitoring infrastructure toolkit and platform, based
+on affordable hardware, wireless telemetry, and modern software.
+
 
 ****
 Note

backdoor/multihop/README.rst

@@ -24,7 +24,7 @@ About
 
 A flexible software breadboard for sensor-, relay-, and gateway-nodes, transmitting
 telemetry data in multi-hop radio link environments. It is a hybrid/unified single-file
-firmware `generic.ino`_, with an accompanying configuration settings header file, `config.h`_.
+firmware `multihop.ino`_, with an accompanying configuration settings header file, `config.h`_.
 
 The system has originally been conceived for beehive monitoring, but can be used for
 other environmental monitoring purposes.
@@ -105,11 +105,11 @@ Build on your workstation
 =========================
 ::
 
-    # Acquire the source code repository including all dependencies.
+    # Acquire source code repository.
     git clone https://github.com/hiveeyes/arduino
 
     # Select this firmware.
-    cd generic
+    cd arduino/backdoor/multihop
 
     # Build firmware.
     make build

backdoor/node-pipa/README.rst

@@ -1,3 +1,5 @@
+.. _pipa-datalogger:
+
 ########################
 Hiveeyes Pipa Datalogger
 ########################
@@ -33,7 +35,7 @@ Usage
 ::
 
     git clone https://github.com/hiveeyes/arduino
-    cd arduino/node-pipa
+    cd arduino/backdoor/node-pipa
     make
 
 

backdoor/node-wifi-mqtt/README.rst

@@ -80,11 +80,11 @@ Clone git repository
 ====================
 ::
 
-    # Get hold of the source code repository including all dependencies
+    # Acquire source code repository
     git clone https://github.com/hiveeyes/arduino
 
     # Select this firmware
-    cd node-wifi-mqtt
+    cd arduino/backdoor/node-wifi-mqtt
 
 
 Configure

doc/rst2md.py

@@ -0,0 +1,23 @@
+import re
+import sys
+import typing as t
+
+
+rst_pattern = re.compile(r"^\.\. _(?P<label>.+?): (?P<url>.+?)$")
+md_format = r"[{label}]: {url}"
+
+
+def rst2md(instream: t.BinaryIO):
+    # print(":orphan:")
+    # print()
+    for line in instream.readlines():
+        line = line.decode("utf-8").strip()
+        matches = rst_pattern.match(line)
+        if matches:
+            data = matches.groupdict()
+            print(md_format.format(**data))
+
+
+if __name__ == "__main__":
+    indata = sys.stdin.buffer
+    rst2md(indata)

doc/source/conf.py

@@ -28,6 +28,7 @@
 extensions = [
     "myst_parser",
     "sphinx_copybutton",
+    "sphinx_design",
     "sphinx_togglebutton",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
@@ -334,6 +335,7 @@ def setup(app):
     "colon_fence",
     "deflist",
     "fieldlist",
+    "html_admonition",
     "linkify",
     "strikethrough",
     "tasklist",

doc/source/coverage.md

@@ -0,0 +1,20 @@
+```{include} ./resources-md.md
+```
+
+
+# Sensors
+
+- [HX711], [BME280], [DS18B20], [DHT22], [TSL2591]
+
+
+# Telemetry transports
+
+- [Cellular]: [GSM], [GPRS], [LTE Cat M1], [LTE Cat NB1].
+- [ISM radio]: RF packet radio [RFM69] [RFM95].
+- [ISM radio]: [LoRa] and [LoRaWAN] telemetry.
+- Classic [Wi-Fi].
+
+
+# Telemetry protocols
+
+- [BERadio], [MQTT], [HTTP]

doc/source/firmware-builder.rst

@@ -47,7 +47,7 @@ suitable for automatic building using the variables described above, please have
 Build node-gprs-http
 ********************
 
-The firmware source code `node-gprs-http.ino`_ of the :ref:`open-hive-firmware-gprs`
+The firmware source code `openhive-gsm-wifi.ino`_ of the :ref:`open-hive-firmware-gprs`
 is pulled from the master branch of the `Hiveeyes Arduino repository`_ on GitHub.
 Specify appropriate parameters to match your environment.
 
@@ -104,7 +104,7 @@ response content on the right side of the screen into a .hex file and upload to
 .. tip::
 
     As the available configuration parameters and possible values are currently not documented
-    in detail, please have a look at the source code (`node-gprs-http.ino`_). All preprocessor
+    in detail, please have a look at the source code (`openhive-gsm-wifi.ino`_). All preprocessor
     variables (``#define ...``) can be changed through HTTP POST parameters.