Merge pull request #330 from joelkoz/SensESP-v1.0-RC1

First code complete set for SensESP v1.0

.clang-format

@@ -1,2 +1,3 @@
 ---
 BasedOnStyle: Google
+IndentWidth: 2

.github/workflows/test.yml

@@ -8,34 +8,29 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        example: [
-          examples/ads1x15_volt_meter.cpp,
-          examples/analog_input.cpp,
-          examples/bme280_example.cpp,
-          examples/bmp280_example.cpp,
-          examples/fuel_flow_meter.cpp,
-          examples/fuel_level_sensor/fuel_level_sensor_example.cpp,
-          examples/gps_compass.cpp,
-          examples/hysteresis.cpp,
-          examples/ina219_example.cpp,
-          examples/lambda_transform.cpp,
-          examples/milone_level_sensor/milone_level_sensor.cpp,
-          examples/onewire_temperature/onewire_temperature_example.cpp,
-          examples/relay_control.cpp,
-          examples/rpm_counter.cpp,
-          examples/sht31_example.cpp,
-          examples/temperature_sender.cpp,
-          examples/thermocouple_temperature_sensor/max31856_thermocouple_example.cpp,
-          examples/ultrasonic_level_sensor/ultrasonic_dvp_example.cpp]
+        example:
+          - examples/ads1x15_volt_meter.cpp
+          - examples/analog_input.cpp
+          - examples/bme280_example.cpp
+          - examples/hysteresis.cpp
+          - examples/lambda_transform.cpp
+          - examples/onewire_temperature/onewire_temperature_example.cpp
+          - examples/relay_control.cpp
+          - examples/rpm_counter.cpp
+          - examples/ultrasonic_level_sensor/ultrasonic_dvp_example.cpp
+        target_device:
+          - d1_mini
+          - esp32dev
     steps:
-    - uses: actions/checkout@v1
-    - name: Set up Python
-      uses: actions/setup-python@v1
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install platformio
-    - name: Run PlatformIO
-      run: platformio ci -v --lib . -c ./platformio.ini
-      env:
-        PLATFORMIO_CI_SRC: ${{ matrix.example }}
+      - uses: actions/checkout@v1
+      - name: Set up Python
+        uses: actions/setup-python@v1
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install platformio
+      - name: Run PlatformIO
+        run: ci/run-ci.sh
+        env:
+          PLATFORMIO_CI_SRC: ${{ matrix.example }}
+          CI_TARGET_DEVICE: ${{ matrix.target_device }}

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = SensESP
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 0.5.1
+PROJECT_NUMBER         = 1.0.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -350,7 +350,7 @@ AUTOLINK_SUPPORT       = YES
 # diagrams that involve STL classes more complete and accurate.
 # The default value is: NO.
 
-BUILTIN_STL_SUPPORT    = NO
+BUILTIN_STL_SUPPORT    = YES
 
 # If you use Microsoft's C++/CLI language, you should set this option to YES to
 # enable parsing support.
@@ -1578,7 +1578,7 @@ FORMULA_TRANSPARENT    = YES
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-USE_MATHJAX            = NO
+USE_MATHJAX            = YES
 
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. See the MathJax site (see:
@@ -2256,7 +2256,7 @@ PERL_PATH              = /usr/bin/perl
 # powerful graphs.
 # The default value is: YES.
 
-CLASS_DIAGRAMS         = NO
+CLASS_DIAGRAMS         = YES
 
 # You can define message sequence charts within doxygen comments using the \msc
 # command. Doxygen will then run the mscgen tool (see:
@@ -2338,7 +2338,7 @@ CLASS_GRAPH            = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-COLLABORATION_GRAPH    = NO
+COLLABORATION_GRAPH    = YES
 
 # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for
 # groups, showing the direct groups dependencies.
@@ -2374,7 +2374,7 @@ UML_LIMIT_NUM_FIELDS   = 10
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-TEMPLATE_RELATIONS     = NO
+TEMPLATE_RELATIONS     = YES
 
 # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to
 # YES then doxygen will generate a graph for each documented file showing the
@@ -2447,7 +2447,7 @@ DIRECTORY_GRAPH        = YES
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg
 
 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.
@@ -2459,7 +2459,7 @@ DOT_IMAGE_FORMAT       = png
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INTERACTIVE_SVG        = NO
+INTERACTIVE_SVG        = YES
 
 # The DOT_PATH tag can be used to specify the path where the dot tool can be
 # found. If left blank, it is assumed the dot tool can be found in the path.

README.md

@@ -35,40 +35,21 @@ the Wemos D1 mini, an implementation of the ESP8266 chip. If you're using a diff
 board dropdown. If you're using an ESP32 that isn't in the board list, choose "Espressif ESP32 Dev Module".)
 The Arduino framework should become automatically selected. Complete the New Project dialog, then open the project you created.
 
