Move param doc (#2843)

moved param doc from docs repo to here

.github/workflows/build.yml

@@ -70,7 +70,7 @@ jobs:
       #run: echo "Testing... ${{ github.ref_name }}, ${{ steps.vars.outputs.sha_short }}" > ./sd-card/html/version.txt; mkdir -p ./code/.pio/build/esp32cam/; cd ./code/.pio/build/esp32cam/; echo "${{ steps.vars.outputs.sha_short }}" > firmware.bin; cp firmware.bin partitions.bin; cp firmware.bin bootloader.bin # Testing
       run: cd code; platformio run --environment esp32cam
 
-    - name: Prepare Web UI (copy data from repo, generate tooltip pages and update hashes in all files)
+    - name: Prepare Web UI (generate tooltip pages and update hashes in all files)
       run: |
         rm -rf ./html
         mkdir html
@@ -79,7 +79,7 @@ jobs:
         python -m pip install markdown
         mkdir html/param-tooltips
         cd tools/parameter-tooltip-generator
-        bash generate-param-doc-tooltips.sh
+        python generate-param-doc-tooltips.py
         cd ../..
 
         cp -r ./sd-card/html/* ./html/

code/README.md

@@ -69,3 +69,6 @@ pio device monitor -p /dev/ttyUSB0
 - `pio run --target erase` to erase the flash
 - `pio run --target upload` this will upload the `bootloader.bin, partitions.bin,firmware.bin` from the `code/.pio/build/esp32cam/` folder. 
 - `pio device monitor` to observe the logs via uart
+
+# Update Parameters
+If you create or rename a parameter, make sure to update its documentation in `../param-docs/parameter-pages`! Check the `../param-docs/README.md` for more information.

param-docs/.idea/.gitignore

@@ -0,0 +1,3 @@
+# Default ignored files
+/shelf/
+/workspace.xml

param-docs/.idea/generate-param-docs.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="jdk" jdkName="Python 3.10" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

param-docs/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

param-docs/.idea/misc.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.10" project-jdk-type="Python SDK" />
+</project>

param-docs/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/generate-param-docs.iml" filepath="$PROJECT_DIR$/.idea/generate-param-docs.iml" />
+    </modules>
+  </component>
+</project>

param-docs/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$/../.." vcs="Git" />
+  </component>
+</project>

param-docs/README.md

@@ -0,0 +1,17 @@
+# Parameter Documentation
+Each parameter which is listed in the [configfile](https://github.com/jomjol/AI-on-the-edge-device/blob/rolling/sd-card/config/config.ini) has its own description page in the folder `parameter-pages` (grouped by the config sections).
+Those pages can be edited as needed.
+
+During a Github action build, those parameter pages will be used to generate the tooltips in the web interface. And they also are used to build the [Online Documentation](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters).
+
+If you create or rename a parameter, make sure to also update its description page!
+
+## Template Generator
+The script `generate-template-param-doc-pages.py` should be run whenever a new parameter gets added to the config file.
+It then checks if there is already a page for each of the parameters.
+ - If no page exists yet, a templated page gets generated.
+ - Existing pages do not get modified.
+
+If the parameter is listed in `expert-params.txt`, an **Expert warning** will be shown.
+
+If the parameter is listed in `hidden-in-ui.txt`, a **Note**  will be shown.

param-docs/expert-params.txt

@@ -0,0 +1,31 @@
+demo
+WaitBeforeTakingPicture
+ImageQuality
+ImageSize
+LEDIntensity
+Brightness
+Contrast
+Saturation
+FixedExposure
+SearchFieldX
+SearchFieldY
+AlignmentAlgo
+InitialMirror
+FlipImageSize
+CNNGoodThreshold
+PreValueAgeStartup
+ErrorMessage
+CheckDigitIncreaseConsistency
+IO0
+IO1
+IO3
+IO4
+IO12
+IO13
+AutoStart
+Hostname
+RSSIThreshold
+TimeServer
+CACert
+ClientCert
+ClientKey

param-docs/generate-template-param-doc-pages.py

@@ -0,0 +1,95 @@
+"""
+For each parameter which can be found in the config file,
+create a markdown file with a templated content if it does not exist yet.
+The files are grouped in sub folders representing the config sections.
+"""
+
+import os
+import configparser
+import urllib.request
+
+
+configFileUrl = "https://raw.githubusercontent.com/jomjol/AI-on-the-edge-device/rolling/sd-card/config/config.ini"
+
+parameterDocsFolder = "parameter-pages"
+parameterTemplateFile = "./templates/parameter.md"
+expertParameterListFile = "./expert-params.txt"
+hiddenInUiParameterListFile = "./hidden-in-ui.txt"
+
+
+# Fetch default config file from URL
+print("Fetching %r..." % configFileUrl)
+with urllib.request.urlopen(configFileUrl) as response:
+   content = response.read().decode("utf-8")
+
+lines = str(content).split("\n")
+
+for l in range(len(lines)):
+    lines[l] = lines[l].strip() + "\n"
+    if lines[l][0] == ";":
+        lines[l] = lines[l][1:] # Remove comment
+
+content = "".join(lines)
+
+# Fetch list of expert parameters
+with open(expertParameterListFile) as f:
+    expertParameters = f.read().splitlines()
+
+# Fetch list of parameters not available through the UI
+with open(hiddenInUiParameterListFile) as f:
+    hiddenInUiParameters = f.read().splitlines()
+
+
+config = configparser.ConfigParser(allow_no_value=True)
+config.optionxform = str # Make it case-insensitive
+config.read_string(content)
+
+#shutil.rmtree(parameterDocsFolder)
+if not os.path.exists(parameterDocsFolder):
+    os.mkdir(parameterDocsFolder)
+
+with open(parameterTemplateFile, 'r') as parameterTemplateFileHandle:
+    parameterTemplate = parameterTemplateFileHandle.read()
+
+
+print("For each section/parameter, check if there is already a documentation page in the folder %r..." % (os.getcwd() + "/" + parameterDocsFolder))
+for section in config:
+    if section != "DEFAULT":
+        #print(section)
+
+        subFolder = parameterDocsFolder + "/" + section
+
+        if not os.path.exists(subFolder):
+            os.mkdir(subFolder)
+
+        for parameter in config[section]:
+            if not " " in parameter: # Ignore parameters with whitespaces in them (special format, not part of editable config)
+                value = config[section][parameter]
+                #print("  %s = %s" % (parameter, value))
+
+                if "main." in parameter:
+                    parameter = parameter.replace("main.", "NUMBER.")
+
+                """
+                For each config line, create a markdown file
+                """
+                parameterDocFile = subFolder + '/' + parameter + ".md"
+
+                if not os.path.exists(parameterDocFile): # File does not exist yet, generate template
+                    print("%r does not exit yet, generating a templated file for it" % (os.getcwd() + "/" + parameterDocFile))
+                    with open(parameterDocFile, 'w') as paramFileHandle:
+                        content = parameterTemplate
+                        content = content.replace("$NAME", parameter)
+                        content = content.replace("$DEFAULT", value)
+
+                        if parameter in expertParameters:
+                            content = content.replace("$EXPERT_PARAMETER", "!!! Warning\n    This is an **Expert Parameter**! Only change it if you understand what it does!") # Note: Needs a 4 whitespace Intent!
+                        else:
+                            content = content.replace("$EXPERT_PARAMETER", "")
+
+                        if parameter in hiddenInUiParameters:
+                            content = content.replace("$HIDDEN_IN_UI", "!!! Note\n    This parameter is not accessible through the Web Interface Configuration Page!") # Note: Needs a 4 whitespace Intent!
+                        else:
+                            content = content.replace("$HIDDEN_IN_UI", "")
+
+                        paramFileHandle.write(content)

param-docs/hidden-in-ui.txt

@@ -0,0 +1,4 @@
+InitialRotate
+MainTopicMQTT
+AutoAdjustSummertime
+SetupMode

param-docs/parameter-pages/Alignment/AlignmentAlgo.md

@@ -0,0 +1,14 @@
+# Parameter `AlignmentAlgo`
+Default Value: `Default`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Algorithm used for the alignment step.
+
+Available options:
+
+- `Default`: Use only red color channel
+- `HighAccuracy`: Use all 3 color channels (3x slower)
+- `Fast`: First time use `HighAccuracy`, then only check if the image is shifted
+- `Off`: Disable alignment algorithm

param-docs/parameter-pages/Alignment/FlipImageSize.md

@@ -0,0 +1,11 @@
+# Parameter `FlipImageSize`
+Default Value: `false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+    
+!!! Note
+    This parameter can also be set on the Reference Image configuration.
+
+This parameter can be used to rotate the viewport together with the alignment rotation:
+![](img/flipImageSize.png) 

param-docs/parameter-pages/Alignment/InitialMirror.md

@@ -0,0 +1,10 @@
+# Parameter `InitialMirror`
+Default Value: `false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+    
+!!! Note
+    This parameter can also be set on the Reference Image configuration.
+
+Option for initially mirroring the image on the original x-axis.

param-docs/parameter-pages/Alignment/InitialRotate.md

@@ -0,0 +1,9 @@
+# Parameter `InitialRotate`
+Default Value: `179`
+
+Unit: Degrees
+
+Initial rotation of image before alignment in degree (0 .. 359)
+
+!!! Note
+    This parameter is accessible on the Reference Image Page but not on the Config page!

param-docs/parameter-pages/Alignment/SearchFieldX.md

@@ -0,0 +1,14 @@
+# Parameter `SearchFieldX`
+Default Value: `20`
+
+Unit: Pixels
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+X-size (width) in which the reference is searched.
+
+!!! Note
+     Since the alignment is one of the steps using a lot of computation time, 
+     the search field should be as small as possible.
+     The calculation time goes quadratic with the search field size.

param-docs/parameter-pages/Alignment/SearchFieldY.md

@@ -0,0 +1,14 @@
+# Parameter `SearchFieldY`
+Default Value: `20`
+
+Unit: Pixels
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Y-size (height) in which the reference is searched.
+
+!!! Note
+     Since the alignment is one of the steps using a lot of computation time, 
+     the search field should be as small as possible.
+     The calculation time goes quadratic with the search field size.

param-docs/parameter-pages/Analog/CNNGoodThreshold.md

@@ -0,0 +1,10 @@
+# Parameter `CNNGoodThreshold`
+Default Value: `0.5`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Threshold above which the classification should be to accept the value (only meaningful for digits).
+
+!!! Warning
+    This is only supported for the `ana-class100` models!

param-docs/parameter-pages/Analog/ExtendedResolution.md

@@ -0,0 +1,5 @@
+# Parameter `ExtendedResolution`
+
+!!! Warning
+    This parameter is unused!
+    Use [`NUMBER.ExtendedResolution`](../Parameters/#PostProcessing-NUMBER.ExtendedResolution) instead!

param-docs/parameter-pages/Analog/Model.md

@@ -0,0 +1,4 @@
+# Parameter `Model`
+Default Value: `/config/ana-cont_*.tflite` (See [/config/config.ini](https://github.com/jomjol/AI-on-the-edge-device/blob/master/sd-card/config/config.ini))
+
+Path to CNN model file for image recognition. See [here](../Choosing-the-Model) for details. 

param-docs/parameter-pages/Analog/ROIImagesLocation.md

@@ -0,0 +1,7 @@
+# Parameter `ROIImagesLocation`
+Default Value: `/log/analog`
+
+Location to store separated analog images on the SD-Card.
+
+!!! Warning
+    A SD-Card has limited write cycles. Since the device does not do [Wear Leveling](https://en.wikipedia.org/wiki/Wear_leveling), this can wear out your SD-Card!

param-docs/parameter-pages/Analog/ROIImagesRetention.md

@@ -0,0 +1,6 @@
+# Parameter `ROIImagesRetention`
+Default Value: `3`
+
+Unit: Days
+
+Days to keep the separated analog images (`0` = forever).

param-docs/parameter-pages/AutoTimer/AutoStart.md

@@ -0,0 +1,12 @@
+# Parameter `AutoStart`
+Default Value: `true`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Automatically start the Flow (Digitization Rounds) immediately after power up.
+
+!!! Note
+    Typically this is set to `true`.
+    The main reasons to set it to `false` is when you want to trigger it manually using the
+    [REST API](../REST-API) or [MQTT-API](../MQTT-API) or for debugging.

param-docs/parameter-pages/AutoTimer/Interval.md

@@ -0,0 +1,7 @@
+# Parameter `Interval`
+Default Value: `5`
+
+Unit: Minutes
+
+Interval in which the Flow (Digitization Round) is run.
+If a round takes longer than this interval, the next round gets postponed until the current round completes.

param-docs/parameter-pages/DataLogging/DataFilesRetention.md

@@ -0,0 +1,6 @@
+# Parameter `DataFilesRetention`
+Default Value: `3`
+
+Unit: Days
+
+Number of days to keep the data files (`0` = forever).

param-docs/parameter-pages/DataLogging/DataLogActive.md

@@ -0,0 +1,8 @@
+# Parameter `DataLogActive`
+Default Value: `true`
+Activate data logging to the SD-Card.
+
+The files will be stored in `/log/data/data_YYYY-MM-DD.csv`. See [`Data Logging`](../data-logging) for details.
+
+!!! Warning
+    A SD-Card has limited write cycles. Since the device does not do [Wear Leveling](https://en.wikipedia.org/wiki/Wear_leveling), this can wear out your SD-Card!

param-docs/parameter-pages/Debug/LogLevel.md

@@ -0,0 +1,16 @@
+# Parameter `LogLevel`
+Default Value: `1` (`ERROR`)
+Define the log level for the logging to the SD-Card.
+
+Available options:
+
+- `1`: `ERROR`
+- `2`: `WARNING`
+- `3`: `INFO`
+- `4`: `DEBUG`
+
+As higher the level, as more log messages get written to the SD-Card.
+
+!!! Warning
+    `DEBUG` or `INFO` might damage the SD-Card if enabled long term due to excessive writes to the SD-Card!
+    A SD-Card has limited write cycles. Since the device does not do [Wear Leveling](https://en.wikipedia.org/wiki/Wear_leveling), this can wear out your SD-Card!

param-docs/parameter-pages/Debug/LogfilesRetention.md

@@ -0,0 +1,6 @@
+# Parameter `LogfilesRetention`
+Default Value: `3`
+
+Unit: Days
+
+Number of days to keep the log files (`0` = forever).

param-docs/parameter-pages/Digits/CNNGoodThreshold.md

@@ -0,0 +1,10 @@
+# Parameter `CNNGoodThreshold`
+Default Value: `0.5`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Threshold above which the classification should be to accept the value (only meaningful for digits).
+
+!!! Warning
+    This is only supported for the `dig-class100` models!

param-docs/parameter-pages/Digits/Model.md

@@ -0,0 +1,4 @@
+# Parameter `Model`
+Default Value: `/config/dig-cont_*.tflite` (See [/config/config.ini](https://github.com/jomjol/AI-on-the-edge-device/blob/master/sd-card/config/config.ini))
+
+Path to CNN model file for image recognition. See [here](../Choosing-the-Model) for details. 

param-docs/parameter-pages/Digits/ROIImagesLocation.md

@@ -0,0 +1,7 @@
+# Parameter `ROIImagesLocation`
+Default Value: `/log/digit`
+
+Location to store separated digit images on the SD-Card.
+
+!!! Warning
+    A SD-Card has limited write cycles. Since the device does not do [Wear Leveling](https://en.wikipedia.org/wiki/Wear_leveling), this can wear out your SD-Card!

param-docs/parameter-pages/Digits/ROIImagesRetention.md

@@ -0,0 +1,6 @@
+# Parameter `ROIImagesRetention`
+Default Value: `3`
+
+Unit: Days
+
+Days to keep the separated digit images (`0` = forever).

param-docs/parameter-pages/GPIO/IO0.md

@@ -0,0 +1,21 @@
+# Parameter `IO0`
+Default Value: `input disabled 10 false false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+This parameter can be used to configure the GPIO `IO0` pin.
+
+!!! Warning
+    This pin is only usable with restrictions!
+    It must be disabled when the camera is used.
+    Additionally, it is used to activate Bootloader mode and must therefore be HIGH after a reset!
+
+Parameters:
+
+- `GPIO 0 state`: One of `input`, `input pullup`, `input pulldown` or `output`.
+- `GPIO 0 use interrupt`: Enable interrupt trigger
+- `GPIO 0 PWM duty resolution`: LEDC PWM duty resolution in bit
+- `GPIO 0 enable MQTT`: Enable MQTT publishing/subscribing
+- `GPIO 0 enable HTTP`: Enable HTTP write/read
+- `GPIO 0 name`: MQTT topic name (empty = `GPIO0`). Allowed characters: `a-z, A-Z, 0-9, _, -`.

param-docs/parameter-pages/GPIO/IO1.md

@@ -0,0 +1,19 @@
+# Parameter `IO1`
+Default Value: `input disabled 10 false false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+This parameter can be used to configure the GPIO `IO1` pin.
+
+!!! Warning
+    This pin is by default used for the serial communication as TX pin (USB logging)!
+
+Parameters:
+
+- `GPIO 1 state`: One of `input`, `input pullup`, `input pulldown` or `output`.
+- `GPIO 1 use interrupt`: Enable interrupt trigger
+- `GPIO 1 PWM duty resolution`: LEDC PWM duty resolution in bit
+- `GPIO 1 enable MQTT`: Enable MQTT publishing/subscribing
+- `GPIO 1 enable HTTP`: Enable HTTP write/read
+- `GPIO 1 name`: MQTT topic name (empty = `GPIO1`). Allowed characters: `a-z, A-Z, 0-9, _, -`.

param-docs/parameter-pages/GPIO/IO12.md

@@ -0,0 +1,19 @@
+# Parameter `IO12`
+Default Value: `input-pullup disabled 10 false false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+This parameter can be used to configure the GPIO `IO12` pin.
+
+!!! Note
+    This pin is usable without known restrictions!
+
+Parameters:
+
+- `GPIO 12 state`: One of `external-flash-ws281x`, `input`, `input pullup`, `input pulldown` or `output`.
+- `GPIO 12 use interrupt`: Enable interrupt trigger
+- `GPIO 12 PWM duty resolution`: LEDC PWM duty resolution in bit
+- `GPIO 12 enable MQTT`: Enable MQTT publishing/subscribing
+- `GPIO 12 enable HTTP`: Enable HTTP write/read
+- `GPIO 12 name`: MQTT topic name (empty = `GPIO12`). Allowed characters: `a-z, A-Z, 0-9, _, -`.

param-docs/parameter-pages/GPIO/IO13.md

@@ -0,0 +1,19 @@
+# Parameter `IO13`
+Default Value: `input-pullup disabled 10 false false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+This parameter can be used to configure the GPIO `IO13` pin.
+
+!!! Note
+    This pin is usable without known restrictions!
+
+Parameters:
+
+- `GPIO 13 state`: One of `input`, `input pullup`, `input pulldown` or `output`.
+- `GPIO 13 use interrupt`: Enable interrupt trigger
+- `GPIO 13 PWM duty resolution`: LEDC PWM duty resolution in bit
+- `GPIO 13 enable MQTT`: Enable MQTT publishing/subscribing
+- `GPIO 13 enable HTTP`: Enable HTTP write/read
+- `GPIO 13 name`: MQTT topic name (empty = `GPIO13`). Allowed characters: `a-z, A-Z, 0-9, _, -`.

param-docs/parameter-pages/GPIO/IO3.md

@@ -0,0 +1,19 @@
+# Parameter `IO3`
+Default Value: `input disabled 10 false false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+This parameter can be used to configure the GPIO `IO3` pin.
+
+!!! Warning
+    This pin is by default used for the serial communication as RX pin (USB logging)!
+
+Parameters:
+
+- `GPIO 3 state`: One of `input`, `input pullup`, `input pulldown` or `output`.
+- `GPIO 3 use interrupt`: Enable interrupt trigger
+- `GPIO 3 PWM duty resolution`: LEDC PWM duty resolution in bit
+- `GPIO 3 enable MQTT`: Enable MQTT publishing/subscribing
+- `GPIO 3 enable HTTP`: Enable HTTP write/read
+- `GPIO 3 name`: MQTT topic name (empty = `GPIO3`). Allowed characters: `a-z, A-Z, 0-9, _, -`.

param-docs/parameter-pages/GPIO/IO4.md

@@ -0,0 +1,20 @@
+# Parameter `IO4`
+Default Value: `built-in-led disabled 10 false false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+This parameter can be used to configure the GPIO `IO4` pin.
+
+!!! Warning
+    This pin is only usable with restrictions!
+    By default, it is used for build-in flash light (onboard LED).
+
+Parameters:
+
+- `GPIO 4 state`: One of `built-in-led`, `input`, `input pullup`, `input pulldown` or `output`.
+- `GPIO 4 use interrupt`: Enable interrupt trigger
+- `GPIO 4 PWM duty resolution`: LEDC PWM duty resolution in bit
+- `GPIO 4 enable MQTT`: Enable MQTT publishing/subscribing
+- `GPIO 4 enable HTTP`: Enable HTTP write/read
+- `GPIO 4 name`: MQTT topic name (empty = `GPIO4`). Allowed characters: `a-z, A-Z, 0-9, _, -`.

param-docs/parameter-pages/GPIO/LEDColor.md

@@ -0,0 +1,5 @@
+# Parameter `LEDColor`
+Default Value: `150 150 150`
+
+Color of the attached LEDs to GPIO12 in **R**ed, **G**reen **B**lue from `0` (full off) .. `255` (full on) 
+(See `IO12` parameter).

param-docs/parameter-pages/GPIO/LEDNumbers.md

@@ -0,0 +1,4 @@
+# Parameter `LEDNumbers`
+Default Value: `2`
+
+Number of LEDs on the external LED-stripe attached to GPIO12 (See `IO12` parameter).

param-docs/parameter-pages/GPIO/LEDType.md

@@ -0,0 +1,3 @@
+# Parameter `LEDType`
+Default Value: `WS2812`
+Type of the `WS2812x` which is connected to GPIO12 (See `IO12` parameter).

param-docs/parameter-pages/GPIO/MainTopicMQTT.md

@@ -0,0 +1,8 @@
+# Parameter `MainTopicMQTT`
+Default Value: `wasserzaehler/GPIO`
+
+!!! Note
+    This parameter is not accessible through the Web Interface Configuration Page!
+
+The GPIO Interface is prepared to report it's status and status changes as a MQTT topic. With this parameter you configure the MQTT main topic, under which the status is published.
+As this parameter is still experimental it can only be set manually in the `config.ini` itself and has not been tested in detail so far.

param-docs/parameter-pages/InfluxDB/Database.md

@@ -0,0 +1,7 @@
+# Parameter `Database`
+Default Value: `''`
+
+Name of the InfluxDB v1 Database into which to publish the values.
+
+!!! Note
+    See section `InfluxDBv2` for InfluxDB v2 support! 

param-docs/parameter-pages/InfluxDB/NUMBER.Field.md

@@ -0,0 +1,4 @@
+# Parameter `<NUMBER>.Field`
+Default Value: `undefined`
+
+Dedicated definition of the field for InfluxDB use for saving in the Influx database (e.g.: "watermeter/value").

param-docs/parameter-pages/InfluxDB/NUMBER.Measurement.md

@@ -0,0 +1,7 @@
+# Parameter `Measurement`
+Default Value: `undefined`
+
+Name of the InfluxDB v1 Measurement to use to publish the value.
+
+!!! Note
+    See section `InfluxDBv2` for InfluxDB v2 support! 

param-docs/parameter-pages/InfluxDB/Uri.md

@@ -0,0 +1,7 @@
+# Parameter `Uri`
+Default Value: `undefined`
+
+URI of the HTTP interface to InfluxDB v1, without trailing slash, e.g. `http://192.168.1.1:8086`.
+
+!!! Note
+    See section `InfluxDBv2` for InfluxDB v2 support! 

param-docs/parameter-pages/InfluxDB/password.md

@@ -0,0 +1,7 @@
+# Parameter `password`
+Default Value: `undefined`
+
+Password for the InfluxDB v1 authentication.
+
+!!! Note
+    See section `InfluxDBv2` for InfluxDB v2 support! 

param-docs/parameter-pages/InfluxDB/user.md

@@ -0,0 +1,7 @@
+# Parameter `user`
+Default Value: `undefined`
+
+Username for the InfluxDB v1 authentication.
+
+!!! Note
+    See section `InfluxDBv2` for InfluxDB v2 support! 

param-docs/parameter-pages/InfluxDBv2/Bucket.md

@@ -0,0 +1,4 @@
+# Parameter `Bucket`
+Default Value: `''`
+
+Name of the InfluxDB v2 Bucket into which to publish the values.

param-docs/parameter-pages/InfluxDBv2/Database.md

@@ -0,0 +1,5 @@
+# Parameter `Database`
+
+!!! Warning
+    This parameter is unused!
+    Use [`Basket`](../Parameters/#InfluxDBv2-Basket) instead!

param-docs/parameter-pages/InfluxDBv2/NUMBER.Field.md

@@ -0,0 +1,4 @@
+# Parameter `<NUMBER>.Field`
+Default Value: `undefined`
+
+Field for InfluxDB v2 to use for saving.

param-docs/parameter-pages/InfluxDBv2/NUMBER.Measurement.md

@@ -0,0 +1,4 @@
+# Parameter `Measurement`
+Default Value: `undefined`
+
+Name of the InfluxDB v2 Measurement to use to publish the value.

param-docs/parameter-pages/InfluxDBv2/Org.md

@@ -0,0 +1,4 @@
+# Parameter `Org`
+Default Value: `undefined`
+
+Organisation (Org) for InfluxDB v2 authentication

param-docs/parameter-pages/InfluxDBv2/Token.md

@@ -0,0 +1,4 @@
+# Parameter `Token`
+Default Value: `undefined`
+
+Token for InfluxDB v2 authentication

param-docs/parameter-pages/InfluxDBv2/Uri.md

@@ -0,0 +1,4 @@
+# Parameter `Uri`
+Default Value: `undefined`
+
+URI of the HTTP interface to InfluxDB v2, without trailing slash, e.g. `http://192.168.1.1:8086`.

param-docs/parameter-pages/MQTT/CACert.md

@@ -0,0 +1,18 @@
+# Parameter `CACert`
+Default Value: `""`
+
+Example: `/config/certs/RootCA.pem`.
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Path to the CA certificate file.
+
+This is part of the configuration to enable TLS for MQTT.
+The CA Certificate is used by the client to validate the broker is who it claims to be.
+It allows the client to authenticate the server, which is the first part of the MTLS handshake.
+
+Usually there is a common RootCA certificate for the MQTT broker
+
+!!! Note
+    This also means that you might have to change the protocol and port in [uri](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-uri) to `mqtts://example.com:8883`!

param-docs/parameter-pages/MQTT/ClientCert.md

@@ -0,0 +1,19 @@
+# Parameter `ClientCert`
+Default Value: `""`
+
+Example: `/config/certs/client.pem.crt`.
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Path to the Client Certificate file.
+
+This is part of the configuration to enable TLS for MQTT.
+The Client Certificate is used by the client to prove its identity to the server, in conjunction with the Client Key. 
+It is the second part of the MTLS handshake.
+
+Usually there is a one pair of Client Certificate/Key for each client that connects to the MQTT broker
+
+!!! Note
+    If set, `ClientKey` must be set too
+    This also means that you might have to change the protocol and port in [uri](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-uri) to `mqtts://example.com:8883`!

param-docs/parameter-pages/MQTT/ClientID.md

@@ -0,0 +1,5 @@
+# Parameter `ClientID`
+Default Value: `watermeter`
+
+Client ID used to connect to the MQTT broker.
+If disabled, the `hostname` will be used.

param-docs/parameter-pages/MQTT/ClientKey.md

@@ -0,0 +1,19 @@
+# Parameter `ClientKey`
+Default Value: `""`
+
+Example: `/config/certs/client.pem.key`.
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Path to the Client Key file.
+
+This is part of the configuration to enable TLS for MQTT.
+The Client Key is used by the client to prove its identity to the server, in conjunction with the Client Certificate.
+It is the second part of the MTLS handshake.
+
+Usually there is a one pair of Client Certificate/Key for each client that connects to the MQTT broker
+
+!!! Note
+    If set, `ClientCert` must be set too
+    This also means that you might have to change the protocol and port in [uri](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-uri) to `mqtts://example.com:8883`!

param-docs/parameter-pages/MQTT/HomeassistantDiscovery.md

@@ -0,0 +1,5 @@
+# Parameter `HomeassistantDiscovery`
+Default Value: `true`
+
+Enable or disable the Homeassistant Discovery.
+See [here](../Integration-Home-Assistant) for details about the discovery.

param-docs/parameter-pages/MQTT/MainTopic.md

@@ -0,0 +1,18 @@
+# Parameter `MainTopic`
+Default Value: `watermeter`
+
+MQTT main topic, under which the counters are published.
+
+The single value will be published with the following key: `MAINTOPIC/NUMBER/RESULT_TOPIC`
+
+With:
+
+- `NUMBER`: The name of the value (a meter might have more than one value). 
+  The names get defined in the analog and digital ROI configuration (defaults to `main`).
+- `RESULT_TOPIC`: Automatically filled with the right name, eg. `value`, `rate`, `timestamp`, `error`, ....
+
+The general connection status can be found in `MAINTOPIC/CONNECTION`. 
+See [MQTT Result Topics](../MQTT-API#result) for a full list of topics.
+
+!!! Note
+    The main topic is allowed to contain `/` which can be used to split it into multiple levels, eg. `/basement/meters/watermeter/1/` if you have multiple water meters in your basement.

param-docs/parameter-pages/MQTT/MeterType.md

@@ -0,0 +1,11 @@
+# Parameter `MeterType`
+Default Value: `other`
+
+Select the Meter Type so the sensors have the right units in Homeassistant.
+
+!!! Note
+    For `Watermeter` you need to have Homeassistant 2022.11 or newer!
+
+Please also make sure that the selected Meter Type matches the dimension of the value provided by the meter!
+Eg. if your meter provides `m³`, you need to also set it to `m³`.
+Alternatively you can set the parameter `DecimalShift` to `3` so the value is converted to `liters`!

param-docs/parameter-pages/MQTT/RetainMessages.md

@@ -0,0 +1,4 @@
+# Parameter `RetainMessages`
+Default Value: `true`
+
+Enable or disable the [Retain Flag](https://www.hivemq.com/blog/mqtt-essentials-part-8-retained-messages/) for all MQTT entries.

param-docs/parameter-pages/MQTT/Uri.md

@@ -0,0 +1,4 @@
+# Parameter `Uri`
+Default Value: `mqtt://example.com:1883`
+
+URI to the MQTT broker including the port. E.g. `mqtt://192.168.1.1:1883`.

param-docs/parameter-pages/MQTT/password.md

@@ -0,0 +1,4 @@
+# Parameter `password`
+Default Value: `PASSWORD`
+
+Password for MQTT authentication.

param-docs/parameter-pages/MQTT/user.md

@@ -0,0 +1,4 @@
+# Parameter `user`
+Default Value: `USERNAME`
+
+Username for MQTT authentication.

param-docs/parameter-pages/PostProcessing/AllowNegativeRates.md

@@ -0,0 +1,5 @@
+# Parameter `AllowNegativeRates`
+
+!!! Warning
+    This parameter is unused!
+    Use [`NUMBER.AllowNegativeRates`](../Parameters/#PostProcessing-NUMBER.AllowNegativeRates) instead!

param-docs/parameter-pages/PostProcessing/CheckDigitIncreaseConsistency.md

@@ -0,0 +1,8 @@
+# Parameter `CheckDigitIncreaseConsistency`
+Default Value: `false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+An additional consistency check.
+It especially improves the zero crossing check between digits.

param-docs/parameter-pages/PostProcessing/ErrorMessage.md

@@ -0,0 +1,8 @@
+# Parameter `ErrorMessage`
+Default Value: `true`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Do not show error message in return value.
+In an error case, the last valid number will be used for the various transmission protocols (MQTT, InfluxDB, REST, ...).

param-docs/parameter-pages/PostProcessing/NUMBER.AllowNegativeRates.md

@@ -0,0 +1,7 @@
+# Parameter `<NUMBERS>.AllowNegativeRates`
+Default Value: `false`
+
+Allow a meter to count backwards (decreasing values).
+
+!!! Note
+    This is unusual (it means there is a negative rate) and not wanted in most cases!

param-docs/parameter-pages/PostProcessing/NUMBER.AnalogDigitalTransitionStart.md

@@ -0,0 +1,9 @@
+# Parameter `<NUMBER>.AnalogDigitalTransitionStart`
+Default Value: `9.2`
+
+This can be used if you have wrong values, but the recognition of the individual ROIs are correct.
+Look for the start of changing of the first digit and note the analog pointer value behind.
+Set it here. Only used on combination of digits and analog pointers.
+See [here](../Watermeter-specific-analog---digital-transition) for details.
+
+Range: `6.0` .. `9.9`.

param-docs/parameter-pages/PostProcessing/NUMBER.DecimalShift.md

@@ -0,0 +1,5 @@
+# Parameter `<NUMBER>.DecimalShift`
+Default Value: `0`
+
+Shift the decimal separator (positiv or negativ).
+Eg. to move from `m³` to `liter` (`1 m³` equals `1000 liters`), you need to set it to `+3`.

param-docs/parameter-pages/PostProcessing/NUMBER.ExtendedResolution.md

@@ -0,0 +1,7 @@
+# Parameter `<NUMBER>.ExtendedResolution`
+Default Value: `false`
+
+Use the decimal place of the last analog counter for increased accuracy.
+
+!!! Note
+    This parameter is only supported on the `*-class*` and `*-const` models! See [Choosing-the-Model](../Choosing-the-Model) for details.

param-docs/parameter-pages/PostProcessing/NUMBER.IgnoreLeadingNaN.md

@@ -0,0 +1,6 @@
+# Parameter `<NUMBER>.IgnoreLeadingNaN`
+Default Value: `true`
+
+Leading `N`'s will be deleted before further processing.
+This is only relevant for models which use `N`!
+See [here](../Choosing-the-Model) for details.

param-docs/parameter-pages/PostProcessing/NUMBER.MaxRateType.md

@@ -0,0 +1,5 @@
+# Parameter `<NUMBER>.MaxRateType`
+Default Value: `AbsoluteChange`
+
+Defines if the **Change Rate** is calculated as the difference between the last two readings (`AbsoluteChange` = difference) or
+as the difference normalized to the interval (`RateChange` = difference per minute).

param-docs/parameter-pages/PostProcessing/NUMBER.MaxRateValue.md

@@ -0,0 +1,6 @@
+# Parameter `<NUMBER>.MaxRateValue`
+Default Value: `0,05`
+
+Maximum allowed change between two readings, if exceeded the last reading will be rejected. Depending on the settings of `<NUMBER>.MaxRateType` the `MaxRateValue` is either treated as the difference between the two measurements (`AbsoluteChange` = difference) not taking the set time interval into account or as the difference normalized to the interval (`RateChange` = difference per minute).
+
+If negative rate is disallowed and no maximum rate value is set, one false high reading will lead to a period of missing measurements until the measurement reaches the previous false high reading. E.g. if the counter is at `600,00` and it's read incorrectly as` 610,00`, all measurements will be skipped until the counter reaches `610,00`. Setting the MaxRateValue to `0,05` leads to a rejection of all readings with a difference `> 0,05`, in this case `610,00`. The rejection also applies to correct readings with a difference `> 0,05`!

param-docs/parameter-pages/PostProcessing/PreValueAgeStartup.md

@@ -0,0 +1,7 @@
+# Parameter `PreValueAgeStartup`
+Default Value: `720`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Time in minutes, how long a previous read value is valid after reboot.

param-docs/parameter-pages/PostProcessing/PreValueUse.md

@@ -0,0 +1,5 @@
+# Parameter `PreValueUse`
+Default Value: `true`
+
+Use the previous value (value from previous round) for consistency checks.
+This also works through a reboot of the device!

param-docs/parameter-pages/System/CPUFrequency.md

@@ -0,0 +1,13 @@
+# Parameter `CPUFrequency`
+Default Value: `160`
+
+Set the CPU Frequency.
+
+!!! Warning
+    Setting it to 240 will lead to a faster device, but it will also require a stronger power supply!
+    Additionally, depending on the quality of your ESP32-CAM, it might run unstable!
+
+Possible values: 
+
+- 160
+- 240 

param-docs/parameter-pages/System/Hostname.md

@@ -0,0 +1,8 @@
+# Parameter `Hostname`
+Default Value: `undefined`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Hostname for the device.
+It gets automatically transferred to `/wlan.ini` on the SD-Card at the next startup.

param-docs/parameter-pages/System/RSSIThreshold.md

@@ -0,0 +1,19 @@
+# Parameter `RSSIThreshold`
+Default Value: `0`
+
+Possible values: `-100` .. `0` (`0` = disabled).
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+
+This parameter activates a client triggered AP switching functionality (simplified roaming). 
+If actual RSSI value is lower (more negative) than `RSSIThreshold`, all WIFI channels will be scanned for configured access point SSID. If an access point is in range which has better RSSI value (less negative) than actual RSSI value + 5 dBm, the device is trying to connect to this access point with the better RSSI value.
+
+
+!!! Note
+    The RSSI check only gets initiated at the end of each round to avoid any disturbance of processing.
+
+
+!!! Note
+    It gets automatically transferred to `/wlan.ini` on the SD-Card at next startup.

param-docs/parameter-pages/System/SetupMode.md

@@ -0,0 +1,7 @@
+# Parameter `SetupMode`
+Default Value: `true`
+
+!!! Note
+    This parameter is not accessible through the Web Interface Configuration Page!
+
+Set this parameter to `true` to stay in the Setup Mode after the next start of the device.

param-docs/parameter-pages/System/TimeServer.md

@@ -0,0 +1,10 @@
+# Parameter `TimeServer`
+Default Value: `pool.ntp.org`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Time server to synchronize system time. If it is disabled or `undefined`, `pool.ntp.org` will be used.
+You can also set it to the IP of your router. Many routers like Fritzboxes can act as a local NTP server.
+To disable NTP, you need to activate it but set the TimeServer config to be empty (`""`).
+In such case the time always starts at `01.01.1970` after each power cycle!

param-docs/parameter-pages/System/TimeZone.md

@@ -0,0 +1,5 @@
+# Parameter `TimeZone`
+Default Value: `CET-1CEST,M3.5.0,M10.5.0/3`
+
+Time zone in POSIX syntax (Europe/Berlin = `CET-1CEST,M3.5.0,M10.5.0/3` - incl. daylight saving)
+Check the table on `http://<DEVICE IP>/timezones.html` to find the settings for your region.

param-docs/parameter-pages/TakeImage/Brightness.md

@@ -0,0 +1,10 @@
+# Parameter `Brightness`
+Default Value: `0`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+      
+!!! Note
+    This parameter can also be set on the Reference Image configuration.
+
+Image Brightness (`-2` .. `2`) 

param-docs/parameter-pages/TakeImage/Contrast.md

@@ -0,0 +1,11 @@
+# Parameter `Contrast`
+Default Value: `0`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+!!! Note
+    This parameter can also be set on the Reference Image configuration.
+
+Image Contrast (`-2` .. `2`)
+

param-docs/parameter-pages/TakeImage/Demo.md

@@ -0,0 +1,6 @@
+# Parameter `Demo`
+Default Value: `false`
+
+Enable to use demo images instead of the real camera images.
+Make sure to have a `/demo` folder on your SD-Card and make sure it contains the expected files!
+Check [here](../Demo-Mode) for details. 

param-docs/parameter-pages/TakeImage/FixedExposure.md

@@ -0,0 +1,7 @@
+# Parameter `FixedExposure`
+Default Value: `false`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Fixes the illumination setting of camera at the startup and uses this later -> Individual round is faster.

param-docs/parameter-pages/TakeImage/ImageQuality.md

@@ -0,0 +1,10 @@
+# Parameter `ImageQuality`
+Default Value: `12`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Quality index for pictures: `8` (highest quality) ... `63` (lowest quality)
+
+!!! Warning
+    Value below 12 could result in system instabilities!

param-docs/parameter-pages/TakeImage/ImageSize.md

@@ -0,0 +1,12 @@
+# Parameter `ImageSize`
+Default Value: `VGA`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Size of the camera picture.
+
+Available options:
+
+- `VGA` (640 x 480 pixel)
+- `QVGA` (320 x 240 pixel)

param-docs/parameter-pages/TakeImage/LEDIntensity.md

@@ -0,0 +1,8 @@
+# Parameter `LEDIntensity`
+Default Value: `50`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+    This parameter can also be set on the Reference Image configuration.
+
+Set the Flash LED Intensity: (`0` .. `100`)

param-docs/parameter-pages/TakeImage/RawImagesLocation.md

@@ -0,0 +1,7 @@
+# Parameter `RawImagesLocation`
+Default Value: `/log/source`
+
+Location on the SD-Card to store the raw images.
+
+!!! Warning
+    A SD-Card has limited write cycles. Since the device does not do [Wear Leveling](https://en.wikipedia.org/wiki/Wear_leveling), this can wear out your SD-Card!

param-docs/parameter-pages/TakeImage/RawImagesRetention.md

@@ -0,0 +1,6 @@
+# Parameter `RawImagesRetention`
+Default Value: `15`
+
+Unit: Days
+
+Number of days to keep the raw images (`0` = forever)

param-docs/parameter-pages/TakeImage/Saturation.md

@@ -0,0 +1,11 @@
+# Parameter `Saturation`
+Default Value: `0`
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+!!! Note
+    This parameter can also be set on the Reference Image configuration.
+
+Image Saturation (`-2` .. `2`)
+

param-docs/parameter-pages/TakeImage/WaitBeforeTakingPicture.md

@@ -0,0 +1,9 @@
+# Parameter `WaitBeforeTakingPicture`
+Default Value: `5`
+
+Unit: seconds
+
+!!! Warning
+    This is an **Expert Parameter**! Only change it if you understand what it does!
+
+Waiting time between switching the flash light (onboard LED) on and taking the picture.

param-docs/templates/overview-old.md

@@ -0,0 +1,13 @@
+# Parameters
+This page lists all available [Configuration](../Configuration) Parameters.
+If a parameter or section has a tick box on its left side, you can disable it.
+In such case the functionality gets disabled respectively the default values will be used.
+
+!!! Note
+    This is an auto-generated page! See the [README](https://github.com/jomjol/AI-on-the-edge-device-docs/blob/main/README.md) for details!
+
+## List of all Parameters
+
+$TOC
+
+<hr style="border:2px solid">

param-docs/templates/overview.md

@@ -0,0 +1,9 @@
+# Parameters
+This page lists all available [Configuration](../Configuration) Parameters.
+If a **parameter** or **section** has a tick box on its left side, you can disable it.
+In such case the functionality gets disabled respectively the default values will be used.
+
+!!! Note
+    This is an auto-generated page! See the [README](https://github.com/jomjol/AI-on-the-edge-device-docs/blob/main/README.md) for details!
+
+<hr style="border:2px solid">

param-docs/templates/parameter.md

@@ -0,0 +1,5 @@
+# Parameter `$NAME`
+Default Value: `$DEFAULT`
+$EXPERT_PARAMETER
+$HIDDEN_IN_UI
+Please fill me with an explanation and useful links.