doc for 20231105

Readme.md

@@ -38,6 +38,7 @@ What is included
 * a WEB UI to configure the gateway and to show the data that has been received
 * a USB Actisense to NMEA2000 gateway
 * a NMEA2000 to USB Actisense gateway
+* starting with 201311xx some I2C Sensors
 
 For the details of the mapped PGNs and NMEA sentences refer to [Conversions](doc/Conversions.pdf).
 
@@ -46,11 +47,15 @@ Hardware
 The software is prepared to run on different kinds of ESP32 based modules and accessoirs. For some of them prebuild binaries are available that only need to be flashed, others would require to add some definitions of the used PINs and features and to build the binary.
 For the list of hardware set ups refer to [Hardware](doc/Hardware.md).
 
+There is a couple of prebuild binaries that you can directly flash to your device. For other combinations of hardware there is an [online build service](doc/BuildService.md) that will allow you to select your hardware and trigger a build.
+
 
 Installation
 ------------
 In the [release section](../../releases) you can find a couple of pre-build binaries.<br>
-They are devided into binaries for an initial flash (xxx-all.bin) and binaries for updating an existing device (xxx-update.bin).
+They are devided into binaries for an initial flash (xxx-all.bin) and binaries for updating an existing device (xxx-update.bin). 
+
+For other Hardware refer to the [online build service](https://circleci.com/).
 
 Initial Flash
 *************
@@ -160,6 +165,17 @@ For details refer to the [example description](lib/exampletask/Readme.md).
 
 Changelog
 ---------
+[20231105](../../releases/tag/20231105)
+**********
+* support for ESP32-S3
+* own [TWAI](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/twai.html) based driver for the NMEA2000 bus
+* add NMEA2000 node address and status to the status tab
+* ability to change the AP ip address 
+* [online build service ](doc/BuildService.md) to select the components you need
+* restructuring of the lib_deps handling (much shorter compile time <br>__Hint__: if this introduces problems for your build, revert back the [lib_ldf_mode](https://github.com/wellenvogel/esp32-nmea2000/blob/9b955d135d74937a60f2926e8bfb9395585ff8cd/platformio.ini#L50) to chain+ 
+* integration of a couple of I2C sensors (e.g. M5 ENVIII, BME280)
+* More functionality for user tasks (counter, interface between tasks, dynamic registration, adding fixed XDR mappings) - refer to the [example description](lib/exampletask/Readme.md)
+
 [20230317](../../releases/tag/20230317)
 **********
 * correctly convert bar to Pascal in XDR records

doc/BuildService.md

@@ -0,0 +1,49 @@
+Online Build Service
+--------------------
+As the supported hardware combinations are already a lot and to support the suage of the converter also in your own designs there is an online build service available that will allow you to select the hardware combinations you would like to have and to start a build.
+
+__Access__
+
+To access the build service go to [wellenvogel.de](https://www.wellenvogel.net/software/esp32/cibuild.html).
+To prevent the build service from being misused you need to authenticate with a username and password.
+ * User: ESP32NMEA2K
+ * Pass: esp32ci
+
+Just consider that the user and password could change in the future - so when bookmarking just always start here and check for the current username and password.
+
+__Workflow__
+
+On the page you select the Hardware combination that fits your needs.
+![buildservice](CiBuild1.png). 
+
+The selected board type and the build flags will be show at the bottom.
+Whenever an existing build with the same parameters is found it will be shown and you will be able to download the build results - or directly go to the [WebInstaller](https://www.wellenvogel.net/software/esp32/install.html).
+If there is no existing build the "Start" button is active and you can trigger a build.
+
+At the bottom you see the status of the build and you get a link to the [used build service](https://app.circleci.com/pipelines/github/wellenvogel/esp32-nmea2000).
+
+![buildservice](CiBuild2.png). 
+
+Once the build is complete you will get the buttons to download the results or directly use them for the web installer.
+
+__Build Results__
+
+The build result is always a zip file that contains a flash for the initial installation, an flash for the update installation and the used configuration for the build.
+This zip file should be stored on your side as the build results will be deleted after 30 days.
+If you later on would like to update with a new release you can upload your configuration using the "LOADCFG" button (either the zip file or the json file from within the zip).
+You can also separately store the configuration of your build using the "SAVECFG" button.
+
+__Hardware__
+
+Currently a couple of different hardware configurations are supported. For M5 devices you typically select the processor unit, the "base" and some groove units.
+For other node mcu boards you can freely configure the peripherals that you would like to connect.
+
+__Local Build__
+
+As the selection of hardware is basically controlled by defines (-D flags on the command line) you can also use the build GUI to create a build command that you run locally (assumimng you have the build environment installed).
+Just click the "?" button beside "Build Flags". The PopUp will give you a "Copy" button that will copy the complete command line you can use for the build.
+
+__Remarks__
+
+Although the online build service tries to make a couple of checks to prevent impossible hardware configurations you still need to check your design (especially if you are using the "free" nodemcu settings).
+The free build service at [CircleCi](https://circleci.com/) has a couple of limitation - so please be careful and avoid too many bauilds that you potentially don't need.

lib/exampletask/Readme.md

@@ -15,17 +15,52 @@ Files
     This file is completely optional.
     You only need this if you want to
     extend the base configuration - we add a dummy library here and define one additional build environment (board)
-   * [GwExampleTask.h](GwExampleTask.h) the name of this include must match the name of the directory (ignoring case) with a "gw" in front. This file includes our special hardware definitions and registers our task at the core (DECLARE_USERTASK in the code). Avoid including headers from other libraries in this file as this could interfere with the main code. Just only include them in your .cpp files (or in other headers).
+   * [GwExampleTask.h](GwExampleTask.h) the name of this include must match the name of the directory (ignoring case) with a "gw" in front. This file includes our special hardware definitions and registers our task at the core.<br>
+   This registration can be done statically using [DECLARE_USERTASK](https://github.com/wellenvogel/esp32-nmea2000/blob/9b955d135d74937a60f2926e8bfb9395585ff8cd/lib/api/GwApi.h#L202) in the header file. <br>
+   As an alternative we just only register an [initialization function](https://github.com/wellenvogel/esp32-nmea2000/blob/9b955d135d74937a60f2926e8bfb9395585ff8cd/lib/exampletask/GwExampleTask.h#L19) using DECLARE_INITFUNCTION and later on register the task function itself via the [API](https://github.com/wellenvogel/esp32-nmea2000/blob/9b955d135d74937a60f2926e8bfb9395585ff8cd/lib/exampletask/GwExampleTask.cpp#L32).<br>
+   This gives you more flexibility - maybe you only want to start your task if certain config values are set.<br>
+   The init function itself should not interact with external hardware and should run fast. It needs to return otherwise the main code will not start up.<br>
+   Avoid including headers from other libraries in this file as this could interfere with the main code. Just only include them in your .cpp files (or in other headers).
    Optionally it can define some capabilities (using DECLARE_CAPABILITY) that can be used in the config UI (see below)
    There are some special capabilities you can set:
      *  HIDEsomeName: will hide the configItem "someName"
-     *  HELP_URL: will set the url that is loaded when clicking the HELP tab (user DECLARE_STRING_CAPABILITY)
+     *  HELP_URL: will set the url that is loaded when clicking the HELP tab (user DECLARE_STRING_CAPABILITY)<br>
+
    * [GwExampleTaks.cpp](GwExampleTask.cpp) includes the implementation of our task. This tasks runs in an own thread - see the comments in the code.
    We can have as many cpp (and header files) as we need to structure our code.  
    * [config.json](config.json)<br>
      This file allows to add some config definitions that are needed for our task. For the possible options have a look at the global [config.json](../../web/config.json). Be careful not to overwrite config defitions from the global file. A good practice wood be to prefix the names of definitions with parts of the library name. Always put them in a separate category so that they do not interfere with the system ones.
      The defined config items can later be accessed in the code (see the example in [GwExampleTask.cpp](GwExampleTask.cpp)).
 
+ Interfaces
+ ----------
+ The task init function and the task function interact with the core using an [API](../api/GwApi.h) that they get when started.
+ The API has a couple of functions that only can be used inside an init function and others that can only be used inside a task function.
+ Avoid any other use of core functions other then via the API - otherwise you carefully have to consider thread synchronization!
+ The API allows you to
+ * access config data
+ * write logs
+ * send NMEA2000 messages
+ * send NMEA0183 messages
+ * get the currently available data values (as shown at the data tab)
+ * get some status information from the core
+ * send some requests to the core (only for very special functionality)
+ * add and increment counter (starting from 20231105)
+ * add some fixed [XDR](../../doc/XdrMappings.md) Mapping - see [example](https://github.com/wellenvogel/esp32-nmea2000/blob/9b955d135d74937a60f2926e8bfb9395585ff8cd/lib/exampletask/GwExampleTask.cpp#L63).
+ * add capabilities (since 20231105 - as an alternative to a static DECLARE_CAPABILITY )
+ * add a user task (since 20231105 - as an alternative to a static DECLARE_USERTASK)
+ * store or read task interface data (see below)
+
+
+ __Interfacing between Task__
+
+Sometimes you may want to exchange data between different user tasks.<br> As this needs thread sychronization (and a place to store this data) there is an interface to handle this in a safe manner (since 20231105).<br>
+The task that would like to provide some data for others must declare a [class](https://github.com/wellenvogel/esp32-nmea2000/blob/9b955d135d74937a60f2926e8bfb9395585ff8cd/lib/exampletask/GwExampleTask.h#L24) that stores this data. This must be declared in the task header file and you need to make this known to the code using DECLARE_TASKIF.<br>
+Before you can use this interface for writing you need to ["claim"](https://github.com/wellenvogel/esp32-nmea2000/blob/9b955d135d74937a60f2926e8bfb9395585ff8cd/lib/exampletask/GwExampleTask.cpp#L55) it - this prevents other tasks from also writing this data.
+Later on you are able to [write](https://github.com/wellenvogel/esp32-nmea2000/blob/9b955d135d74937a60f2926e8bfb9395585ff8cd/lib/exampletask/GwExampleTask.cpp#L278) this data via the api.<br>
+Any other task that is interested in your data can read it at any time. The read function will provide an update counter - so the reading side can easily see if the data has been written.
+The core uses this concept for the interworking between the [button task](../buttontask/) - writing - and the [led task](../ledtask/) - [reading](https://github.com/wellenvogel/esp32-nmea2000/blob/9b955d135d74937a60f2926e8bfb9395585ff8cd/lib/ledtask/GwLedTask.cpp#L52).
+
  Hints
  -----
  Just be careful not to interfere with C symbols from the core - so it is a good practice to prefix your files and class like in the example.
@@ -47,7 +82,4 @@ Files
 
  By following the hints in this doc the merge should always succeed without conflicts.
 
- Future Plans
- ------------
- If there will be a need we can extend this extension API by means of adding  specific java script code and css for the UI.