-Once you have your new project open, open the `platformio.ini` file that's in your project's directory (NOT the one that you find if you go down into the .pio/libdeps/... folders). Add the SensESP dependency to the section for your board:
+Once you have your new project open, open the automatically generated `platformio.ini` file that's in your project's directory (NOT the one that you find if you go down into the .pio/libdeps/... folders). Save it as `platformio.ini.auto` so you can refer back to it.
 
-``` 
-lib_deps =
-    https://github.com/SignalK/SensESP.git
-```
+Create a new file, and copy/paste the entire contents of [this example `platformio.ini` file](https://github.com/SignalK/SensESP/blob/master/examples/platformio.ini) into it. Save it as `platformio.ini`.
 
-Look at [this file](https://github.com/SignalK/SensESP/blob/master/platformio.ini). Notice there are two `env` sections: `[env:d1_mini]` and `[env:esp32dev]` . `[env:d1_mini]` is for the Wemos D1 Mini ESP8266. If your board is an ESP8266, copy all of the lines from that section into the `env` section of your platformio.ini. `[env:esp32dev]` is for a basic ESP32. If your board is an ESP32, copy all the lines from that section into the `env` section of your platformio.ini.
+If the `[platformio]` section of this file contains your ESP board, make sure your board is not commented out, and that all other boards are commented out, and save it. This should be a good `platformio.ini` file for SensESP. If your board is NOT included, you need to add it (see how it's represented in the `platformio.ini.auto` that you saved). And you need to merge the other lines in `platformio.ini.auto` into your `platformio.ini` file. (Detailed instructions for merging these two files are available [in the Wiki](https://github.com/SignalK/SensESP/wiki/SensESP-Overview-and-Programming-Details#getting-a-good-platformioini-file).)
 
-Then, open `src/main.cpp` . The default template is for the Arduino IDE, but a SensESP main.cpp file will look very different. Replace the contents of `main.cpp` with the contents of one of the SensESP examples in the `examples` subdirectory here on GitHub. (This is a good one to start with: https://github.com/SignalK/SensESP/blob/master/examples/analog_input.cpp .) Check that the settings (pin numbers, etc.) match your hardware and select "Build" from the PlatformIO submenu (the little alien face) on the left toolbar. If the build succeeds, you can plug in your ESP board and press "Upload and Monitor".
+Now, open `src/main.cpp`. The default template is for the Arduino IDE, but a SensESP `main.cpp` file will look very different. Replace the contents of `main.cpp` with the contents of one of the SensESP examples in the examples subdirectory here on GitHub. (This is a good one to start with: https://github.com/SignalK/SensESP/blob/master/examples/analog_input.cpp .) Check that the settings (pin numbers, etc.) match your hardware. Then click on the checkmark icon on the blue status bar along the bottom of your screen. (That's the "Build" shortcut.) If the build succeeds, you can plug in your ESP board and press "Upload and Monitor".
 
-If the project compiles and uploads, your ESP will be running the example code. Since the first thing it needs to do is connect to a wifi network, and it doesn't know what network to connect to, it will broadcast a wifi SSID for you to connect to so you can configure it. Connect your computer or phone wifi to the "Configure sensesp" network. A captive portal may pop up, but if it doesn't, open a browser and go to 192.168.4.1. Enter your wifi credentials to allow the device to access the network that your Signal K Server is on. Also enter a suitable name for the ESP, for example `BilgeMonitor` or `EngineTemps` . (No more than 16 characters, no spaces.) Save the configuration with the button on the bottom of the page, and the ESP will restart and try to connect to your wifi network.
+If the project compiles and uploads, your ESP will be running the example code. Since the first thing it needs to do is connect to a wifi network, and it doesn't know what network to connect to, it will broadcast a wifi SSID for you to connect to so you can configure it. Connect your computer or phone wifi to the "Configure SensESP" network. A captive portal may pop up, but if it doesn't, open a browser and go to 192.168.4.1. Enter your wifi credentials to allow the device to access the network that your Signal K Server is on. Also enter a suitable name for the ESP, for example `BilgeMonitor` or `EngineTemps`. (No more than 16 characters, no spaces.) Save the configuration with the button on the bottom of the page, and the ESP will restart and try to connect to your wifi network.
 
-Once on the network, SensESP should automatically find your Signal K server, assuming it has mDNS enabled (see instructions above). ESP32 ONLY: If you see (in the Serial Monitor) that your ESP32 is restarting over and over, with these as the last lines of each failure:
-
-``` 
-␛[0m(I) (enable)(C1) All sensors and transforms enabled
-␛[0m(D) (connect)(C1) Initiating connection
-␛[0mGuru Meditation Error: Core  1 panic'ed (LoadProhibited). Exception was unhandled.
-```
-
-it means that your Signal K Server is not responding to the ESP's mDNS request. On your Signal K Server Dashboard, click the "Restart" button. It should restart in a few seconds, and then you should see that the ESP32 is no longer failing after `Initiating connection` . (There is an Issue to try to handle this condition more gracefully, but the Server restart seems to always fix it, so for now, that's what we've got.)
+Once on the network, SensESP should automatically find your Signal K server, assuming it has mDNS enabled (see instructions above). 
 
 If your server has security enabled (it does by default), you should see an access request for your ESP in the Signal K Dashboard, under Security - Access Requests. (You must be logged into the Signal K Server to see the Security sub-menu.) Set the "Authentication Timeout" field to "NEVER", set the Permission to "Read / Write", then Approve it. You should start getting data on the Signal K Instrument Panel. (Dashboard - Webapps - Instrument Panel) You can see lots of activity in the Serial Monitor, including the connection to the Signal K Server, the request for and approval of the security token, and the flow of data.
 
-ESP32 ONLY: in the Serial Monitor, until you authorize the security request, you'll see that the ESP32 is continually getting to the following point, and failing:
-
-``` 
-[0m(D) (poll_access_request)(C1) Polling SK Server for authentication token
-␛[0m(D) (poll_access_request)(C1) PENDING
-␛[0mGuru Meditation Error: Core  1 panic'ed (LoadProhibited). Exception was unhandled.
-```
-
-Once you approve the security request, the ESP will do this a few more times, and then it will see the authorization, and will then continue on, and finally start sending data to the Signal K Server. (There is an Issue to try to handle this condition more gracefully, but approving the security request on the server solves it, and it happens only once, so for now, that's what we've got.)
+If you have any problems with configuring the wifi credentials, or with SensESP finding your Signal K server, you can hard-code those settings. See [Hard-coding Certain Program Attributes](https://github.com/SignalK/SensESP/wiki/SensESP-Overview-and-Programming-Details#hard-coding-certain-program-attributes).
 
 Some additional instructions are available on the [SensESP wiki](https://github.com/SignalK/SensESP/wiki/). 
 

ci/README.md

@@ -0,0 +1,4 @@
+# CI directory contents
+
+This directory contains files required for running the Continuous Integration tests in GitHub.
+It is not required for other uses and should be ignored unless you want to modify the CI functionality.

ci/platformio-d1_mini.ini

@@ -0,0 +1,18 @@
+; CI platformio.ini for d1_mini
+
+[env]
+; Global data for all [env:***]
+framework = arduino
+lib_ldf_mode = deep
+monitor_speed = 115200
+lib_deps = ${PROJDIR}
+
+[env:d1_mini]
+platform = espressif8266
+board = d1_mini
+board_build.ldscript = eagle.flash.4m1m.ld
+build_flags =
+   -Wall
+   -Wno-reorder
+   -D LED_BUILTIN=2
+board_build.f_cpu = 160000000L

ci/platformio-esp32dev.ini

@@ -0,0 +1,17 @@
+; CI platformio.ini for d1_mini
+
+[env]
+; Global data for all [env:***]
+framework = arduino
+lib_ldf_mode = deep
+monitor_speed = 115200
+lib_deps = ${PROJDIR}
+
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+build_unflags = -Werror=reorder
+board_build.partitions = min_spiffs.csv
+monitor_filters = esp32_exception_decoder
+build_flags =
+   -D LED_BUILTIN=2

ci/run-ci.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# assume this command is always run from the project root directory
+
+PROJDIR=$(pwd)
+
+# replace the 
+sed -e "s|\${PROJDIR}|$PROJDIR|" ci/platformio-${CI_TARGET_DEVICE}.ini > ci/platformio.ini
+
+# the example to build comes from $PLATFORMIO_CI_SRC
+
+pio ci -c ci/platformio.ini

docs/RELEASE_PROCESS.md

@@ -24,12 +24,14 @@ The release process is as follows:
 
    Remember to commit the results.
 
-3. Update the doxygen docs (first bump the version number in `Doxyfile`)
+3. Update the Doxygen docs (first bump the version number in `Doxyfile`). To
+   run Doxygen, you need to have Graphviz installed on your system. It is 
+   available on your favorite package manager on any Linux distribution or Mac.
 
     rm -rf docs/generated/docs/
     doxygen
 
-   Again, commit the results.
+   Again, commit the changes.
 
 4. Push the changes to your local fork.