From 3900f264a76b63c958b04ed9673a37e8fa680488 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sun, 28 May 2023 16:03:56 +0200 Subject: [PATCH] Documentation: Update README --- README.rst | 56 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 38 insertions(+), 18 deletions(-) diff --git a/README.rst b/README.rst index beb9e9a..7783383 100644 --- a/README.rst +++ b/README.rst @@ -6,11 +6,15 @@ Hiveeyes Arduino Firmwares ########################## - .. image:: https://github.com/hiveeyes/arduino/actions/workflows/platformio-ci.yaml/badge.svg :target: https://github.com/hiveeyes/arduino/actions/workflows/platformio-ci.yaml :alt: PlatformIO CI outcome +ยป `Documentation`_ +| `Forum`_ +| `Issues`_ +| `Source code`_ + .. tip:: Please `continue reading this document on our documentation space `_, @@ -22,14 +26,14 @@ Introduction ************ This is the documentation for the `Hiveeyes Arduino repository`_ of the `Hiveeyes project`_, -a beehive monitoring system. Enjoy reading! +conceiving an open source and open hardware beehive monitoring system. All Arduino Core based firmware source code is living here. -We support different hardware, so there are different flavors +It supports different hardware, so there are different flavors of firmwares, reflected by the directory naming convention ``--``. -There are firmwares for ATmega328_, ESP8266_ and ESP32_ MCUs. +There are firmwares for ATmega328_, ESP8266_, and ESP32_ MCUs. * ``purpose`` role name, either *node* or *gateway* * ``transport`` name of the physical transport mechanism, e.g. *rfm69*, *gprs* or *wifi*. @@ -43,7 +47,6 @@ Setup ***** .. highlight:: bash - Source code =========== Acquire source code repository:: @@ -56,20 +59,37 @@ Toolchain PlatformIO ---------- We recommend to use `PlatformIO`_. Installing all dependency libraries will be managed -automatically, accurately, and reproducibly, and you will be able to choose between -CLI and UI operations, see `PlatformIO IDE`_. +automatically, accurately, and reproducibly, because each programs' subdirectory contains +a ``platformio.ini`` file, which enumerates the list of dependencies within the +``env.lib_deps`` sections, like:: + +[env] +lib_deps = + lowpowerlab/RFM69@^1.5 + lowpowerlab/SPIFlash@^101 + https://github.com/hiveeyes/embencode + +You will be able to choose between CLI and UI operations, see `PlatformIO IDE`_. + +When using PlatformIO, we recommend to turn off telemetry, by running that command +within your Python environment you are running ``pio`` in:: + + pio settings set enable_telemetry false Arduino IDE ----------- -If you want to use the Arduino IDE, you have to install all necessary libraries manually. -In each programs subdirectory, there is a ``platformio.ini`` which will give you a clue -about the libraries to use. +If you want to use the Arduino IDE, you will have to install all necessary libraries +manually. We do not recommend it, because it can produce arbitrary results when +building and running the firmware. +If you absolutely have to use it, to give you a clue about the required dependencies +for each individual firmware, please inspect the ``env.lib_deps`` sections within the +``platformio.ini`` files. -******* -Operate -******* +***** +Usage +***** Compile ======= @@ -78,8 +98,6 @@ Compile cd node-esp32-generic make - - Upload to MCU ============= To build a firmware hex file, upload it to the MCU and @@ -96,21 +114,23 @@ finally start a serial port monitor, do:: License ******* - Software ======== All source codes are licensed under the GNU General Public License, see also "LICENSE.txt". - Hardware ======== All hardware designs and related things are licensed under the `CERN Open Hardware Licence v1.2`_. .. _CERN Open Hardware Licence v1.2: http://www.ohwr.org/licenses/cern-ohl/v1.2 - Documentation ============= Licensed under the Creative Commons `CC-BY-SA 4.0 license`_. + .. _CC-BY-SA 4.0 license: https://creativecommons.org/licenses/by-sa/4.0/ +.. _Documentation: https://hiveeyes.org/docs/arduino/ +.. _Forum: https://community.hiveeyes.org/ +.. _Issues: https://github.com/hiveeyes/arduino/issues +.. _Source code: https://github.com/hiveeyes/arduino